bsplot 0.0.10__tar.gz → 0.0.11__tar.gz

{bsplot-0.0.10 → 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.10 → bsplot-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bsplot
-Version: 0.0.10
+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
@@ -11,8 +11,8 @@ Requires-Dist: matplotlib
 Requires-Dist: pybtex
 Requires-Dist: pyaml
 Requires-Dist: scikit-image
+Requires-Dist: scipy
 Requires-Dist: nibabel
-Requires-Dist: nilearn
 Requires-Dist: templateflow
 Requires-Dist: graphviz
 Requires-Dist: cmap
@@ -22,6 +22,8 @@ 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"
@@ -109,11 +111,21 @@ Reading tvbo result files needs `pip install "bsplot[tvbo]"`.
 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`
-- `nilearn`
+- `scipy`
 - `templateflow`
 - `scikit-image`
+- `nilearn` — optional, only for `project_vol_to_surf` and cortical flatmaps
+  (`pip install "bsplot[projection]"`)
 

{bsplot-0.0.10 → bsplot-0.0.11}/README.md

@@ -79,11 +79,21 @@ Reading tvbo result files needs `pip install "bsplot[tvbo]"`.
 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`
-- `nilearn`
+- `scipy`
 - `templateflow`
 - `scikit-image`
+- `nilearn` — optional, only for `project_vol_to_surf` and cortical flatmaps
+  (`pip install "bsplot[projection]"`)
 

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

@@ -1,7 +1,7 @@
 # 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.10"
+__version__ = "0.0.11"
 
 ROOT = abspath(dirname(__file__))
 datadir = join(ROOT, "data")

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

{bsplot-0.0.10 → bsplot-0.0.11}/bsplot/brain.py

@@ -4,7 +4,6 @@ import inspect
 
 import matplotlib.pyplot as plt
 import numpy as np
-from nilearn import surface
 
 from bsplot import anat, data
 
@@ -124,22 +123,26 @@ def glass_brain_3d(img, ax=None, surf="fsaverage", cmap="viridis", brain_color="
     img_data = img.get_fdata()
 
     if surf == "fsaverage":
-        # fsaverage = datasets.fetch_surf_fsaverage()
-        # mesh = surface.load_surf_mesh(fsaverage.pial_right)
-        mesh = surface.load_surf_mesh(
+        mesh = data.surface.load_mesh(
             data.surface.get_surface_geometry(
                 template="fsaverage", hemi="rh", suffix="pial", density="10k"
             )
         )
         linewidth = 0.1
     elif surf == "mni09c":
-        mesh = surface.load_surf_mesh(join(data.surface.root, "MNI152.rh.pial"))
+        mesh = data.surface.load_mesh(join(data.surface.root, "MNI152.rh.pial"))
         linewidth = 0.05
+    elif surf == "nilearn":
+        # No schematic mesh outline; render only the intensity projection.
+        mesh = None
+    else:
+        raise ValueError(
+            f"Unknown surf '{surf}'. Expected 'fsaverage', 'mni09c', or 'nilearn'."
+        )
 
-    coords, faces = mesh[0], mesh[1]
-    x, y, z = coords.T
-
-    if surf != "nilearn":
+    if mesh is not None:
+        coords, faces = mesh[0], mesh[1]
+        x, y, z = coords.T
         ax.triplot(
             y, z, faces, color=brain_color, alpha=0.8, linewidth=linewidth, zorder=100
         )

bsplot-0.0.11/bsplot/data/glass_brain/NILEARN_LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) The nilearn developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the name of the University nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

bsplot-0.0.11/bsplot/data/glass_brain/README.md

@@ -0,0 +1,34 @@
+# Third-party data: glass-brain schematics (vendored from nilearn)
+
+## Source / provenance
+
+- **Project:** nilearn — <https://github.com/nilearn/nilearn>
+- **Version:** 0.13.1
+- **Upstream files:** `nilearn/plotting/glass_brain_files/brain_schematics_side.json`,
+  `…_back.json`, `…_top.json`
+- **Copyright:** © The nilearn developers. All rights reserved.
+- **Licence:** BSD 3-Clause — reproduced verbatim in `NILEARN_LICENSE` in this
+  directory.
+
+## What these are and how they are used
+
+`brain_schematics_{side,back,top}.json` describe the MNI152 brain outline drawn
+by `bsplot.volume.plot_brain_schematics` (and hence `bsplot.brain.glass_brain`).
+They are redistributed **byte-for-byte unmodified** from the upstream files
+listed above.
+
+The loader and patch-building code adapted from nilearn's `glass_brain.py` lives
+in `bsplot/_glass_brain.py`, which retains the nilearn copyright notice as the
+BSD 3-Clause licence requires.
+
+## Licence compatibility
+
+bsplot as a whole is licensed under the **EUPL-1.2**. The BSD 3-Clause licence
+is a permissive licence whose only obligations are to retain the copyright
+notice and the licence text (both done here, for source and binary
+distributions). BSD-licensed material may be incorporated into and distributed
+as part of an EUPL-licensed work; these specific files remain under their
+original BSD 3-Clause terms.
+
+This note is an honest description of provenance and licensing, not legal
+advice. If in doubt, have the licensing reviewed by counsel.