Command Line Interface

cubids --help

This will print the instructions for using the command line interface in your command line.

usage: cubids [-h] [-v]
              {validate,bids-version,bids-sidecar-merge,group,apply,purge,add-nifti-info,add-file-collections,copy-exemplars,undo,datalad-save,print-metadata-fields,remove-metadata-fields}
              ...

Named Arguments

-v, --version: show program’s version number and exit

Sub-commands

validate

cubids validate: Wrapper around the official BIDS Validator

cubids validate [-h] [--validation-scope {dataset,subject}]
                [--ignore-nifti-headers]
                [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [--local-validator] [--schema SCHEMA] [--n-cpus N_CPUS]
                bids_dir output_prefix

Positional Arguments

bids_dir: The root of a BIDS dataset. It should contain sub-X directories and dataset_description.json
output_prefix: file prefix to which tabulated validator output is written. If users pass in just a filename prefix e.g. V1, then CuBIDS will put the validation output in bids_dir/code/CuBIDS. If the user specifies a path (e.g. /Users/scovitz/BIDS/V1) then output files will go to the specified location.

Named Arguments

--validation-scope

Possible choices: dataset, subject

Scope of validation. ‘dataset’ validates the entire dataset (default). ‘subject’ validates each subject separately.

Default: 'dataset'

--ignore-nifti-headers

Disregard NIfTI header content during validation

Default: False

--participant-label

List: Filter the validation to only include the listed subjects. e.g. –participant-label sub-01 sub-02 sub-03

--local-validator

Lets user run a locally installed BIDS validator. Default is set to False

Default: False

--schema

Path to a BIDS schema JSON file. Default is None, which uses the latest schema available to the validator.

--n-cpus, --n_cpus

Number of CPUs to use for parallel validation when –validation-scope is ‘subject’. Defaults to 1 (sequential processing).

Default: 1

bids-version

cubids bids-version: Get BIDS Validator and Schema version

cubids bids-version [-h] [--write] [--schema SCHEMA] bids_dir

Positional Arguments

bids_dir: The root of a BIDS dataset. It should contain sub-X directories and dataset_description.json

Named Arguments

--write

Save the validator and schema version to ‘dataset_description.json’ when using cubids bids-version /bids/path –write. By default, cubids bids-version /bids/path prints to the terminal.

Default: False

--schema

Path to a BIDS schema JSON file. Default is None, which uses the latest schema available to the validator.

bids-sidecar-merge

bids-sidecar-merge: merge critical keys from one sidecar to another

cubids bids-sidecar-merge [-h] from_json to_json

Positional Arguments

from_json: Source json file.
to_json: destination json. This file will have data from from_json copied into it.

group

cubids group: find key and parameter groups in BIDS

cubids group [-h] [--acq-group-level {subject,session}] [--config CONFIG]
             [--ignore-entity IGNORE_ENTITY [IGNORE_ENTITY ...]]
             [--schema SCHEMA]
             bids_dir output_prefix

Positional Arguments

bids_dir: The root of a BIDS dataset. It should contain sub-X directories and dataset_description.json
output_prefix: file prefix to which a _summary.tsv, _files.tsv _AcqGrouping.tsv, and _AcqGroupInfo.txt, are written. If users pass in just a filename prefix e.g. V1, then CuBIDS will put the four grouping outputs in bids_dir/code/CuBIDS. If the user specifies a path (e.g. /Users/scovitz/BIDS/V1 then output files will go to the specified location.

Named Arguments

--acq-group-level

Possible choices: subject, session

Level at which acquisition groups are created options: ‘subject’ or ‘session’

Default: 'subject'

--config

Path to a config file for grouping. If not provided, then the default config file from CuBIDS will be used.

--ignore-entity

One or more BIDS entities to ignore when creating entity sets. Example: –ignore-entity task run direction

--schema

Path to a BIDS schema JSON file. Default is None, which uses the latest schema available to the validator.

apply

cubids apply: apply the changes specified in a tsv to a BIDS directory

cubids apply [-h] [--use-datalad] [--acq-group-level {subject,session}]
             [--config CONFIG] [--schema SCHEMA] [--n-cpus N_CPUS]
             bids_dir edited_summary_tsv files_tsv new_tsv_prefix

Positional Arguments

bids_dir: The root of a BIDS dataset. It should contain sub-X directories and dataset_description.json
edited_summary_tsv: path to the _summary.tsv that has been edited in the MergeInto and RenameEntitySet columns. If the summary table is located in the code/CuBIDS directory, then users can just pass the summary tsv filename instead of the full path to the tsv
files_tsv: path to the _files.tsv that has been edited in the MergeInto and RenameEntitySet columns. If the files table is located in the code/CuBIDS directory, then users can just pass the files tsv filename instead of the full path to the tsv
new_tsv_prefix: file prefix for writing the post-apply grouping outputs. If users pass in just a filename prefix e.g. V2, then CuBIDS will put the four grouping outputs in bids_dir/code/CuBIDS. If the user specifies a path (e.g. /Users/scovitz/BIDS/V2 then output files will go to the specified location.

Named Arguments

--use-datalad

ensure that there are no untracked changes before finding groups

Default: False

--acq-group-level

Possible choices: subject, session

Level at which acquisition groups are created options: ‘subject’ or ‘session’

Default: 'subject'

--config

Path to a config file for grouping. If not provided, then the default config file from CuBIDS will be used.

--schema

Path to a BIDS schema JSON file. Default is None, which uses the latest schema available to the validator.

--n-cpus, --n_cpus

Number of CPUs to use for datalad jobs. Used as –jobs for datalad save and datalad run.

Default: 1

purge

cubids purge: purge associations from the dataset

cubids purge [-h] [--use-datalad] [--n-cpus N_CPUS] bids_dir scans

Positional Arguments

bids_dir: path to the root of a BIDS dataset. It should contain sub-X directories and dataset_description.json.
scans: path to the txt file of scans whose associations should be purged. When specifying files in this txt file, always use relative paths starting from your BIDS directory. e.g., sub-01/ses-01/func/sub-01_ses-01_task-rest_bold.nii.gz

Named Arguments

--use-datalad

ensure that there are no untracked changes before finding groups

Default: False

--n-cpus, --n_cpus

Number of CPUs to use for datalad save –jobs. Defaults to 1 (sequential processing).

Default: 1

add-nifti-info

cubids add-nifti-info: Add information from niftifiles to the sidecars of each dataset

cubids add-nifti-info [-h] [--use-datalad] [--force-unlock] [--n-cpus N_CPUS]
                      bids_dir

Positional Arguments

bids_dir: absolute path to the root of a BIDS dataset. It should contain sub-X directories and dataset_description.json.

Named Arguments

--use-datalad

ensure that there are no untracked changes before finding groups

Default: False

--force-unlock

unlock dataset before adding nifti info

Default: False

--n-cpus, --n_cpus

Number of CPUs to use for parallel add-nifti-info. Defaults to 1 (sequential processing). When –use-datalad is set, this will set parallel jobs for datalad save -J <n-cpus>.

Default: 1

add-file-collections

cubids add-file-collections: Add file collection metadata to the sidecars of each NIfTI file in the BIDS dataset

cubids add-file-collections [-h] [--use-datalad] [--force-unlock]
                            [--n-cpus N_CPUS]
                            bids_dir

Positional Arguments

bids_dir: absolute path to the root of a BIDS dataset. It should contain sub-X directories and dataset_description.json.

Named Arguments

--use-datalad

ensure that there are no untracked changes before finding groups

Default: False

--force-unlock

unlock dataset before adding file collection metadata

Default: False

--n-cpus, --n_cpus

Number of CPUs to use for datalad save –jobs. Defaults to 1 (sequential processing).

Default: 1

copy-exemplars

cubids copy-exemplars: create and save a directory with one subject from each Acquisition Group in the BIDS dataset

cubids copy-exemplars [-h] [--use-datalad] [--min-group-size MIN_GROUP_SIZE]
                      [--force-unlock]
                      bids_dir exemplars_dir exemplars_tsv

Positional Arguments

bids_dir: path to the root of a BIDS dataset. It should contain sub-X directories and dataset_description.json.
exemplars_dir: name of the directory to create where to store exemplar dataset. It will include one subject from each Acquisition Group. It should contain sub-X directories and dataset_description.json.
exemplars_tsv: path to the .tsv that lists one subject from each Acquisition Group (*_AcqGrouping.tsv from the cubids group output). If the file is located in the code/CuBIDS directory, then users can just pass the .tsv filename instead of the full path

Named Arguments

--use-datalad

check exemplar dataset into DataLad

Default: False

--min-group-size

minimum number of subjects an Acquisition Group must have in order to be included in the exemplar dataset

Default: 1

--force-unlock

unlock dataset before adding nifti info

Default: False

undo

cubids undo: revert most recent commit

cubids undo [-h] bids_dir

Positional Arguments

bids_dir: The root of a BIDS dataset. It should contain sub-X directories and dataset_description.json

datalad-save

cubids datalad-save: perform a DataLad save on a BIDS directory

cubids datalad-save [-h] [-m M] [--n-cpus N_CPUS] bids_dir

Positional Arguments

bids_dir: The root of a BIDS dataset. It should contain sub-X directories and dataset_description.json

Named Arguments

-m

message for this commit

--n-cpus, --n_cpus

Number of CPUs (jobs) to use for datalad save –jobs. Defaults to 1.

Default: 1

print-metadata-fields

cubids print-metadata-fields: print all unique metadata fields

cubids print-metadata-fields [-h] bids_dir

Positional Arguments

bids_dir: The root of a BIDS dataset. It should contain sub-X directories and dataset_description.json

remove-metadata-fields

cubids remove-metadata-fields: delete fields from metadata

cubids remove-metadata-fields [-h] [--fields FIELDS [FIELDS ...]] bids_dir

Positional Arguments

bids_dir: The root of a BIDS dataset. It should contain sub-X directories and dataset_description.json

Named Arguments

--fields

space-separated list of metadata fields to remove.

Default: []