Input Data¶
The first step of configuring a rCBP project is to define the modality of the input data. The files that are required or allowed differ per modality. Currently supported modalities are rsfMRI and dMRI. It is also possible to provide connectivity matrices directly as input. This will skip the steps in the workflow used to generate connectivity matrices from rsfMRI or dMRI data. All input data should be quality controlled prior to using CBPtools, as only marginal validation is performed on the input data. Faulty data may halt processing, but in a worst-case scenario such data may provide untrustworthy output.
Regardless of the chosen modality, the following input data can be provided: (1) a binary 3-dimensional ROI file in the NIfTI image data format (data:masks:seed), and (2) an optional 3-dimensional target mask in the same data format, used to define the connections that are considered for each ROI voxel. If not provided by the user, a modified FSL (http://www.fmrib.ox.ac.uk/fsl/) distributed average Montreal Neurological Institute (MNI) 152 T1 whole-brain gray matter group template (2mm isotropic) will be used (data:masks:target). In this case, the input data should match the same MNI152 template as well. If connectivity matrices are entered directly, the target mask will not be used. Lastly, (3) a participants file as a tab-separated text file with a column called ‘participant_id’ containing all unique identifiers of the subjects to be included in this project (data:participants).
Resting-State Data¶
A 4-dimensional time-series NIfTI image per subject (as defined in the participants file) is required (data:time_series), optionally accompanied by a tab-separated text file containing confounds for each time point as columns (data:confounds). CBPtools assumes that the rsfMRI data has been treated with necessary fMRI preprocessing including realignment and normalisation to a template space. If the default target mask is used, then the template space must be MNI152 with 2mm isotropic voxels. Denoising based on independent component analysis like Automatic Removal of Motion Artifacts (ICA-AROMA) [1] or FMRIB’s ICA-based X-noiseifier (FIX) [2] is encouraged if suitable.
Diffusion-Weighted Imaging Data¶
CBPtools uses probabilistic diffusion tractography to generated connectivity matrices for the dMRI modality. Therefore, input necessary to perform FSL’s probabilistic diffusion tractography (PROBTRACKX2) is required per subject, consisting of: (1) Outputs from Bayesian Estimation of Diffusion Parameters Obtained using Sampling Techniques (BEDPOSTX) (data:samples), (2) a brain extraction (BET) binary mask file (data:bet_binary_mask), (3) a transform file taking seed space to DTI space (either a FLIR matrix or FNIR warpfield) (data:xfm), and (4) a file describing the transformation from DTI space to seed space (data:inv_xfm). Each of these files is subject-specific and can be obtained from FSL’s BEDPOSTX output. File 3 (XFM) and 4 (inverse XFM) are optional, although if the XFM is provided, then the inverse XFM must also be provided. If the XFM is not provided, an identity matrix will be used as a default probtrackx2 setting.
Connectivity Data¶
Connectivity matrices may be provided as source input in lieu of rsfMRI or dMRI data. The masking and connectivity (rsfMRI, dMRI) tasks are then skipped. This means that connectivity matrices must be presented in the way CBPtools generates them. They must be provided in an ROI-voxel by target-voxel shape as a NumPy array. This can either be done in the uncompressed .npy format, or as a compressed .npz file. In case of the latter, make sure that the array is stored as connectivity.npy inside of the .npz archive (data:connectivity). Along with the connectivity matrix, a binary 3-dimensional mask of the ROI in NIfTI image data format is expected. The number of voxels in this mask must coincide with the number of seed voxels on the first dimension of the connectivity matrix (data:masks:seed). Lastly, a NumPy array (.npy) of seed voxel coordinates must be provided in the order the voxels are represented in the connectivity matrix. This is used to map the clustering results onto the ROI mask for visualization purposes (data:seed_coordinates).
Data fields¶
participants:
file: string, required, allowed = [‘*.tsv’, ‘*.csv’, ‘*.xls’, ‘*.xlsx’], modality = any Path to a tabular file containing a column with participant IDs. When a `{participant_id} template is requested, then the file path must contain this template at the place where otherwise the participant ID would go. This template will be replaced by the actual participant IDs during execution of the pipeline`
delimiter: string, modality = any Delimiter to use (e.g., ‘ ‘ for tab-, or ‘,’ for comma-delimited files)
index_column: string, modality = any Name of the column containing the participant IDs
session: list[string], modality = any If multiple sessions are to be used for each subject, enter the sessions as partial paths here. For example, [sess1, sess2] will replace the {session} wildcard used in time_series and confounds with both sess1 and sess2, similar to how {participant_id} is replaced with the subject-id
time_series: string, required, allowed = [‘*.nii’, ‘*.nii.gz’], modality = rsfmri Path to a 4D NIfTI image containing the resting-state time-series (x, y, z, timepoints). The time-series shape and affine must match that of the seed and target masks. This field must contain the {participant_id} template, as there should be one time-series image per subject
confounds:
apply: boolean, modality = rsfmri Apply nuisance signal regression using data.confounds.file
file: string, allowed = [‘*.tsv’, ‘*.csv’], modality = rsfmri Path to a delimited (e.g., .tsv for tab-delimited) file with a confound signal per columns and a 1-line header. Columns can be selected using the columns parameter. The column length must match the length of the timepoints in the signal time-series
delimiter: string, modality = rsfmri Delimiter to use (e.g., ‘ ‘ for tab-, or ‘,’ for comma-delimited files)
columns: list[string], modality = rsfmri List of columns that should be used. If left empty, all columns are used. Otherwise only the selected columns will be used in nuisance signal regression. A glob pattern (*) can be used to select multiple columns that match the expression (e.g., ‘motion-*’ includes ‘motion-x’, ‘motion-y’, ‘motion-z’, etc.)
bet_binary_mask: string, required, allowed = [‘*.nii’, ‘*.nii.gz’], modality = dmri File path to a BET binary mask file. This field must contain the {participant_id} template
xfm: string, allowed = [‘*.nii’, ‘*.nii.gz’], modality = dmri Transform taking seed space to DTI space (either FLIRT matrix or FNIRT warpfield). This field must contain the {participant_id} template
inv_xfm: string, allowed = [‘*.nii’, ‘*.nii.gz’], modality = dmri Transform taking DTI space to seed space. This field must contain the {participant_id} template
samples: string, required, modality = dmri Merged samples derived from bedpostX output. This field must contain the {participant_id} template. Note that this is the same file path that would otherwise be entered in FSL. This it selects all files that start with the entered file path (e.g., /path/to/samples/merged will take all files starting with merged)
connectivity: string, required, allowed = [‘*.npy’, ‘*.npz’], modality = connectivity The path to a seed by target connectivity matrix. The number of seed voxels on the first dimension must match the number of seed voxels in the seed mask image. The order in which the seed voxels are listed along the first axis depends on the order that was used to extract the voxels from the mask (i.e., F- or C-contiguous order). CBPtools connectivity matrices have the seed voxels in C-order. This field must contain the {participant_id} template. The extension must be either .npy or .npz. If the compressed .npz format is used, the array in the archive must be named connectivity.npy
seed_coordinates: string, required, allowed = [‘*.npy’], modality = connectivity The path to a 2-dimensional NumPy array file with shape seed voxels by 3. The file contains the 3D coordinates of each seed voxel in the order that the seed voxels appear in the connectivity matrix. The extension must be .npy
masks:
seed: string, required, allowed = [‘*.nii’, ‘*.nii.gz’], modality = any Path to a binary region-of-interest NIfTI image in the same space as the time-series and target mask
region_id: list[integer], modality = [‘rsfmri’, ‘dmri’] If an atlas is used as the seed, specify a list of integers containing the IDs of the regions that should be merged into the seed mask. If only one ID is given, the voxels carrying that ID in the atlas will become the seed mask. If multiple IDs are given, a composite mask will be generated of all selected regions in the atlas
target: string, allowed = [‘*.nii’, ‘*.nii.gz’], modality = [‘rsfmri’, ‘dmri’] Path to a binary NIfTI image covering a target region (e.g., the whole brain). If left empty, the MNI152 2mm gray-matter mask will be used by default
space: string, allowed = [‘standard’, ‘native’], modality = any If native is used, then CBPtools assumes that both seed- and target masks are in the native space of the individual subject. This requires {participant_id} to be present in the file path to the seed and target masks. Note that group results cannot be computed in native space and are therefore skipped. If standard is used, then the seed and target masks are assumed to be in the same group template space (e.g., MNI152 2mm space).
resample: boolean, modality = any Resample the seed and target masks to the space of the input data. This option will use the NiBabel function “nibabel.processing.resample_to_from” with mode=”nearest” and order=”0”. It is only used for single-subject parcellations (data.masks.space = native) when one seed and target mask are given rather than one seed and target mask per subject. For dMRI data it is only used on the seed image if the xfm and inv_xfm are not given.
references: list[string], allowed = [‘*.nii’, ‘*.nii.gz’], modality = any Paths to one or more reference images. These images must be in the same space as the seed mask, cover the exact same voxels, and have at least 2 clusters. The reference images will be compared to the group clustering results