bsplot 0.0.2__py3-none-any.whl

bsplot/templates.py

@@ -0,0 +1,270 @@
+"""Neuroimaging template volumes, downloaded on first access to ~/.bsplot/templates/."""
+
+import urllib.request
+from pathlib import Path
+
+import templateflow.api as tflow
+
+from bsplot import datadir
+
+_CACHE_DIR = Path.home() / ".bsplot" / "templates"
+_LEGACY_DIR = Path(datadir)
+
+
+# ---------------------------------------------------------------------------
+# Core infrastructure
+# ---------------------------------------------------------------------------
+
+
+def _download(url: str, dest: Path, label: str = "") -> None:
+    """Download *url* → *dest* with a progress bar."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(".part")
+    print(f"Downloading {label} from\n  {url}")
+    try:
+        resp = urllib.request.urlopen(url)
+        total = int(resp.headers.get("Content-Length", 0))
+        done = 0
+        with open(tmp, "wb") as f:
+            while chunk := resp.read(1 << 20):
+                f.write(chunk)
+                done += len(chunk)
+                if total:
+                    print(f"\r  {done/1e6:.1f}/{total/1e6:.1f} MB ({done/total*100:.0f}%)",
+                          end="", flush=True)
+        print()
+        tmp.rename(dest)
+    except Exception:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+class Template:
+    """A remote neuroimaging template with multiple resolutions.
+
+    Acts as an ``os.PathLike`` for the default resolution (lazy download),
+    so it can be passed directly to ``nibabel.load()`` or ``plot_slice()``.
+
+    Parameters
+    ----------
+    name : str
+        Human-readable name shown in progress messages and repr.
+    files : dict[str, tuple[str, str]]
+        ``{resolution: (filename, url)}`` for every available variant.
+    default : str
+        Key into *files* used when the template is accessed as a path.
+    migrate_legacy : bool
+        If True, check ``bsplot/data/`` for a bundled copy before downloading.
+    postprocess : callable or None
+        ``f(raw_path) -> derived_path``.  Called once after the first
+        download to create a derived file (e.g. background-masked).
+        The *derived* path is what ``get()`` returns.
+    """
+
+    def __init__(self, name: str, files: dict, default: str, *,
+                 migrate_legacy: bool = False, postprocess=None):
+        self._name = name
+        self._files = files
+        self._default = default
+        self._migrate = migrate_legacy
+        self._postprocess = postprocess
+        self._resolved: dict[str, Path] = {}
+
+    # -- public API ---------------------------------------------------------
+
+    @property
+    def resolutions(self) -> list[str]:
+        """Available resolution strings."""
+        return list(self._files)
+
+    def get(self, resolution: str | None = None) -> Path:
+        """Return the path for *resolution*, downloading if necessary.
+
+        If a ``postprocess`` function was provided, returns the derived
+        (post-processed) path.  Use :meth:`get_raw` for the original.
+        """
+        res = resolution or self._default
+        if res in self._resolved:
+            return self._resolved[res]
+        raw = self._get_raw(res)
+
+        # Post-processing: create a derived file once, return it instead
+        if self._postprocess is not None:
+            derived = self._postprocess(raw)
+            self._resolved[res] = derived
+            return derived
+
+        self._resolved[res] = raw
+        return raw
+
+    def get_raw(self, resolution: str | None = None) -> Path:
+        """Return the raw (unprocessed) path, bypassing any postprocess."""
+        return self._get_raw(resolution or self._default)
+
+    def _get_raw(self, res: str) -> Path:
+        if res not in self._files:
+            raise ValueError(
+                f"Unknown resolution '{res}' for {self._name}. "
+                f"Choose from {self.resolutions}."
+            )
+        fname, url = self._files[res]
+        path = _CACHE_DIR / fname
+
+        if not path.exists():
+            legacy = _LEGACY_DIR / fname
+            if self._migrate and legacy.exists():
+                path.parent.mkdir(parents=True, exist_ok=True)
+                legacy.rename(path)
+            else:
+                _download(url, path, label=f"{self._name} ({res})")
+
+        return path
+
+    # -- os.PathLike (default resolution, lazy) -----------------------------
+
+    def __fspath__(self) -> str:
+        return str(self.get())
+
+    def __str__(self) -> str:
+        return str(self.get())
+
+    def __repr__(self) -> str:
+        return f"Template({self._name!r}, default={self._default!r})"
+
+    def __truediv__(self, other):
+        return self.get() / other
+
+
+class TFlowTemplate:
+    """A TemplateFlow-backed template, lazily resolved on first access.
+
+    Acts as ``os.PathLike`` so it can be passed directly to ``plot_slice()``
+    or ``nibabel.load()``.
+
+    Parameters
+    ----------
+    name : str
+        Human-readable name shown in repr.
+    template : str
+        TemplateFlow template ID, e.g. ``"MNI152NLin2009cAsym"``.
+    suffix : str
+        BIDS suffix, e.g. ``"T1w"``, ``"T2w"``, ``"mask"``.
+    desc : str or None
+        BIDS desc entity, e.g. ``"brain"``.
+    resolution : int
+        Resolution index (TemplateFlow convention).
+    """
+
+    def __init__(self, name: str, template: str, suffix: str,
+                 desc: str | None = None, resolution: int = 1):
+        self._name = name
+        self._template = template
+        self._suffix = suffix
+        self._desc = desc
+        self._resolution = resolution
+        self._path: Path | None = None
+
+    def get(self, resolution: int | None = None) -> Path:
+        """Return the path, downloading via TemplateFlow if necessary."""
+        res = resolution or self._resolution
+        # Always re-resolve if a different resolution is requested
+        if self._path is not None and res == self._resolution:
+            return self._path
+        kwargs = dict(
+            resolution=res, suffix=self._suffix, extension=".nii.gz"
+        )
+        if self._desc is not None:
+            kwargs["desc"] = self._desc
+        result = tflow.get(self._template, **kwargs)
+        if isinstance(result, list):
+            result = result[0]
+        path = Path(result)
+        if res == self._resolution:
+            self._path = path
+        return path
+
+    def __fspath__(self) -> str:
+        return str(self.get())
+
+    def __str__(self) -> str:
+        return str(self.get())
+
+    def __repr__(self) -> str:
+        parts = [self._template, self._suffix]
+        if self._desc:
+            parts.append(f"desc-{self._desc}")
+        return f"TFlowTemplate({', '.join(parts)})"
+
+    def __truediv__(self, other):
+        return self.get() / other
+
+
+# ---------------------------------------------------------------------------
+# Template definitions
+# ---------------------------------------------------------------------------
+
+_BB = "https://ftp.bigbrainproject.org/bigbrain-ftp/BigBrainRelease.2015/3D_Volumes/MNI-ICBM152_Space/nii"
+_DD = "https://datadryad.org/downloads/file_stream"
+
+# ---------------------------------------------------------------------------
+# MNI 152 templates (via TemplateFlow — handles its own caching)
+# ---------------------------------------------------------------------------
+
+# MNI152NLin2009cAsym (ICBM 2009c, asymmetric — most common)
+mni09c          = TFlowTemplate("MNI152 2009c T1w brain",  "MNI152NLin2009cAsym", "T1w",  desc="brain")
+mni09c_T1w      = mni09c  # alias
+mni09c_T2w      = TFlowTemplate("MNI152 2009c T2w",       "MNI152NLin2009cAsym", "T2w")
+mni09c_mask     = TFlowTemplate("MNI152 2009c brain mask", "MNI152NLin2009cAsym", "mask", desc="brain")
+
+# MNI152NLin2009cSym (ICBM 2009c, symmetric)
+mni09c_sym      = TFlowTemplate("MNI152 2009c sym T1w brain", "MNI152NLin2009cSym", "T1w", desc="brain")
+mni09c_sym_T2w  = TFlowTemplate("MNI152 2009c sym T2w",      "MNI152NLin2009cSym", "T2w")
+
+# MNI152NLin6Asym (6th generation — FSL/SPM default)
+mni6            = TFlowTemplate("MNI152 6th gen T1w brain", "MNI152NLin6Asym", "T1w", desc="brain")
+mni6_T1w        = mni6  # alias
+mni6_T2w        = TFlowTemplate("MNI152 6th gen T2w",      "MNI152NLin6Asym", "T2w")
+mni6_mask       = TFlowTemplate("MNI152 6th gen brain mask","MNI152NLin6Asym", "mask", desc="brain")
+
+# ---------------------------------------------------------------------------
+# BigBrain histological volume (8-bit, MNI ICBM 152 2009b sym)
+# Amunts et al. (2013) Science 340(6139):1472–1475
+# The raw volume has the background at max intensity — postprocess replaces
+# max → NaN so the background is transparent when plotting.
+
+def _bigbrain_mask_background(raw_path: Path) -> Path:
+    """Replace background (max intensity) with NaN; cache result on disk."""
+    import nibabel as nib
+    import numpy as np
+
+    masked_path = raw_path.with_name(raw_path.name.replace(".nii", "_masked.nii"))
+    if masked_path.exists():
+        return masked_path
+    print(f"  Masking BigBrain background (max → NaN) …")
+    img = nib.load(raw_path)
+    data = img.get_fdata()
+    out = np.where(data == data.max(), np.nan, data).astype(np.float32)
+    new_img = nib.Nifti1Image(out, img.affine)
+    new_img.header.set_data_dtype(np.float32)
+    nib.save(new_img, masked_path)
+    return masked_path
+
+
+bigbrain = Template("BigBrain", {
+    "100um": ("full8_100um_2009b_sym.nii.gz",  f"{_BB}/full8_100um_2009b_sym.nii.gz"),   # 1.1 GB
+    "200um": ("full8_200um_2009b_sym.nii.gz",  f"{_BB}/full8_200um_2009b_sym.nii.gz"),   # 149 MB
+    "300um": ("full8_300um_2009b_sym.nii.gz",  f"{_BB}/full8_300um_2009b_sym.nii.gz"),   # 46 MB
+    "400um": ("full8_400um_2009b_sym.nii.gz",  f"{_BB}/full8_400um_2009b_sym.nii.gz"),   # 20 MB
+}, default="300um", postprocess=_bigbrain_mask_background)
+
+# Synthesized FLASH25 ex-vivo 7T MRI in MNI space (CC0)
+# Edlow et al. (2019) Scientific Data 6:244
+flash25 = Template("FLASH25", {
+    "100um": ("Synthesized_FLASH25_in_MNI_v2_100um.nii.gz", f"{_DD}/182487"),  # 4.7 GB
+    "200um": ("Synthesized_FLASH25_in_MNI_v2_200um.nii.gz", f"{_DD}/182488"),  # 1.15 GB
+    "500um": ("Synthesized_FLASH25_in_MNI_v2_500um.nii.gz", f"{_DD}/182489"),  # 74 MB
+}, default="500um", migrate_legacy=True)
+
+# Convenience aliases for backwards compatibility
+get_bigbrain = bigbrain.get
+get_flash25 = flash25.get

bsplot/text.py

@@ -0,0 +1,199 @@
+import black
+import matplotlib.pyplot as plt
+from pygments.lexers import PythonLexer, get_lexer_by_name
+from pygments.styles import get_style_by_name
+import textwrap
+
+
+def _wrap_lines(text: str, line_length: int) -> str:
+    """Wrap long lines in text while preserving structure for non-Python code."""
+    lines = text.splitlines()
+    wrapped_lines = []
+
+    for line in lines:
+        if len(line) <= line_length:
+            wrapped_lines.append(line)
+        else:
+            wrapped = textwrap.fill(
+                line,
+                width=line_length,
+                break_long_words=True,
+                break_on_hyphens=True,
+                expand_tabs=False,
+                replace_whitespace=False,
+            )
+            wrapped_lines.extend(wrapped.splitlines())
+
+    return "\n".join(wrapped_lines)
+
+
+def draw_code(
+    ax,
+    code: str,
+    fontsize=7,
+    bg=None,
+    style="monokai",
+    language: str = "python",
+    line_length=60,
+    line_height=None,
+    char_width=0.015,
+):
+    """Render syntax-highlighted code (Python by default) inside a matplotlib axis.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Axis to draw on.
+    code : str
+        Source code string to render.
+    fontsize : int, optional
+        Font size for text (default 7).
+    bg : str | None, optional
+        Background face color. If None, uses the selected Pygments style's
+        background color; if unavailable, falls back to the current Matplotlib
+        axes facecolor (rcParams["axes.facecolor"]).
+    style : str, optional
+        Pygments style name (default 'monokai'). See ``pygments.styles.STYLE_MAP``.
+    language : str, optional
+        Lexer language (``python``, ``yaml``, ``json``, ``bash``, etc.). If ``python``
+        the code is first formatted with *black*. For other languages the string is
+        used as-is (black is skipped to avoid syntax errors).
+    line_length : int, optional
+        Maximum line length for formatting (default 60). For Python, this is passed
+        to black formatter. For other languages, long lines are wrapped at word
+        boundaries when possible.
+    line_height : float, optional
+        Fixed line height as fraction of axis height (each row's vertical advance).
+        If None, the available space between equal top/bottom padding is divided
+        equally over the number of rendered lines.
+    char_width : float, optional
+        Approximate width advance per character (fraction of axis width). If None, defaults to 0.015.
+
+    Notes
+    -----
+    - Backwards compatible: existing calls without new parameters behave identically.
+    - For long code blocks, consider reducing ``fontsize`` or adjusting ``line_length``.
+    """
+    # Setup
+    ax.set_xlim(0, 1)
+    ax.set_ylim(0, 1)
+
+    # Resolve Pygments style early (avoid shadowing the style parameter)
+    style_name = style
+    pyg_style = get_style_by_name(style_name)
+
+    # Resolve background color preference: Pygments style -> Matplotlib rcParams -> fallback
+    if bg is None:
+        bg_color = getattr(pyg_style, "background_color", None)
+        if not bg_color:
+            bg_color = plt.rcParams.get("axes.facecolor", "#ffffff")
+    else:
+        bg_color = bg
+
+    ax.add_patch(
+        plt.Rectangle((0, 0), 1, 1, facecolor=bg_color, edgecolor=None, linewidth=0.5)
+    )
+
+    # Select lexer & format code
+    if language.lower() == "python":
+        formatted_code = black.format_str(
+            code, mode=black.Mode(line_length=line_length)
+        )
+        lexer = PythonLexer()
+    else:
+        # Apply line wrapping for non-Python languages
+        formatted_code = _wrap_lines(code, line_length)
+        lexer = get_lexer_by_name(language.lower())
+
+    tokens = list(lexer.get_tokens(formatted_code))
+
+    # Use built-in Pygments style (already resolved as pyg_style)
+
+    def get_token_color(token_type):
+        """Get hex color for a token using the active Pygments style.
+
+        Uses normalized style attributes (pyg_style._styles) and walks up the
+        token hierarchy. Returns a hex color string or None if unspecified.
+        """
+        from pygments.token import Token as PygToken
+
+        def normalize(col: str | None) -> str | None:
+            if not col:
+                return None
+            return col if col.startswith("#") else f"#{col}"
+
+        cur = token_type
+        while cur is not None:
+            attrs = pyg_style._styles.get(cur)
+            if attrs:
+                col = normalize(attrs[0])  # first field is the foreground color
+                if col:
+                    return col
+            cur = cur.parent
+
+        # Try the generic Token entry
+        attrs = pyg_style._styles.get(PygToken)
+        if attrs:
+            col = normalize(attrs[0])
+            if col:
+                return col
+
+        return None
+
+    # Build lines from tokens
+    def build_lines(tokens):
+        lines, current_line = [], []
+        for token_type, value in tokens:
+            if "\n" not in value:
+                current_line.append((token_type, value))
+            else:
+                parts = value.split("\n")
+                if parts[0]:
+                    current_line.append((token_type, parts[0]))
+                lines.append(current_line)
+
+                for part in parts[1:-1]:
+                    lines.append([(token_type, part)] if part else [])
+
+                current_line = [(token_type, parts[-1])] if parts[-1] else []
+
+        if current_line:
+            lines.append(current_line)
+        return lines
+
+    # Render with adaptive spacing
+    lines = build_lines(tokens)
+    if not lines:
+        return
+
+    padding = 0.02
+    x_start = padding
+    y_start = 1 - padding
+
+    if char_width is None:
+        char_width = 0.015
+
+    if line_height is None:
+        usable_height = max(0.0, 1 - 2 * padding)
+        row_height = usable_height / len(lines) if len(lines) else usable_height
+    else:
+        row_height = line_height
+
+    for i, line_tokens in enumerate(lines):
+        y_pos = y_start - i * row_height
+        x_pos = x_start
+        for token_type, value in line_tokens:
+            # Preserve indentation & spaces: still render empty strings for alignment
+            if value:
+                color = get_token_color(token_type)
+                ax.text(
+                    x_pos,
+                    y_pos,
+                    value,
+                    fontfamily="monospace",
+                    fontsize=fontsize,
+                    color=color,
+                    va="top",
+                    ha="left",
+                )
+            x_pos += len(value) * char_width

bsplot/text2obj.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+
+import sys
+from os.path import join, isfile
+
+def main(base_path):
+    """
+    Converts vertex, normal, and triangle data into an OBJ file format.
+
+    Parameters:
+        base_path (str): The base directory containing vertices.txt, normals.txt, and triangles.txt.
+
+    Outputs:
+        surface.obj file in the specified directory.
+    """
+    vertices_file = join(base_path, "vertices.txt")
+    normals_file = join(base_path, "normals.txt")
+    triangles_file = join(base_path, "triangles.txt")
+    output_file = join(base_path, "surface.obj")
+
+    # Check if normals file exists
+    normals_exist = isfile(normals_file)
+
+    # Reading vertices and triangles
+    with open(vertices_file, "r") as vf, open(triangles_file, "r") as tf:
+        vertices = [line.strip().split() for line in vf]
+        triangles = [line.strip().split() for line in tf]
+
+    # Read normals only if they exist
+    if normals_exist:
+        with open(normals_file, "r") as nf:
+            normals = [line.strip().split() for line in nf]
+
+    # Writing to OBJ format
+    with open(output_file, "w") as of:
+        # Write vertices
+        for v in vertices:
+            of.write(f"v {' '.join(v)}\n")
+
+        # Write normals if available
+        if normals_exist:
+            for n in normals:
+                of.write(f"vn {' '.join(n)}\n")
+
+        # Write faces with or without normals
+        for t in triangles:
+            indices = [str(int(idx) + 1) for idx in t]
+            if normals_exist:
+                of.write(
+                    f"f {indices[0]}//{indices[0]} {indices[1]}//{indices[1]} {indices[2]}//{indices[2]}\n"
+                )
+            else:
+                of.write(f"f {indices[0]} {indices[1]} {indices[2]}\n")
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python text2obj.py <base_path>")
+    else:
+        main(sys.argv[1])

bsplot/timeseries.py

@@ -0,0 +1,10 @@
+import matplotlib.pyplot as plt
+
+
+def plot_ts(ax, time, data, label, data_label="X", time_unit="ms", box_aspect=1):
+    ax.plot(time, data, label=label)
+    ax.set_xlabel(f"Time in {time_unit}")
+    ax.set_ylabel(data_label)
+
+    ax.set_box_aspect(box_aspect)
+

bsplot/utils.py

@@ -0,0 +1,13 @@
+"""Utility helpers for plotting and figure management."""
+
+
+def autoscale_axis(ax):
+    """Recompute axis limits after adding artists like LineCollection.
+
+    Useful when plotting line collections, which do not always update limits
+    automatically. Call this only when you want the axis limits to be reset
+    from current artists.
+    """
+    ax.autoscale(enable=True)
+    ax.autoscale_view()
+    return ax