From 0268251435f6a42248aa4ea38a07774c88395c0e Mon Sep 17 00:00:00 2001 From: tyler Date: Wed, 22 Apr 2026 15:45:37 -0700 Subject: [PATCH] added a lot for analysis options --- Home.md | 186 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 185 insertions(+), 1 deletion(-) diff --git a/Home.md b/Home.md index e044774..a94d0a7 100644 --- a/Home.md +++ b/Home.md @@ -97,4 +97,188 @@ When performing a fNIRS analysis, these parameters are some of the most importan Information about the individual parameters can be found by chicking the "?" icon next to the respective parameter. There are more popups and menus that will appear after the analysis has completed. They will be discussed further down in the Analysis section. # Performing an Analysis # -Now that the app layout is understood, perfomring an analysis is simple. To start, open a file or a folder from the Navigation Bar. Once the file/files are loaded, ensure that the per-file and global parameters are correct for the study. Once you are satisfied with the parameters, click the "Process" button to start processing the files. This processing step will take some time, however you can validate progression visually by looking at the progress bars of the files in the [Loaded Files](https://git.research.dezeeuw.ca/tyler/flares/wiki/Home#loaded-files) area. \ No newline at end of file +Now that the app layout is understood, perfomring an analysis is simple. To start, open a file or a folder from the Navigation Bar. Once the file/files are loaded, ensure that the per-file and global parameters are correct for the study. Once you are satisfied with the parameters, click the "Process" button to start processing the files. This processing step will take some time, however you can validate progression visually by looking at the progress bars of the files in the [Loaded Files](https://git.research.dezeeuw.ca/tyler/flares/wiki/Home#loaded-files) area. + + + + + +## **Preprocessing** +Loads the snirf files into memory and will downsample the file. 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): True if downsampling should occur, False if no downsampling should occur. +- DOWNSAMPLE_FREQUENCY (int): Frequency in Hz to downsample the SNIRF to. If this value is set higher than the input frequency, data will be repeated. + +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): True if trimming should occur, False if no trimming should occur. +- SECONDS_TO_KEEP (int): Number of seconds before the first event occurs to keep to ensure the file is not starting exactly at the first event. + +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): True if the image should be generated, False if the image should not be generated. +- SHOW_OPTODE_NAMES (bool): True if optode names should be applied on the image, False if optode names should not be applied on the image. + +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 two optodes. 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 designed and user preferences. 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. +Note: FLARES currently only guarantees support for one short channel. If your design has multiple short channels, raise a feature request on the git page. +### Parameters +- SHORT_CHANNEL (bool): True if the data has a short channel, False if the data does not have a short channel. +- SHORT_CHANNEL_THRESH (float): Maximum distance the short channel can be in metres. +- LONG_CHANNEL_THRESH (float): Maximum distance a channel can be in metres before it is removed. + +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): True if the heart rate should be identified, False if the heart rate should not be identified. +- SECONDS_TO_STRIP_HR (int): 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): 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): 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): Number of unique datapoints to be averaged into a single data point to create a smoother heart rate. +- HEART_RATE_WINDOW (int): Purely for visualization. Will create an estimation window ± this value for the BPM calculation. + +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): True if SCI should be calculated, False if SCI should not be calculated. +- SCI_TIME_WINDOW (int): Value in seconds to evaluate the signal over repeatedly. +- SCI_THRESHOLD (float): 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. + +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): True if SNR should be calculated, False if SNR should not be calculated. +- SNR_THRESHOLD (float): Any value >=0, where 0 is extreme noise. + +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): True if PSP should be calculated, False if PSP should not be calculated. +- PSP_TIME_WINDOW (int): Value in seconds to evaluate the signal over repeatedly. +- PSP_THRESHOLD (float): 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 + +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): True if CV should be calculated, False if CV should not be calculated. +- CV_THRESHOLD (int): 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. + +If CV is set to False, CV_THRESHOLD will be ignored. + +## Mean 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): True if MAD should be calculated, False if MAD should not be calculated. +- MAD_THRESHOLD (int): Any value >=0, where 0 is no deviations. A good threshold value would be <=4. + +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): True if PSD Noise should be calculated, False if PSD Noise should not be calculated. +- TARGET_FREQ_DIV (int): 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): What value the PSD has to be below when the target frequency is encountered. + +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): True if channel variance should be calculated, False if channel variance should not be calculated. +- CHANNEL_THRESH (float): Value between 0 and 1 representing how much variance to require. A good threshold value would be >=0.05. + +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): How the bad channels should be dealt with. +- MAX_DIST (float): Maximum distance to look for potential neighbours to interpolate from in meters. +- MIN_NEIGHBOURS (int): Minimum number of neighbours inside the distance threshold required to interpolate from. +- MAX_BAD_CHANNLES (int): 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. + +If BAD_CHANNELS_HANDLING is not set to “Interpolate”, MAX_DIST and MIN_NEIGHBOURS will be ignored. +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 here at . 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 here at . +### Parameters +- TDDR (bool): 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 +Description coming soon. +### Parameters +- WAVELET (bool): 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): Inter-Quartile Range +- WAVELET_TYPE (list): What type of wavelet filter to use. See the “?” on this parameter in the application to get a complete list of valid values. +- WAVELET_LEVEL (int): Wavelet decomposition level. Must be a value >= 0. + +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 here at . 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 here at . +### Parameters +- ENHANCE_NEGATIVE_CORRELATION (bool): 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): 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): Low cutoff frequency. Any frequencies lower than this value will be removed. +- H_FREQ (float): High cutoff frequency. Any frequencies higher than this value will be removed. +- L_TRANS_BANDWIDTH (float): How wide the transitional period should be on the lower end. +- H_TRANS_BANDWITH (float): How wide the transitional period should be on the higher end. + +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. Better description coming soon. +## Epoch Calculations +Performs various epoch calculations from the data. Can handle epochs with “shift” or “strict”. Better description coming soon. +### Parameters +- EPOCH_HANDLING (list): How the epochs should be handled if two or more occur at the exact same time. +- MAX_SHIFT (int): 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): Seconds before the epoch to be used. +- T_MAX (int): Seconds after the epoch to be used. + +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”. Better description coming soon. +### Parameters +- RESAMPLE (bool): 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): Frequency in Hz to downsample to. +- HRF_MODEL (list): What HRF model to use. See the “?” on this parameter in the application to get a complete list of valid values. +- STIM_DUR (float): Length of the stimulus for a block design HRF model, otherwise how wide a bin should be in seconds. +- DRIFT_MODEL (list): What type of drift model should be used. +- HIGH_PASS (float): High pass frequency in Hz in case of a cosine drift model. +- DRIFT_ORDER (int): Order of the drift model in case of a polynomial drift model. +- FIR_DELAYS (range): Number of bins in case of the HRF_MODEL being “fir”. +- MIN_ONSET (int): Minimal onset in seconds relative to frame times. +- OVERSAMPLING (int): Oversampling factor used in temporal convolutions. +- REMOVE_EVENTS (list): Remove events matching the names provided before generating the design matrix. +- SHORT_CHANNEL_REGRESSION (bool): 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 in the data. + +Lots of unique combinations of parameters being used or not being used - see the application for more information. +## 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 can be set to any integer value by modifying the value of n, so you can use ar5 for a fifth order model. +### Parameters +- NOISE_MODEL (str): Temporal variance model. +- BINS (int): The maximum number of discrete bins for the AR coef. histogram/clustering. +- N_JOBS (int): 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): 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): 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): 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 around 2GB of RAM. +- VERBOSITY (bool): 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. +