Usage¶
Command-Line Arguments¶
NiBetaSeries BIDS arguments
usage: nibs [-h] [-v] -a ATLAS_IMG -l ATLAS_LUT [-sm SMOOTHING_KERNEL]
[-lp LOW_PASS] [-c CONFOUNDS [CONFOUNDS ...]]
[--hrf-model {glover,spm,fir,glover + derivative,glover + derivative + dispersion,spm + derivative,spm + derivative + dispersion}]
[-w WORK_DIR]
[--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
[--session-label SESSION_LABEL] [-t TASK_LABEL]
[--run-label RUN_LABEL] [-sp {MNI152NLin2009cAsym}]
[--variant-label VARIANT_LABEL] [--exclude-variant-label]
[--nthreads NTHREADS] [--use-plugin USE_PLUGIN] [--graph]
bids_dir derivatives_pipeline output_dir {participant,group}
Positional Arguments¶
- bids_dir
The directory with the input dataset formatted according to the BIDS standard.
- derivatives_pipeline
The pipeline that contains minimally preprocessed img, brainmask, and confounds.tsv
- output_dir
The directory where the output directory and files should be stored. If you are running group level analysis this folder should be prepopulated with the results of theparticipant level analysis.
- analysis_level
Possible choices: participant, group
Level of the analysis that will be performed Multiple participant level analyses can be run independently (in parallel) using the same output_dir
Named Arguments¶
- -v, --version
show program’s version number and exit
- --participant-label
The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“). If this parameter is not provided all subjects should be analyzed. Multiple participants can be specified with a space separated list.
Required Atlas Arguments¶
- -a, --atlas-img
input atlas nifti where each voxel within a “region” is labeled with the same integer and there is a unique integer associated with each region of interest. THIS OPTION IS REQUIRED.
- -l, --atlas-lut
atlas look up table (tsv) formatted with the columns: index, regions which correspond to the regions in the nifti file specified by –atlas-img. THIS OPTION IS REQUIRED.
Options for processing¶
- -sm, --smoothing-kernel
select a smoothing kernel (mm)
- -lp, --low-pass
low pass filter (Hz)
- -c, --confounds
The confound column names that are to be included in nuisance regression. write the confounds you wish to include separated by a space
- --hrf-model
Possible choices: glover, spm, fir, glover + derivative, glover + derivative + dispersion, spm + derivative, spm + derivative + dispersion
convolve your regressors with one of the following hemodynamic response functions
- -w, --work-dir
directory where temporary files are stored (i.e. non-essential files). This directory can be deleted once you are reasonably certain nibs finished as expected.
Options for selecting images¶
- --session-label
select a session to analyze
- -t, --task-label
select a specific task to be processed
- --run-label
select a run to analyze
- -sp, --space-label
Possible choices: MNI152NLin2009cAsym
select a bold derivative in a specific space to be used
- --variant-label
select a variant bold to process
- --exclude-variant-label
exclude the variant from FMRIPREP
Options to handle performance¶
- --nthreads, -n-cpus
maximum number of threads across all processes
- --use-plugin
nipype plugin configuration file
misc options¶
- --graph
generates a graph png of the workflow
Example Call(s)¶
If you want to see a full example on preparing data and running nibs
, see:
Running NiBetaSeries.
Example 1¶
nibs \
/home/james/bids/ \
fmriprep \
/home/james/bids/derivatives/betaSeries/schaefer_parcel-400_network-17 \
participant
-a /home/james/bids/derivatives/atlas/Schaefer2018_400Parcels_17Networks_order_FSLMNI152_2mm.nii.gz \
-l /home/james/bids/derivatives/atlas/schaefer_parcel-400_network-17.tsv \
-w /home/james/bids/derivatives/betaSeries/work_n17 \
-c WhiteMatter CSF Cosine01 Cosine02 Cosine03 Cosine04 Cosine05 Cosine06 Cosine07 \
--nthreads 32 \
--variant AROMAnonaggr \
--hrf-model 'glover + derivative + dispersion'
In this example we have our top-level BIDS directory /home/james/bids
,
and our derivatives directory /home/james/bids/derivatives
.
nibs
currently assumes that derivatives
is immediately underneath
the top-level BIDS directory.
The 1st positional argument is the BIDS directory (
/home/james/bids
)The 2nd positional argument is the derivatives pipeline that was used to preprocess your data. In this case we are using
fmriprep
.The 3rd positional argument determines where the desired output of
nibs
should go. These are the output files you will use later on for analysis. Here, the directory is:/home/james/bids/derivatives/betaSeries/schaefer_parcel-400_network-17
The 4th positional argument specifies whether we are running participant- or group-level analyses; since group-level analyses are not yet implemented,
participant
is the only option.Within the derivatives directory, we have the atlas (
-a
) and lookup table (-l
) in an atlas directory. The atlas is in MNI space and the look up table has a row per unique parcel in the atlas.The work directory (
-w
) specifies where all the intermediate outputs go; these are useful for making surenibs
ran correctly, but are not necessary to keep after you are reasonably confidentnibs
worked as expected.The confounds (
-c
) we select are column names from the*_confounds.tsv
file. See the fmriprep documentation on confounds for details.--nthreads
tells us across how many thread to parallelizenibs
; in this example we use 32 threads!If there were multiple types of derivatives output from a preprocessing application (like
fmriprep
), you may only be interested in analyzing one variant; in this scenerio, we are only interested in analyzing images denoised byICA-AROMA
.The HRF model argument (
--hrf-model
) passes all the available options from nistats.