cmtklib.parcellation module

Module that defines CMTK utility functions and Nipype interfaces for anatomical parcellation.

CombineParcellations

Link to code

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 in freeview.

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 in graphml 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.

CombineParcellations.ismember(b)[source]

ComputeParcellationRoiVolumes

Link to code

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

Link to code

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

Link to code

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

Link to code

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

Link to code

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.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.get_parcellation(parcel='NativeFreesurfer')[source]

Returns a dictionary containing atlas information.

Note

atlas_info often used in the code refers to such a dictionary.

Parameters

parcel (parcellation scheme) – It can be: ‘NativeFreesurfer’ or ‘Lausanne2018’