Description

Generates a signal quality report for fNIRS data file(s), including a wide range of quality related metrics on both the raw signal (intensity) and computed optical density and HbO/HbR. Currently supports .nirs and .xdf file formats. If an input path resolving to multiple files is passed, a report with the averages of all files will be generated in addition to a quality report for each individual session.

Report sections

This pipeline generates a report in HTML format that contains the following:

• File Information
• Data Quality Measures
  • Instrumentation artifacts
    • Flatline Channels (topoplots)
    • Saturating channels (topoplots)
    • Channel correlation (topoplots)
  • Motion artifacts
    • Motion susceptibility index (relative units) (topoplots)
    • Motion susceptibility index (absolute units) (topoplots)
    • Motion susceptibility index (above threshold) (topoplots)
    • Motion artifact profile (line plot)
  • Neural effects
    • HbO/HbR anti-correlation (relative units) (topoplots)
    • HbO/HbR anti-correlation (absolute units) (topoplots)
    • Signal-to-Noise Ratio (topoplots)
    • Signal-to-Noise Ratio (z-score) (topoplots)
  • Raw intensity (by wavelength)
    • Coefficient of Variation (intensity %) (topoplots)
    • Relative Intensity (Z-score) (topoplots)
    • Mean to Noise Ratio (intensity, dB) (topoplots)

References

PARAMETERS

Category: Input

This pipeline expects one file (or a Path Iterator formatted path name) and its path is relative to your Neuroscale account storage bucket. (The easiest way to run it is to go to your Storage page, select the file, click the Task button which will take you to the Create Task page, and then select this pipeline. The filename will be filed in automatically.)

input path

The path to the file to be processed (see above).

device

Devices for which custom preset settings will apply. Select 'Default' if the device from which the data was recorded is not listed here.

nirs stream

The name of the NIRS stream if not the default ('nirs').

marker stream

The name of the marker/event stream if not identified as an event stream.

channel range

Channels to import and process, expressed as a 0-base range (2:66 will import channels 3 through 66, '15:' selects channel 16 onward, ':25' selects the first 25 channels). If empty or ':', all channels are selected. If a known device is selected in the 'device' parameter and this 'channel_range' parameter is empty, a preset number of channels for that device will be selected.

rename channels

Rename channels using a regex pattern. This is a list with two strings, one containing the search pattern and the other containing the replace pattern. In the replace pattern using a double backslash \ to indicate the group number, i.e., \1.

device info

A dictionary of metadata specific to a particular device and cap. At present this is required for LUMO devices. The dictionary should include the following keys: cap_id (string), group_id (string), and montage (either a JSON object or a path to a .json file). For example, cap_id and group_id are both strings, and montage can be a JSON object or a file path. If the cap_id is registered with Neuropype, the group_id and montage can be skipped.

probe locations

If the probe location coordinates are not recorded in the data file itself for each channel, this information can be passed in here as a dictionary. The dictionary should include the following keys: 'sources' (a list of [x, y, z] coordinates), 'detectors' (a list of [x, y, z] coordinates), and 'landmarks' (a dictionary with keys like 'Nz' and values as [x, y, z] coordinates). Optionally, the dictionary can also contain a 'channel_name_pattern' key with a regex string with 3 named groups to extract the source probe id, detector probe id, and wavelength from each channel name (to match against the locations). For example, the pattern 'f(?P<wl>\d*)_S(?P<src>\d*)D(?P<dct>\d*)' would match a channel name like 'f770_S1D1'.

stim conditions

For files in .nirs format only: Provide a list of the stim conditions for the dataset as a dictionary. Each entry should have:

• A condition index (integer, matching the column number of the condition in the stim matrix, starting with 1)
• A condition name (string descriptor of the stim)
• A duration (decimal number in seconds)

For example, you might have a condition index of 1 with the name 'left' and duration 10.0, and a condition index of 2 with the name 'right' and duration 10.0.

Matching 'start' and 'end' markers will be inserted into the data in the format: condition_name-duration-start, condition_name-duration-end (e.g., 'left-10.0-start', 'left-10.0-end'). If no conditions are provided, only a stim onset marker will be added as a string of the condition index (e.g., '1').

Category: Preprocessing

decimate data

Reduce the volume of data by this factor. A factor of 2 will remove every other sample, effectively cutting the sampling rate in half and reducing the size of the data. Only needed for data with an unnecessarily high sampling rate in order to save compute time/resources.

baseline pca

Do baseline PCA on the optical density data as part of the preprocessing. If enabled the baseline start and end markers must be specified in 'baseline_markers'.

short channel threshold

Drop channels with a source-detector distance below than this value (in mm). Set to 0 to allow all short channels.

long channel threshold

Drop channels with a source-detector distance greater than this value (in mm). Set to 0 to allow all long channels.

highpass cutoff

Frequency cutoff (lower bound) for highpass filter. Leave empty to skip highpass filter. Use a two value list to specify the rolloff.

lowpass cutoff

Frequency cutoff (upper bound) for lowpass filter. Leave empty to skip lowpass filter. Use a two value list to specify the rolloff.

remove bad channels

Remove bad channels when computing quality. The report will more closely reflect the quality of the data during standard preprocessing when bad channels would typically be removed. Leave False to show the quality of the raw data (the most common case.)

regress short channels

Remove bad channels when computing quality. The report will more closely reflect the quality of the data during standard preprocessing when bad channels would typically be removed. Leave False to show the quality of the raw data (the most common case.)

detrend

Detrend the data as a preprocessing step.

tddr

Apply TDDR as a preprocessing step.

Category: Output

The pipeline will automatically generate a .html report into the same path as the input file using an appropriate tag to indicate the type of report that was run. There are additional optional outputs one can choose to save out.

group by cluster

Group channels by cluster of source/detectors to reduce the channel count. (Currently only applicable if 'lumo' device is selected.

group reports only

If multiple file paths are passed to the pipeline a group report is automatically generated in addition to an individual report for each file. Setting this to true only outputs the group report and not the individual reports.

probe scale

Scale of the probe circles and lines drawn in the plots. If empty or 0, this will be automatically set for a known device selected in the 'device' parameter or a default of 0.5 will be used. For other cases, the dots and lines can be made smaller or larger by setting a value smaller or greater than 0.5 (between 0 and 1).

Category: Curation

segments to drop

A list of pairs of markers between which data will be dropped before computing quality metrics, such as breaks or baseline data. Use the following format: [['baseline-begin', 'baseline-end'], ['break-begin', 'break-end']].

baseline markers

A pair of markers used to indicate baseline data. This is used to remove the baseline from the data using PCA if Baseline_PCA is selected as part of the preprocessing. Example: ['baseline-begin', 'baseline-end'].

trim ends

Trim data at both ends before processing. Use this to drop a certain number of seconds of data from the beginning or the end (i.e., when adjusting or taking off device) that should not be taken into account when computing data quality. This should be a list of two numbers, the first represents the start trim position from the beginning, in seconds, while the second should be a negative number indicating the end trim position from the end of the data, also in seconds. Example: [30, -30] will trim the first and last 30 seconds of data, whereas [30, 0] will trim only the first 30 seconds of data.

event markers

A dictionary of pairs of onset event markers and event duration (in seconds). This is optional and is used for computing SNR on optical density data and the explained variance measures. Use the 'event_markers_format' parameter to specify the format used for the marker strings (such as wildcards or regex). For example, you might have a key like 'condition-left' with a value of 3 (seconds), and another key 'condition-right' with a value of 3 (seconds).

event markers format

The format used to specify the event markers in the 'event_markers' parameter.

Category: Curation

mayer band

Frequency range for Mayer waves.

respiration band

Frequency range for respiration effects.

cardiac band

Frequency range for cardiac cycle.

correlate streams

Additional streams used to calculate variance explained measures.

skip explained variance metrics

Skip the variance explained quality metrics. These can require significant compute resources depending on the size of your file.

skip channel correlation metric

Skip the channel correlation metric (can require significant compute resources depending on the size of your file).