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 ‘Lausanne2008’ or ‘Lausanne2018’
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.
Erode¶
Bases: nipype.interfaces.base.core.BaseInterface
Erodes a mask.
Examples
>>> erode = Erode() >>> erode.inputs.in_file = '/path/to/sub-01_desc-brain_mask.nii.gz' >>> erode.run()
- in_filea pathlike object or string representing an existing file
Input mask to erode.
- out_filea pathlike object or string representing an existing file
Eroded mask.
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‘Lausanne2008’ or ‘Lausanne2018’ or ‘NativeFreesurfer’
Parcellation scheme. (Nipype default value:
Lausanne2008
)- 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_annot_label
(subject_id, subjects_dir)[source]¶ Creates annotation labels for the Lausanne2008 parcellation scheme.
- 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)[source]¶ Iteratively creates the ROI_%s.nii.gz files using the given Lausanne2008 parcellation information from networks.
- Parameters
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)
-
cmtklib.parcellation.
create_roi_v2
(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)[source]¶ Creates the white-matter mask using the Freesurfer ribbon as basis in the Lausanne2008 framework.
- Parameters
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)
-
cmtklib.parcellation.
create_wm_mask_v2
(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
(parcellation_scheme, subject_id, subjects_dir)[source]¶ Convert Freesurfer images back to original native space when Lausanne20XX parcellation schemes are used.
- Parameters
parcellation_scheme (string) – Parcellation scheme: ‘Lausanne2008’, ‘Lausanne2018’
subject_id (string) – Freesurfer subject id
subjects_dir (string) – Freesurfer subjects dir (Typically
/path/to/output_dir/freesurfer
)
-
cmtklib.parcellation.
define_atlas_variables
()[source]¶ Returns a dictionary containing atlas information for the Lausanne2018 parcellation scheme.
Note
atlas_info
often used in the code refers to such a dictionary.
-
cmtklib.parcellation.
erode_mask
(fsdir, maskFile)[source]¶ Erodes the mask and saves it the Freesurfer subject directory.
- Parameters
fsdir (string) – Freesurfer subject directory
maskFile (string) – Path to mask file
-
cmtklib.parcellation.
extract
(Z, shape, position, fill)[source]¶ Extract voxel neighbourhood.
- Parameters
Z (numpy.array) – The original data
shape (tuple) – Tuple containing neighbourhood dimensions
position (tuple) – Tuple containing central point indexes
fill (value) – Value for the padding of Z
- Returns
R – The output neighbourhood of the specified point in Z
- Return type
numpy.array
-
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
)
-
cmtklib.parcellation.
generate_single_parcellation
(v, i, fs_string, subject_dir, subject_id)[source]¶ Generates the volumetric parcellation from the annotation file for one scale of Lausanne2018 parcellation.
- Parameters
v (Boolean) – Verbose mode
i (int) – Parcellation scale index
fs_string (string) – Command executed before running Freesurfer tool
subject_id (string) – Freesurfer subject id
subject_dir (string) – Freesurfer subject dir (Typically
/path/to/output_dir/freesurfer/<subject_id>
)