Usage

Command-Line Arguments

NiBetaSeries BIDS arguments

usage: nibs [-h] [-v] [-a ATLAS_IMG] [-l ATLAS_LUT] [--return-residuals]
            [--estimator {lss,lsa}] [-sm SMOOTHING_KERNEL] [-hp HIGH_PASS]
            [-c CONFOUNDS [CONFOUNDS ...]]
            [--hrf-model {glover,spm,fir,glover + derivative,glover + derivative + dispersion,spm + derivative,spm + derivative + dispersion}]
            [--fir-delays VOL [VOL ...]] [-w WORK_DIR] [--no-signal-scaling]
            [--normalize-betas]
            [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
            [--session-label SESSION_LABEL] [-t TASK_LABEL]
            [--run-label RUN_LABEL] [-sp SPACE_LABEL]
            [--description-label DESCRIPTION_LABEL]
            [--exclude-description-label] [--database-path DATABASE_PATH]
            [--nthreads NTHREADS] [--use-plugin USE_PLUGIN] [--graph]
            [--boilerplate]
            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

Either the name of the pipeline (e.g., fmriprep) or the directory path to the pipeline (e.g., /some/dir/fmriprep) that contains the minimally preprocessed img, brainmask, and confounds.tsv. If you only give the name of the pipeline, it is assumed to be under a derivatives directory within the bids directory (e.g., /my/bids/derivatives).

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

Workflow 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.

-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.

--return-residuals

setting this option returns the residuals from the modelwhile straightforward for LSA, for any other methods, takethe residuals with a grain of salt.

Options for processing

--estimator

Possible choices: lss, lsa

beta series modeling method

-sm, --smoothing-kernel

select a smoothing kernel (mm)

-hp, --high-pass

high 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

--fir-delays

FIR delays in volumes

-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.

--no-signal-scaling

do not scale every voxel with respect to time meaning beta estimates will be in the same units as the bold signal

--normalize-betas

beta estimates will be divided by the square root of their variance

Options for selecting images

--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.

--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

select a bold derivative in a specific space to be used

--description-label

select a bold file with particular desc label to process

--exclude-description-label

exclude this desc label from nibetaseries

--database-path

Path to directory containing SQLite database indicies for this BIDS dataset. If a value is passed and the file already exists, indexing is skipped.

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

--boilerplate

generate boilerplate without running 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 \
--estimator lss \
--description-label 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!

  • --estimator tells us we are using lss or Least Squares Separate for the generation of the betas.

  • 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, denoted by --description-label.

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

Example 2

nibs \
/home/james/bids/ \
fmriprep \
/home/james/bids/derivatives \
participant
--participant-label 001 \
-w /tmp/work \
-c white_matter csf cosine01 cosine02 cosine03 cosine04 cosine05 cosine06 cosine07 \
--nthreads 32 \
--estimator lsa \
--hrf-model 'glover'

In this example, we are not interested in generating correlation matrices, but we are interested in the beta maps. Since the beta maps are given by default, we need remove the correlation output. We can remove the correlation matrix output by removing the -l and -a options. Another significant difference with Example 1 is the inclusion of --participant-label. This option says we only want to run nibs on participant sub-001 in the bids dataset.