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 sure nibs ran correctly, but are not necessary to keep after you are reasonably confident nibs 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 parallelize nibs; 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 by ICA-AROMA.

  • The HRF model argument (--hrf-model) passes all the available options from nistats.