mesh_metrics
- subcortexmesh.mesh_metrics.mesh_metrics(inputdir: str | Path, outputdir: str | Path, template: str, toolboxdata: str | Path | None = None, metric: str | Sequence[str] = ['thickness', 'curvature', 'surfarea'], roilabel: str | Sequence[str] = ['left-cerebellum-cortex', 'right-cerebellum-cortex', 'left-pallidum', 'right-pallidum', 'left-putamen', 'right-putamen', 'left-thalamus', 'right-thalamus', 'left-amygdala', 'right-amygdala', 'left-hippocampus', 'right-hippocampus', 'left-accumbens-area', 'right-accumbens-area', 'left-caudate', 'right-caudate', 'left-ventraldc', 'right-ventraldc', 'brain-stem'], smooth: tuple[int, int, int] = (0, 5, 5), plot_medial_curve: bool = False, plot_projection: bool = False, native_meshes: bool = False, overwrite: bool = True, silent: bool = False)[source]
Thickness and surface area computation
This function extract thickness and surface area metrics from subcortical surface objects outputted in “sub_surfaces”, via the following steps:
It renders medial curves, i.e. singular lines spanning the “core” of the meshes, between its two polar axes (estimated with principal component analysis)
The medial curve is used to align the subject mesh to the template mesh
Thickness is measured as each surface vertex’s distance from the curve (i.e., the radial distance between the surface and the center of the mesh)
Surface area is measured as the sum of the area of all triangles a given vertex belongs to, divided by 3. By default, a Gaussian (FWHM=5) smoothing is applied.
Curvature is the mean curvature from vtkCurvatures, which indicates how bent is the surface at a each vertex, with higher mean curvature meaning more concave surface and lower convex. By default, a Gaussian (FWHM=5) smoothing is applied.
Optional (native_meshes, disabled by default): meshes with their thickness and surface area scalar values can be saved in native subject space, before projection.
Metric values, separately, are “projected” on an empty template
mesh via a nearest neighbour approach (i.e., each vertex in the template mesh is assigned the metric value of the closest vertex in the subject mesh) - Meshes with their thickness and surface area scalar values can be saved in template space.
Two optional arguments can be provided to visualise the medial curve (plot_medial_curve), and later the projection (plot_projection) in order to check the quality of the medial curve and projection for every mesh.
Parallel processes: to avoid conflicts, subjects will be skipped if a “isrunning” tmp file exists to mark them as currently processing. The tmp file is removed at the end or replaced if 1 hour old. If a process has been interrupted, remove the tmp manually to rerun a subject before the 1 hour (its path is printed when flagged).
- Parameters:
inputdir (str, Path) – The sub_surfaces/ directory where the surface objects were outputted (using vol2surf()).
outputdir (str, Path) – The path where subcortical meshes with vertex-wise metrics assigned will be saved (will create a “surface_metrics” directory).
template (str) – The name of the template the surfaces are supposed to be matching to. For FreeSurfer outputs, it is ‘fsaverage’. For FSL FIRST, it is ‘fslfirst’.
toolboxdata (str, Path, optional) – The path of the “subcortexmesh_data” package data directory. The default path is assumed to be the user’s home directory (pathlib’s Path.home()). Users will be prompted to download it if not found.
metric (str, Sequence) – The name(s) of the metric(s) to be computed as strings. Options are “thickness”, “curvature”, “surfarea”, and default is all of them.
roilabel (str, Sequence) – The name(s) of the region(s)-of-interest to be computed as strings. Default is all subcortices across all segmentation templates: ‘left-cerebellum-cortex’, ‘right-cerebellum-cortex’, ‘left-pallidum’, ‘right-pallidum’, ‘left-putamen’, ‘right-putamen’, ‘left-thalamus’, ‘right-thalamus’,’left-amygdala’, ‘right-amygdala’, ‘left-hippocampus’, ‘right-hippocampus’, ‘left-accumbens-area’,’right-accumbens-area’,’left-caudate’, ‘right-caudate’, ‘left-ventraldc’, ‘right-ventraldc’, and ‘brain-stem’.
smooth (tuple) – The full-maximum half-width (FMHW) values that will be applied for smoothing each surface-based measure along the surface. 0 means no smoothing is applied. In the following order: thickness, surface area, curvature. There should be always three floats corresponding to that order, even if some metrics are not selected in the “metric” argument.
plot_medial_curve (bool) – Whether to plot the mesh and its computed medial curve. Default is False.
plot_projection (bool) – Whether to plot the subject-space mesh next to its template-space mesh. Default is False.
native_meshes (bool, optional) – Whether to save the meshes computed in subject space before they are projected to template space (they will contain one scalar for each metric). Default is False. overwrite must be True for this process to be accounted for.
overwrite (bool) – Whether files are to be overwritten or skipped if already in outputdir. Default is True.
silent (bool) – Whether messages about the process are to be printed. Default is False.