tyler/flares
2
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 18 Wiki Activity
Page: Home
Pages
Home
Clone
25
Home
tyler edited this page 2026-04-22 16:07:24 -07:00
Table of Contents

Welcome to the Wiki for FLARES (fNIRS Lightweight, Analysis, Research, & Evaluation Suite). Here will be the home of all the information that you will need to use this software.

Getting Started

In order to use FLARES, you will need a device with the following hardware specifications:

  • OS: Windows 10/11 (64-Bit), Ubuntu 22.04/24.04 (64-Bit), MacOS Ventura/Sonoma/Sequoia/Tahoe (x64/ARM64) or newer
  • Processor: Intel Core i7 Skylake, Ryzen 7 2nd Gen, Apple M1 or newer
  • Memory: 16 GB RAM or more
  • Storage: 4 GB available space

Download the appropriate version from the Releases tab and extract the zip file once it has completed downloading. Once the folder has been extractes, run the "flares" executable. The first launch of FLARES will take some time, so please be patient. FLARES will automatically check and download available updates every time the application starts. If you do not want FLARES to perform this action, you can block the app in your devices firewall or set your internet options to be a metered connection.

Getting used to FLARES

Once FLARES opens, you will be greeted with many options on the screen. To remain simple this guide will break down what is visible on the screen into four sections:

  • Navigation Bar (Top of screen)
  • File Information (Top left area)
  • Loaded files (Bottom left area)
  • Parameters (Right area)

These names will be reused throughout the Wiki to refer to content in these physical locations.

Navigation Bar

The navigation bar stores most of the actions that you will want to use. There are 5 buttons availabe and all of them have submenus. Here is a high level overview of the buttons and what they do:

  • File
    • Open File... - Opens a singular file into the application
    • Open Folder... - Opens all files in a singular folder into the application
    • Load Project... - Loads an existing saved project created by FLARES
    • Save Project... - Saves all loaded files, parameters, and results into a single file that can be opened at a later time by FLARES
    • Save Project As... - Same as above, but asks for the destination to save the project every time
    • Exit - Exits the application
  • Edit
    • Cut - Cuts the highlighted text
    • Copy - Copies the highlighted text
    • Paste - Pastes text from the clipboard
  • View
    • Toggle Status Bar - Turns on or off visibility of text notifications at the bottom of the application
  • Options
    • User Guide - Opens a pop-up window containing some information about processing stages
    • Check for updates... - Checks the Git repository for any available updates. If an update is found, it is downloaded and extracted automatically
    • Update optodes in snirf file... - See Updating Optodes in SNIRF File
    • Update events in snirf file... - See Updating Events in SNIRF File
  • Terminal
    • New Terminal... - Opens a text based terminal

File Information

This area is designated to providing information about a singular file. Once a file has been opened and selected from the Loaded files area, generic information will be visible. This includes:

  • File name
  • File size
  • Creation date
  • Modifies date
  • Full file path

On top of this generic information, there is also some data that is unique to SNIRF files:

  • Measurement date
  • Short channels (this is a guess based on distance)
  • Source-Detector distances
  • Digitization points
  • Annotations

This information panel is purely for validation purposes, and it is not possible to change any of the values from this area. There is three parameters that do get added when a file is selected that can be changed. None of these values need to be set for the analysis to function. These parameters are:

  • Age - Used to calculate the DPF of the participant. If Age is not specified, the value will be set to 25
  • Gender - Used as a filter option to filter results at the end of the analysis. Not currently implemented.
  • Group - Used as a filter option to filter results at the end of the analysis.. If Group is not specified, the value will be set to "Default"

Loaded files

When files are loaded either from opening a singular file or opening a whole folder, all valid files will be shown in this area, along with a progress bar. Clicking on a file will bring up its information in the File Information area and allow for changes to the participants Age, Gender, and Group. When the analysis is running, the progress bar will update based on how far the participant has been processed. Right clicking the file will bring up two buttons:

  • Reveal - Opens a file browser to the location that this file is stored on disk
  • Remove - Unloads and removes the file, preventing it from being processed. This does not modify the file on disk. If the participant is removes after an analysis, their data will be still included in the analysis. To get data without this file, the analysis will have to be run again

The analysis will finish when all progress bars have completed. If the analysis completes and a progress bar has not finished, then something went wrong processing that file. Checking the logs could provide insight into what went wrong.

Parameters

When performing a fNIRS analysis, these parameters are some of the most important settings and it is crucial that they are correct for the study that is being performed. FLARES exposes most of the parameters needed for an analysis allowing for immense customizability. These parameters have been broken down into subcategories in an attempt to keep them simple. These parameters are also shown in the order that they will be applied, and logical values have been applied by default. Below is a list of the submenus:

Information about the individual parameters can be found by chicking the "?" icon next to the respective parameter, or below in the Performing an Analysis section. There are more popups and menus that will appear after the analysis has completed. They will be discussed further down.

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 area. Below is every parameter and what actions they perform.

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.

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.

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): 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.