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. It also adds the wavelength to the .units property of each channel, which it extracts from the channel name. In addition to the coordinates themselves, 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.

Version 0.1.1

Ports/Properties

  • 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)
  • 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. This uses regex groups, with (?P\d) used to identify the source id, (?P\d) used to identify the detector id, and (?P\d) used to identify the wavelength. I.e., f(?P\d)_S(?P\d)D(?P\d) would match the channel name f770_S1D1.

    • verbose name: Channel Name Pattern
    • default value: None
    • port type: StringPort
    • value type: str (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

  • 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)
  • 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)
  • 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)

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

  • 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)
  • 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)
  • 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)

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

  • 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)
  • 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)

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

  • 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)
  • 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)

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. Incorrect assumptions will mostly result in incorrect scaling of the estimated optical density changes.

Version 0.5.0

Ports/Properties

  • 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)
  • 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)

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. 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. Incorrect assumptions will mostly result in incorrect scaling of the estimated concentrations (or their changes).

Version 0.8.0

Ports/Properties

  • 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)
  • 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)

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, .units (containing 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.

Version 0.7.0

Ports/Properties

  • 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)
  • 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

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.2.0

Ports/Properties

  • 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)
  • 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 'Src1-Dct2:680' (e.g. Source ID#1 connected to Detector ID#2 with wavelength 680 nm.

    • verbose name: Channel Pattern
    • default value: Src(?P\d)-Dct(?P\d):(?P\d*)
    • port type: StringPort
    • value type: str (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 can then be further processed 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

  • 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)
  • 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)

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

  • 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)
  • 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)

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

  • 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)
  • 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)

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

  • 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)
  • 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)

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

  • 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)
  • 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)