Advanced Usage

In this example we demonstrate the more advanced usage of fNIRS Apps. See the introductory tutorial for an overview of how to use these apps. In this example we will conduct the same analysis as in the tutorial, but demonstrate how this can be automated, such as may be conducted on a server or in a more complex analysis pipeline.

Boutiques

This example utilises the boutiques framework. Boutiques is a descriptive command-line framework automating analysis. It allows you to specify the app you wish to run and the parameters you wish to use. Boutiques will validate your parameters before running the app, minimising the risk of error. All fNIRS Apps are registered with boutiques

You can use the bosh tool from boutiques to search for and list all fNIRS apps by using the command:

bosh search 'fNIRS Apps'

which will return something like…

[ INFO ] Showing 4 of 4 result(s), exluding 0 deprecated result(s).

ID              TITLE                             DESCRIPTION                                
zenodo.5112758  fNIRS Apps: Sourcedata to BIDS    Create fNIRS BIDS datasets from source d...
zenodo.5112722  fNIRS Apps: Scalp Coupling Index  Compute Scalp Coupling Index and mark BI...
zenodo.5112773  fNIRS Apps: Quality Reports       Generate quality reports for fNIRS data    
zenodo.5113225  fNIRS Apps: GLM Pipeline          A GLM pipeline for fNIRS data

which includes the app ID (which is automatically updated each time a new version is release), the app names, and brief description. As new fNIRS Apps are added, they will appear both on this website and automatically when using the bosh tool.

Usage

To run an fNIRS App using the bosh tool you must provide:

  1. the app id (as shown above)
  2. a configuration file in json format that contains the arguments to the app (See below)
  3. the path to the data (as specified in introductory tutorial).

Configuration file

Each app has a number of configuration options. For example, the threshold value for scalp coupling index, or the sample rate of the analysis. The configuration options are listed on the web page of each app. For the Sourcedata to BIDS app, the introductory tutorial specified the task label, stimulus duration, and trigger names as command line options. Passing many command line options can get lengthy and cause issues, instead we can specify these options in a json file (perhaps stored as 01-raw-data-to-bids.json):

{
    "input_datasets": "/bids_dataset",
    "task_label": "tapping",
    "duration": 5,
    "events": "{\"1\":\"Control\", \"2\":\"Tapping/Left\", \"3\":\"Tapping/Right\"}"
}

When using bosh we specify the input dataset location as the same path as specifed below, usually this is always `/bids_dataset``.

Putting it all together

Now that we have the app ID and the configuration file we can run the app using bosh:

bosh exec launch zenodo.5112758 01-raw-data-to-bids.json -v /path/to/data:/bids_dataset

which will first validate the arguments you provided and make sure they are suitable for the specified app, it will then pull the correct version of the app for you, run the app with the dataset you provide, and print out a report.

More information

An example of how to run an entire analysis pipeline using bosh and fNIRS Apps can be found in the nirs-apps-demo GitHub page. This demo runs for apps in sequence to perform a complete analysis pipleline, from raw data to group level GLM statistical analysis. The demo provides example configuration files to:

  1. Convert the raw data to a BIDS dataset (configuration file)
  2. Calculate the scalp coupling index for each channel and mark channels with SCI<0.7 as bad (configuration file)
  3. Generate a data quality report for each file (configuration file)
  4. Execute a GLM analysis on the dataset, including a group level mixed effects analysis (configuration file)

All of these steps are also run automatically each time an app is updated to ensure nothing is broken using the GitHub actions framework. You can view the complete analysis and output on the GitHub page.