pyfsviz 0.1.1__py3-none-any.whl

pyfsviz/__init__.py

@@ -0,0 +1,26 @@
+"""pyFSViz package.
+
+Python tools for FreeSurfer visualization and QA
+"""
+
+from __future__ import annotations
+
+from pyfsviz import freesurfer, reports
+from pyfsviz._internal.cli import get_parser, main
+from pyfsviz.freesurfer import (
+    FreeSurfer,
+    get_freesurfer_colormap,
+)
+from pyfsviz.reports import (
+    Template,
+)
+
+__all__: list[str] = [
+    "FreeSurfer",
+    "Template",
+    "freesurfer",
+    "get_freesurfer_colormap",
+    "get_parser",
+    "main",
+    "reports",
+]

pyfsviz/__main__.py

@@ -0,0 +1,14 @@
+"""Entry-point module, in case you use `python -m pyfsviz`.
+
+Why does this file exist, and why `__main__`? For more info, read:
+
+- https://www.python.org/dev/peps/pep-0338/
+- https://docs.python.org/3/using/cmdline.html#cmdoption-m
+"""
+
+import sys
+
+from pyfsviz._internal.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

pyfsviz/_internal/cli.py

@@ -0,0 +1,59 @@
+# Why does this file exist, and why not put this in `__main__`?
+#
+# You might be tempted to import things from `__main__` later,
+# but that will cause problems: the code will get executed twice:
+#
+# - When you run `python -m pyfsviz` python will execute
+#   `__main__.py` as a script. That means there won't be any
+#   `pyfsviz.__main__` in `sys.modules`.
+# - When you import `__main__` it will get executed again (as a module) because
+#   there's no `pyfsviz.__main__` in `sys.modules`.
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from pyfsviz._internal import debug
+
+
+class _DebugInfo(argparse.Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        debug._print_debug_info()
+        sys.exit(0)
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Return the CLI argument parser.
+
+    Returns
+    -------
+    An argparse parser.
+    """
+    parser = argparse.ArgumentParser(prog="pyfsviz")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
+    parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
+    return parser
+
+
+def main(args: list[str] | None = None) -> int:
+    """Run the main program.
+
+    This function is executed when you type `pyfsviz` or `python -m pyfsviz`.
+
+    Parameters
+    ----------
+    args: Arguments passed from the command line.
+
+    Returns
+    -------
+    An exit code.
+    """
+    parser = get_parser()
+    opts = parser.parse_args(args=args)
+    print(opts)
+    return 0

pyfsviz/_internal/debug.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from importlib import metadata
+
+
+@dataclass
+class _Variable:
+    """Dataclass describing an environment variable."""
+
+    name: str
+    """Variable name."""
+    value: str
+    """Variable value."""
+
+
+@dataclass
+class _Package:
+    """Dataclass describing a Python package."""
+
+    name: str
+    """Package name."""
+    version: str
+    """Package version."""
+
+
+@dataclass
+class _Environment:
+    """Dataclass to store environment information."""
+
+    interpreter_name: str
+    """Python interpreter name."""
+    interpreter_version: str
+    """Python interpreter version."""
+    interpreter_path: str
+    """Path to Python executable."""
+    platform: str
+    """Operating System."""
+    packages: list[_Package]
+    """Installed packages."""
+    variables: list[_Variable]
+    """Environment variables."""
+
+
+def _interpreter_name_version() -> tuple[str, str]:
+    if hasattr(sys, "implementation"):
+        impl = sys.implementation.version
+        version = f"{impl.major}.{impl.minor}.{impl.micro}"
+        kind = impl.releaselevel
+        if kind != "final":
+            version += kind[0] + str(impl.serial)
+        return sys.implementation.name, version
+    return "", "0.0.0"
+
+
+def _get_version(dist: str = "pyfsviz") -> str:
+    """Get version of the given distribution.
+
+    Parameters
+    ----------
+        dist: A distribution name.
+
+    Returns
+    -------
+        A version number.
+    """
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+def _get_debug_info() -> _Environment:
+    """Get debug/environment information.
+
+    Returns
+    -------
+        Environment information.
+    """
+    py_name, py_version = _interpreter_name_version()
+    packages = ["pyfsviz"]
+    variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("PYFSVIZ")]]
+    return _Environment(
+        interpreter_name=py_name,
+        interpreter_version=py_version,
+        interpreter_path=sys.executable,
+        platform=platform.platform(),
+        variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))],  # ty: ignore[invalid-argument-type]
+        packages=[_Package(pkg, _get_version(pkg)) for pkg in packages],
+    )
+
+
+def _print_debug_info() -> None:
+    """Print debug/environment information."""
+    info = _get_debug_info()
+    print(f"- __System__: {info.platform}")
+    print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})")
+    print("- __Environment variables__:")
+    for var in info.variables:
+        print(f"  - `{var.name}`: `{var.value}`")
+    print("- __Installed packages__:")
+    for pkg in info.packages:
+        print(f"  - `{pkg.name}` v{pkg.version}")
+
+
+if __name__ == "__main__":
+    _print_debug_info()

pyfsviz/_internal/html/individual.html

@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="MRIQC" />
+<title>FreeSurfer: Individual Report</title>
+<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
+<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous"></script>
+<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
+
+<style type="text/css">
+body {
+  font-family: helvetica;
+  padding: 50px 10px 10px;
+}
+
+div.warning p.admonition-title, .code .error {
+  color: red ;
+  font-weight: bold ;
+}
+
+span.problematic {
+  color: red;
+  font-weight: bold ;
+}
+
+p.label {
+  white-space: nowrap }
+
+span.section-subtitle {
+  /* font-size relative to parent (h1..h6 element) */
+  font-size: 80% }
+
+div.embeded-report {
+  width: 100%;
+  page-break-before:always;
+  padding-top: 20px;
+}
+
+div.embeded-report svg { width: 100%; }
+
+div#accordionOther {
+    margin: 0 20px;
+}
+
+.add-padding {
+    padding-top: 15px;
+}
+
+#report-qi2-fitting {
+    max-width: 450px;
+}
+
+</style>
+</head>
+<body>
+<div class="document">
+
+<nav class="navbar fixed-top navbar-expand-lg navbar-light bg-light">
+<div class="collapse navbar-collapse">
+    <ul class="navbar-nav">
+      <li class="nav-item"><a class="nav-link" href="#summary">Summary</a></li>
+      <li class="nav-item"><a class="nav-link" href="#tlrc">Talairach Registration</a></li>
+      <li class="nav-item"><a class="nav-link" href="#aseg">Aparc+Aseg Parcellations</a></li>
+      <li class="nav-item"><a class="nav-link" href="#surf">Surfaces</a></li>
+    </ul>
+</div>
+</nav>
+<noscript>
+    <h1 class="text-danger"> The navigation menu uses Javascript. Without it this report might not work as expected </h1>
+</noscript>
+
+<h1 class="mt-5 mb-5">FreeSurfer: Individual Report</h1>
+
+<div class="card mt-3" style="width: 480pt;">
+    <h2 id="summary" class="card-header">Summary</h2>
+    <div class="card-body">
+        <ul class="simple">
+        <li>Date and time: {{ timestamp }}.</li>
+        </ul>
+    </div>
+</div>
+
+<h2 id="tlrc" class="mt-5 mb-2">Talairach Registration</h2>
+{% for tag in tlrc %}
+    <div class="card mt-2">
+        <div id="report-tlrc" class="card-body">
+        {{ tag }}
+        </div>
+    </div>
+{% endfor %}
+
+<h2 id="aseg" class="mt-5 mb-2">Aparc+Aseg Parcellations</h2>
+{% for tag in aseg %}
+    <div class="card mt-2">
+        <div id="report-aseg" class="card-body">
+        {{ tag }}
+        </div>
+    </div>
+{% endfor %}
+
+<h2 id="surf" class="mt-5 mb-2">Surfaces</h2>
+{% for label, tag in surf %}
+    <div class="card mt-2">
+        <h4 id="surf" class="mt-5 mb-2">{{ label }}</h4>
+        <div id="report-{{ label }}" class="card-body">
+        {{ tag }}
+        </div>
+    </div>
+{% endfor %}
+
+</div>
+</div>
+</div>
+
+
+</body>
+</html>

pyfsviz/freesurfer.py

@@ -0,0 +1,616 @@
+"""FreeSurfer data."""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import os
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from importlib_resources import files
+from matplotlib import colors
+from matplotlib import pyplot as plt
+from nilearn import plotting
+from nipype.interfaces.freesurfer import MRIConvert
+from nipype.interfaces.fsl import FLIRT
+from nireports.interfaces.reporting.base import SimpleBeforeAfterRPT
+
+from pyfsviz.reports import Template
+
+
+def get_freesurfer_colormap(freesurfer_home: Path | str) -> colors.ListedColormap:
+    """Generate matplotlib colormap from FreeSurfer LUT.
+
+    Code from:
+    https://github.com/Deep-MI/qatools-python/blob/freesurfer-module-releases/qatoolspython/createScreenshots.py
+
+    Parameters
+    ----------
+    freesurfer_home : path or str representing a path to a directory
+        Path corresponding to FREESURFER_HOME env var.
+
+    Returns
+    -------
+    colormap : matplotlib.colors.ListedColormap
+        A matplotlib compatible FreeSurfer colormap.
+
+    """
+    freesurfer_home = Path(freesurfer_home) if isinstance(freesurfer_home, str) else freesurfer_home
+    lut = pd.read_csv(
+        freesurfer_home / "FreeSurferColorLUT.txt",
+        sep=r"\s+",
+        comment="#",
+        header=None,
+        skipinitialspace=True,
+        skip_blank_lines=True,
+    )
+    lut = np.array(lut)
+    lut_tab = np.array(lut[:, (2, 3, 4, 5)] / 255, dtype="float32")
+    lut_tab[:, 3] = 1
+
+    return colors.ListedColormap(lut_tab)
+
+
+class FreeSurfer:
+    """Base class for FreeSurfer data."""
+
+    def __init__(
+        self,
+        freesurfer_home: str | None = None,
+        subjects_dir: str | None = None,
+        log_level: str = "INFO",
+    ):
+        """Initialize the FreeSurfer data.
+
+        Parameters
+        ----------
+        freesurfer_home : str representing a path to a directory
+            Path corresponding to FREESURFER_HOME env var.
+        subjects_dir : str representing a path to a directory
+            Path corresponding to SUBJECTS_DIR env var.
+        log_level : str
+            Logging level (e.g., "INFO", "DEBUG", "WARNING").
+            Default is "INFO".
+
+        Returns
+        -------
+        None
+
+        """
+        # Set up logger
+        logging.basicConfig(level=getattr(logging, log_level.upper()))
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+        """Logger for the FreeSurfer class."""
+
+        if freesurfer_home is None:
+            self.freesurfer_home = Path(os.environ.get("FREESURFER_HOME") or "")
+            """Path to the FreeSurfer home directory."""
+        else:
+            self.freesurfer_home = Path(freesurfer_home)
+            """Path to the FreeSurfer home directory."""
+        if not self.freesurfer_home.exists():
+            raise FileNotFoundError(f"FREESURFER_HOME not found: {self.freesurfer_home}")
+        if self.freesurfer_home is None:
+            raise ValueError("FREESURFER_HOME must be set")
+
+        if subjects_dir is None:
+            self.subjects_dir = Path(os.environ.get("SUBJECTS_DIR") or "")
+            """Path to the subjects directory."""
+        else:
+            self.subjects_dir = Path(subjects_dir)
+            """Path to the subjects directory."""
+        if not self.subjects_dir.exists():
+            raise FileNotFoundError(f"SUBJECTS_DIR not found: {self.subjects_dir}")
+        """Path to the subjects directory."""
+        self._mni_nii = files("pyfsviz._internal") / "mni305.cor.nii.gz"
+        """Path to the MNI template NIfTI file."""
+        self._mni_mgz = files("pyfsviz._internal") / "mni305.cor.mgz"
+        """Path to the MNI template MGH file."""
+
+    def get_colormap(self) -> colors.ListedColormap:
+        """Return the colormap for the FreeSurfer data."""
+        return get_freesurfer_colormap(self.freesurfer_home)
+
+    def get_subjects(self) -> list[str]:
+        """Return the subjects in the subjects directory."""
+        return [
+            subject.name
+            for subject in self.subjects_dir.iterdir()
+            if subject.is_dir() and (subject / "mri" / "transforms" / "talairach.lta").exists()
+        ]
+
+    def check_recon_all(self, subject: str) -> bool:
+        """Verify that the subject's FreeSurfer recon finished successfully."""
+        recon_file = self.subjects_dir / subject / "scripts" / "recon-all.log"
+
+        with open(recon_file, encoding="utf-8") as f:
+            line = f.readlines()[-1]
+            return "finished without error" in line
+
+    def gen_tlrc_data(self, subject: str, output_dir: str) -> None:
+        """Generate inverse talairach data for report generation.
+
+        Parameters
+        ----------
+        output_dir : str
+            Path for intermediate file output.
+
+        Examples
+        --------
+        >>> from pyfsviz.freesurfer import FreeSurfer
+        >>> fs_dir = FreeSurfer(
+        ...     freesurfer_home="/opt/freesurfer",
+        ...     subjects_dir="/opt/data",
+        ...     subject="sub-001",
+        ... )
+        >>> fs_dir.gen_tlrc_data("sub-001", Path("/opt/data/sub-001/mri/transforms"))
+        """
+        # get inverse transform
+        lta_file = self.subjects_dir / subject / "mri" / "transforms" / "talairach.xfm.lta"
+        xfm = np.genfromtxt(lta_file, skip_header=5, max_rows=4)
+        inverse_xfm = np.linalg.inv(xfm)
+        np.savetxt(
+            f"{output_dir}/inv.xfm",
+            inverse_xfm,
+            fmt="%0.8f",
+            delimiter=" ",
+            newline="\n",
+            encoding="utf-8",
+        )
+
+        # convert subject original T1 to nifti (for FSL)
+        convert = MRIConvert(
+            in_file=self.subjects_dir / subject / "mri" / "orig.mgz",
+            out_file=f"{output_dir}/orig.nii.gz",
+            out_type="niigz",
+        )
+        convert.run()
+
+        # use FSL to convert template file to subject original space
+        flirt = FLIRT(
+            in_file=self._mni_nii,
+            reference=f"{output_dir}/orig.nii.gz",
+            out_file=f"{output_dir}/mni2orig.nii.gz",
+            in_matrix_file=f"{output_dir}/inv.xfm",
+            apply_xfm=True,
+            out_matrix_file=f"{output_dir}/out.mat",
+        )
+        flirt.run()
+
+    def gen_tlrc_report(
+        self,
+        subject: str,
+        output_dir: str,
+        tlrc_dir: str | None = None,
+        *,
+        gen_data: bool = True,
+    ) -> Path:
+        """Generate a before and after report of Talairach registration. (Will also run file generation if needed).
+
+        Parameters
+        ----------
+        subject : str
+            Subject ID.
+        output_dir : str
+            Path to SVG output.
+        gen_data : bool
+            Generate inverse Talairach data, by default True
+        tlrc_dir : str | None
+            Path to output of `gen_tlrc_data`. Default is the subject's mri/transforms directory.
+
+        Returns
+        -------
+        Path:
+            SVG file generated from the niworkflows SimpleBeforeAfterRPT
+
+        Examples
+        --------
+        >>> from pyfsviz.freesurfer import FreeSurfer
+        >>> fs_dir = FreeSurfer(
+        ...     freesurfer_home="/opt/freesurfer",
+        ...     subjects_dir="/opt/data",
+        ...     subject="sub-001",
+        ... )
+        >>> report = fs_dir.gen_tlrc_report(
+        ...     "sub-001", Path("/opt/data/sub-001/mri/transforms")
+        ... )
+        """
+        if tlrc_dir is None:
+            tlrc_dir = f"{self.subjects_dir}/{subject}/mri/transforms"
+
+        mri_dir = f"{self.subjects_dir}/{subject}/mri"
+
+        if gen_data:
+            self.gen_tlrc_data(subject, tlrc_dir)
+
+        # use white matter segmentation to compare registrations
+        report = SimpleBeforeAfterRPT(
+            before=f"{mri_dir}/orig.mgz",
+            after=f"{tlrc_dir}/mni2orig.nii.gz",
+            wm_seg=f"{mri_dir}/wm.mgz",
+            before_label="Subject Orig",
+            after_label="Template",
+            out_report=f"{output_dir}/tlrc.svg",
+        )
+        result = report.run()
+        return result.outputs.out_report
+
+    def gen_aparcaseg_plots(self, subject: str, output_dir: str, num_imgs: int = 10) -> list[Path]:
+        """Generate parcellation images (aparc & aseg).
+
+        Parameters
+        ----------
+        output_dir : str
+            Path to output directory.
+        num_imgs : int
+            Number of images/slices to make.
+
+        Returns
+        -------
+        list
+            List of SVG image paths
+
+        Examples
+        --------
+        >>> from pyfsviz.freesurfer import FreeSurfer
+        >>> fs_dir = FreeSurfer(
+        ...     freesurfer_home="/opt/freesurfer",
+        ...     subjects_dir="/opt/data",
+        ...     subject="sub-001",
+        ... )
+        >>> images = fs_dir.gen_aparcaseg_plots(
+        ...     "sub-001", Path("/opt/data/sub-001/mri/transforms")
+        ... )
+        """
+        mri_dir = f"{self.subjects_dir}/{subject}/mri"
+        cmap = self.get_colormap()
+
+        # get parcellation and segmentation images
+        plotting.plot_roi(
+            f"{mri_dir}/aparc+aseg.mgz",
+            f"{mri_dir}/T1.mgz",
+            cmap=cmap,
+            display_mode="mosaic",
+            dim=-1,
+            cut_coords=num_imgs,
+            alpha=0.5,
+            output_file=f"{output_dir}/aseg.svg",
+        )
+        display = plotting.plot_anat(
+            f"{mri_dir}/brainmask.mgz",
+            display_mode="mosaic",
+            cut_coords=num_imgs,
+            dim=-1,
+        )
+        display.add_contours(
+            f"{mri_dir}/lh.ribbon.mgz",
+            colors="b",
+            linewidths=0.5,
+            levels=[0.5],
+        )
+        display.add_contours(
+            f"{mri_dir}/rh.ribbon.mgz",
+            colors="r",
+            linewidths=0.5,
+            levels=[0.5],
+        )
+        display.savefig(f"{output_dir}/aparc.svg")
+        display.close()
+
+        return [Path(f"{output_dir}/aseg.svg"), Path(f"{output_dir}/aparc.svg")]
+
+    def gen_surf_plots(self, subject: str, output_dir: str) -> list[Path]:
+        """Generate pial, inflated, and sulcal images from various viewpoints.
+
+        Parameters
+        ----------
+        output_dir : str
+            Surface plot output directory.
+
+        Returns
+        -------
+        list[Path]:
+            List of generated SVG images
+
+        Examples
+        --------
+        >>> from pyfsviz.freesurfer import FreeSurfer
+        >>> fs_dir = FreeSurfer(
+        ...     freesurfer_home="/opt/freesurfer",
+        ...     subjects_dir="/opt/data",
+        ...     subject="sub-001",
+        ... )
+        >>> images = fs_dir.gen_surf_plots("sub-001", Path("/opt/data/sub-001/surf"))
+        """
+        surf_dir = f"{self.subjects_dir}/{subject}/surf"
+        label_dir = f"{self.subjects_dir}/{subject}/label"
+        cmap = self.get_colormap()
+
+        hemis = {"lh": "left", "rh": "right"}
+        for key, val in hemis.items():
+            pial = f"{surf_dir}/{key}.pial"
+            inflated = f"{surf_dir}/{key}.inflated"
+            sulc = f"{surf_dir}/{key}.sulc"
+            white = f"{surf_dir}/{key}.white"
+            annot = f"{label_dir}/{key}.aparc.annot"
+
+            label_files = {pial: "pial", inflated: "infl", white: "white"}
+
+            for surf, label in label_files.items():
+                fig, axs = plt.subplots(2, 3, subplot_kw={"projection": "3d"})
+                plotting.plot_surf_roi(
+                    surf,
+                    annot,
+                    hemi=val,
+                    view="lateral",
+                    bg_map=sulc,
+                    bg_on_data=True,
+                    darkness=1,
+                    cmap=cmap,
+                    axes=axs[0, 0],
+                    figure=fig,
+                )
+                plotting.plot_surf_roi(
+                    surf,
+                    annot,
+                    hemi=val,
+                    view="medial",
+                    bg_map=sulc,
+                    bg_on_data=True,
+                    darkness=1,
+                    cmap=cmap,
+                    axes=axs[0, 1],
+                    figure=fig,
+                )
+                plotting.plot_surf_roi(
+                    surf,
+                    annot,
+                    hemi=val,
+                    view="dorsal",
+                    bg_map=sulc,
+                    bg_on_data=True,
+                    darkness=1,
+                    cmap=cmap,
+                    axes=axs[0, 2],
+                    figure=fig,
+                )
+                plotting.plot_surf_roi(
+                    surf,
+                    annot,
+                    hemi=val,
+                    view="ventral",
+                    bg_map=sulc,
+                    bg_on_data=True,
+                    darkness=1,
+                    cmap=cmap,
+                    axes=axs[1, 0],
+                    figure=fig,
+                )
+                plotting.plot_surf_roi(
+                    surf,
+                    annot,
+                    hemi=val,
+                    view="anterior",
+                    bg_map=sulc,
+                    bg_on_data=True,
+                    darkness=1,
+                    cmap=cmap,
+                    axes=axs[1, 1],
+                    figure=fig,
+                )
+                plotting.plot_surf_roi(
+                    surf,
+                    annot,
+                    hemi=val,
+                    view="posterior",
+                    bg_map=sulc,
+                    bg_on_data=True,
+                    darkness=1,
+                    cmap=cmap,
+                    axes=axs[1, 2],
+                    figure=fig,
+                )
+
+                plt.savefig(f"{output_dir}/{key}_{label}.svg", dpi=300, format="svg")
+                plt.close()
+
+        return sorted(Path(output_dir).glob("*svg"))
+
+    def gen_html_report(
+        self,
+        subject: str,
+        output_dir: str,
+        img_out: str | None = None,
+        template: str | None = None,
+    ) -> Path:
+        """Generate html report with FreeSurfer images.
+
+        Parameters
+        ----------
+        subject : str
+            Subject ID.
+        output_dir : str
+            HTML file name
+        img_out : str | None
+            Location where SVG images are saved, default is subject's data directory.
+        template : str | None
+            HTML template to use. Default is local freesurfer.html.
+
+        Returns
+        -------
+        Path:
+            Path to html file.
+
+        Examples
+        --------
+        >>> from pyfsviz.freesurfer import FreeSurfer
+        >>> fs_dir = FreeSurfer(
+        ...     freesurfer_home="/opt/freesurfer",
+        ...     subjects_dir="/opt/data",
+        ...     subject="sub-001",
+        ... )
+        >>> report = fs_dir.gen_html_report(out_name="sub-001.html", output_dir=".")
+        """
+        if template is None:
+            template = files("pyfsviz._internal.html") / "individual.html"
+        if img_out is None:
+            image_list = list((self.subjects_dir / subject).glob("*/*svg"))
+        else:
+            image_list = list(Path(img_out).glob("*svg"))
+
+        tlrc = []
+        aseg = []
+        surf = []
+
+        for img in image_list:
+            with open(img, encoding="utf-8") as img_file:
+                img_data = img_file.read()
+
+            if "tlrc" in img.name:
+                tlrc.append(img_data)
+            elif "aseg" in img.name or "aparc" in img.name:
+                aseg.append(img_data)
+            else:
+                labels = {
+                    "lh_pial": "LH Pial",
+                    "rh_pial": "RH Pial",
+                    "lh_infl": "LH Inflated",
+                    "rh_infl": "RH Inflated",
+                    "lh_white": "LH White Matter",
+                    "rh_white": "RH White Matter",
+                }
+                surf_tuple = (labels[img.stem], img_data)
+                surf.append(surf_tuple)
+
+        _config = {
+            "timestamp": datetime.datetime.now(tz=datetime.timezone.utc).strftime("%Y-%m-%d, %H:%M"),
+            "subject": subject,
+            "tlrc": tlrc,
+            "aseg": aseg,
+            "surf": surf,
+        }
+
+        tpl = Template(str(template))
+        tpl.generate_conf(_config, f"{output_dir}/{subject}.html")
+
+        return Path(output_dir) / f"{subject}.html"
+
+    def gen_batch_reports(
+        self,
+        output_dir: str | Path,
+        subjects: list[str] | None = None,
+        template: str | None = None,
+        *,
+        gen_images: bool = True,
+        skip_failed: bool = True,
+    ) -> dict[str, Path | Exception]:
+        """Generate HTML reports with images for multiple subjects.
+
+        This method first generates all required images (TLRC, aparc+aseg, surfaces)
+        and then creates HTML reports for each subject.
+
+        Parameters
+        ----------
+        output_dir : str or Path
+            Directory where HTML reports will be saved.
+        subjects : list[str] or None
+            List of subject IDs to process. If None, processes all subjects
+            in the subjects directory.
+        template : str or None
+            HTML template to use. Default is local individual.html.
+        gen_images : bool
+            Generate images for each subject. Default is True.
+        skip_failed : bool
+            If True, continues processing other subjects if one fails.
+            If False, raises exception on first failure.
+
+        Returns
+        -------
+        dict[str, Path | Exception]
+            Dictionary mapping subject IDs to either the generated HTML file
+            path or the exception that occurred during processing.
+
+        Examples
+        --------
+        >>> from pyfsviz.freesurfer import FreeSurfer
+        >>> fs = FreeSurfer()
+        >>> results = fs.gen_batch_reports("reports/", log_level="INFO")
+        >>> for subject, result in results.items():
+        ...     if isinstance(result, Path):
+        ...         print(f"Generated report for {subject}: {result}")
+        ...     else:
+        ...         print(f"Failed to generate report for {subject}: {result}")
+        """
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        if subjects is None:
+            subjects = self.get_subjects()
+
+        self.logger.info(f"Generating reports with images for {len(subjects)} subjects...")
+        self.logger.info(f"Output directory: {output_dir}")
+
+        results: dict[str, Path | Exception] = {}
+
+        for i, subject in enumerate(subjects, 1):
+            self.logger.info(f"[{i}/{len(subjects)}] Processing subject: {subject}")
+
+            try:
+                # Check if recon-all completed successfully
+                if not self.check_recon_all(subject):
+                    self.logger.warning(f"Subject {subject} recon-all did not complete successfully")
+
+                # Create subject-specific output directory for images
+                subject_output_dir = output_dir / subject
+                subject_output_dir.mkdir(parents=True, exist_ok=True)
+
+                # Generate images
+                self.logger.info(f"  Generating images for {subject}...")
+
+                if gen_images:
+                    # Generate TLRC data and report
+                    tlrc_dir = subject_output_dir / "tlrc"
+                    tlrc_dir.mkdir(parents=True, exist_ok=True)
+                    self.gen_tlrc_data(subject, str(tlrc_dir))
+                    self.gen_tlrc_report(subject, str(tlrc_dir))
+
+                    # Generate aparc+aseg plots
+                    aparc_dir = subject_output_dir / "aparcaseg"
+                    aparc_dir.mkdir(parents=True, exist_ok=True)
+                    self.gen_aparcaseg_plots(subject, str(aparc_dir))
+
+                    # Generate surface plots
+                    surf_dir = subject_output_dir / "surfaces"
+                    surf_dir.mkdir(parents=True, exist_ok=True)
+                    self.gen_surf_plots(subject, str(surf_dir))
+
+                # Generate HTML report using all generated images
+                html_file = self.gen_html_report(
+                    subject=subject,
+                    output_dir=str(output_dir),
+                    img_out=str(subject_output_dir),
+                    template=template,
+                )
+
+                results[subject] = html_file
+
+                self.logger.info(f"  ✓ Generated report with images: {html_file}")
+
+            except Exception as e:
+                error_msg = f"Failed to generate report with images for {subject}: {e!s}"
+                results[subject] = e
+
+                self.logger.error(f"  ✗ {error_msg}")  # noqa: TRY400
+
+                if not skip_failed:
+                    raise e  # noqa: TRY201 # pylint: disable=try-except-raise
+
+        successful = sum(1 for result in results.values() if isinstance(result, Path))
+        failed = len(results) - successful
+        self.logger.info("\nBatch report generation with images completed:")
+        self.logger.info(f"  Successful: {successful}")
+        self.logger.info(f"  Failed: {failed}")
+
+        return results

pyfsviz/reports.py

@@ -0,0 +1,48 @@
+# Copyright 2025 Lezlie España <www.github.com/l-espana>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Utility class for generating a config file from a jinja template.
+
+https://github.com/oesteban/endofday/blob/f2e79c625d648ef45b08cc1f11fd0bd84342d604/endofday/core/template.py.
+
+Along with other report-related functions.
+
+"""
+
+import jinja2
+
+
+class Template:
+    """Simplified jinja2 template class from oesteban."""
+
+    def __init__(self, template_str: str) -> None:
+        self._template_str = template_str
+        self._env = jinja2.Environment(
+            loader=jinja2.FileSystemLoader(searchpath="/"),
+            trim_blocks=True,
+            lstrip_blocks=True,
+            autoescape=True,
+        )
+
+    def compile(self, configs: dict) -> str:
+        """Generate a string with the replacements."""
+        template = self._env.get_template(self._template_str)
+        return template.render(configs)
+
+    def generate_conf(self, configs: dict, path: str) -> None:
+        """Save the outcome after replacement on the template to file."""
+        output = self.compile(configs)
+        with open(path, "w+", encoding="utf-8") as output_file:
+            output_file.write(output)

pyfsviz-0.1.1.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: pyfsviz
+Version: 0.1.1
+Summary: Python tools for FreeSurfer visualization and QA
+Author-Email: Lezlie Espana <lespana@mcw.edu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://mcw-meier-lab.github.io/pyFSViz
+Project-URL: Documentation, https://mcw-meier-lab.github.io/pyFSViz
+Project-URL: Changelog, https://mcw-meier-lab.github.io/pyFSViz/changelog
+Project-URL: Repository, https://github.com/mcw-meier-lab/pyFSViz
+Project-URL: Issues, https://github.com/mcw-meier-lab/pyFSViz/issues
+Project-URL: Discussions, https://github.com/mcw-meier-lab/pyFSViz/discussions
+Requires-Python: >=3.10
+Requires-Dist: importlib-resources>=6.5.2
+Requires-Dist: matplotlib>=3.9.4
+Requires-Dist: nilearn>=0.12.1
+Requires-Dist: nipype>=1.10.0
+Requires-Dist: nireports>=25.0.1
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: plotly>=6.3.1
+Description-Content-Type: text/markdown
+
+# pyFSViz
+
+[![ci](https://github.com/mcw-meier-lab/pyFSViz/workflows/ci/badge.svg)](https://github.com/mcw-meier-lab/pyFSViz/actions?query=workflow%3Aci)
+[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://mcw-meier-lab.github.io/pyFSViz/)
+[![pypi version](https://img.shields.io/pypi/v/pyfsviz.svg)](https://pypi.org/project/pyfsviz/)
+
+Python tools for FreeSurfer visualization and QA
+
+## Installation
+
+```bash
+pip install pyfsviz
+```
+
+With [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install pyfsviz
+```

pyfsviz-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+pyfsviz-0.1.1.dist-info/METADATA,sha256=pqEjcd4Wso3eiKAW9IOayReb83p_bXaGWS25WVCPai4,2119
+pyfsviz-0.1.1.dist-info/WHEEL,sha256=9P2ygRxDrTJz3gsagc0Z96ukrxjr-LFBGOgv3AuKlCA,90
+pyfsviz-0.1.1.dist-info/entry_points.txt,sha256=cre399MbfrIUVQUwxNKa1ur6ne0s-CkD6_tRL80fKgE,71
+pyfsviz-0.1.1.dist-info/licenses/LICENSE,sha256=Ey0-DGBtdr06UFzAOHz4YEyp8SSCHHkanQy5T2b7Vlc,1070
+pyfsviz/__init__.py,sha256=w7v2Fen3VPhL2hKJ2Mdvhgybcn1REPnHkNL9SJCEZng,482
+pyfsviz/__main__.py,sha256=h_atneBM9iWXrAHRSGS20eaPSCKpWP50_2MBMnXO6wo,349
+pyfsviz/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyfsviz/_internal/cli.py,sha256=Hs-pypt6Mgg2373TLqCrCZH-6Eh3xxDGqWxtJ0hM8_g,1699
+pyfsviz/_internal/debug.py,sha256=FaBMWd86h58Rl05q4wwGkt7XSnZJYIAeUdJt3z4OByQ,2882
+pyfsviz/_internal/html/individual.html,sha256=-QJkMm-0pV_cEUHy3ziTzMohe1Kq-fI9NHfp4bv7QAw,3567
+pyfsviz/_internal/mni305.cor.mgz,sha256=U1i2rb8Y1cQrJysZvc3aGo8osdXOS3GdU56G810XN-k,3285041
+pyfsviz/_internal/mni305.cor.nii.gz,sha256=M9Li-7fXl0RoZyF3Re8HQnsNLrz-hgWC8-4YfHma6Yo,3295839
+pyfsviz/freesurfer.py,sha256=hhGgeEMKJUSJersRKBZPmmbcwbMd7mzXgp9aUmTXQLc,21116
+pyfsviz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyfsviz/reports.py,sha256=uJh0mjNCtORWZDrMYarqCgM1Eva-iYhjd2yGPXhKEvs,1703
+pyfsviz-0.1.1.dist-info/RECORD,,

pyfsviz-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.5)
+Root-Is-Purelib: true
+Tag: py3-none-any

pyfsviz-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+pyfsviz = pyfsviz._internal.cli:main
+
+[gui_scripts]
+

pyfsviz-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mcw-meier-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.