cmtklib.parcellation module
Module that defines CMTK utility functions and Nipype interfaces for anatomical parcellation.
CombineParcellations
Bases: nipype.interfaces.base.core.BaseInterface
Creates the final parcellation.
It combines the original cortico sub-cortical parcellation with the following extra segmented structures:
Segmentation of the 8 thalamic nuclei per hemisphere
Segmentation of 14 hippocampal subfields per hemisphere
Segmentation of 3 brainstem sub-structures
It also generates by defaults the corresponding (1) description of the nodes in
graphml
format and (2) color lookup tables in FreeSurfer format that can be displayed infreeview
.Examples
>>> parc_combine = CombineParcellations() >>> parc_combine.inputs.input_rois = ['/path/to/sub-01_atlas-L2018_desc-scale1_dseg.nii.gz', >>> '/path/to/sub-01_atlas-L2018_desc-scale2_dseg.nii.gz', >>> '/path/to/sub-01_atlas-L2018_desc-scale3_dseg.nii.gz', >>> '/path/to/sub-01_atlas-L2018_desc-scale4_dseg.nii.gz', >>> '/path/to/sub-01_atlas-L2018_desc-scale5_dseg.nii.gz'] >>> parc_combine.inputs.lh_hippocampal_subfields = '/path/to/lh_hippocampal_subfields.nii.gz' >>> parc_combine.inputs.rh_hippocampal_subfields = '/path/to/rh_hippocampal_subfields.nii.gz' >>> parc_combine.inputs.brainstem_structures = '/path/to/brainstem_structures.nii.gz' >>> parc_combine.inputs.thalamus_nuclei = '/path/to/thalamus_nuclei.nii.gz' >>> parc_combine.inputs.create_colorLUT = True >>> parc_combine.inputs.create_graphml = True >>> parc_combine.inputs.subjects_dir = '/path/to/output_dir/freesurfer') >>> parc_combine.inputs.subject_id = 'sub-01' >>> parc_combine.run()
- brainstem_structuresa pathlike object or string representing a file
Brainstem segmentation file.
- create_colorLUTa boolean
If
True
, create the color lookup table in Freesurfer format.- create_graphmla boolean
If
True
, create the parcellation node description files ingraphml
format.- input_roisa list of items which are a pathlike object or string representing an existing file
Input parcellation files.
- lh_hippocampal_subfieldsa pathlike object or string representing a file
Input hippocampal subfields file for left hemisphere.
- rh_hippocampal_subfieldsa pathlike object or string representing a file
Input hippocampal subfields file for right hemisphere.
- subject_ida string
Freesurfer subject id.
- subjects_dira pathlike object or string representing a directory
Freesurfer subjects dir.
- thalamus_nucleia pathlike object or string representing a file
Thalamic nuclei segmentation file.
- verbose_level1 or 2
Verbose level (1: partial (default) / 2: full).
- aparc_asega pathlike object or string representing a file
Modified Freesurfer aparc+aseg file.
- colorLUT_filesa list of items which are a pathlike object or string representing an existing file
Color lookup table files in Freesurfer format.
- graphML_filesa list of items which are a pathlike object or string representing an existing file
Parcellation node description files in
graphml
format.- output_roisa list of items which are a pathlike object or string representing an existing file
Output parcellation with all structures combined.
ComputeParcellationRoiVolumes
Bases: nipype.interfaces.base.core.BaseInterface
Computes the volumes of each ROI for each parcellation scale.
Examples
>>> compute_vol = ComputeParcellationRoiVolumes() >>> compute_vol.inputs.roi_volumes = ['/path/to/sub-01_atlas-L2018_desc-scale1_dseg.nii.gz', >>> '/path/to/sub-01_atlas-L2018_desc-scale2_dseg.nii.gz', >>> '/path/to/sub-01_atlas-L2018_desc-scale3_dseg.nii.gz', >>> '/path/to/sub-01_atlas-L2018_desc-scale4_dseg.nii.gz', >>> '/path/to/sub-01_atlas-L2018_desc-scale5_dseg.nii.gz'] >>> compute_vol.inputs.roi_graphmls = ['/path/to/sub-01_atlas-L2018_desc-scale1_dseg.graphml', >>> '/path/to/sub-01_atlas-L2018_desc-scale2_dseg.graphml', >>> '/path/to/sub-01_atlas-L2018_desc-scale3_dseg.graphml', >>> '/path/to/sub-01_atlas-L2018_desc-scale4_dseg.graphml', >>> '/path/to/sub-01_atlas-L2018_desc-scale5_dseg.graphml'] >>> compute_vol.inputs.parcellation_scheme = ['Lausanne2018'] >>> compute_vol.run()
- parcellation_scheme‘NativeFreesurfer’ or ‘Lausanne2018’ or ‘Custom’
Parcellation scheme. (Nipype default value:
Lausanne2018
)- roi_graphMLsa list of items which are a pathlike object or string representing an existing file
GraphML description of ROI volumes (Lausanne2018).
- roi_volumesa list of items which are a pathlike object or string representing an existing file
ROI volumes registered to diffusion space.
- roi_volumes_statsa list of items which are a pathlike object or string representing a file
TSV files with computed parcellation ROI volumes.
Parcellate
Bases: nipype.interfaces.base.core.BaseInterface
Subdivides segmented ROI file into smaller subregions.
- This interface interfaces with the CMTK parcellation functions
available in
cmtklib.parcellation
module for all parcellation resolutions of a given scheme.Example
>>> from cmtklib.parcellation import Parcellate >>> parcellate = Parcellate() >>> parcellate.inputs.subjects_dir = '/path/to/output_dir/freesurfer' >>> parcellate.inputs.subject_id = 'sub-01' >>> parcellate.inputs.parcellation_scheme = 'Lausanne2018' >>> parcellate.run()
- subject_ida string
Subject ID.
- erode_masksa boolean
If
True
erode the masks.- parcellation_scheme‘Lausanne2018’ or ‘NativeFreesurfer’
Parcellation scheme. (Nipype default value:
Lausanne2018
)- subjects_dira pathlike object or string representing a directory
Freesurfer main directory.
- T1a pathlike object or string representing a file
T1 image file.
- aparc_asega pathlike object or string representing a file
APArc+ASeg image file (in native space).
- asega pathlike object or string representing a file
ASeg image file (in native space).
- braina pathlike object or string representing a file
Brain-masked T1 image file.
- brain_erodeda pathlike object or string representing a file
Eroded brain file in original space.
- brain_maska pathlike object or string representing a file
Brain mask file.
- csf_erodeda pathlike object or string representing a file
Eroded csf file in original space.
- csf_mask_filea pathlike object or string representing a file
Cerebrospinal fluid (CSF) mask file.
- gray_matter_mask_filea pathlike object or string representing a file
Cortical gray matter (GM) mask file.
- ribbon_filea pathlike object or string representing an existing file
Image file detailing the cortical ribbon.
- roi_files_in_structural_spacea list of items which are a pathlike object or string representing an existing file
ROI image resliced to the dimensions of the original structural image.
- white_matter_mask_filea pathlike object or string representing a file
White matter (WM) mask file.
- wm_erodeda pathlike object or string representing a file
Eroded wm file in original space.
ParcellateBrainstemStructures
Bases: nipype.interfaces.base.core.BaseInterface
Parcellates the brainstem sub-structures using Freesurfer [Iglesias2015Brainstem].
References
- Iglesias2015Brainstem
Iglesias et al., NeuroImage, 113, June 2015, 184-195. <http://www.nmr.mgh.harvard.edu/~iglesias/pdf/Neuroimage_2015_brainstem.pdf>
Examples
>>> parc_bstem = ParcellateBrainstemStructures() >>> parc_bstem.inputs.subjects_dir = '/path/to/derivatives/freesurfer' >>> parc_bstem.inputs.subject_id = 'sub-01' >>> parc_bstem.run()
- subject_ida string
Subject ID.
- subjects_dira pathlike object or string representing a directory
Freesurfer main directory.
- brainstem_structuresa pathlike object or string representing a file
Parcellated brainstem structures file.
ParcellateHippocampalSubfields
Bases: nipype.interfaces.base.core.BaseInterface
Parcellates the hippocampal subfields using Freesurfer [Iglesias2015Hippo].
References
- Iglesias2015Hippo
Iglesias et al., Neuroimage, 115, July 2015, 117-137. <http://www.nmr.mgh.harvard.edu/~iglesias/pdf/subfieldsNeuroimage2015preprint.pdf>
Examples
>>> parc_hippo = ParcellateHippocampalSubfields() >>> parc_hippo.inputs.subjects_dir = '/path/to/derivatives/freesurfer' >>> parc_hippo.inputs.subject_id = 'sub-01' >>> parc_hippo.run()
- subject_ida string
Subject ID.
- subjects_dira pathlike object or string representing a directory
Freesurfer main directory.
- lh_hipposubfieldsa pathlike object or string representing a file
Left hemisphere hippocampal subfields file.
- rh_hipposubfieldsa pathlike object or string representing a file
Right hemisphere hippocampal subfields file.
ParcellateThalamus
Bases: nipype.interfaces.base.core.BaseInterface
Parcellates the thalamus into 8 nuclei using an atlas-based method [Najdenovska18].
References
- Najdenovska18
Najdenovska et al., Sci Data 5, 180270 (2018). <https://doi.org/10.1038/sdata.2018.270>
Examples
>>> parc_thal = ParcellateThalamus() >>> parc_thal.inputs.T1w_image = File(mandatory=True, desc='T1w image to be parcellated') >>> parc_thal.inputs.bids_dir = Directory(desc='BIDS root directory') >>> parc_thal.inputs.subject = '01' >>> parc_thal.inputs.template_image = '/path/to/atlas/T1w.nii.gz' >>> parc_thal.inputs.thalamic_nuclei_maps = '/path/to/atlas/nuclei/probability/map.nii.gz' >>> parc_thal.inputs.subjects_dir = '/path/to/output_dir/freesurfer' >>> parc_thal.inputs.subject_id = 'sub-01' >>> parc_thal.inputs.ants_precision_type = 'float' >>> parc_thal.run()
- T1w_imagea pathlike object or string representing a file
T1w image to be parcellated.
- subject_ida string
Subject ID.
- subjects_dira pathlike object or string representing a directory
Freesurfer main directory.
- template_imagea pathlike object or string representing a file
Template T1w.
- thalamic_nuclei_mapsa pathlike object or string representing a file
Probability maps of thalamic nuclei (4D image) in template space.
- ants_precision_type‘double’ or ‘float’
Precision type used during computation.
- bids_dira pathlike object or string representing a directory
BIDS root directory.
- sessiona string
Session id.
- subjecta string
Subject id.
- inverse_warped_imagea pathlike object or string representing a file
Inverse warped template.
- max_prob_registereda pathlike object or string representing a file
Max probability label image (native).
- prob_maps_registereda pathlike object or string representing a file
Probabilistic map of thalamus nuclei (native).
- thalamus_maska pathlike object or string representing a file
Thalamus mask.
- transform_filea pathlike object or string representing a file
Transform file.
- warp_filea pathlike object or string representing a file
Deformation file.
- warped_imagea pathlike object or string representing a file
Template registered to T1w image (native).
- cmtklib.parcellation.create_T1_and_Brain(subject_id, subjects_dir)[source]
Generates T1, T1 masked and aseg+aparc Freesurfer images in NIFTI format.
- Parameters
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)
- cmtklib.parcellation.create_roi(subject_id, subjects_dir, v=True)[source]
Iteratively creates the ROI_%s.nii.gz files using the given Lausanne2018 parcellation information from networks.
- Parameters
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)v (Boolean) – Verbose mode
- cmtklib.parcellation.create_wm_mask(subject_id, subjects_dir, v=True)[source]
Creates the white-matter mask using the Freesurfer ribbon as basis in the Lausanne2018 framework.
- Parameters
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)v (Boolean) – Verbose mode
- cmtklib.parcellation.crop_and_move_WM_and_GM(subject_id, subjects_dir)[source]
Convert Freesurfer images back to original native space when NativeFreesurfer parcellation scheme is used.
- Parameters
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)
- cmtklib.parcellation.crop_and_move_datasets(subject_id, subjects_dir)[source]
Convert Freesurfer images back to original native space when Lausanne2018 parcellation schemes are used.
- Parameters
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)
- cmtklib.parcellation.erode_mask(fsdir, mask_file)[source]
Erodes the mask and saves it the Freesurfer subject directory.
- Parameters
fsdir (string) – Freesurfer subject directory
mask_file (string) – Path to mask file
- cmtklib.parcellation.generate_WM_and_GM_mask(subject_id, subjects_dir)[source]
Generates the white-matter and gray-matter masks when NativeFreesurfer parcellation is used.
- Parameters
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)