bsplot 0.0.9__tar.gz → 0.0.11__tar.gz

{bsplot-0.0.9 → bsplot-0.0.11}/MANIFEST.in

@@ -8,6 +8,12 @@ include bsplot/data/HCP_avg-SC.txt
 include bsplot/data/MNI152.rh.pial
 include bsplot/data/parcellations/HCP-MMP1.L.label.gii
 include bsplot/data/parcellations/HCP-MMP1.R.label.gii
+# Glass-brain schematics vendored from nilearn (BSD-3-Clause). The JSON data
+# AND the NILEARN_LICENSE must ship with the source distribution to satisfy the
+# BSD licence's source-redistribution clause.
+recursive-include bsplot/data/glass_brain *.json
+include bsplot/data/glass_brain/NILEARN_LICENSE
+include bsplot/data/glass_brain/README.md
 recursive-include bsplot/scientific_color_maps *
 
 prune docs

bsplot-0.0.11/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: bsplot
+Version: 0.0.11
+Summary: Plotting utilities for neuroscience: styles, palettes, surfaces, glass-brain, and panel helpers.
+License-Expression: EUPL-1.2
+Project-URL: Repository, https://github.com/leon-k-martin/bsplot
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: pybtex
+Requires-Dist: pyaml
+Requires-Dist: scikit-image
+Requires-Dist: scipy
+Requires-Dist: nibabel
+Requires-Dist: templateflow
+Requires-Dist: graphviz
+Requires-Dist: cmap
+Provides-Extra: docs
+Requires-Dist: quarto; extra == "docs"
+Requires-Dist: quartodoc; extra == "docs"
+Requires-Dist: griffe<1.0; extra == "docs"
+Requires-Dist: jupyter-cache; extra == "docs"
+Requires-Dist: cairosvg; extra == "docs"
+Provides-Extra: projection
+Requires-Dist: nilearn; extra == "projection"
+Provides-Extra: tvbo
+Requires-Dist: xarray; extra == "tvbo"
+Requires-Dist: h5netcdf; extra == "tvbo"
+Requires-Dist: h5py; extra == "tvbo"
+Dynamic: license-file
+
+<h1>
+  bsplot
+  <img src="docs/Usage/_output/anim1.gif" alt="Sagittal volume animation" height="55" align="right">
+  <img src="docs/Usage/_output/anim4.gif" alt="Surface rotation animation" height="55" align="right">
+</h1>
+
+Neuroscience plotting utilities built on **matplotlib**.
+
+## Overview
+
+![](docs/overview_figure.png)
+
+- Brain surfaces and glass-brain visualizations
+- Volume slicing with anatomical overlays
+- Tractography rendering
+- Publication-ready styles and scientific colormaps
+- Panel helpers for multi-figure layouts
+- Terminal (ASCII) surface backend — render a lit brain as text, with data overlays
+
+## Terminal (ASCII) rendering
+
+Render a cortical surface straight to text — no matplotlib figure — as a lit
+"surface of letters", with optional scalar overlays and parcellations in colour.
+The default is the folded **pial** cortex, and the output adapts to wherever it
+is drawn: **terminal** (ANSI colour), **notebook/website** (`color_mode="html"`,
+auto-selected in a notebook), or **README/plain-text** (`color_mode="none"`).
+
+```python
+import bsplot
+
+bsplot.plot_surf_ascii()                       # pial template brain, lateral
+bsplot.plot_surf_ascii(data=my_stat_map)       # scalar overlay, colour-mapped
+bsplot.plot_surf_ascii(parcellation=labels)    # coloured regions
+bsplot.plot_surf_ascii(width=140)              # width = resolution knob
+bsplot.plot_surf_ascii(background="light")     # for a white background
+```
+
+```bash
+bsplot-ascii                          # pial fsaverage, lateral (or: python -m bsplot.ascii)
+bsplot-ascii --view top --hemi both   # both hemispheres, dorsal
+bsplot-ascii --html > brain.html      # emit an HTML block
+bsplot-ascii --sphere                 # offline demo (no download)
+```
+
+See the [Terminal surface guide](docs/Usage/AsciiSurface.qmd) for ramps, colormaps, views, and resolution.
+
+### Timeseries — recordings and simulations
+
+Surface colouring over time, cheap enough to stream live. The geometry is
+prepared once, so each frame only re-colours the visible faces: **~0.7 ms/frame
+(>1000 fps)** against ~184 ms for a full render.
+
+```python
+mov = bsplot.AsciiSurfaceMovie(data, hemi="lh", view="lateral", width=80)
+mov.play(fps=20)                    # live in the terminal
+mov.to_gif("sim.gif"); mov.to_html("sim.html"); mov.to_cast("sim.cast")
+
+# region-level data (TVB-style) mapped onto the surface by an atlas
+bsplot.AsciiSurfaceMovie(data, atlas="DesikanKilliany", region_labels=labels)
+
+# straight from a tvbo simulation result
+bsplot.AsciiSurfaceMovie.from_tvbo("exp-3_result.h5", atlas="dk").play()
+```
+
+```bash
+bsplot-ascii-movie data.npy --atlas Destrieux --fps 20     # play
+bsplot-ascii-movie result.h5 --tvbo -o sim.gif             # or export
+```
+
+See the [Timeseries guide](docs/Usage/AsciiTimeseries/AsciiTimeseries.qmd).
+Reading tvbo result files needs `pip install "bsplot[tvbo]"`.
+
+![alt text](docs/figures/brain_network_with_insets.png)
+
+
+## Installation
+
+```bash
+pip install bsplot
+```
+
+Two optional features — volume-to-surface projection (`project_vol_to_surf`)
+and fsaverage cortical flatmaps (`get_flat_surface_geometry`) — additionally
+need `nilearn`:
+
+```bash
+pip install "bsplot[projection]"
+```
+
+## Dependencies
+
+- `matplotlib`
+- `nibabel`
+- `scipy`
+- `templateflow`
+- `scikit-image`
+- `nilearn` — optional, only for `project_vol_to_surf` and cortical flatmaps
+  (`pip install "bsplot[projection]"`)
+

bsplot-0.0.11/README.md

@@ -0,0 +1,99 @@
+<h1>
+  bsplot
+  <img src="docs/Usage/_output/anim1.gif" alt="Sagittal volume animation" height="55" align="right">
+  <img src="docs/Usage/_output/anim4.gif" alt="Surface rotation animation" height="55" align="right">
+</h1>
+
+Neuroscience plotting utilities built on **matplotlib**.
+
+## Overview
+
+![](docs/overview_figure.png)
+
+- Brain surfaces and glass-brain visualizations
+- Volume slicing with anatomical overlays
+- Tractography rendering
+- Publication-ready styles and scientific colormaps
+- Panel helpers for multi-figure layouts
+- Terminal (ASCII) surface backend — render a lit brain as text, with data overlays
+
+## Terminal (ASCII) rendering
+
+Render a cortical surface straight to text — no matplotlib figure — as a lit
+"surface of letters", with optional scalar overlays and parcellations in colour.
+The default is the folded **pial** cortex, and the output adapts to wherever it
+is drawn: **terminal** (ANSI colour), **notebook/website** (`color_mode="html"`,
+auto-selected in a notebook), or **README/plain-text** (`color_mode="none"`).
+
+```python
+import bsplot
+
+bsplot.plot_surf_ascii()                       # pial template brain, lateral
+bsplot.plot_surf_ascii(data=my_stat_map)       # scalar overlay, colour-mapped
+bsplot.plot_surf_ascii(parcellation=labels)    # coloured regions
+bsplot.plot_surf_ascii(width=140)              # width = resolution knob
+bsplot.plot_surf_ascii(background="light")     # for a white background
+```
+
+```bash
+bsplot-ascii                          # pial fsaverage, lateral (or: python -m bsplot.ascii)
+bsplot-ascii --view top --hemi both   # both hemispheres, dorsal
+bsplot-ascii --html > brain.html      # emit an HTML block
+bsplot-ascii --sphere                 # offline demo (no download)
+```
+
+See the [Terminal surface guide](docs/Usage/AsciiSurface.qmd) for ramps, colormaps, views, and resolution.
+
+### Timeseries — recordings and simulations
+
+Surface colouring over time, cheap enough to stream live. The geometry is
+prepared once, so each frame only re-colours the visible faces: **~0.7 ms/frame
+(>1000 fps)** against ~184 ms for a full render.
+
+```python
+mov = bsplot.AsciiSurfaceMovie(data, hemi="lh", view="lateral", width=80)
+mov.play(fps=20)                    # live in the terminal
+mov.to_gif("sim.gif"); mov.to_html("sim.html"); mov.to_cast("sim.cast")
+
+# region-level data (TVB-style) mapped onto the surface by an atlas
+bsplot.AsciiSurfaceMovie(data, atlas="DesikanKilliany", region_labels=labels)
+
+# straight from a tvbo simulation result
+bsplot.AsciiSurfaceMovie.from_tvbo("exp-3_result.h5", atlas="dk").play()
+```
+
+```bash
+bsplot-ascii-movie data.npy --atlas Destrieux --fps 20     # play
+bsplot-ascii-movie result.h5 --tvbo -o sim.gif             # or export
+```
+
+See the [Timeseries guide](docs/Usage/AsciiTimeseries/AsciiTimeseries.qmd).
+Reading tvbo result files needs `pip install "bsplot[tvbo]"`.
+
+![alt text](docs/figures/brain_network_with_insets.png)
+
+
+## Installation
+
+```bash
+pip install bsplot
+```
+
+Two optional features — volume-to-surface projection (`project_vol_to_surf`)
+and fsaverage cortical flatmaps (`get_flat_surface_geometry`) — additionally
+need `nilearn`:
+
+```bash
+pip install "bsplot[projection]"
+```
+
+## Dependencies
+
+- `matplotlib`
+- `nibabel`
+- `scipy`
+- `templateflow`
+- `scikit-image`
+- `nilearn` — optional, only for `project_vol_to_surf` and cortical flatmaps
+  (`pip install "bsplot[projection]"`)
+

{bsplot-0.0.9 → bsplot-0.0.11}/bsplot/__init__.py

@@ -1,13 +1,22 @@
 # Copyright © Charité Universitätsmedizin Berlin. This software is licensed under the terms of the European Union Public Licence (EUPL) version 1.2 or later.
 from os.path import abspath, dirname, join
 
-__version__ = "0.0.9"
+__version__ = "0.0.11"
 
 ROOT = abspath(dirname(__file__))
 datadir = join(ROOT, "data")
 
 from . import volume, anat, animate, brain, colors, data, figure, streamlines, style, timeseries, surface, templates, utils
+from . import ascii
 from .surface import vol_to_mesh, LabeledMeshes, project_vol_to_surf, plot_surf
+from .ascii import (
+    AsciiGrid,
+    AsciiSurfaceRenderer,
+    plot_surf_ascii,
+    prepare_surf_ascii,
+    render_surf_ascii,
+)
+from .ascii_movie import AsciiSurfaceMovie, animate_surf_ascii, load_atlas_labels
 from .brain import glass_brain
 from .volume import plot_slice, apply_brain_mask
 from .colors import explore_colormaps

bsplot-0.0.11/bsplot/_glass_brain.py

@@ -0,0 +1,151 @@
+# Copyright © Charité Universitätsmedizin Berlin. This software is licensed under
+# the terms of the European Union Public Licence (EUPL) version 1.2 or later.
+#
+# ---------------------------------------------------------------------------
+# Third-party attribution (BSD-3-Clause)
+#
+# This module and the brain-schematic data files in ``bsplot/data/glass_brain/``
+# are derived from nilearn 0.13.1 (https://github.com/nilearn/nilearn):
+#   * code:  ``nilearn/plotting/glass_brain.py`` — the helpers ``_codes*``,
+#            ``_invert_color``, ``_get_mpl_patches`` and
+#            ``_get_json_and_transform`` below are adapted from it;
+#   * data:  ``nilearn/plotting/glass_brain_files/brain_schematics_{side,back,
+#            top}.json`` — redistributed byte-for-byte unmodified.
+#
+# nilearn is distributed under the BSD 3-Clause License:
+#
+#     Copyright (c) The nilearn developers.
+#     All rights reserved.
+#
+# The BSD 3-Clause conditions and disclaimer are reproduced verbatim in
+# ``bsplot/data/glass_brain/NILEARN_LICENSE`` and retained here as that licence
+# requires. Vendoring lets bsplot draw glass-brain outlines without depending on
+# nilearn (whose private API previously supplied them).
+# ---------------------------------------------------------------------------
+"""Vendored glass-brain schematic outlines (adapted from nilearn, BSD-3-Clause).
+
+Provides drop-in replacements for the private ``nilearn.plotting.glass_brain``
+functions that ``bsplot.volume.plot_brain_schematics`` relied on:
+``_get_json_and_transform`` and ``_get_mpl_patches``.
+"""
+import pathlib
+
+from matplotlib import colors, patches, transforms
+from matplotlib.path import Path
+
+# Directory holding the vendored ``brain_schematics_*.json`` files.
+_FILES_DIR = pathlib.Path(__file__).resolve().parent / "data" / "glass_brain"
+
+# Only the views used by bsplot are vendored (sagittal/coronal/horizontal ->
+# x/y/z -> side/back/top). ``l``/``r`` map to the side view, mirroring nilearn.
+_DIRECTION_TO_VIEW_NAME = {
+    "x": "side",
+    "y": "back",
+    "z": "top",
+    "l": "side",
+    "r": "side",
+}
+
+# Affine parameters hand-tuned by nilearn to align each schematic with the MNI
+# template, in matplotlib ``Affine2D.from_values`` order (a, b, c, d, e, f).
+_DIRECTION_TO_TRANSFORM_PARAMS = {
+    "x": [0.38, 0, 0, 0.38, -108, -70],
+    "y": [0.39, 0, 0, 0.39, -73, -73],
+    "z": [0.36, 0, 0, 0.37, -71, -107],
+    "l": [0.38, 0, 0, 0.38, -108, -70],
+    "r": [0.38, 0, 0, 0.38, -108, -70],
+}
+
+
+def _codes_bezier(pts):
+    bezier_num = len(pts)
+    # Next two lines are meant to handle both Bezier 3 and 4
+    path_attr = f"CURVE{bezier_num}"
+    codes = [getattr(Path, path_attr)] * (bezier_num - 1)
+    return [Path.MOVETO, *codes]
+
+
+def _codes_segment(pts):
+    # pts is accepted for API consistency with _codes_bezier
+    return [Path.MOVETO, Path.LINETO]
+
+
+def _codes(atype, pts):
+    dispatch = {"bezier": _codes_bezier, "segment": _codes_segment}
+    return dispatch[atype](pts)
+
+
+def _invert_color(color):
+    """Return inverted color.
+
+    If ``color`` is (R, G, B) it returns (1 - R, 1 - G, 1 - B). If ``color``
+    cannot be converted to a color it is returned unmodified.
+    """
+    try:
+        color_converter = colors.ColorConverter()
+        color_rgb = color_converter.to_rgb(color)
+        return tuple(1 - level for level in color_rgb)
+    except ValueError:
+        return color
+
+
+def _get_mpl_patches(json_content, transform=None, invert_color=False, **kwargs):
+    """Walk over the json content and build a list of matplotlib patches."""
+    mpl_patches = []
+    kwargs_edgecolor = kwargs.pop("edgecolor", None)
+    kwargs_linewidth = kwargs.pop("linewidth", None)
+    for path in json_content["paths"]:
+        if kwargs_edgecolor is not None:
+            edgecolor = kwargs_edgecolor
+        else:
+            edgecolor = path["edgecolor"]
+            if invert_color:
+                edgecolor = _invert_color(edgecolor)
+        linewidth = kwargs_linewidth or path["linewidth"]
+        path_id = path["id"]
+
+        for item in path["items"]:
+            type = item["type"]
+            pts = item["pts"]
+            codes = _codes(type, pts)
+            path = Path(pts, codes)
+            patch = patches.PathPatch(
+                path,
+                edgecolor=edgecolor,
+                linewidth=linewidth,
+                facecolor="none",
+                gid=path_id,
+                transform=transform,
+                **kwargs,
+            )
+
+            mpl_patches.append(patch)
+
+    return mpl_patches
+
+
+def _get_json_and_transform(direction):
+    """Return the vendored json path and its hand-tuned MNI affine transform.
+
+    Parameters
+    ----------
+    direction : {'x', 'y', 'z', 'l', 'r'}
+        Viewing direction. ``x``/``l``/``r`` -> side, ``y`` -> back,
+        ``z`` -> top.
+
+    Returns
+    -------
+    (pathlib.Path, matplotlib.transforms.Affine2D)
+    """
+    view_name = _DIRECTION_TO_VIEW_NAME.get(direction)
+    if view_name is None:
+        raise ValueError(
+            f"No glass brain view associated with direction '{direction}'. "
+            f"Possible directions are {list(_DIRECTION_TO_VIEW_NAME)}."
+        )
+
+    json_filename = _FILES_DIR / f"brain_schematics_{view_name}.json"
+    transform = transforms.Affine2D.from_values(
+        *_DIRECTION_TO_TRANSFORM_PARAMS[direction]
+    )
+    return json_filename, transform