Table of Contents

Understanding Parameters

Preprocessing
Trimming
Verify Optode Placement
Short/Long Channels
Heart Rate
Scalp Coupling Index
Signal to Noise Ratio
Peak Spectral Power
Coefficient of Variation
Median Absolute Deviation
Power Spectral Density Noise
Channel Variance
Bad Channels Handling
Optical Density
Temporal Derivative Distribution Repair filtering
Wavelet filtering
Haemoglobin Concentration
Enhance Negative Correlation
Filtering
Extracting Events
Epoch Calculations
Design Matrix
General Linear Model
Finishing Touches
Other

What's Next

Understanding Parameters

This page is dedicated to understanding the parameters inside the Parameter section on the right of the screen. If you haven't already, visit the Home Page before following along with this guide.

All parameters discussed in this Wiki page are global parameters. This means that every snirf file loaded will have the same parameters applied to them. If you think a parameter should be on a per file basis (such as Age, Gender, Group) and not on a global basis, raise a feature request along with an explaination as to why you think it should be on a per file basis.

Good to know information before reading this Wiki page includes a brief understanding of data types to ensure that the correct values are inserted. Here is a short explaination of data types that FLARES uses:

bool - A boolean data type. This includes True or False, but can be represented by a 1 (True) or a 0 (False).
int - An integer data type. This includes whole numbers without fractions or decimals (-23, 5, 0, 10).
float - A floating point data type. This includes numbers that contain fractions or decimals (-23.0, 4.12, 22.8)
list - A list data type. For FLARES, all lists will be available in a dropdown. It is only required that one item in the list be selected.
range - A range data type. For FLARES, all ranges will be present as an int,
str - A string data type. This includes any character or gouping of characters (hello, 5t6y7, this is a string!).

Any parameter that has been changed from its default value will appear with blue text and bolded.

Preprocessing

Loads the snirf files into memory and will downsample the file if requested. Downsampling can be beneficial to speed up processing times on underpowered devices, or if dense temporal resolution is not required for the study being performed.

Parameters:

DOWNSAMPLE (bool, default=True): True if downsampling should occur, False if no downsampling should occur.
DOWNSAMPLE_FREQUENCY (int, default=25): Frequency in Hz to downsample the snirf file to. If this value is set higher than the input frequency, data will be repeated.

Note: If DOWNSAMPLE is set to False, DOWNSAMPLE_FREQUENCY will be ignored.

Trimming

Reads annotations in the snirf file and throws away all data prior to n number of seconds before the first event, where n is the number of requested seconds prior to the first event to keep. This is useful if the fNIRS recording was started a tangible amount of time before any event in the study occurred, as this data will not be valuable and will consume more memory by keeping it loaded.

Parameters:

TRIM (bool, default=True): True if trimming should occur, False if no trimming should occur.
SECONDS_TO_KEEP (float, default=5.0): Number of seconds before the first event occurs to keep to ensure the start of the file is not starting exactly at the first event.

Note: If TRIM is set to False, SECONDS_TO_KEEP will be ignored.

Verify Optode Placement

Generates an image showing where the optodes were located. This is an important validation step to ensure that the correct coordinate space has been used, or in the case of some systems, to ensure the data present is not 2D. There is no noticeable performance impact to generating this image. There is also an option to render the optode names onto the image for further validation.

Parameters:

OPTODE_PLACEMENT (bool, default=True): True if the image should be generated, False if the image should not be generated.
SHOW_OPTODE_NAMES (bool, default=True): True if optode names should be applied on the image, False if optode names should not be applied on the image.

Note: If OPTODE_PLACEMENT is set to False, SHOW_OPTODE_NAMES will be ignored.

Short/Long Channels

Identifies both short and long channels. A channel is the inter-optode distance between a source (transmitter) and detector (receiver) optode. Different fNIRS caps will vary in spatial resolution, and as such the requirements for what constitutes a short or long channel will vary depending on the hardware design and/or user preference. If your design has a short channel included, you will need to use this method. If a channel is longer than the allowable distance, it will be removed entirely. If a short channel is requested but no channels are found below the set threshold, the processing of the participant will fail.

Parameters:

SHORT_CHANNEL (bool, deafult=True): True if the data has a short channel, False if the data does not have a short channel.
SHORT_CHANNEL_THRESH (float, default=0.015): Maximum distance the short channel can be in metres.
LONG_CHANNEL_THRESH (float, default=0.045): Maximum distance a channel can be in metres before it is removed.

Note: If SHORT_CHANNEL is set to False, SHORT_CHANNEL_THRESH & SHORT_CHANNEL_REGRESSION will be ignored.

Heart Rate

Identifies the heart rate of the participant. Heart rate in fNIRS is considered noise, and as such it is important to identify it and regress it out. Underneath, two methods of calculating heart rate from two different scientific libraries are used in an attempt to get more accurate results. There are options to strips a couple of seconds from the start and end of the file to ensure that the heart rate calculation does not see potential spikes from a cap being placed after recording started or removed before recording ended. Because the calculations for heart rate can spike over time, there are parameters set to encapsulate the heart rate into an acceptable minimum and maximum value. Each individual data point calculation for heart rate will be averaged into a window defined by a user parameter to provide a smoother result.

Parameters:

HEART_RATE (bool, default=True): True if the heart rate should be identified, False if the heart rate should not be identified.
SECONDS_TO_STRIP_HR (int, default=5): How many seconds to remove at the start and end of the file for the heart rate calculation to eliminate artifacts from cap placement or removal.
MAX_LOW_HR (int, default=40): Minimum value in BPM the heart rate can be for an individual data point. Any values lower than this will be capped to this value.
MAX_HIGH_HR (int, default=200): Maximum value in BPM the heart rate can be for an individual data point. Any values higher than this will be capped to this value.
SMOOTHING_WINDOW_HR (int, default=100): Number of unique datapoints to be averaged into a single data point to create a smoother heart rate.
HEART_RATE_WINDOW (int, default=25): Purely for visualization. Will create an estimation window ± this value for the BPM calculation.

Note: If HEART_RATE is set to false, SECONDS_TO_STRIP_HR, MAX_LOW_HR, MAX_HIGH_HR, SMOOTHING_WINDOW_HR, & HEART_RATE_WINDOW will be ignored.

Scalp Coupling Index

Calculates the scalp coupling index of the participant over multiple time windows, and will report a pass or fail for each channel and time window based on a user defined threshold. The scalp coupling index is an important quality metric that calculates the quality of the connection between the participants scalp and the fNIRS cap. This process is documented better here at . The time windows start at time 0, and if the end of the file is not a complete window, the SCI is simply calculated over the remaining time. If the entire channel averaged across all windows do not meet the threshold value, then the channel will be marked as a bad channel.

Parameters:

SCI (bool, default=True): True if SCI should be calculated, False if SCI should not be calculated.
SCI_TIME_WINDOW (int, default=3): Value in seconds to evaluate the signal over repeatedly.
SCI_THRESHOLD (float, default=0.6): Value between 0-1 where 1 is perfect coupling and 0 is poor coupling. A good threshold value would be at least over 0.5.

Note: If SCI is set to False, SCI_TIME_WINDOW & SCI_THRESHOLD will be ignored.

Signal to Noise Ratio

Calculates the signal to noise ratio, and will report a pass or fail for each channel based on a user defined threshold. The signal to noise ratio is an important quality metric that calculates how much of the observed signal was noise versus how much of it was a useful signal. This process is documented better here at . There is no concrete value at which there is minimal noise, with different individuals reporting varying thresholding values. If the entire channel does not meet the threshold value, then the channel will be marked as a bad channel.

Parameters:

SNR (bool, default=True): True if SNR should be calculated, False if SNR should not be calculated.
SNR_THRESHOLD (float, default=5.0): Any value >=0, where 0 is considered extreme noise.

Note: If SNR is set to false, SNR_THRESHOLD will be ignored.

Peak Spectral Power

Calculates the peak spectral power of the participant over multiple time windows, and will report a pass or fail for each channel and window based on a user defined threshold. The peak spectral power is an important quality metric that calculates the amplitude or strength of a frequency component that is most prominent in a particular frequency range or spectrum. This process is documented better here at . The time windows start at time 0, and if the end of the file is not a complete window, the PSP is simply calculated over the remaining time. If the entire channel averaged across all windows do not meet the threshold value, then the channel will be marked as a bad channel.

Parameters:

PSP (bool, default=True): True if PSP should be calculated, False if PSP should not be calculated.
PSP_TIME_WINDOW (int, default=3): Value in seconds to evaluate the signal over repeatedly.
PSP_THRESHOLD (float, default=0.1): Value between 0-1 where 1 is perfect spectral power and 0 is poor spectral power. A good threshold value would be at least over 0.1

Note: If PSP is set to False, PSP_TIME_WINDOW & SCI_THRESHOLD will be ignored.

Coefficient of Variation

Calculates the coefficient of variance of the participant. This quality metric is a way to measure the "relative noise" of a signal. If the entire channel averaged does not remain under the threshold value, then the channel will be marked as a bad channel.

Parameters:

CV (bool, default=True): True if the Coefficient of Variation should be calculated, False if the Coefficient of Variation should not be calculated.
CV_THRESHOLD (int, default=20): Value between 0-100 representing a percentage, where 0 is an extremely steady signal and 100 is a massively fluctuating signal. A good threshold value would be under 25.

Note: If CV is set to False, CV_THRESHOLD will be ignored.

Median Absolute Deviation

Calculates the mean absolute deviation of the participant. This quality metric identifies outliers based on how much their signal swings compared to all other channels. If the entire channel averaged does not remain under the threshold value, then the channel will be marked as a bad channel.

Parameters:

MAD (bool, default=True): True if the Median Absolute Deviation should be calculated, False if the Median Absolute Deviation should not be calculated.
MAD_THRESHOLD (int, default=4): Any value >=0, where 0 is no deviations. A good threshold value would be <=4.

Note: If MAD is set to False, MAD_THRESHOLD will be ignored.

Power Spectral Density Noise

Calculates how much noise is present in the power spectral density. This quality metric checks for higher frequency noises that should not be present at a certain frequency threshold which is likely indicative of electronic noise. If the channel does not remain under the threshold value after the target frequency, then the channel will be marked as a bad channel.

Parameters:

PSD_NOISE (bool, default=True): True if PSD Noise should be calculated, False if PSD Noise should not be calculated.
TARGET_FREQ_DIV (int, default=4): Target frequency divisor to examine. If the SNIRF file is at 25Hz and this value is set to 4, the frequency to examine would be 6.25. Not recommended to divide by a big number, as then you will likely be looking at meaningful data.
DB_LIMIT (int, default=-60): What value the PSD has to be below when the target frequency is encountered.

Note: If PSD_NOISE is set to False, TARGET_FREQ_DIV & DB_LIMIT will be ignored.

Channel Variance

Calculates how much a channel varied throughout the experiment. This quality metric will examine the variance of the first 25% of the recording to the last 25% of the recording and compares the variance between them. If there is low variance, it is likely that the sensor was dislodged at some point during the experiment. If the variance does not meet the threshold value, then the channel will be marked as a bad channel.

Parameters:

CHANNEL_VAR (bool, default=True): True if channel variance should be calculated, False if channel variance should not be calculated.
CHANNEL_THRESH (float, default=0.05): Value between 0 and 1 representing how much variance to require. A good threshold value would be >=0.05.

Note: If CHANNEL_VAR is set to False, CHANNEL_THRESH will be ignored.

Bad Channels Handling

Determines what to do with channels that were marked as bad in the previous quality steps. There are three options to choose from - “Interpolate”, “Remove”, or “None”. Interpolate will utilize the closest channels to the bad channel and interpolate what the bad channels signal should have been and generate a signal from them. This requires a minimum number of neighbours and the maximum distance a neighbour can be away from the bad channel in metres. If there are not enough neighbours located inside the distance threshold, the offending channel will be unmarked as bad and continue on as if the handling was set to None. Remove will simply drop the channels from memory. None will unflag all the bad channels, and continue as if they are good channels. If bad channels are being removed, an option to completely eliminate a participant is present if they do not meet a specified threshold.

Parameters:

BAD_CHANNELS_HANDLING (list, default=Interpolate): How the bad channels should be dealt with.
MAX_DIST (float, default=0.03): Maximum distance to look for potential neighbours to interpolate from in meters.
MIN_NEIGHBOURS (int, default=2): Minimum number of neighbours inside the distance threshold required to interpolate from.
MAX_BAD_CHANNLES (int, default=12): Maximum number of bad channels a participant can have before they are eliminated. This considers hbO and hbR as separate channels, and this value is exclusive.

Note: If BAD_CHANNELS_HANDLING is not set to “Interpolate”, MAX_DIST and MIN_NEIGHBOURS will be ignored. Note: If BAD_CHANNELS_HANDLING is not set to “Remove”, MAX_BAD_CHANNELS will be ignored.

Optical Density

Calculates the optical density of the data. This process is documented better at this link. This process is self contained and is required step, so it does not contain any user exposed parameters.

Temporal Derivative Distribution Repair filtering

Calculates and applies temporal derivative distribution repair filtering to the data. This is a method that removes baseline shift and spike artifacts from the data. This process is documented better at this link.

Parameters:

TDDR (bool, default=True): True if TDDR should be calculated and applied to the data, False if TDDR should not be calculated and applied to the data.

Wavelet filtering

TBD.

Parameters:

WAVELET (bool, default=True): True if a wavelet filter should be applied to the data, False if a wavelet filter should not be applied to the data.
IQR (float, default=1.5): Inter-Quartile Range
WAVELET_TYPE (str, default=db4): What type of wavelet filter to use. See the “?” button on this parameter in the application to get a complete list of valid values.
WAVELET_LEVEL (int, default=3): Wavelet decomposition level. Must be a value >= 0.

Note: If WAVELET is set to False, IQR, WAVELET_TYPE, & WAVELET_LEVEL will be ignored.

Haemoglobin Concentration

Calculates the haemoglobin concentration of the data. This process is documented better at this link. This process is self contained and is required step, so it does not contain any user exposed parameters.

Enhance Negative Correlation

Calculates and applies enhanced negative correlation to the data. This is a signal improvement algorithm that is based on the negative correlation between oxygenated and deoxygenated hemoglobin dynamics. This process is documented better at this link.

Parameters:

ENHANCE_NEGATIVE_CORRELATION (bool, default=False): True if enhanced negative correlation should be calculated and applied to the data, False if enhanced negative correlation should not be calculated and applied to the data.

Filtering

Calculates and applies a bandpass filter to the data based on user defined thresholds on the low frequency end and the high frequency end. A lower frequency value will remove more active signals, as a value of 0.005 is 200 times a second, whereas a value of 0.25 is 4 times a second. Both ends have a transitional period to allow for smooth transitions into the bandpass filter.

Parameters:

FILTER (bool, default=True): True if a bandpass filter should be applied to the data, False if a bandpass filter should not be applied to the data.
L_FREQ (float, default=0.005): Low cutoff frequency. Any frequencies lower than this value will be removed.
H_FREQ (float, default=0.03): High cutoff frequency. Any frequencies higher than this value will be removed.
L_TRANS_BANDWIDTH (float, default=0.002): How wide the transitional period should be on the lower end.
H_TRANS_BANDWITH (float, default=0.002): How wide the transitional period should be on the higher end.

Note: If FILTER is set to False, L_FREQ, H_FREQ, L_TRANS_BANDWITH, & H_TRANS_BANDWITH will be ignored.

Extracting Events

Extracts events from the data. This step currently does not expose any user defined parameters, but may in the future. TBD.

Epoch Calculations

Performs various epoch calculations from the data. Can handle epochs with “shift” or “strict”. TBD.

Parameters:

EPOCH_HANDLING (list, default=shift): How the epochs should be handled if two or more occur at the exact same time.
MAX_SHIFT (int, default=5): Number of indexes to look ahead and see if there is a valid index to shift an event to. If no valid indexes are found in this threshold, will treat the event as “strict”. Recommended to keep this value very low to not shift an event far from when it actually occurred.
T_MIN (int, default=-5): Seconds before the epoch to be used.
T_MAX (int, default=15): Seconds after the epoch to be used.

Note: If EPOCH_HANDLING is not set to “shift”, MAX_SHIFT will be ignored.

Design Matrix

Generates a design matrix from the data. DRIFT_MODEL can be “cosine” or “polynomial”. TBD.

Parameters:

RESAMPLE (bool, default=True): True if the data should be resampled before generating the design matrix, False if the data should not be resampled before generating the design matrix.
RESAMPLE_FREQ (int, default=1): Frequency in Hz to downsample to.
HRF_MODEL (list, default=fir): What HRF model to use. See the “?” on this parameter in the application to get a complete list of valid values.
STIM_DUR (float, default=0.5): Length of the stimulus for a block design HRF model, otherwise how wide a bin should be in seconds.
DRIFT_MODEL (list, default=cosine): What type of drift model should be used.
HIGH_PASS (float, default=0.01): High pass frequency in Hz in case of a cosine drift model.
DRIFT_ORDER (int, default=1): Order of the drift model in case of a polynomial drift model.
FIR_DELAYS (range, default=15): Number of bins in case of the HRF_MODEL being “fir”.
MIN_ONSET (int, default=-24): Minimal onset in seconds relative to frame times.
OVERSAMPLING (int, default=50): Oversampling factor used in temporal convolutions.
REMOVE_EVENTS (list, default=?): Remove events matching the names provided before generating the design matrix.
SHORT_CHANNEL_REGRESSION (bool, default=True): True if short channel regression should be used when creating the design matrix, False if short channel regression should not be used when creating the design matrix. Requires a short channel to be present in the data of all participants.

Lots of unique combinations of parameters being used or not being used - see the application for more information. TBD.

General Linear Model

Uses the previously generated design matrix to make a first level general linear model. The general linear model creation itself is required step and can not be omitted. There are multiple different noise models that can be used, and it currently will default to a first order auto regressive model 'ar1'. The AR model (arn) can be set to any integer value by modifying the value of n, so a valid model could be ar5 for a fifth order model.

Parameters:

NOISE_MODEL (str, default=ar1): Temporal variance model.
BINS (int, default=0): The maximum number of discrete bins for the AR coef. histogram/clustering.
N_JOBS (int, default=1): The number of CPUs to use to do the GLM computation. While -1 signifies 'all CPUs', it has been found that limiting this to a single CPU ends up being faster on higher end devices.

Finishing Touches

This stage just involves some under-the-hood calculations that will be used for further analysis. This process is self contained and is required step, so it does not contain any user exposed parameters.

Other

Section that contains other variables that can be important but do not affect the analysis in any shape or form.

Parameters:

TIME_WINDOW_START (int, default=0): Starting value for the x-axis of an image that will only be generated if HRF_MODEL is set to “fir”. Will be deprecated in the future in preference of generating the bounds automatically.
TIME_WINDOW_END (int, default=15): Ending value for the x-axis of an image that will only be generated if HRF_MODEL is set to “fir”. Will be deprecated in the future in preference of generating the bounds automatically.
MAX_WORKERS (int, default=6): How many SNIRF files can be processed simultaneously. More powerful devices can specify a higher value, but must have both the CPU and RAM available. It is estimated that an individual participant will require a peak of around 2GB of RAM. Will allow for the value of 'auto' in the future.
VERBOSITY (bool, default=False): True if the log file should contain more details, False if the log file should only contain minimal details. Should be set to True when raising an issue with the application to provide helpful information to the developer.

What's Next

Congratulations! You now understand what each parameter does and hopefully have an idea of the best values for your study. See the Processing & Analysis Wiki page to continue your journey.

FLARES is distributed under the GPL-3.0 license.