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:
- the app id (as shown above)
- a configuration file in json format that contains the arguments to the app (See below)
- 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:
- Convert the raw data to a BIDS dataset (configuration file)
- Calculate the scalp coupling index for each channel and mark channels with SCI<0.7 as bad (configuration file)
- Generate a data quality report for each file (configuration file)
- 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.