Module: nirs

Near-infrared spectroscopy nodes.

These nodes implement domain-specific methods for processing near-infrared spectroscopy (fNIRS) data. NIRS data requires a specific processing pipeline, which involves optionally Subtract Dark Intensity, Intensity to Optical Density, and Estimate Concentrations. Other nodes, such as HDDOT, TDDR and so forth may be inserted into the pipeline as well.

AddProbeLocations

Assign probe locations to channels from an fNIRS device.

This takes in a set of source and detector coordinates and adds those to the .source_positions and .positions fields (for source and detector, respectively), of each channel. In addition to the positions, if the space axis does not already hold the channel wavelengths, source and source and detector indexes in the .wavelengths, .sources, and .detectors fields, these will be extracted from the channel names and added. This node takes a pattern (using regex) that defines how the channels are named, so as to be able to identify, from each channel name, the source id (number), detector id, and wavelength, for that channel. This node is used for cases where the position data is not already provided using a standard format (XDF, NIRS, SNIRF). Usually you will need to follow this node with the CoregisterExistingLocations node to convert the coordinates to the coordinate system used by Neuropype. Optionally this node can standardize the channel names to the format S-D-.

Version 0.9.1

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • sources
    A list of xyz coordinates for each source, in order (that is, the first set of xyz coordinates is for Source 1 probe, the second for Source 2 probe, etc.) I.e.: [[17.376,4.6384,17.799], [8.8819,4.1688,17.697], ...].

    • verbose name: Sources
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • detectors
    A list of xyz coordinates for each detector, in order (that is, the first set of xyz coordinates is for Detector 1 probe, the second for Detector 2 probe, etc.) I.e.: [[17.376,4.6384,17.799], [8.8819,4.1688,17.697], ...].

    • verbose name: Detectors
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • channel_name_pattern
    A regex pattern with 3 named groups that define the location, within each channel name, of the source id, detector id and wavelength. These are then used to assign the corresponding source/detector positions to the .source_positions and .positions properties of each channel in the Space axis, and the .wavelength property. This uses regex groups, with (?P<src>\d*) used to identify the source id, (?P<dct>\d*) used to identify the detector id, and (?P<wl>\d*) used to identify the wavelength. I.e., f(?P<wl>\d*)_S(?P<src>\d*)D(?P<dct>\d*) would match the channel name f770_S1D1. The default pattern will match channel names in the format S15-D10-770.

    • verbose name: Channel Name Pattern
    • default value: S(?P\d)-D(?P\d)-(?P\d*)
    • port type: StringPort
    • value type: str (can be None)
  • standardize_channel_names
    If True, the channel names will be standardized to the format S-D-, where is the source or detector id, and is the wavelength of the channel. This is useful for ensuring that the channel names are in a consistent format.

    • verbose name: Standardize Channel Names
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

BadChannelRemovalNIRSCoV

Remove channels with abnormal data from a continuous NIRS signal.

This node is based on the classic coefficient of variation (CoV) metric, and works well on a wide range of headset types. For certain headsets, the alternative inter-channel correlation-based method, which is implemented in the BadChannelRemovalNIRSCorr node, can give better results, but you will have to try both to see which one works best for your data.

Version 1.1.1

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • cov_threshold
    Coefficient of variation threshold. Channels that have higher CoV than this for a sufficiently large fraction of the recording duration will be removed.

    • verbose name: Coeff Of Var Threshold
    • default value: 30
    • port type: FloatPort
    • value type: float (can be None)
  • quality_metric
    Quality metric to use. CoV is the coefficient of variation and CoV@ramp is the coefficient of variation normalized by channel length (the cutoff is the equiv to 1cm, e.g. 7.5). CoV@quad is the coeffient of variation normalized to a quadratic curve (good thresholds are 1-1.5).

    • verbose name: Quality Metric
    • default value: CoV@ramp
    • port type: EnumPort
    • value type: str (can be None)
  • window_len
    Window length to compute CoV. Ideally this is short enough to isolate periods with transient per-channel artifacts.

    • verbose name: Sliding Window Length
    • default value: 5
    • port type: FloatPort
    • value type: float (can be None)
  • min_intensity
    Minimum average intensity below which a channel is marked as bad.

    • verbose name: Min Intensity
    • default value: None
    • port type: FloatPort
    • value type: float (can be None)
  • max_broken_time
    Maximum duration or fraction of broken data to tolerate. Maximum time, either in seconds or as fraction of the calibration data, if below 1.0, during which a channel may be broken while still considered good (i.e., usable). This value should not be larger than half the duration of the calibration data.

    • verbose name: Max Allowed Broken Fraction
    • default value: 0.4
    • port type: FloatPort
    • value type: float (can be None)
  • init_on
    Time range to calibrate (initialize) the filter on. This parameter can take a single number or two numbers. In case of streaming data, this should always be a single number, representing the number of seconds to buffer from the start of the data for calibration. In case of offline (recorded) data, this can either be a single number, in which case it represents the window of time in seconds from the beginning of the recording to be used; or, it can be a list of two numbers, in which case this refers to a range of data in seconds, relative to the start of the data, to be used for calibration. The latter allows you to calibrate on data other than the first segment of the data (i.e., if known to be bad), or to avoid running the (fairly expensive) filter on a very long file or on each fold of a cross-validation. Note that a value of 0 here will in the case of offline data be interpreted as the entire file, and in the case of streaming data will raise an error.

    • verbose name: Initialize On This Time Range
    • default value: [10, 70]
    • port type: ListPort
    • value type: list (can be None)
  • emit_calib
    Whether and how to emit the calibration data, if the node is used in a streaming context. If set to dont-emit, then the calibration data will be swallowed by the node. If set to as-nonstreaming the calibration data will be emitted, but will be marked as non-streaming (offline) data, which can trigger special behavior on downstream nodes, e.g., causing them to calibrate themselves on this portion of the data only. If set to as-streaming, then the calibration data will appear like a regular, albeit long, streaming chunk. In this mode the node can be dropped into a stream pipeline with the least disruption, but some subsequent nodes could experience hiccups on the potentially minutes-long chunk.

    • verbose name: Emit Calib
    • default value: as-streaming
    • port type: EnumPort
    • value type: str (can be None)
  • action
    Action to perform on bad channels. Remove means the channels will be dropped form the data, and mark_nan means that the data of bad channels will be replaced with NaN values (indicating missing data to downstream nodes that can handle it).

    • verbose name: Action
    • default value: remove
    • port type: EnumPort
    • value type: str (can be None)
  • verbose
    Print verbose output.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

BadChannelRemovalNIRSCorr

Remove channels with abnormal data from a continuous NIRS signal.

This node uses between-channel correlations to identify bad channels. This is a fairly sophisticated method, which may work best with fairly high density multi-distance headsets (e.g., Gowerlabs Lumo). For simpler, low-density headsets, or extremely high resolution headsets, this method may not work as well as the simpler coefficient of variation based method, which is implemented in the CoV-Based Bad Channel Removal (NIRS) node. If unsure, it is best to try both methods and compare the results.

Version 0.2.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • cov
    Data covariance matrix. Optional.

    • verbose name: Cov
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: IN
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • diagnostic_chn
    Diagnostic information indicating the per-channel error measure. Range 0 (best) to 1 (worst).

    • verbose name: Diagnostic Chn
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: OUT
  • diagnostic_opt
    Diagnostic information indicating the per-optode error measure (coupling length). Only available if denoise is enabled.

    • verbose name: Diagnostic Opt
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: OUT
  • desired_quality
    Desired minimum quality level per channel. This is a value between 0 and 1. Channels where either source or detector optode have a lower estimated quality at the respective channel's length are removed.

    • verbose name: Desired Quality
    • default value: 0.5
    • port type: FloatPort
    • value type: float (can be None)
  • quality_metric
    Channel quality metric to use. rMAE is a linear reconstruction error (relative mean absolute error), and corr is a correlation-based reconstruction error. Corr is similar to rMAE but more forgiving (e.g., is insensitive to scale error).

    • verbose name: Quality Metric
    • default value: rMAE
    • port type: EnumPort
    • value type: str (can be None)
  • action
    Action to perform on bad channels. Remove means the channels will be dropped form the data, and mark_nan means that the data of bad channels will be replaced with NaN values (indicating missing data to downstream nodes that can handle it).

    • verbose name: Action
    • default value: remove
    • port type: EnumPort
    • value type: str (can be None)
  • init_on
    Time range to calibrate (initialize) the filter on. This parameter can take a single number or two numbers. In case of streaming data, this should always be a single number, representing the number of seconds to buffer from the start of the data for calibration. In case of offline (recorded) data, this can either be a single number, in which case it represents the window of time in seconds from the beginning of the recording to be used; or, it can be a list of two numbers, in which case this refers to a range of data in seconds, relative to the start of the data, to be used for calibration. The latter allows you to calibrate on data other than the first segment of the data (i.e., if known to be bad), or to avoid running the (fairly expensive) filter on a very long file or on each fold of a cross-validation. Note that a value of 0 here will in the case of offline data be interpreted as the entire file, and in the case of streaming data will raise an error.

    • verbose name: Initialize On This Time Range
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • emit_calib
    Whether and how to emit the calibration data, if the node is used in a streaming context. If set to dont-emit, then the calibration data will be swallowed by the node. If set to as-nonstreaming the calibration data will be emitted, but will be marked as non-streaming (offline) data, which can trigger special behavior on downstream nodes, e.g., causing them to calibrate themselves on this portion of the data only. If set to as-streaming, then the calibration data will appear like a regular, albeit long, streaming chunk. In this mode the node can be dropped into a stream pipeline with the least disruption, but some subsequent nodes could experience hiccups on the potentially minutes-long chunk.

    • verbose name: Emit Calib
    • default value: as-streaming
    • port type: EnumPort
    • value type: str (can be None)
  • denoise
    Whether to denoise the metric. If True, then the metric will be round-tripped through the optodes and back to channels.

    • verbose name: Denoise
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • optimizer
    Optimization methods to use. This will usually have little impact on the results, although compute times will differ, and all methods are prone to occasional spurious breakdown on some channels. The shgo method is fastest but can at times have limited accuracy. Dual_annealing is slower but more robust. Basinhopping is slowest. If you observe strange results (e.g., very large coupling lengths for some channels), this can be switched to another method to diagnose whether this resolves the issue.

    • verbose name: Optimizer
    • default value: shgo
    • port type: EnumPort
    • value type: str (can be None)
  • optimizer_maxiter
    Number of iterations to run the optimizer

    • verbose name: Optimizer Maxiter
    • default value: None
    • port type: IntPort
    • value type: int (can be None)
  • min_reliable_length
    Minimum channel length where the measure is assumed to be reliable. With some devices, very short channels can show erratic measures, e.g., due to direct light bridging. This threshold drops those data points from the quality analysis.

    • verbose name: Min Reliable Length
    • default value: 15
    • port type: FloatPort
    • value type: float (can be None)
  • max_reliable_length
    Maximum channel length where the measure is assumed to be useful. Data points beyond that are dropped since we assume that the quality is essentially flatlining past this point.

    • verbose name: Max Reliable Length
    • default value: 60
    • port type: FloatPort
    • value type: float (can be None)
  • min_intensity
    Minimum intensity that a channel needs to have to be retained.

    • verbose name: Min Intensity
    • default value: 0
    • port type: FloatPort
    • value type: float (can be None)
  • backend
    Compute backend to use for the non-CoV metrics. The torch backend is fastest for large numbers of channels but requires a compatible GPU. The tf backend can run on the CPU but is currently considerably slower.

    • verbose name: Backend
    • default value: torch
    • port type: EnumPort
    • value type: str (can be None)
  • precision
    Numeric precision to use. Typically, 32-bit should be sufficient, but 64-bit mode is available to check if precision issues impact results.

    • verbose name: Precision
    • default value: 32-bit
    • port type: EnumPort
    • value type: str (can be None)
  • analysis_band
    Frequency band of interest. The quality metric will be computed with respect to the signal in this band. This should ideally be a fairly narrow band, since otherwise the range of the raw internal measures will be off. If you have a task with very slow changes (e.g., long task durations), you could consider lowering one or both band edges (but test the effect on some data).

    • verbose name: Analysis Band
    • default value: [0.015, 0.025, 0.05, 0.08]
    • port type: ListPort
    • value type: list (can be None)
  • cov_huber
    Huber parameter for robust covariance estimation. Only used if covariance is not provided. If this is set to None, the covariance is is estimated non-robustly. If set to 0, the geometric median is used. Otherwise, the value is used as the relative Huber t threshold (larger values are less robust but more statistically efficient of the data segment is short).

    • verbose name: Cov Huber
    • default value: 0.75
    • port type: FloatPort
    • value type: float (can be None)
  • cov_windowlen
    Window length for robust covariance calculation. This will catch artifacts at time scales of this duration or shorter.

    • verbose name: Cov Windowlen
    • default value: 10
    • port type: FloatPort
    • value type: float (can be None)
  • robust_measure
    Use robust estimation for the rMAE measure. If the data contain artifacts, the non-robust measure will appear artificially more forgiving than justified by the data.

    • verbose name: Robust Measure
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • block_size
    Block size for parallel computation. If you run out of memory, you can use a smaller value here.

    • verbose name: Block Size
    • default value: 30
    • port type: IntPort
    • value type: int (can be None)
  • num_procs
    Number of processes for fitting. This is only used if denoise is enabled.

    • verbose name: Num Procs
    • default value: None
    • port type: IntPort
    • value type: int (can be None)
  • debug_plots
    Debug plots to generate. One can include 'quality' in this list to enable a debug quality plot (in a very ad hoc coordinate system). Adding 'save' causes the figure to be saved in the current working directory. Adding 'noshow' will suppress the figure pop-up window.

    • verbose name: Debug Plots
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • verbose
    Print verbose output.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

BadChannelRemovalNIRSSCI

Remove channels with low scalp coupling correlation from NIRS signals.

This node uses between-channel correlations to identify bad channels. This method requires optical densities and uses both wavelengths per channel to calculate the correlation coefficient between the two. Before computing correlation coefficients the optical densities should first be band-pass filtered (FIR) to avoid systematic factors such as cardiac and Mayer waves. Changing the filter settings can greatly impact the resulting correlations. Currently, this node is for offline use only. The SCI metric is based on Pollonini et. al. 2016. Info: https://github.com/lpollonini/phoebe

Version 0.0.3

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • diagnostic_chn
    Diagnostic information indicating the per-channel error measure.

    • verbose name: Diagnostic Chn
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: OUT
  • threshold
    Minimum scalp coupling index threshold per channel. This is a value between 0 and 1 (correlation coefficient). Both channels wavelengths in which the optodes are below threshold are removed.

    • verbose name: Threshold
    • default value: 0.7
    • port type: FloatPort
    • value type: float (can be None)
  • action
    Action to perform on bad channels. Remove means the channels will be dropped form the data, and mark_nan means that the data of bad channels will be replaced with NaN values (indicating missing data to downstream nodes that can handle it).

    • verbose name: Action
    • default value: remove
    • port type: EnumPort
    • value type: str (can be None)
  • axis
    Axis along which to filter. Rarely anything other than 'time' is used here.

    • verbose name: Filter Along Axis
    • default value: time
    • port type: ComboPort
    • value type: str (can be None)
  • order
    Filter order. If unspecified, this will be auto-determined based on the tightness of the transition bands and the desired stopband attenuation (using the Kaiser window rule). Note that high orders (e.g., 1000 or greater) will be fairly heavy on the CPU, especially with many channels.

    • verbose name: Filter Order
    • default value: None
    • port type: IntPort
    • value type: int (can be None)
  • frequencies
    Transition frequencies. For a lowpass/highpass filter, you can either give the cutoff frequency, or two frequencies to determine the rolloff curve. For a bandpass/bandstop filter, you can give two cutoff frequencies, or 4 frequencies to determine the rolloff curve. The syntax for 'freeform' filters is [(frequency1, gain1), (frequency2, gain2), ...], and you can use the special frequency value -1 as a stand-in for the highest frequency at which a filter can be designed for the given sampling rate (the signal's Nyquist frequency).

    • verbose name: Frequencies
    • default value: [0.4, 0.7, 1.5, 1.8]
    • port type: ListPort
    • value type: list (can be None)
  • mode
    Filter mode. Low/highpass lets low/high frequencies through, bandpass lets frequencies in a limited band through, and bandstop (a.k.a. notch) removes frequency in a limited band. The freeform mode (rarely used) can design arbitrary filters by specifying frequencies in the spectrum and corresponding desired gain factors.

    • verbose name: Filter Mode
    • default value: bandpass
    • port type: EnumPort
    • value type: str (can be None)
  • minimum_phase
    Design minimum-phase filter. If enabled, a filter with minimum signal delay will be designed, which will distort the signal phases, especially in the transition region. If disabled, a linear-phase filter will be designed, which will not distort the signal at all, but which incurs a delay of half the filter order in samples.

    • verbose name: Minimum Phase
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • antisymmetric
    Design antisymmetric filter. This designs rarely-used / special-purpose filters for signal differentiation or 90 degree phase shifting. Make sure you specify the order explicitly and choose and odd number if you use this.

    • verbose name: Antisymmetric
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • stop_atten
    Minimum attenuation in stopband. This is the minimum acceptable attenuation, in dB, in the stopband, which is ideally infinitely suppressed, but in practice 30-80 dB are enough, depending on the amplitudes of the signals to attenuate.

    • verbose name: Min Stopband Attenuation
    • default value: 45.0
    • port type: FloatPort
    • value type: float (can be None)
  • convolution_method
    FIRFilter coefficients can be convolved with the input signal using multiple methods. The standard method performs time-domain convolution. For long signals (>214 samples) using filters with a modest number of coefficients (>24), it can be faster to do the convolution in the frequency domain using the overlap-add method.

    • verbose name: Method Of Convolution
    • default value: standard
    • port type: EnumPort
    • value type: str (can be None)
  • cut_preringing
    Cut off the pre-ringing portion generated by the filter. This is currently only supported in linear-phase mode and offline.

    • verbose name: Cut Preringing
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • direction
    Filtering direction. This describes how information is propagated during the filter process. Forward means that an event (e.g., a spike) will result in a ripple that follows the event. Forward-backward means that the ripple will propagate in both directions, and will be symmetric around the event, but this results in effects preceding their causes, which can be problematic when performing causality analysis and is not replicable in real time. Gap-aware filtering additionally respects data boundaries (e.g., where bad time windows have been cut out) and does not propagate information across them.

    • verbose name: Filtering Direction
    • default value: forward
    • port type: EnumPort
    • value type: str (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

BaselinePCA

Perform Baseline PCA artifact removal.

This node calculates a PCA decomposition on some given baseline data (e.g., resting state, or any data not affected by evoked responses and/or task-related activity). Using this decomposition, the task data (data input) are then broken down into components, and the top num_components components are removed from the data. In effect, this will find components with large- amplitude (likely artifactual) activity on the baseline periods, thus resulting in components that are unlikely to include any task-related activity, and these components are then removed from the on-task data.

Version 0.1.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • baseline
    Baseline data.

    • verbose name: Baseline
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: IN
  • num_components
    Number of principal components to remove.

    • verbose name: Num Components
    • default value: 1
    • port type: IntPort
    • value type: int (can be None)
  • demean
    Whether to zero-mean the data and baseline beforehand. The mean will be re-added to the data afterwards.

    • verbose name: Demean
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • detrend
    Whether to detrend the data and baseline beforehand.

    • verbose name: Detrend
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

CBSI

Apply the Correlation-Based Signal Improvement method to enhance the HbO/HbR contrast and downweight artifacts.

This node is applied after concentrations have been estimated, and after a wide bandpass filter that retains 0.01 Hz to 0.5 Hz. This filter is meant to be run on continuous data. Therefore, it should not be preceded by a Segmentation node. This node maintains internal state.

Version 0.5.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • window_length
    Length of statistics window. This is the window length over which the standard deviation of the signal is tracked (online).

    • verbose name: Window Length
    • default value: 30
    • port type: FloatPort
    • value type: float (can be None)
  • simulate_online
    Simulate online processing even if data is available offline.

    • verbose name: Simulate Online
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

ConcentrationsToOpticalDensity

Infer NIRS (delta-)optical density from chormophore (HbO, HbR) concentration changes.

This node implements the reverse process of the EstimateConcentrations node, and is therefore less frequently used. One use case is to work backwards from concentration data to optical density at different wavelengths in order to then image the optical density using tomographic imaging methods such as HD-DOT. This node uses the modified Beer-Lambert Law (MBLL) which relies on the fact that the different chromophores have different light absorption spectra. The calculation depends on a number of parameters, notably the differential pathlength factor and the partial volume correction, which can be looked up from textbooks. Both of these are configurable as parameters to this node. Incorrect assumptions will mostly result in incorrect scaling of the estimated optical density changes.

Version 0.5.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • dpf
    Differential Pathlength Factor (DPF). This is a factor, often between 4-9, which relates optical pathlength through some tissue (e.g., bone, skin, brain) to the distance between optodes.

    • verbose name: Differential Pathlength Factor
    • default value: 6
    • port type: FloatPort
    • value type: float (can be None)
  • pvc
    Partial Volume Correction (PVC). A correction term that quantifies what fraction of the optical path is subject to concentration changes -- for fNIRS this is typically on the other of 40-90. The DPF is divided by the PVC to yield the Partial Pathlength Factor (PPF), which is often loosely around 0.1.

    • verbose name: Partial Volume Correction
    • default value: 60
    • port type: FloatPort
    • value type: float (can be None)
  • wavelengths
    List of NIRS wavelengths at which to estimate concentrations. Given in nanometers.

    • verbose name: Wavelengths
    • default value: []
    • port type: ListPort
    • value type: list (can be None)
  • coords_unit
    Unit of the channel positions. Typically this would be m for meters, but some data may have it wrong.

    • verbose name: Coordinates Unit
    • default value: m
    • port type: EnumPort
    • value type: str (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

EstimateConcentrations

Estimate chromophore concentrations (HbO, HbR) from delta-optical density (OD) at multiple wavelengths.

This uses the modified Beer-Lambert Law (MBLL) which relies on the fact that the different chromophores have different light absorption spectra. This calculation depends on a number of parameters, notably the differential pathlength factor and the partial volume correction, both of which can be set as parameters of this node. The value ranges to use can be looked up from textbooks. Incorrect assumptions will mostly result in incorrect scaling of the estimated concentrations (or their changes).

Version 0.9.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • dpf
    Differential Pathlength Factor (DPF). This is a factor, often between 4-9, which relates optical pathlength through some tissue (e.g., bone, skin, brain) to the distance between optodes.

    • verbose name: Differential Pathlength Factor
    • default value: 6
    • port type: FloatPort
    • value type: float (can be None)
  • pvc
    Partial Volume Correction (PVC). A correction term that quantifies what fraction of the optical path is subject to concentration changes -- for fNIRS this is typically on the other of 40-90. The DPF is divided by the PVC to yield the Partial Pathlength Factor (PPF), which is often loosely around 0.1.

    • verbose name: Partial Volume Correction
    • default value: 60
    • port type: FloatPort
    • value type: float (can be None)
  • chromophores
    List of chromophores for which to estimate quantities.

    • verbose name: Chromophores
    • default value: ['HbO', 'HbR']
    • port type: SubsetPort
    • value type: list (can be None)
  • coords_unit
    Unit of the channel positions. Typically this would be m for meters, but some data may have it wrong.

    • verbose name: Coordinates Unit
    • default value: m
    • port type: EnumPort
    • value type: str (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

GroupChannelsByWavelength

Group channels into groups by wavelength.

Channels with the same source detector but differing in wavelength are grouped, indicated by a Feature axis (with the wavelength as the name). Expects a packet with space and time axes as well as .positions, .positions_source, .wavelengths. Reshapes the signal data tensor from 2D space x time to 3D (space / num wavelengths) x feature x time. Adds a Feature axis with a row for each wavelength, named with the wavelength + nm, i.e. '760nm'.

Version 0.7.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

HDDOT

Transform fNIRS optical densities into brain mesh images using optical tomography.

This can use a pre-computed Jacobian that is matched to a specific NIRS montage or it will re-compute the Jacobian using toast++ finite element solver to simulate light propagation through the head, and then uses the inverse model to calculate magnitudes at the cortical surface.

Version 0.3.1

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • headmodel
    Head model file to use (.h m or .mshs). If omitted, the node checks if the data has a current head model associated with it, e.g., because a previous node has annotated it, and then uses that head model. If a relative path is given, the file is searched in the resources/headmodels folder of the cpe.

    • verbose name: Head Model File
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • save_jacobian_path
    Path (including filename) to save computed Jacobian.

    • verbose name: Save Jacobian Path
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • load_jacobian_path
    Path (including filename) to an existing Jacobian file if available. If file doesn't exist or isn't compatible it will be recomputed

    • verbose name: Load Jacobian Path
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • basis
    Dimensions of mesh rasterization grid. Maps between the unstructured FEM and a regular pixel/voxel grid used for reconstruction.

    • verbose name: Basis
    • default value: [30, 30, 30]
    • port type: ListPort
    • value type: list (can be None)
  • fine_basis
    Dimensions of intermediate mesh rasterization grid.

    • verbose name: Fine Basis
    • default value: [60, 60, 60]
    • port type: ListPort
    • value type: list (can be None)
  • refraction_index
    Always 1.3 in DOTHUB

    • verbose name: Refraction Index
    • default value: 1.3
    • port type: FloatPort
    • value type: float (can be None)
  • jtype
    Solver to use.

    • verbose name: Jtype
    • default value: bicgstab
    • port type: EnumPort
    • value type: str (can be None)
  • jtol
    Convergence tolerance

    • verbose name: Jtol
    • default value: 1e-12
    • port type: FloatPort
    • value type: float (can be None)
  • regularizer_params
    Regularization proportion.

    • verbose name: Regularizer Params
    • default value: [0.01]
    • port type: ListPort
    • value type: list (can be None)
  • channel_pattern
    Channel pattern naming using a regex pattern. This is a search pattern used to associate source and detector pairs along with their respective wavelength value. Regex pattern must include '' for the source IDs and '' for the detector IDs, '' can optionally be used for wavelength value if that is specified in the channel names, otherwise if '' is excluded in the regex pattern it will require wavelength values are stored in the space axis 'units' array with the same length as the number of channel names. Default regex pattern expects channel names in format example 'S01-D02-680' (e.g. Source ID#1 connected to Detector ID#2 with wavelength 680 nm.

    • verbose name: Channel Pattern
    • default value: S(?P\d)-D(?P\d)-(?P\d*)
    • port type: StringPort
    • value type: str (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

IntensityToOpticalDensity

Convert light intensity to delta-optical density (OD).

This node performs a simple conversion of light intensity as measured by an fNIRS system to the dimensionless quantity delta Optical Density, which does not depend on the unit or scale of the intensity measure. Optical Density can be thought to quantify the degree to which the medium between source and detector absorbs light. The delta refers to the fact that the optical density is here being calculated with respect to, not the true incoming light intensity, but a somewhat arbitrary proxy, which is here the average intensity for the recording. So it is the difference in optical density with respect to the average state of the channel. The delta-OD, simply referred to as OD, can be used to calculate chromophore concentration changes (e.g., HbO, HbR, HbT) relative to the average concentration, using the node EstimateConcentrations.

Version 1.0.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • adapt_online
    Whether to update the mean on streaming data. This will incrementally re-estimate the mean over the whole data, including any calibration data.

    • verbose name: Adapt Online
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • trim_proportion
    Proportion of lowest/highest values to ignore in robust trimmed mean. This can be set to 0 to use the regular mean (textbook fNIRS approach), 0.5 to use the median, or in between to achieve robustness to a proportion of abnormally high/low data values. This currently applies to offline processing only.

    • verbose name: Trim Proportion
    • default value: 0.1
    • port type: FloatPort
    • value type: float (can be None)
  • bias
    Optional numerical bias value. This is to prevent division by zero or logarithm of zero. By default no bias is applied.

    • verbose name: Numerical Bias
    • default value: 1e-07
    • port type: FloatPort
    • value type: float (can be None)
  • unreferenced
    Output unreferenced measure. If this is checked, the optical density will not be relative to the average intensity, but instead the offset will remain uncorrected. One case where this can make sense is during online processing, if the subsequent modeling stage can account for an arbitrary signal offset.

    • verbose name: Unreferenced
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • ensure_nonnegative
    Ensure that the incoming intensity data is non-negative. Typically that should not be the case, but some operations (like resampling) can create small sways into the negative range.

    • verbose name: Ensure Nonnegative
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • round_digits
    Round result to this many digits after the decimal point. This can be used to obtain numerically identical results on different processor architectures despite the logarithm being implemented potentially differently.

    • verbose name: Round Digits
    • default value: None
    • port type: IntPort
    • value type: int (can be None)
  • keep_intensity
    Keep the intensity stream in the output.

    • verbose name: Keep Intensity
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

OptodeAttribution

Attribute channel measures to optodes.

This node accepts channel NIRS data, and factorizes it into per-optode measures. This can be used to work out overall light transmission through an optode, or optode contact fidelity, for instance.

Version 0.1.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • combiner
    Method for to combine multiple readings for an optode into a single value.

    • verbose name: Combiner
    • default value: mean
    • port type: EnumPort
    • value type: str (can be None)
  • transform
    How to transform the data prior to factorization. These are mainly useful to attribute measures where there is no obviously right relationship between channels and optodes, such as different quality or noise scores.

    • verbose name: Transform
    • default value: None
    • port type: EnumPort
    • value type: str (can be None)
  • beta
    Bias for very small signal values.

    • verbose name: Beta
    • default value: 0.0
    • port type: FloatPort
    • value type: float (can be None)
  • length_falloff_exponent
    Exponent for the falloff function. This is used to correct for differences in channel length.

    • verbose name: Length Falloff Exponent
    • default value: 2
    • port type: FloatPort
    • value type: float (can be None)
  • factorization
    Optional data factorization. None will simply consider all channels associated with an optode. The other two can be used in combination with num_components to keep only the dominant latent between-optode factors in the data, while cutting off noise on individual channels.

    • verbose name: Factorization
    • default value: None
    • port type: EnumPort
    • value type: str (can be None)
  • num_components
    Number of components to consider, if factorization is used.

    • verbose name: Num Components
    • default value: 1
    • port type: IntPort
    • value type: int (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

SeparateChannelsByDistance

Calculate the distance between channels and either remove or place into a separate chunk channels which fall either below or above the threshold.

This is useful for either separating short channels into a separate chunk, or separating and/or dropping/removing channels which are considered too long to be included in the analysis.

Version 1.2.1

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • stream
    Stream(s) on which to perform this action. Leave empty to perform on all qualifying streams, that is, all streams which have a space axis and both .positions and .positions_source values. Wildcards are supported, i.e. mystream* will select the streams whose name starts with mystream.

    • verbose name: Stream
    • default value: None
    • port type: StringPort
    • value type: str (can be None)
  • threshold
    Distance threshold, in mm. Channels which have a distance either above or below this threshold, depending on the value of the 'greater or less' parameter, will be separated and either placed into a separate chunk or removed.

    • verbose name: Threshold
    • default value: 15
    • port type: FloatPort
    • value type: float (can be None)
  • reference_locs
    Set of reference locations from which to calculate the distance. If not given, then the source-detector distance will be computed.

    • verbose name: Reference Locs
    • default value: None
    • port type: ListPort
    • value type: list (can be None)
  • reference_geom
    Type of geometry for which the distance to the reference locations shall be computed. This only applies if reference_locs is given. Position uses the regular ("detector") position, source uses the source position, line-segment is the straight line between source and detector position, midpoint the midpoint of that line. For backwards compatibility only, ray and its alias line use the (infinitely long) ray connecting the two. Optical-midpoint calculates the midpoint displaced towards the head center in accordance with the (rough) photon path, where the displacement is proportional to the channel length (scaled by optical_depth_scale). Banana represents a quadratic 'banana'-shaped photon path that passes through the optical modpoint.

    • verbose name: Reference Geom
    • default value: position
    • port type: EnumPort
    • value type: str (can be None)
  • unit
    Unit in which the distance threshold is specified.

    • verbose name: Threshold Unit
    • default value: mm
    • port type: EnumPort
    • value type: str (can be None)
  • operator
    Comparison to use between distance and threshold. For example if <, the action is applied to channels that are less than the threshold. The ~ operator means approx. equal.

    • verbose name: Comparison Type
    • default value: <
    • port type: EnumPort
    • value type: str (can be None)
  • action
    Action to be taken on the selected channels. Move them into a new chunk (and remove from original chunk), or remove only (drop from the packet).

    • verbose name: Action
    • default value: move
    • port type: EnumPort
    • value type: str (can be None)
  • optical_depth_scale
    Optical depth scale for NIRS geometries. Applies to optical-midpoint and the banana geometries. Given as the max channel depth as a factor of channel length. Note that the default of 0.5 is exaggerated, whereas the physically plausible scale is around 0.2 for 20-40mm channel lengths.

    • verbose name: Optical Depth Scale
    • default value: 0.5
    • port type: FloatPort
    • value type: float (can be None)
  • depth_displacement
    Direction of depth displacement.

    • verbose name: Depth Displacement
    • default value: center
    • port type: EnumPort
    • value type: str (can be None)
  • new_chunk
    Optional name of the chunk into which the separated channels are placed if 'action' is set to 'move'. If unspecified, will be automatically derived from the old chunk name, operator, threshold, and unit (i.e., 'nirs<60mm'.

    • verbose name: New Chunk
    • default value: None
    • port type: StringPort
    • value type: str (can be None)
  • verbose
    Print verbose output.

    • verbose name: Verbose
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • debug_plot
    Enable debug/inspection plot. This will open a matplotlib window showing some inspection graphics. Currently only applies when reference_locs is given.

    • verbose name: Debug Plot
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • streams
    Deprecated. Use stream instead.

    • verbose name: Streams
    • default value: None
    • port type: ListPort
    • value type: list (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

SubtractDarkIntensity

Subtract dark intensity channels from intensity channels.

If the data have dark intensity channels, this will subtract those channels' activity from the regular NIRS intensity measures and optionally remove the dark intensity channels from the data (default=True). This node assumes that dark channels have positions set, but positions_source is set to NaN. Alternatively, the dark intensity channels can be passed into the 'dark' data port.

Version 1.0.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • dark
    Dark intensity data.

    • verbose name: Dark
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: OUT
  • remove_dark_channels
    Remove dark intensity channels.

    • verbose name: Remove Dark Channels
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • epsilon
    Allow no intensities lower than this.

    • verbose name: Epsilon
    • default value: 1e-08
    • port type: FloatPort
    • value type: float (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

TDDR

This node implements the TDDR method for fNIRS motion artifact reduction.

The method squashes jumps or sleep slopes in the data using Tukey's bisquare weight to score outliers. The online implementation has an approximately zero-mean output, while the offline implementation outputs the same mean as the original data (like the published method). Applying the node to concentration is recommended over applying to optical density, since the node could have unintended side effects on the concentration estimates otherwise. CAUTION: the method should be applied only to the low-frequency part of the data (typically below 0.5 Hz). For this, use a band-splitting filter prior to using this node (e.g., FIR Filter). For the offline case there is also the offline_prefilter option, which is a simple built-in filtering step. This filter is meant to be run on continuous data. That is, it should not be preceded by a Segmentation node.

Version 0.8.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • diagnostic
    Motion artifact diagnostics. Offline only.

    • verbose name: Diagnostic
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: OUT
  • stats_window
    Sliding window length, for online processing only. The node calculates statistics over a running window of this length (in seconds).

    • verbose name: Stats Window
    • default value: 300
    • port type: FloatPort
    • value type: float (can be None)
  • mean_window
    Effective window length of for mean tracking, online only. This is the halving time for an exponentially weighted window used to remove trends in the output (in seconds).

    • verbose name: Mean Window
    • default value: 20
    • port type: FloatPort
    • value type: float (can be None)
  • bisquare_constant
    Tuning constant of Tukey's Bisquare weight. The default of 4.685 has 95% statistical efficiency, and lower values of 4.00 and 3.55 have 90% and 85%, respectively.

    • verbose name: Bisquare Constant
    • default value: 4.685
    • port type: FloatPort
    • value type: float (can be None)
  • simulate_online
    Simulate online processing even if data is available offline.

    • verbose name: Simulate Online
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • maxiter
    Max number of iterations for IRLS procedure.

    • verbose name: Maxiter
    • default value: 50
    • port type: IntPort
    • value type: int (can be None)
  • reltol
    Relative trend error during IRLS optimization. Smaller values will take longer to estimate, but the trend will be estimated to a higher accuracy.

    • verbose name: Reltol
    • default value: 1e-05
    • port type: FloatPort
    • value type: float (can be None)
  • offline_prefilter
    Apply zero-phase Butterworth pre-filter (offline only). This is mostly for comparison with the published TDDR method.

    • verbose name: Offline Prefilter
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • diagnostic_threshold
    Threshold for the outlyingness score to calculate the fraction of samples above threshold diagnostic.

    • verbose name: Diagnostic Threshold
    • default value: 0.8
    • port type: FloatPort
    • value type: float (can be None)
  • use_caching
    Use caching.

    • verbose name: Use Caching
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)