Data handling tools¶
This page describes data handling tools provided by Clinica for BIDS and CAPS compliant datasets. These tools provide easy interaction mechanisms with datasets, including generating subject lists or merging all tabular data into a single TSV for analysis with external statistical software tools.
describe - Describe a BIDS or CAPS dataset¶
This tool describes a BIDS or CAPS dataset, basically parsing the dataset_description.json file and displaying the information in the console in a nice way.
Note
This tool has been added in Clinica 0.9.0 and is not available in older versions.
clinica iotools describe DATASET_PATH
where:
DATASET_PATH: path to the BIDS or CAPS dataset to be described.
Examples:
With a BIDS dataset:
clinica iotools describe ./bids
Dataset information
╭───────────────────────────────┬──────┬─────────────────────────────╮
│ Name │ Type │ BIDS Specifications Version │
├───────────────────────────────┼──────┼─────────────────────────────┤
│ The mother of all experiments │ raw │ 1.6.0 │
╰───────────────────────────────┴──────┴─────────────────────────────╯
With a CAPS dataset:
clinica iotools describe ./caps
Dataset information
╭──────────────────────────────────────┬────────────┬─────────────────────────────┬─────────────────────────────╮
│ Name │ Type │ BIDS Specifications Version │ CAPS Specifications Version │
├──────────────────────────────────────┼────────────┼─────────────────────────────┼─────────────────────────────┤
│ 05c5794b-2d20-4217-b727-c215d079ab35 │ derivative │ 1.9.0 │ 1.0.0 │
╰──────────────────────────────────────┴────────────┴─────────────────────────────┴─────────────────────────────╯
Processing information
╭────────────────────────────┬────────────────────────────┬───────────────────┬─────────────────┬────────────────────────────────────────────┬────────────────┬────────────────────────────────────────────╮
│ Name │ Date │ Author │ Machine │ InputPath │ ClinicaVersion │ Dependencies │
├────────────────────────────┼────────────────────────────┼───────────────────┼─────────────────┼────────────────────────────────────────────┼────────────────┼────────────────────────────────────────────┤
│ dwi-preprocessing-using-t1 │ 2024-09-01 13:41:05.529799 │ nicolas.gensollen │ UMR-COLLI-MP050 │ /Users/nicolas.gensollen/dwi_datasets/bids │ 0.9.0 │ Dependencies │
│ │ │ │ │ │ │ ╭───────────┬──────────────┬─────────────╮ │
│ │ │ │ │ │ │ │ Name │ VersionCons… │ InstalledV… │ │
│ │ │ │ │ │ │ ├───────────┼──────────────┼─────────────┤ │
│ │ │ │ │ │ │ │ ants │ >=2.3.0 │ 2.5.0 │ │
│ │ │ │ │ │ │ │ fsl │ >=6.0.1 │ 6.0.2 │ │
│ │ │ │ │ │ │ │ mrtrix │ >=0.0.0 │ 3.0.3 │ │
│ │ │ │ │ │ │ │ convert3d │ >=0.0.0 │ 1.0.0 │ │
│ │ │ │ │ │ │ ╰───────────┴──────────────┴─────────────╯ │
╰────────────────────────────┴────────────────────────────┴───────────────────┴─────────────────┴────────────────────────────────────────────┴────────────────┴────────────────────────────────────────────╯
create-subjects-visits - Generate the list all subjects and visits of a given dataset¶
A TSV file with two columns (participant_id and session_id) containing the list of visits for each subject can be created as follows:
clinica iotools create-subjects-visits BIDS_DIRECTORY OUTPUT_TSV
where:
BIDS_DIRECTORY: input folder of a BIDS compliant dataset,OUTPUT_TSV: output TSV file containing the subjects with their sessions.
Here is an example of the file generated by this tool:
participant_id session_id
sub-01 ses-M000
sub-02 ses-M024
sub-03 ses-M024
...
Note
The format of the participant ID and the session ID follows the BIDS standard.
Example
clinica iotools create-subjects-visits /home/ADNI_BIDS/ adni_participants.tsv
check-missing-modalities - Check missing modalities for each subject¶
Starting from a BIDS compliant dataset, this command creates:
<prefix>_ses-<session_label>.tsv: TSV files for each session available with the list of the modalities found for each subject.<prefix>_summary.txt: a text file containing the number and the percentage of modalities missing for each session.analysis.txt: a text file in which a table is written per session. This table contains the number of images per modality per diagnosis when the columndiagnosisis available in the session- level files of the BIDS directory.
If no value for <prefix> is specified by the user, the default will be missing_mods.
clinica iotools check-missing-modalities [OPTIONS] BIDS_DIRECTORY OUTPUT_DIRECTORY
where:
BIDS_DIRECTORY: input folder of a BIDS compliant datasetOUTPUT_DIRECTORY: output folder-op/--output_prefix(Optional): prefix used for the name of the output files. If not specified the default value will bemissing_mods
If, for example, only the session M00 is available and the parameter -op is not specified, the command will create the files:
missing_mods_ses-M000.tsvmissing_mods_summary.txt.
The content of missing_mods_ses-M000.tsv will look like:
participant_id T1w DWI
sub-01 1 1
sub-02 1 0
sub-03 1 0
Where the column participant_id contains all the subjects found and the following columns correspond to the list of all the modalities available for the given dataset.
The availability is expressed by a boolean value.
The nomenclature of the modalities tries to follow, as much as possible, the one proposed by the BIDS standard.
Example
clinica iotools check-missing-modalities /Home/ADNI_BIDS/ /Home/
clinica iotools check-missing-modalities /Home/ADNI_BIDS/ /Home/ -op new_name
check-missing-processing - Check missing processing in a CAPS directory¶
Starting from a CAPS compliant dataset, this command creates a TSV file with columns
participant_id, session_id and names corresponding to steps of
t1-volume, t1-freesurfer, t1-linear, pet-volume and pet-surface.
For PET pipelines one column is created per tracer and the PVC option is considered for pet-volume.
clinica iotools check-missing-processing BIDS_DIRECTORY CAPS_DIRECTORY OUTPUT_FILE
where:
BIDS_DIRECTORY: input folder of a BIDS compliant datasetCAPS_DIRECTORY: input folder of a CAPS compliant datasetOUTPUT_FILE: output file path (filename included).
The content of output_file will look like:
participant_id session_id t1-linear ... pet-volume_trc-<tracer>_group-<group_label>_pvc-{True|False}
sub-01 ses-M000 1 1
sub-01 ses-M012 1 0
sub-02 ses-M000 0 0
- columns associated with
pet-volumeoutputs will specify the PET tracer, the group label and if a PVC correction was performed. - columns associated with
t1-volumeoutputs will specify the group label and which steps oft1-volumewere performed. - columns associated with
pet-surfaceoutputs will specify the PET tracer used.
merge-tsv - Gather BIDS and CAPS data into a single TSV file¶
BIDS and CAPS datasets are composed of multiple TSV files for the different subjects and sessions. While this has some advantages, it may not be convenient when performing statistical analyses (with external statistical software tools for instance). This command merges all the TSV files into a single larger TSV file and can be run with the following command line:
clinica iotools merge-tsv [OPTIONS] BIDS_DIRECTORY OUTPUT_TSV
where:
BIDS_DIRECTORYis the input folder containing the dataset in a BIDS hierarchy.OUTPUT_TSVis the path of the output TSV file. If a directory is specified instead of a file name, the default name for the file created will bemerge-tsv.tsv.
The optional arguments allow the user to also merge data from a CAPS directory, which will be concatenated to the BIDS summary. The main optional arguments are the following:
-caps: input folder of a CAPS compliant dataset
If a CAPS folder is given, data generated by the pipelines of Clinica (regional measures) will be merged to the output file, and a summary file containing the names of the atlases merged will be generated in the same folder.
-tsv: input list of subjects and sessions
If an input list of subjects and sessions is given, the merged file will only gather information from the pairs of subjects and sessions specified.
Example
clinica iotools merge-tsv /Home/ADNI_BIDS /Home/merge-tsv.tsv -caps /Home/ADNI_CAPS -tsv /Home/list_subjects.tsv
The output file will contain one row for each visit:
participant_id session_id date_of_birth ... ..._ROI-0 ..._ROI-1 ...
sub-01 ses-M000 25/04/41 ... 9.824750 0.023562
sub-01 ses-M018 25/04/41 ... 8.865353 0.012349
sub-02 ses-M000 09/01/91 ... 9.586342 0.027254
...
Note
The suffix "_intensity" is added systematically to the atlas statistics of t1-volume and pet-volume pipelines.
A complete list of optional arguments can be obtained with the command line clinica merge-tsv --help
center-nifti - Center NIfTI files of a BIDS directory¶
Your BIDS dataset may contain NIfTI files whose origin does not correspond to the center of the image (i.e. the anterior commissure).
SPM is especially sensitive to this case, and segmentation procedures may result in blank images, or even fail.
To mitigate this issue, we propose a simple tool that convert your BIDS dataset into a dataset with centered NIfTI files for the selected modalities.
Only NIfTI volumes whose center is at more than 50 mm from the origin of the world coordinate system are centered (this can be changed by the --center_all_files flag).
This threshold has been chosen empirically after a set of experiments to determine at which distance from the origin SPM segmentation and coregistration procedures stop working properly.
By default, this tool will only center T1w images but you can specify other modalities.
clinica iotools center-nifti [OPTIONS] BIDS_DIRECTORY OUTPUT_BIDS_DIRECTORY
where:
BIDS_DIRECTORYis the input folder containing the dataset in a BIDS hierarchy.OUTPUT_BIDS_DIRECTORYis the output path to the new version of your BIDS dataset, with faulty NIfTI centered. This folder can be empty or nonexistent.
Optional arguments:
--modalityis a parameter that defines which modalities are converted (only T1w images are centered by default).--center_all_filesis an option that forces Clinica to center all the files of the modalities selected with the--modalityflag.
Note
The images contained in the input bids_directory folder that do not need to be centered will also be copied to the output folder new_bids_directory.
If you want to convert FDG PET images (e.g. with _trc-18FFDG key/value in PET filename), use:
clinica iotools center-nifti bids_directory new_bids_directory --modality "18ffdg_pet"
If you want to convert AV45 PET images and T1w:
clinica iotools center-nifti bids_directory new_bids_directory --modality "18fav45_pet t1w"
To know if a NIfTI image must be centered, the algorithm checks the filenames of the NIfTI images.
For example, regarding the file bids/sub-01/ses-M000/anat/sub-01_ses-M000_T1w.nii:
- The filename is
sub-01_ses-M000_T1w.nii. - The algorithm tests (in a case insensitive way) if the string
18ffdg_petis in the filename: False. - The algorithm tests (in a case insensitive way) if the string
t1wis in the filename: True! - The algorithm tests if the volume has its center at more than 50 mm (Euclidean distance) from the origin: True.
- This file will be centered by the algorithm.
Understanding this, you can now center any modality you want! If your files are named following this pattern : sub-X_ses-Y_magnitude1.nii.gz, specify the modality as follows:--modality "magnitude1".
The list of the converted files will appear in a text file in new_bids_directory/centered_nifti_list_TIMESTAMP.txt.
Contact us !¶
- Check for past answers on Clinica Google Group
- Start a discussion on GitHub
- Report an issue on Github