morphometrytools module

clabtoolkit.morphometrytools.compute_reg_val_fromannot(metric_file, parc_file, hemi, output_table=None, metric='unknown', units=None, stats_list=['value', 'median', 'std', 'min', 'max'], table_type='metric', include_unknown=False, include_global=True, add_bids_entities=True)[source]

Compute regional statistics from a surface metric file and an annotation file.

This function extracts regional values by combining vertex-wise surface metrics with anatomical parcellation data. It supports various statistical measures and output formats.

Parameters:

  • metric_file (str or np.ndarray) – Path to the surface map file or array containing metric values for each vertex.

  • parc_file (str or cltfree.AnnotParcellation) – Path to the annotation file or AnnotParcellation object defining regions.

  • hemi (str) – Hemisphere identifier (‘lh’ or ‘rh’).

  • output_table (str, optional) – Path to save the resulting table. If None, the table is not saved.

  • metric (str, default="unknown") – Name of the metric being analyzed. Used for naming columns in the output DataFrame.

  • units (str, optional) – Units of the metric. If None, units are determined from the metric name.

  • stats_list (str or list, default=["value", "median", "std", "min", "max"]) – Statistics to compute for each region. Note: “value” is equivalent to the mean.

  • table_type (str, default="metric") – Output format specification: - “metric”: Each column represents a specific statistic for each region - “region”: Each column represents a region, with rows for different statistics

  • include_unknown (bool, default=False) – Whether to include non-anatomical regions (medialwall, unknown, corpuscallosum).

  • include_global (bool, default=True) – Whether to include hemisphere-wide statistics in the output.

  • add_bids_entities (bool, default=True) – Whether to include BIDS entities as columns in the resulting DataFrame.

Returns:

  • df (pd.DataFrame) – DataFrame containing the computed regional statistics.

  • metric_vect (np.ndarray) – Array of metric values.

  • output_path (str or None) – Path where the table was saved, or None if no table was saved.

Return type:

Tuple[DataFrame, ndarray, str | None]

Examples

Basic usage with default parameters:

>>> import os
>>> import clabtoolkit.morphometrytools as morpho
>>> hemi = 'lh'
>>> metric_name = 'thickness'
>>> fs_dir = os.environ.get('FREESURFER_HOME')
>>> metric_file = os.path.join(fs_dir, 'subjects', 'bert', 'surf', f'{hemi}.{metric_name}')
>>> parc_file = os.path.join(fs_dir, 'subjects', 'bert', 'label', f'{hemi}.aparc.annot')
>>> df_region, metric_values, _ = morpho.compute_reg_val_fromannot(
...     metric_file, parc_file, hemi, metric=metric_name, include_global=False
... )

Using region format for output:

>>> df_metric, _, _ = morpho.compute_reg_val_fromannot(
...     metric_file, parc_file, hemi, metric=metric_name,
...     include_global=False, table_type="region", add_bids_entities=True
... )

Including hemisphere-wide statistics and saving to file:

>>> output_path = '/path/to/output/regional_stats.csv'
>>> df_global, _, saved_path = morpho.compute_reg_val_fromannot(
...     metric_file, parc_file, hemi, output_table=output_path,
...     metric=metric_name, include_global=True
... )
>>> print(df_global.head())
clabtoolkit.morphometrytools.compute_reg_area_fromsurf(surf_file, parc_file, hemi, table_type='metric', surf_type='', include_unknown=False, include_global=True, add_bids_entities=True, output_table=None)[source]

Compute surface area for each region defined in an annotation file.

This function calculates the area for anatomical regions by combining surface mesh data with parcellation information. It supports different output formats and can include global hemisphere measurements.

Parameters:

  • surf_file (str or cltsurf.Surface) – Path to the surface file or Surface object containing mesh data.

  • parc_file (str or cltfree.AnnotParcellation) – Path to the annotation file or AnnotParcellation object defining regions.

  • hemi (str) – Hemisphere identifier (‘lh’ or ‘rh’).

  • table_type (str, default="metric") – Output format specification: - “metric”: Each row represents a region with area value in a column - “region”: Each column represents a region with area values in rows

  • surf_type (str, default="") – Description of the surface type (e.g., “white”, “pial”). Used for metadata.

  • include_unknown (bool, default=False) – Whether to include non-anatomical regions (medialwall, unknown, corpuscallosum).

  • include_global (bool, default=True) – Whether to include hemisphere-wide area calculations in the output.

  • add_bids_entities (bool, default=True) – Whether to include BIDS entities as columns in the resulting DataFrame.

  • output_table (str, optional) – Path to save the resulting table. If None, the table is not saved.

Returns:

  • df (pd.DataFrame) – DataFrame containing the computed regional area values.

  • output_path (str or None) – Path where the table was saved, or None if no table was saved.

Return type:

Tuple[DataFrame, str | None]

Examples

Basic usage with default parameters:

>>> import os
>>> import clabtoolkit.morphometrytools as morpho
>>> fs_dir = os.environ.get('FREESURFER_HOME')
>>> surf_file = os.path.join(fs_dir, 'subjects', 'fsaverage', 'surf', 'lh.white')
>>> parc_file = os.path.join(fs_dir, 'subjects', 'fsaverage', 'label', 'lh.aparc.annot')
>>> df_area, _ = morpho.compute_reg_area_fromsurf(surf_file, parc_file, 'lh', surf_type="white")
>>> print(df_area.head())

Using region format for output:

>>> df_region, _ = morpho.compute_reg_area_fromsurf(
...     surf_file, parc_file, 'lh',
...     table_type="region", surf_type="white", include_global=False
... )
>>> print(df_region.head())

Using Surface and AnnotParcellation objects:

>>> import clabtoolkit.surfacetools as cltsurf
>>> import clabtoolkit.freesurfertools as cltfree
>>> surf = cltsurf.Surface(surface_file=surf_file)
>>> annot = cltfree.AnnotParcellation(parc_file=parc_file)
>>> df_obj, _ = morpho.compute_reg_area_fromsurf(surf, annot, 'lh', surf_type="white")
>>> print(df_obj.head())

Saving results to a file:

>>> output_path = '/path/to/area_stats.tsv'
>>> df_out, saved_path = morpho.compute_reg_area_fromsurf(
...     surf_file, parc_file, 'lh', output_table=output_path, surf_type="white"
... )
>>> print(f"Table saved to: {saved_path}")
clabtoolkit.morphometrytools.compute_euler_fromsurf(surf_file, hemi, output_table=None, table_type='metric', surf_type='', add_bids_entities=True)[source]

Compute the Euler characteristic of a surface mesh.

This function calculates the Euler characteristic (χ = V - E + F) of a surface mesh, which is a topological invariant that provides information about the surface’s topology.

Parameters:

  • surf_file (str or cltsurf.Surface) – Path to the surface file or Surface object containing the mesh.

  • hemi (str) – Hemisphere identifier (‘lh’ or ‘rh’).

  • output_table (str, optional) – Path to save the resulting table. If None, the table is not saved.

  • table_type (str, default="metric") – Output format specification: - “metric”: Each column represents a specific metric for each region - “region”: Each column represents a region, with rows for different metrics

  • surf_type (str, default="") – Type of surface (e.g., “white”, “pial”) for metadata. If empty, determined from filename.

  • add_bids_entities (bool, default=True) – Whether to include BIDS entities as columns in the resulting DataFrame.

Returns:

  • df (pd.DataFrame) – DataFrame containing the computed Euler characteristic.

  • output_path (str or None) – Path where the table was saved, or None if no table was saved.

Return type:

Tuple[DataFrame, str | None]

Examples

Basic usage with default parameters:

>>> import os
>>> import clabtoolkit.morphometrytools as morpho
>>> fs_dir = os.environ.get('FREESURFER_HOME')
>>> hemi = 'lh'
>>> surf_file = os.path.join(fs_dir, 'subjects', 'bert', 'surf', f'{hemi}.white')
>>> df, _ = morpho.compute_euler_fromsurf(surf_file, hemi)
>>> print(df.head())

Using region format for output:

>>> df_region, _ = morpho.compute_euler_fromsurf(
...     surf_file, hemi, table_type="region", add_bids_entities=True
... )
>>> print(df_region.head())

Saving results to a file:

>>> output_path = '/path/to/output/euler_stats.csv'
>>> df_saved, saved_path = morpho.compute_euler_fromsurf(
...     surf_file, hemi, output_table=output_path
... )
>>> print(f"Table saved to: {saved_path}")

Notes

The Euler characteristic (χ) is calculated as χ = V - E + F, where: - V is the number of vertices - E is the number of edges - F is the number of faces

For a closed, orientable surface without boundaries, the Euler characteristic is related to the genus (g) by the formula: χ = 2 - 2g.

clabtoolkit.morphometrytools.area_from_mesh(coords, faces)[source]

Compute the total area and per-triangle areas of a mesh surface.

This function calculates the area of each triangle in a mesh using Heron’s formula and returns both the total surface area and individual triangle areas.

Parameters:

  • coords (np.ndarray) – Coordinates of the vertices of the mesh. Shape must be (n, 3) where n is the number of vertices. Each row contains the [x, y, z] coordinates of a vertex.

  • faces (np.ndarray) – Triangular faces of the mesh defined by vertex indices. Shape must be (m, 3) where m is the number of faces. Each row contains three indices referring to vertices in the coords array.

Returns:

  • face_area (float) – Total surface area of the mesh in square centimeters (cm²).

  • tri_area (np.ndarray) – Array of areas for each triangle in the mesh in square centimeters (cm²). Shape is (m,) where m is the number of faces.

Return type:

Tuple[float, ndarray]

Notes

The function uses Heron’s formula to calculate the area of each triangle:

Area = √(s(s-a)(s-b)(s-c))

where s is the semi-perimeter: s = (a + b + c)/2, and a, b, c are the side lengths.

The resulting areas are converted to square centimeters (cm²) by dividing by 100 (assuming the input coordinates are in millimeters).

Examples

Calculate area of a simple mesh with two triangles:

>>> import numpy as np
>>> coords = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]])
>>> faces = np.array([[0, 1, 2], [1, 3, 2]])
>>> total_area, triangle_areas = area_from_mesh(coords, faces)
>>> print(f"Total area: {total_area:.4f} cm²")
Total area: 1.0000 cm²
>>> print(f"Triangle areas: {triangle_areas}")
Triangle areas: [0.5 0.5]

Calculate area of a pyramid:

>>> coords = np.array([[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0], [0.5, 0.5, 1]])
>>> faces = np.array([[0, 1, 4], [1, 2, 4], [2, 3, 4], [3, 0, 4], [0, 2, 1], [0, 3, 2]])
>>> total_area, _ = area_from_mesh(coords, faces)
>>> print(f"Total area: {total_area:.4f} cm²")
Total area: ...
clabtoolkit.morphometrytools.euler_from_mesh(coords, faces)[source]

Compute the Euler characteristic of a mesh surface.

The Euler characteristic (χ) is a topological invariant that describes the shape or structure of a topological space regardless of how it is bent or deformed. For a mesh, it is calculated as χ = V - E + F, where V is the number of vertices, E is the number of edges, and F is the number of faces.

Parameters:

  • coords (np.ndarray) – Coordinates of the vertices of the mesh. Shape must be (n, 3) where n is the number of vertices. Each row contains the [x, y, z] coordinates of a vertex.

  • faces (np.ndarray) – Triangular faces of the mesh defined by vertex indices. Shape must be (m, 3) where m is the number of faces. Each row contains three indices referring to vertices in the coords array.

Returns:

euler – Euler characteristic of the mesh. For a closed manifold surface of genus g, χ = 2 - 2g. - Sphere: χ = 2 (genus 0) - Torus: χ = 0 (genus 1) - Double torus: χ = -2 (genus 2)

Return type:

int

Notes

The Euler characteristic provides information about the topology of a mesh: - For closed, orientable surfaces: χ = 2 - 2g, where g is the genus (number of “holes”) - For surfaces with boundaries (like cortical surfaces): χ = 2 - 2g - b, where b is the number of boundary components

A change in the Euler characteristic can indicate topological defects in a surface.

Examples

Calculate Euler characteristic of a tetrahedron (a closed surface):

>>> import numpy as np
>>> coords = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]])
>>> faces = np.array([[0, 1, 2], [0, 1, 3], [0, 2, 3], [1, 2, 3]])
>>> euler = euler_from_mesh(coords, faces)
>>> print(f"Euler characteristic: {euler}")
Euler characteristic: 2

Calculate Euler characteristic of a simple two-triangle surface:

>>> coords = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]])
>>> faces = np.array([[0, 1, 2], [1, 2, 3]])
>>> euler = euler_from_mesh(coords, faces)
>>> print(f"Euler characteristic: {euler}")
Euler characteristic: 1
clabtoolkit.morphometrytools.compute_reg_val_fromparcellation(metric_file, parc_file, output_table=None, metric='unknown', units=None, stats_list=['value', 'median', 'std', 'min', 'max'], table_type='metric', exclude_by_code=None, exclude_by_name=None, include_by_code=None, include_by_name=None, include_global=True, add_bids_entities=True, region_prefix='supra-side', interp_method='linear')[source]

Compute regional statistics from a volumetric metric map and a parcellation.

This function extracts regional values by combining voxel-wise volumetric metrics with parcellation data defining anatomical regions. It supports various statistical measures and output formats to facilitate regional analysis of volumetric neuroimaging data.

If the metric and parcellation files have different resolutions, the metric data will be automatically resampled to match the parcellation’s resolution.

Parameters:

  • metric_file (str or np.ndarray) – Path to the volumetric metric file or array containing metric values for each voxel. If array, it should have the same dimensions as the parcellation data.

  • parc_file (str, cltparc.Parcellation, or np.ndarray) – Path to the parcellation file, Parcellation object, or numpy array defining regions. Each unique integer value in the array represents a different anatomical region.

  • output_table (str, optional) – Path to save the resulting table. If None, the table is not saved.

  • metric (str, default="unknown") – Name of the metric being analyzed. Used for naming columns in the output DataFrame and determining appropriate units.

  • units (str, optional) – Units of the metric being analyzed. If None, units are determined based on the metric. Supported units include “intensity”, “thickness”, “area”, “euler”, “volume”, etc. If not specified, the function will attempt to infer units from the metric name.

  • stats_list (str or list, default=["value", "median", "std", "min", "max"]) – Statistics to compute for each region. Note: “value” is equivalent to the mean. Supported statistics: “value”, “median”, “std”, “min”, “max”, “count”, “sum”.

  • table_type (str, default="metric") – Output format specification: - “metric”: Each column represents a specific statistic for each region (regions as rows) - “region”: Each column represents a region, with rows for different statistics

  • exclude_by_code (list or np.ndarray, optional) – Region codes to exclude from the analysis. If None, no regions are excluded by code. Useful for excluding regions like ventricles or non-brain tissue.

  • exclude_by_name (list or str, optional) – Region names to exclude from the analysis. If None, no regions are excluded by name. Example: [“Ventricles”, “White-Matter”] to focus only on gray matter regions.

  • include_by_code (list or np.ndarray, optional) – Region codes to include in the analysis. If None, all regions are included by code. This parameter takes precedence over exclude_by_code.

  • include_by_name (list or str, optional) – Region names to include in the analysis. If None, all regions are included by name. This parameter takes precedence over exclude_by_name.

  • include_global (bool, default=True) – Whether to include global statistics in the output DataFrame.

  • add_bids_entities (bool, default=True) – Whether to include BIDS entities as columns in the resulting DataFrame. This extracts subject, session, and other metadata from the filename.

  • region_prefix (str, default="region-unknown-") – Prefix to use for region names when they cannot be determined from the parcellation object. The prefix will be combined with the region index number.

  • interp_method (str, default="linear") – Interpolation method to use when resampling the metric data to match parcellation resolution. Options include: “linear”, “nearest”, “cubic”. Use “nearest” for categorical data.

Returns:

  • df (pd.DataFrame) – DataFrame containing the computed regional statistics.

  • metric_data (np.ndarray) – Array of metric values used in the calculation.

  • output_path (str or None) – Path where the table was saved, or None if no table was saved.

Return type:

Tuple[DataFrame, ndarray, str | None]

Examples

Basic usage with default parameters:

>>> import os
>>> import clabtoolkit.morphometrytools as morpho
>>> # Define paths to sample data
>>> metric_file = os.path.join('data', 'sub-01', 'anat', 'sub-01_T1w_intensity.nii.gz')
>>> parc_file = os.path.join('data', 'sub-01', 'anat', 'sub-01_T1w_parcellation.nii.gz')
>>> # Compute regional statistics
>>> df, metric_values, _ = morpho.compute_reg_val_fromparcellation(
...     metric_file, parc_file, metric='intensity'
... )
>>> # Display the first few rows of results
>>> print(f"Number of regions: {df.shape[0]}")
>>> print(df[['Region', 'Value', 'Median', 'Std']].head())

Using region format for output (regions as columns, statistics as rows):

>>> df_region, _, _ = morpho.compute_reg_val_fromparcellation(
...     metric_file, parc_file, metric='intensity',
...     table_type="region", add_bids_entities=True
... )
>>> # View statistics across regions
>>> print(df_region[['Statistics', 'brain-brain-wholebrain']].head())

Working with images that have different resolutions:

>>> # High-resolution functional metric with lower-resolution anatomical parcellation
>>> metric_file = os.path.join('data', 'sub-01', 'func', 'sub-01_task-rest_bold.nii.gz')
>>> parc_file = os.path.join('data', 'sub-01', 'anat', 'sub-01_T1w_parcellation.nii.gz')
>>> # The function will automatically resample the metric to the parcellation's space
>>> df, _, _ = morpho.compute_reg_val_fromparcellation(
...     metric_file, parc_file, metric='bold',
...     interpolation='linear'  # Use linear interpolation for continuous data
... )
>>> print(df.head())

Computing only specific statistics for each region:

>>> df_custom_stats, _, _ = morpho.compute_reg_val_fromparcellation(
...     metric_file, parc_file, metric='FA',
...     stats_list=['median', 'std'], table_type="metric"
... )
>>> # View only median and standard deviation
>>> print(df_custom_stats[['Region', 'Median', 'Std']].head())

Excluding specific regions from analysis:

>>> # Exclude regions by name
>>> exclude_names = ["brain-left-ventricle", "brain-right-ventricle"]
>>> df_filtered, _, _ = morpho.compute_reg_val_fromparcellation(
...     metric_file, parc_file, metric='thickness',
...     exclude_by_name=exclude_names
... )
>>> # Check that ventricles are not in results
>>> ventricle_count = sum(1 for r in df_filtered['Region'] if 'ventricle' in r.lower())
>>> print(f"Ventricle regions in results: {ventricle_count}")

Saving the results to a file:

>>> output_path = os.path.join('results', 'sub-01_regional_intensity.tsv')
>>> df_saved, _, saved_path = morpho.compute_reg_val_fromparcellation(
...     metric_file, parc_file, output_table=output_path,
...     metric='intensity'
... )
>>> print(f"Table saved to: {saved_path}")
>>> # You can load this table later with pandas
>>> import pandas as pd
>>> df_loaded = pd.read_csv(saved_path, sep='       ')

Working with in-memory data instead of files:

>>> import numpy as np
>>> import nibabel as nib
>>> # Load data into memory first
>>> metric_obj = nib.load(metric_file)
>>> metric_data = metric_obj.get_fdata()
>>> parc_obj = nib.load(parc_file)
>>> parc_data = parc_obj.get_fdata()
>>> # Process the in-memory arrays
>>> df_memory, _, _ = morpho.compute_reg_val_fromparcellation(
...     metric_data, parc_data, metric='intensity',
...     add_bids_entities=False  # No BIDS entities for in-memory data
... )
>>> print(df_memory.head())

Notes

This function is designed for volumetric data, extracting statistics from voxel-wise metrics within each region defined by a parcellation. For surface-based metrics, consider using compute_reg_val_fromannot instead.

The function handles both file paths and in-memory arrays, making it versatile for different workflows. When working with arrays directly, ensure the metric and parcellation arrays have the same dimensions.

When metric and parcellation images have different resolutions, the metric data is automatically resampled to match the parcellation’s resolution using the specified interpolation method. For continuous metrics (like intensity), linear or cubic interpolation is recommended. For categorical data, use ‘nearest’ interpolation.

When working with BIDS-formatted data, setting add_bids_entities=True will extract subject, session, and other metadata from the filename to include in the output table.

See also

compute_reg_val_fromannot

Similar function for surface-based metrics and annotations

clabtoolkit.morphometrytools.compute_reg_volume_fromparcellation(parc_file, output_table=None, table_type='metric', exclude_by_code=None, exclude_by_name=None, include_by_code=None, include_by_name=None, add_bids_entities=True, region_prefix='supra-side', include_global=True)[source]

Compute volume for all regions in a parcellation.

This function calculates the volume of each region defined in a parcellation by counting the number of voxels in each region and multiplying by the voxel volume. It supports various output formats and can exclude specific regions from the analysis.

Parameters:

  • parc_file (str, cltparc.Parcellation, or np.ndarray) – Path to the parcellation file, Parcellation object, or numpy array defining regions. Each unique integer value in the array represents a different anatomical region.

  • output_table (str, optional) – Path to save the resulting table. If None, the table is not saved.

  • table_type (str, default="metric") – Output format specification: - “metric”: Each column represents a specific statistic for each region (regions as rows) - “region”: Each column represents a region, with rows for different statistics

  • exclude_by_code (list or np.ndarray, optional) – Region codes to exclude from the analysis. If None, no regions are excluded by code. Useful for excluding regions like ventricles or non-brain tissue.

  • exclude_by_name (list or str, optional) – Region names to exclude from the analysis. If None, no regions are excluded by name. Example: [“Ventricles”, “White-Matter”] to focus only on gray matter regions.

  • include_by_code (list or np.ndarray, optional) – Region codes to include in the analysis. If None, all regions are included. Useful for focusing on specific regions of interest.

  • include_by_name (list or str, optional) – Region names to include in the analysis. If None, all regions are included. Example: [“Cortex”, “Hippocampus”] to focus on specific structures.

  • add_bids_entities (bool, default=True) – Whether to include BIDS entities as columns in the resulting DataFrame. This extracts subject, session, and other metadata from the filename.

  • region_prefix (str, default="supra-side") – Prefix to use for region names when they cannot be determined from the parcellation object. The prefix will be combined with the region index number.

  • include_global (bool, default=True) – Whether to include a the total volume in the output table. If True, adds a row for the total volume calculated from the parcellation.

Returns:

  • df (pd.DataFrame) – DataFrame containing the computed regional volumes.

  • output_path (str or None) – Path where the table was saved, or None if no table was saved.

Return type:

Tuple[DataFrame, str | None]

Examples

Basic usage with default parameters:

>>> import os
>>> import clabtoolkit.morphometrytools as morpho
>>> # Define path to sample data
>>> parc_file = os.path.join('data', 'sub-01', 'anat', 'sub-01_T1w_parcellation.nii.gz')
>>> # Compute regional volumes
>>> df, _ = morpho.compute_reg_volume_fromparcellation(parc_file)
>>> # Display the first few rows of results
>>> print(f"Number of regions: {df.shape[0]}")
>>> print(df[['Region', 'Value']].head())

Using region format for output (regions as columns):

>>> df_region, _ = morpho.compute_reg_volume_fromparcellation(
...     parc_file, table_type="region", add_bids_entities=True
... )
>>> # View volumes across regions
>>> print(df_region.head())

Excluding specific regions from analysis:

>>> # Exclude regions by name
>>> exclude_names = ["brain-left-ventricle", "brain-right-ventricle"]
>>> df_filtered, _ = morpho.compute_reg_volume_fromparcellation(
...     parc_file, exclude_by_name=exclude_names
... )
>>> # Check that ventricles are not in results
>>> ventricle_count = sum(1 for r in df_filtered['Region'] if 'ventricle' in r.lower())
>>> print(f"Ventricle regions in results: {ventricle_count}")

Saving the results to a file:

>>> output_path = os.path.join('results', 'sub-01_regional_volumes.tsv')
>>> df_saved, saved_path = morpho.compute_reg_volume_fromparcellation(
...     parc_file, output_table=output_path
... )
>>> print(f"Table saved to: {saved_path}")
>>> # You can load this table later with pandas
>>> import pandas as pd
>>> df_loaded = pd.read_csv(saved_path, sep='       ')

Working with in-memory data instead of files:

>>> import numpy as np
>>> import nibabel as nib
>>> # Load data into memory first
>>> parc_obj = nib.load(parc_file)
>>> parc_data = parc_obj.get_fdata()
>>> # Create a custom affine matrix (example: 1mm isotropic voxels)
>>> affine = np.eye(4)
>>> # Process the in-memory array
>>> df_memory, _ = morpho.compute_reg_volume_fromparcellation(
...     parc_data, add_bids_entities=False
... )
>>> print(df_memory.head())

Notes

This function calculates volumes in milliliters (ml) by default. The voxel volume is calculated from the affine transformation matrix of the parcellation image. For arrays without an affine matrix, an identity matrix is assumed (1mm isotropic voxels).

The regional volumes are calculated by counting the number of voxels in each region and multiplying by the voxel volume in cubic millimeters, then dividing by 1000 to convert to milliliters.

When working with BIDS-formatted data, setting add_bids_entities=True will extract subject, session, and other metadata from the filename to include in the output table.

See also

compute_reg_val_fromparcellation

Calculate statistics for metric values within parcellation regions

clabtoolkit.morphometrytools.parse_freesurfer_global_fromaseg(stat_file, output_table=None, table_type='metric', add_bids_entities=True, include_missing=True, config_json=None)[source]

Parse global volume measurements from a FreeSurfer aseg.stats file.

This function extracts key global volumetric measurements from FreeSurfer’s aseg.stats file, including intracranial volume, brain volume, gray/white matter volumes, and ventricle volumes. It converts values to milliliters and organizes them into a structured DataFrame.

Parameters:

  • stat_file (str) – Path to the aseg.stats file generated by FreeSurfer.

  • output_table (str, optional) – Path to save the resulting table. If None, the table is not saved.

  • table_type (str, default="metric") – Output format specification: - “metric”: Each column represents a specific statistic for each region (regions as rows) - “region”: Each column represents a region, with rows for different statistics

  • add_bids_entities (bool, default=True) – Whether to include BIDS entities as columns in the resulting DataFrame. This extracts subject, session, and other metadata from the filename.

  • include_missing (bool, default=True) – Whether to include missing values as zeros in the output. If False, missing values will be excluded from the DataFrame.

  • config_json (str, optional) – Path to a JSON configuration file defining volume measurements to extract. If None, a default configuration will be used.

Returns:

  • df (pd.DataFrame) – DataFrame containing the extracted global volume measurements.

  • output_path (str or None) – Path where the table was saved, or None if no table was saved.

Return type:

Tuple[DataFrame, str | None]

clabtoolkit.morphometrytools.parse_freesurfer_stats_fromaseg(stat_file, output_table=None, table_type='metric', add_bids_entities=True, include_missing=True, config_json=None)[source]

Parse regional volume measurements from a FreeSurfer aseg.stats file.

This function extracts volume measurements for specific brain regions from the tabular data section of FreeSurfer’s aseg.stats file. It converts values to milliliters and organizes them into a structured DataFrame.

Parameters:

  • stat_file (str) – Path to the aseg.stats file generated by FreeSurfer.

  • output_table (str, optional) – Path to save the resulting table. If None, the table is not saved.

  • table_type (str, default="metric") – Output format specification: - “metric”: Each column represents a specific statistic for each region (regions as rows) - “region”: Each column represents a region, with rows for different statistics

  • add_bids_entities (bool, default=True) – Whether to include BIDS entities as columns in the resulting DataFrame. This extracts subject, session, and other metadata from the filename.

  • include_missing (bool, default=True) – Whether to include missing values as zeros in the output. If False, missing values will be excluded from the DataFrame.

  • config_json (str, optional) – Path to a JSON configuration file defining region measurements to extract. If None, a default configuration will be used.

Returns:

  • df (pd.DataFrame) – DataFrame containing the extracted region volume measurements.

  • output_path (str or None) – Path where the table was saved, or None if no table was saved.

Return type:

Tuple[DataFrame, str | None]

Examples

Basic usage with default parameters:

>>> import os
>>> import clabtoolkit.morphometrytools as morpho
>>> # Define path to FreeSurfer stats file
>>> stats_file = os.path.join('freesurfer', 'sub-01', 'stats', 'aseg.stats')
>>> # Parse the stats file
>>> df, _ = morpho.parse_freesurfer_stats_fromaseg(stats_file)
>>> # Display the first few rows of results
>>> print(df[['Region', 'Value']].head())

Using region format (regions as columns, statistics as rows):

>>> df_region, _ = morpho.parse_freesurfer_stats_fromaseg(
...     stats_file, table_type="region"
... )
>>> # View volumes across regions
>>> print(df_region.head())

Saving the results to a file:

>>> output_path = os.path.join('results', 'sub-01_fs-regional-volumes.tsv')
>>> df_saved, saved_path = morpho.parse_freesurfer_stats_fromaseg(
...     stats_file, output_table=output_path
... )
>>> print(f"Table saved to: {saved_path}")

Notes

This function extracts regional volume measurements from the table section of the aseg.stats file. The aseg.stats file contains a table with measurements for different brain regions, with each row representing a different segmented region.

All volumes are converted to milliliters (ml) by dividing the FreeSurfer values (typically in mm³) by 1000.

The aseg.stats file is typically found in the [subject]/stats/ directory of a FreeSurfer output directory.

See also

parse_freesurfer_global_fromaseg

Extract global volume measurements from aseg.stats

clabtoolkit.morphometrytools.parse_freesurfer_cortex_stats(stats_file, output_table=None, table_type='metric', add_bids_entities=True, hemi=None, config_json=None, include_metrics=None)[source]

Parse cortical parcellation statistics from a FreeSurfer aparc.stats file.

This function extracts regional measurements from FreeSurfer’s aparc.stats files, including surface area, gray matter volume, cortical thickness, and curvature for each cortical region. It organizes the data into a structured DataFrame.

Surface area is automatically converted from mm² to cm² (divided by 100) and volume is automatically converted from mm³ to cm³ (divided by 1000).

Parameters:

  • stats_file (str) – Path to the aparc.stats file generated by FreeSurfer (lh.aparc.stats or rh.aparc.stats).

  • output_table (str, optional) – Path to save the resulting table. If None, the table is not saved.

  • table_type (str, default="metric") – Output format specification: - “metric”: Each row represents a region, with columns for different metrics - “region”: Each row represents a metric, with columns for different regions

  • add_bids_entities (bool, default=True) – Whether to include BIDS entities as columns in the resulting DataFrame. This extracts subject, session, and other metadata from the filename.

  • hemi (str, optional) – Hemisphere identifier (‘lh’ for left or ‘rh’ for right). If None, it will be automatically detected from the filename or the file content.

  • config_json (str, optional) – Path to a JSON configuration file defining cortical metrics to extract. If None, a default configuration will be used.

  • include_metrics (list, optional) – List of metrics to extract from the stats file. If provided, only these metrics will be extracted from the configuration. If None, all metrics in the configuration will be extracted.

Returns:

  • df (pd.DataFrame) – DataFrame containing the extracted cortical measurements.

  • output_path (str or None) – Path where the table was saved, or None if no table was saved.

Return type:

Tuple[DataFrame, str | None]

Examples

Basic usage with default parameters:

>>> import os
>>> import clabtoolkit.morphometrytools as morpho
>>> # Define path to FreeSurfer stats file
>>> stats_file = os.path.join('freesurfer', 'sub-01', 'stats', 'lh.aparc.stats')
>>> # Parse the stats file
>>> df, _ = morpho.parse_freesurfer_cortex_stats(stats_file)
>>> # Display the results for thickness
>>> thickness_df = df[df['Metric'] == 'thickness']
>>> print(thickness_df[['Region', 'Value', 'Std']].head())

Using a custom configuration file:

>>> config_file = os.path.join('config', 'stats_mapping.json')
>>> df, _ = morpho.parse_freesurfer_cortex_stats(stats_file, config_json=config_file)

Extract only specific metrics:

>>> df_area_vol, _ = morpho.parse_freesurfer_cortex_stats(
...     stats_file, include_metrics=["area", "volume"]
... )
>>> print(df_area_vol['Metric'].unique())

Using region format (metrics as rows, regions as columns):

>>> df_region, _ = morpho.parse_freesurfer_cortex_stats(
...     stats_file, table_type="region"
... )
>>> # View thickness across regions
>>> thickness_row = df_region[df_region['Statistics'] == 'thickness']
>>> print(thickness_row.iloc[:, :5])  # Print first 5 columns for thickness

Saving the results to a file:

>>> output_path = os.path.join('results', 'sub-01_lh_cortical-metrics.tsv')
>>> df_saved, saved_path = morpho.parse_freesurfer_cortex_stats(
...     stats_file, output_table=output_path
... )
>>> print(f"Table saved to: {saved_path}")

Notes

This function extracts metrics from aparc.stats files based on the configuration. By default, these include: - Surface area (SurfArea column) in cm² (converted from mm² by dividing by 100) - Gray matter volume (GrayVol column) in cm³ (converted from mm³ by dividing by 1000) - Cortical thickness (ThickAvg column) in mm (unchanged) - Thickness standard deviation (ThickStd column) in mm (unchanged) - Mean curvature (MeanCurv column) in mm⁻¹ (unchanged)

The function automatically detects the hemisphere from the filename or file content if not specified.

Cortical parcellation stats files (lh.aparc.stats and rh.aparc.stats) are typically found in the [subject]/stats/ directory of a FreeSurfer output directory.

See also

parse_freesurfer_global_fromaseg

Parse global volumes from aseg.stats file

parse_freesurfer_stats_fromaseg

Parse regional volumes from aseg.stats file

clabtoolkit.morphometrytools.get_stats_dictionary(region_level='global')[source]

Return the default global volume measurements configuration for FreeSurfer aseg.stats files.

Returns:

Dictionary containing configuration for extracting global volume measurements.

Return type:

dict

clabtoolkit.morphometrytools.network_metrics_to_table(conn_mat, lut_file=None, cmat_met='weight')[source]

Compute network metrics from a connectivity matrix and return them in a DataFrame. This function calculates various graph theory metrics from a given connectivity matrix using the Brain Connectivity Toolbox (BCT) and organizes the results into a pandas DataFrame.

Parameters:

  • conn_mat (np.ndarray) – Square connectivity matrix (2D numpy array) representing the connections between brain regions.

  • lut_file (str, Path, or dict, optional) – Path to a lookup table (LUT) file or a dictionary defining region codes and names. If provided, it is used to map region indices to names. If None, regions are named generically as “auto-roi-0001”, “auto-roi-0002”, etc.

  • cmat_met (str or list of str, default="weight") – Description of the connectivity matrix type. This string is used to label the metric in the output DataFrame. It can be a single string or a list of strings.

Returns:

DataFrame containing the computed network metrics for each region and global metrics.

Return type:

pd.DataFrame

Examples

Basic usage with a connectivity matrix: >>> import numpy as np >>> import clabtoolkit.morphometrytools as morpho >>> # Create a sample connectivity matrix >>> conn_mat = np.array([[0, 1, 2], … [1, 0, 3], … [2, 3, 0]]) >>> # Compute network metrics >>> df_metrics = morpho.network_metrics_to_table(conn_mat) >>> print(df_metrics)

clabtoolkit.morphometrytools.stats_from_vector(metric_vect, stats_list)[source]

Computes specified statistics from a numeric vector.

This function calculates various statistical measures from a numpy array based on the requested statistics in stats_list.

Parameters:

  • metric_vect (np.ndarray) – Vector with the values of the metric.

  • stats_list (list) – List of statistics to compute. Supported values are: ‘mean’, ‘value’ (same as ‘mean’), ‘median’, ‘std’, ‘min’, ‘max’.

Returns:

List with the computed statistics in the same order as requested. Values are returned as Python floats, not numpy.float64.

Return type:

list

Raises:

  • ValueError – If an unsupported statistic is requested.

  • TypeError – If inputs are not of expected types.

Examples

>>> import numpy as np
>>> data = np.array([1, 2, 3, 4, 5])
>>> stats_from_vector(data, ['mean', 'median', 'std'])
[3.0, 3.0, 1.4142135623730951]

>>> stats_from_vector(data, ['min', 'max'])
[1.0, 5.0]

>>> # Case-insensitive statistic names
>>> stats_from_vector(data, ['MEAN', 'Mean', 'mean'])
[3.0, 3.0, 3.0]

>>> # 'value' is an alias for 'mean'
>>> stats_from_vector(data, ['mean', 'value'])
[3.0, 3.0]

>>> # Empty arrays return NaN for all statistics
>>> stats_from_vector(np.array([]), ['mean', 'median'])
[nan, nan]

>>> # Error on unsupported statistic
>>> stats_from_vector(data, ['mean', 'mode'])
Traceback (most recent call last):
    ...
ValueError: Unsupported statistics: mode
clabtoolkit.morphometrytools.get_units(metrics, metrics_json=None)[source]

Get the units associated with specified metrics.

Retrieves the corresponding units for one or more metrics from either a provided JSON file, dictionary, or the default configuration.

Parameters:

  • metrics (str or list of str) – Name(s) of the metrics. Can be a single metric as a string or multiple metrics as a list.

  • metrics_json (str or dict, optional) – Either: - Path to a JSON file containing the metrics units dictionary - Dictionary directly containing the metrics units mapping - None (default), which uses the package’s built-in configuration

Returns:

Units corresponding to each requested metric. Returns “unknown” for any metric not found in the dictionary.

Return type:

list of str

Raises:

ValueError – If the provided JSON file path is invalid or the metrics_json structure is incorrect.

Examples

>>> import clabtoolkit.morphometrytools as clmorphtools
>>> # Get unit for a single metric
>>> clmorphtools.get_units('thickness')
['mm']
>>>
>>> # Get units for multiple metrics
>>> clmorphtools.get_units(['thickness', 'area', 'volume'])
['mm', 'cm²', 'cm³']
>>>
>>> # Using a custom metrics dictionary
>>> custom_dict = {"metrics_units": {"custom_metric": "kg"}}
>>> clmorphtools.get_units('custom_metric', metrics_json=custom_dict)
['kg']
>>>
>>> # Handling unknown metrics
>>> clmorphtools.get_units(['thickness', 'unknown_metric'])
['mm', 'unknown']

The morphometrytools module provides specialized tools for surface-based morphometric analysis, enabling extraction and analysis of cortical measurements across brain regions.

Key Features

  • Regional value extraction from surface annotations

  • Multi-hemisphere morphometric analysis

  • Surface area and Euler characteristic computation from meshes

  • FreeSurfer statistics file parsing and processing

  • Volume-based morphometry from parcellations

  • Statistical summary generation and unit management

Main Functions

Regional Analysis

  • compute_reg_val_fromannot(): Extract regional statistics from surface scalar data

  • process_hemisphere_morphometry(): Process morphometric data for single hemisphere

  • generate_morphometry_table(): Create comprehensive morphometry tables

  • validate_morphometric_data(): Quality control for morphometric measurements

FreeSurfer Analysis

  • parse_freesurfer_global_fromaseg(): Parse FreeSurfer global statistics from aseg

  • parse_freesurfer_stats_fromaseg(): Parse FreeSurfer statistics from aseg

  • parse_freesurfer_cortex_stats(): Parse FreeSurfer cortex statistics

  • get_stats_dictionary(): Get statistics dictionary from FreeSurfer data

Utility Functions

  • network_metrics_to_table(): Convert network metrics to table format

  • stats_from_vector(): Compute statistics from vector data

  • get_units(): Get measurement units for morphometric data

Common Usage Examples

Basic regional morphometry extraction:

from clabtoolkit.morphometrytools import compute_reg_val_fromannot

# Extract cortical thickness by region
thickness_stats = compute_reg_val_fromannot(
    scalar_file="lh.thickness.mgh",
    annot_file="lh.aparc.a2009s.annot",
    lut_file="aparc.a2009s.lut"
)

print(thickness_stats.head())

Multi-hemisphere analysis:

# Process both hemispheres
hemispheres = ['lh', 'rh']
all_stats = {}

for hemi in hemispheres:
    stats = compute_reg_val_fromannot(
        scalar_file=f"{hemi}.thickness.mgh",
        annot_file=f"{hemi}.aparc.annot",
        lut_file="aparc.lut"
    )
    all_stats[hemi] = stats

# Combine hemisphere data
combined_stats = pd.concat(all_stats, axis=0)

FreeSurfer statistics parsing:

# Parse cortical statistics from FreeSurfer
cortex_stats = parse_freesurfer_cortex_stats(
    stats_file="/path/to/freesurfer/stats/lh.aparc.stats"
)

# Get global statistics from aseg
global_stats = parse_freesurfer_global_fromaseg(
    aseg_file="/path/to/freesurfer/stats/aseg.stats"
)

# Convert to table format with proper units
stats_table = network_metrics_to_table(
    stats_dict=cortex_stats,
    subject_id="sub-001"
)

# Get measurement units
units = get_units(measure_type="thickness")
print(f"Thickness measured in: {units}")