merge_tools

subcortexmesh.merge_tools.merge_all(inputdir: str | Path, template: str, toolboxdata: str | Path | None = None, metric: str | Sequence[str] = ['thickness', 'curvature', 'surfarea'], plot_merged: bool = False, overwrite: bool = True, silent: bool = False)[source]

Merging all subcortical outputs into a single surface object

This function creates a new mesh merging all subcortical meshes outputted by mesh_metrics() in a given template, for available metrics separately, keeping their vertex-wise values. It will only work if all subcortices have been processed. The merged mesh will be saved along the surface meshes in the directories used as input.

For fslfirst, the cerebella need to have been created in FSL FIRST inside the same output directory as run_first_all’s, naming them “*R_Cereb_first” and “*L_Cereb_first”, and processed with subseg_getvol() and vol2surf(). See subseg_getvol()’s description for guidance.

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 path where the surface-based metrics were outputted (using mesh_metrics()). The outputdir will be the inputdir.

  • 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.

  • plot_merged (bool) – Whether to plot the resulting merged mesh. Default is False.

  • overwrite (bool) – Whether files are to be overwritten or skipped if already made. Default is True.

  • silent (bool) – Whether messages about the process are to be printed. Default is False.

subcortexmesh.merge_tools.vis_merged(merged_vtk: str | Path | vtk.vtkPolyData, cmap: str = 'viridis', clim: Tuple[float, float] | None = None, smooth_mesh: int | None = 0)[source]

Interactive 3D viewer for a merged subcortical surface.

Loads a merged mesh produced by merge_all(), separates ROIs by roi_id, and displays them with a slider to spread the structures apart from their global centroid.

Authors: Charly H.A. Billaud, Nicolas P.M. Lavarde

Parameters:

  • merged_vtk (str, Path, vtk.vtkPolyData) – Path to the merged .vtk file produced by merge_all() or the VTK polydata variable itself

  • cmap (str) – Name of the color map to be assigned to the background volume, as listed in matplotlib’s colormaps. Default is “viridis”.

  • clim (Tuple, optional) – Sequence of float stating the minimum and maximum value of the color bar. Default is minimum and maximum value.

  • smooth_mesh (int, optional) – Number of iterations of cosmetic smoothing to make the surface appear smoother. Default is 0.

subcortexmesh.merge_tools.vis_merged_flat(merged_vtk: str | Path | vtk.vtkPolyData, output_path: str | Path = 'flat_plot.png', ncols: int = 4, silent: bool = False, scalars: str = None, cmap: str = 'viridis', clim: Tuple[float, float] | None = None, smooth_mesh: int | None = 0, toolboxdata: str | Path | None = None)[source]

Flat 2D grid preview of all subcortical ROIs from a merged VTK surface

Reads a merged .vtk file produced by merge_all() which contains all subcortical structures concatenated into a single mesh, where each ROI was assigned a number ID. For each ROI, the corresponding sub-mesh is extracted, centered, and placed in a 2D grid layout saved as PNG. The layout is paired (left/right structures in adjacent columns); in a top and bottom views.

Authors: Nicolas P.M. Lavarde, Charly H.A. Billaud

Parameters:

  • merged_vtk (str, Path, vtk.vtkPolyData) – Path to the merged .vtk file produced by merge_all().

  • output_path (str, Path) – Path for the output PNG file. Default is ‘flat_plot_preview.png’.

  • ncols (int) – Number of columns in the grid layout. Default is 4.

  • silent (bool) – Whether to suppress progress messages. Default is False.

  • scalars (str) – Name of the vertex-wise value which was assigned. Default is whatever measure was assigned by mesh_metrics() (‘thickness’, ‘curvature’, or ‘surfarea’). Can also be the ‘roi_id’ assigned by merge_all().

  • cmap (str) – Name of the color map to be assigned to the background volume, as listed in matplotlib’s colormaps. Default is “viridis”.

  • clim (Tuple, optional) – Sequence of float stating the minimum and maximum value of the color bar. Default is minimum and maximum value.

  • smooth_mesh (int, optional) – Number of iterations of cosmetic smoothing to make the surface appear smoother. Default is 0.

  • 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.