← nirs package

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

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)

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)