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.
data¶
Data to process.
diagnostic_chn¶
Diagnostic information indicating the per-channel error measure. Range 0 (best) to 1 (worst).
diagnostic_opt¶
Diagnostic information indicating the per-optode error measure (coupling length). Only available if denoise is enabled.
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.
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).
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).
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.
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.
denoise¶
Whether to denoise the metric. If True, then the metric will be round-tripped through the optodes and back to channels.
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.
optimizer_maxiter¶
Number of iterations to run the optimizer
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.
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.
min_intensity¶
Minimum intensity that a channel needs to have to be retained.
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.
precision¶
Numeric precision to use. Typically, 32-bit should be sufficient, but 64-bit mode is available to check if precision issues impact results.
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).
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).
cov_windowlen¶
Window length for robust covariance calculation. This will catch artifacts at time scales of this duration or shorter.
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.
block_size¶
Block size for parallel computation. If you run out of memory, you can use a smaller value here.
num_procs¶
Number of processes for fitting. This is only used if denoise is enabled.
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¶
Print verbose output.
set_breakpoint¶
Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.
metadata¶
User-definable meta-data associated with the node. Usually reserved for technical purposes.