rsHRF (Resting State HRF Estimation and Deconvolution) BIDS-App Documentation

Installation and Setup

This App can be used as a standalone Python Package OR as a BIDS-App through Docker.

Standalone Python Package (Command Line Interface)

To be used as a command line tool, ensure that you have Python>=3.6 and use the command pip3 install rsHRF. This command takes care of all the necessary dependencies so that the tool is usable straight out of the box. Once done, run rsHRF --help to see the required positional and optional arguments. The command line for the app installed in this way is rsHRF.

BIDS-App through Dockers (Command Line Interface)

To be used as a BIDS-App, ensure that you have docker installed. The image for the app needs to be pulled which can be done via the command docker pull bids/rshrf. The App can then be run by launching an instance / running a container of this image via the command docker run -ti --rm bids/rshrf followed by the options for the app.

Running rsHRF after installing as a Python Package OR running docker run -ti --rm bids/rshrf after pulling the image through docker are equivalent. Thus, rsHRF --help is similar to docker run -ti --rm bids/rshrf --help.

Graphical User Interface

To run the the application in a Graphical User Interface, run rsHRF --GUI. For more information regarding the GUI, click here.

Usage

In essence, the whole usage of the application can be broken down to 8 major steps:

The input:

There are 3 ways one can input data to this application.

A standalone .nii / .nii.gz or .gii / .gii.gz file. This option can be accessed using the --input_file optional argument followed by the path of the file.
A standalone .txt file. This option can be accessed using the --ts optional argument followed by the path of the file.
A BIDS formatted data-set directory. This option can be accessed using the --bids_dir optional argument followed by the path of the directory. This requires the input dataset to be in valid BIDS format, and have a derivatives type with preprocessed resting-state fMRI data. We highly recommend that you validate your dataset with the free, online BIDS Validator.

Out of the above 3 options, one of them is always required and more than one cannot be supplied at once.

The mask / atlas files:

Mask files are only provided along with the --input_file or bids_dir argument. There are 2 ways one can supply the corresponding mask / atlas files.

A standalone .nii / .nii.gz or .gii / .gii.gz file. This option can be accessed using the --atlas optional argument followed by the name of the file.
The --brainmask argument which tells the application that the mask files are present within the BIDS formatted data-set directory itself (which was supplied with --bids_dir).
Out of the above 2 options, both cannot be supplied at once. In the case where neither of the 2 options are supplied, the app proceeds to generate a mask by computing the variance, however, providing a mask-file is strongly recommended.
Also, --input_file and --brainmask together are an invalid combination.

The 5 use-cases are explained below:

--input_file : The standalone .nii / .nii.gz or .gii / .gii.gz file is passed to the application for the analysis, the mask gets generated by computing the variance, and the outputs are determined accordingly.
--ts : The standalone .txt file containing a time-series (floating point values separated by line breaks), or multiple time-series’ (, separated floating point values, where one time-series corresponds to a column). No mask file is required in this scenario, and the outputs are determined accordingly.
--input_file and --atlas : The standalone atlas and the standalone input_file are passed to the application for the analysis and the outputs are determined accordingly.
--bids_dir and --atlas : The standalone atlas is used with ALL the input files present in the bids_dir directory. Thus, the atlas serves as a common mask for the whole BIDS formatted data-set.
--bids_dir and --brainmask : This should be used when for each input file present in the BIDS formatted data-set, the corresponding mask file exists within the same data-set. The application then pairs the input_files with their corresponding masks provided that the 2 files share a common prefix.

The output directory:

The output directory is accessed using --output_dir, and is the folder under which all the resulting .nii / .gii / .mat / .png files will be stored. The application further makes folders for each of the participants / subjects if the input is supplied through the argument --bids_dir. In the case of --ts argument, all the output types are stored in the .mat file. It is mandatory to provide an output directory.

The Analysis Level:

There are 2 kinds of analysis that can be performed. This can be accessed using --analysis_level.

participant : participant level analysis performs the analysis for each (or some) subject(s) present in the BIDS formatted data-set. This is mandatory when the input is supplied with --bids_dir as group level analysis is not supported yet. This should not be supplied when input is supplied with --input_file argument. Doing so shall result in an error.
group : Coming Soon! - Use participant for now.

The Analysis Method:

The analysis can be carried out using 6 estimation methods.

These are canon2dd, gamma, fourier, hanning, sFIR and FIR.

One of them needs to be supplied using the --estimation argument followed by one of the above 3 choices.

The input parameters:

There are many input parameters that can be supplied to customize the analysis. Please see all of them under the Parameters heading under the documentation by running rsHRF --help.

The participant labels:

Specifying which subjects to perform the analysis on can be given as a space separated list after specifying the --participant_label argument. Only the valid subjects in the list (which are actually present in the BIDS directory) will be considered. The sub- prefix should not be supplied.

Select only certain BIDS files to be input to the BIDS-App:

Using the --bids_filter_file argument, you can pass the BIDS-App a JSON file that describes a custom BIDS filter for selecting files with PyBIDS, with the syntax {<query>: {<entity>: <filter>, ...},...}.

Queries can be defined for bold and/or mask in the .JSON file which allows the user to filter the BIDS-data to be input.

For example :

{
    'bold': {
     'datatype': 'func',
     'task': 'restingstate'
     'desc': 'preproc',
     'suffix': 'bold',
     'extension' : 'nii.gz'
     
     },
        'mask': {
     'datatype': 'func',
     'task': 'restingstate'
     'desc': 'brain',
     'suffix': 'mask',
     'extension': 'nii.gz'
     } 
}

The queries defined in this JSON file will filter the bold and mask data according to the defined entities. The mask query will only have an effect when the --brainmask argument is defined.

rsHRF-BIDS app uses the following queries, by default :

   'bold' : {'datatype':' func', 'suffix': 'bold', 'extension': 'nii.gz', 'desc': 'preproc', 'task': 'rest'}
   'mask' : {'datatype': 'func', 'suffix': 'mask', 'extension': 'nii.gz', 'desc': 'brain', 'task': 'rest'}

This means that the BIDS-App by default checks for bold or mask BIDS-data that has the following entities:

 bold : sub-<label>/func/sub<label>-task_rest-desc_preproc_bold.nii.gz
 mask : sub-<label>/func/sub<label>-task_rest-desc_brain_mask.nii.gz

Only modification of these queries will have any effect. You may filter on any entity defined in the PyBIDS config file and derivatives file

Example Use-Cases

Running the analysis with a single input file (.txt).

a) Through the Python Package

rsHRF --ts input_file.txt --estimation hanning --output_dir results -TR 2.0

b) Through the BIDS-App

docker run -ti --rm \
-v /path/to/input:/input:ro \
-v /path/to/output/directory/results:/results \
bids/rshrf --ts /input/input.txt --output_dir results --estimation hanning -TR 2.0

In the above example, the input file is a .txt file input_file.txt. The estimation method passed is hanning. The -TR argument (which represents the BOLD repetition time) needs to be supplied here.

Running the analysis with a single input file (.nii / .nii.gz or .gii / .gii.gz)

a) Through the Python Package

rsHRF --input_file input_file --estimation fourier --output_dir results.

b) Through the BIDS-App

docker run -ti --rm \
-v /path/to/input:/input:ro \
-v /path/to/output/directory/results:/results \
bids/rshrf --input_file /input/input_file  --estimation fourier --output_dir results

In the above example, the input_file can be a .nii/.nii.gz or .gii/ gii.gz image. The estimation method passed is fourier. The -TR argument (which represents the BOLD repetition time) needs to be supplied if a .gii/.gii.gz input file is used.

Running the analysis with a single input file and a single mask file.

a) Through the Python Package

rsHRF --input_file input_file --atlas mask_file --estimation canon2dd --output_dir results.

b) Through the BIDS-App

docker run -ti --rm \
-v /path/to/input:/input:ro \
-v /path/to/mask:/mask \
-v /path/to/output/directory/results:/results \
bids/rshrf --input_file /input/input_file --atlas /mask/mask_file --estimation canon2dd --output_dir results

In the above example, the input_file can be a .nii/.nii.gz or .gii/ gii.gz image. The output_dir is the results directory. The corresponding mask is the mask_file that should have a matching extension (.nii/.nii.gz or .gii/gii.gz) with the input_file. The estimation method passed is canon2dd. The analysis level is not to be supplied here. The -TR argument (which represents the BOLD repetition time) needs to be supplied if .gii / .gii.gz input file is used.

Running the analysis with a BIDS formatted data-set and a common mask file to be used for all the input files present in the data-set.

Note: By default all input files in the BIDS directory need to be of the type *_bold.nii or *_bold.nii.gz. Also, they must be present in the func directory under their respective subject / session folder.

a) Through the Python Package

rsHRF --bids_dir input_dir --output_dir results --analysis_level participant --atlas mask_file --estimation sFIR

b) Through the BIDS-App

docker run -ti --rm \
-v /path/to/bids_dir:/input_dir:ro \
-v /path/to/mask:/mask \
-v /path/to/output/directory/results:/results \
bids/rshrf --bids_dir input_dir --output_dir results --analysis_level participant --atlas mask/mask_file  --estimation sFIR

In the above example, the output_dir is results directory. The corresponding mask supplied is mask_file which should have the same extension as input files from the BIDS formatted data-set (.nii/.nii.gz). The BIDS formatted data-set lies in the input_dir directory. The analysis level is participant. The analysis will be performed for all subjects since no specific subjects are mentioned using --participant_label.

Running the analysis with a BIDS formatted data-set that also includes a unique mask file for each of the input file present.

Note: By default all input files in the BIDs directory need to have the suffix of the type *_bold.nii or *_bold.nii.gz. The corresponding mask files in the BIDs directory need to be of the type *_mask.nii or *_mask.nii.gz. Also, they must be present in the func directory under their respective subject / session folder. Furthermore, two corresponding input and mask files need to have the same prefix.

For example, 2 corresponding input and mask files according to BIDS format can be input_bold.nii and input_mask.nii. These 2 will then be paired up for analysis.

a) Through the Python Package

rsHRF --bids_dir input_dir --output_dir results --analysis_level participant --brainmask --estimation canon2dd --participant_label 001 002.

b) Through the BIDS-App

docker run -ti --rm \
-v /path/to/bids_dir:/input_dir:ro \
-v /path/to/output/directory/results:/results \
bids/rshrf --bids_dir input_dir --output_dir results --analysis_level participant --brainmask --estimation canon2dd --participant_label 001 002

In the above example, the output directory is results directory. The BIDS formatted data-set lies in the input_dir directory. The associated mask files also lie within the BIDS dataset. The analysis level is participant. The analysis is performed only for sub-001 & sub-002 out of all the available subjects in the BIDS dataset.

Running the analysis using BIDS-filter to input certain files to BIDS-App.

a) Through the Python Package

rsHRF --bids_dir input_dir --output_dir results --analysis_level participant --bids_filter_file bids_filter_file.json --brainmask --estimation canon2dd --participant_label 001 002.

b) Through the BIDS-App

docker run -ti --rm \
-v /path/to/bids_dir:/input_dir:ro \
-v /path/to/output/directory/results:/results \
-v /path/to/bids_filter/:/filter \
bids/rshrf --bids_dir input_dir --output_dir results --analysis_level participant --bids_filter_file /filter/bids_filter_file.json --brainmask --estimation canon2dd --participant_label 001 002

In the above example, the output directory is results directory. The BIDS formatted data-set lies in the input_dir directory. The associated mask files also lie within the BIDS dataset. The analysis level is participant. A custom bids_filter_file.json to filter the BIDS-data input to the BIDS-App. The analysis is performed only for sub-001 & sub-002 out of all the available subjects in the BIDS dataset.

rsHRF (Resting State HRF Estimation and Deconvolution) BIDS-App Documentation

Resting state HRF estimation from BOLD-fMRI signal