bsplot 0.0.6__tar.gz

bsplot-0.0.6/LICENSE

@@ -0,0 +1,193 @@
+Copyright © Charité Universitätsmedizin Berlin. This software is licensed under the terms of the European Union Public Licence (EUPL) version 1.2 or later.
+
+EUROPEAN UNION PUBLIC LICENCE v. 1.2
+EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined below) which is provided under the
+terms of this Licence. Any use of the Work, other than as authorised under this Licence is prohibited (to the extent such
+use is covered by a right of the copyright holder of the Work).
+The Work is provided under the terms of this Licence when the Licensor (as defined below) has placed the following
+notice immediately following the copyright notice for the Work:
+                          Licensed under the EUPL
+or has expressed by any other means his willingness to license under the EUPL.
+
+1.Definitions
+In this Licence, the following terms have the following meaning:
+— ‘The Licence’:this Licence.
+— ‘The Original Work’:the work or software distributed or communicated by the Licensor under this Licence, available
+as Source Code and also as Executable Code as the case may be.
+— ‘Derivative Works’:the works or software that could be created by the Licensee, based upon the Original Work or
+modifications thereof. This Licence does not define the extent of modification or dependence on the Original Work
+required in order to classify a work as a Derivative Work; this extent is determined by copyright law applicable in
+the country mentioned in Article 15.
+— ‘The Work’:the Original Work or its Derivative Works.
+— ‘The Source Code’:the human-readable form of the Work which is the most convenient for people to study and
+modify.
+— ‘The Executable Code’:any code which has generally been compiled and which is meant to be interpreted by
+a computer as a program.
+— ‘The Licensor’:the natural or legal person that distributes or communicates the Work under the Licence.
+— ‘Contributor(s)’:any natural or legal person who modifies the Work under the Licence, or otherwise contributes to
+the creation of a Derivative Work.
+— ‘The Licensee’ or ‘You’:any natural or legal person who makes any usage of the Work under the terms of the
+Licence.
+— ‘Distribution’ or ‘Communication’:any act of selling, giving, lending, renting, distributing, communicating,
+transmitting, or otherwise making available, online or offline, copies of the Work or providing access to its essential
+functionalities at the disposal of any other natural or legal person.
+
+2.Scope of the rights granted by the Licence
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, sublicensable licence to do the following, for
+the duration of copyright vested in the Original Work:
+— use the Work in any circumstance and for all usage,
+— reproduce the Work,
+— modify the Work, and make Derivative Works based upon the Work,
+— communicate to the public, including the right to make available or display the Work or copies thereof to the public
+and perform publicly, as the case may be, the Work,
+— distribute the Work or copies thereof,
+— lend and rent the Work or copies thereof,
+— sublicense rights in the Work or copies thereof.
+Those rights can be exercised on any media, supports and formats, whether now known or later invented, as far as the
+applicable law permits so.
+In the countries where moral rights apply, the Licensor waives his right to exercise his moral right to the extent allowed
+by law in order to make effective the licence of the economic rights here above listed.
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to any patents held by the Licensor, to the
+extent necessary to make use of the rights granted on the Work under this Licence.
+
+3.Communication of the Source Code
+The Licensor may provide the Work either in its Source Code form, or as Executable Code. If the Work is provided as
+Executable Code, the Licensor provides in addition a machine-readable copy of the Source Code of the Work along with
+each copy of the Work that the Licensor distributes or indicates, in a notice following the copyright notice attached to
+the Work, a repository where the Source Code is easily and freely accessible for as long as the Licensor continues to
+distribute or communicate the Work.
+
+4.Limitations on copyright
+Nothing in this Licence is intended to deprive the Licensee of the benefits from any exception or limitation to the
+exclusive rights of the rights owners in the Work, of the exhaustion of those rights or of other applicable limitations
+thereto.
+
+5.Obligations of the Licensee
+The grant of the rights mentioned above is subject to some restrictions and obligations imposed on the Licensee. Those
+obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or trademarks notices and all notices that refer to
+the Licence and to the disclaimer of warranties. The Licensee must include a copy of such notices and a copy of the
+Licence with every copy of the Work he/she distributes or communicates. The Licensee must cause any Derivative Work
+to carry prominent notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the Original Works or Derivative Works, this
+Distribution or Communication will be done under the terms of this Licence or of a later version of this Licence unless
+the Original Work is expressly distributed only under this version of the Licence — for example by communicating
+‘EUPL v. 1.2 only’. The Licensee (becoming Licensor) cannot offer or impose any additional terms or conditions on the
+Work or Derivative Work that alter or restrict the terms of the Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative Works or copies thereof based upon both
+the Work and another work licensed under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause, ‘Compatible Licence’ refers to the licences listed
+in the appendix attached to this Licence. Should the Licensee's obligations under the Compatible Licence conflict with
+his/her obligations under this Licence, the obligations of the Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the Work, the Licensee will provide
+a machine-readable copy of the Source Code or indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade names, trademarks, service marks, or names
+of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6.Chain of Authorship
+The original Licensor warrants that the copyright in the Original Work granted hereunder is owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each Contributor warrants that the copyright in the modifications he/she brings to the Work are owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each time You accept the Licence, the original Licensor and subsequent Contributors grant You a licence to their contributions
+to the Work, under the terms of this Licence.
+
+7.Disclaimer of Warranty
+The Work is a work in progress, which is continuously improved by numerous Contributors. It is not a finished work
+and may therefore contain defects or ‘bugs’ inherent to this type of development.
+For the above reason, the Work is provided under the Licence on an ‘as is’ basis and without warranties of any kind
+concerning the Work, including without limitation merchantability, fitness for a particular purpose, absence of defects or
+errors, accuracy, non-infringement of intellectual property rights other than copyright as stated in Article 6 of this
+Licence.
+This disclaimer of warranty is an essential part of the Licence and a condition for the grant of any rights to the Work.
+
+8.Disclaimer of Liability
+Except in the cases of wilful misconduct or damages directly caused to natural persons, the Licensor will in no event be
+liable for any direct or indirect, material or moral, damages of any kind, arising out of the Licence or of the use of the
+Work, including without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, loss
+of data or any commercial damage, even if the Licensor has been advised of the possibility of such damage. However,
+the Licensor will be liable under statutory product liability laws as far such laws apply to the Work.
+
+9.Additional agreements
+While distributing the Work, You may choose to conclude an additional agreement, defining obligations or services
+consistent with this Licence. However, if accepting obligations, You may act only on your own behalf and on your sole
+responsibility, not on behalf of the original Licensor or any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against such Contributor by
+the fact You have accepted any warranty or additional liability.
+
+10.Acceptance of the Licence
+The provisions of this Licence can be accepted by clicking on an icon ‘I agree’ placed under the bottom of a window
+displaying the text of this Licence or by affirming consent in any other similar way, in accordance with the rules of
+applicable law. Clicking on that icon indicates your clear and irrevocable acceptance of this Licence and all of its terms
+and conditions.
+Similarly, you irrevocably accept this Licence and all of its terms and conditions by exercising any rights granted to You
+by Article 2 of this Licence, such as the use of the Work, the creation by You of a Derivative Work or the Distribution
+or Communication by You of the Work or copies thereof.
+
+11.Information to the public
+In case of any Distribution or Communication of the Work by means of electronic communication by You (for example,
+by offering to download the Work from a remote location) the distribution channel or media (for example, a website)
+must at least provide to the public the information requested by the applicable law regarding the Licensor, the Licence
+and the way it may be accessible, concluded, stored and reproduced by the Licensee.
+
+12.Termination of the Licence
+The Licence and the rights granted hereunder will terminate automatically upon any breach by the Licensee of the terms
+of the Licence.
+Such a termination will not terminate the licences of any person who has received the Work from the Licensee under
+the Licence, provided such persons remain in full compliance with the Licence.
+
+13.Miscellaneous
+Without prejudice of Article 9 above, the Licence represents the complete agreement between the Parties as to the
+Work.
+If any provision of the Licence is invalid or unenforceable under applicable law, this will not affect the validity or
+enforceability of the Licence as a whole. Such provision will be construed or reformed so as necessary to make it valid
+and enforceable.
+The European Commission may publish other linguistic versions or new versions of this Licence or updated versions of
+the Appendix, so far this is required and reasonable, without reducing the scope of the rights granted by the Licence.
+New versions of the Licence will be published with a unique version number.
+All linguistic versions of this Licence, approved by the European Commission, have identical value. Parties can take
+advantage of the linguistic version of their choice.
+
+14.Jurisdiction
+Without prejudice to specific agreement between parties,
+— any litigation resulting from the interpretation of this License, arising between the European Union institutions,
+bodies, offices or agencies, as a Licensor, and any Licensee, will be subject to the jurisdiction of the Court of Justice
+of the European Union, as laid down in article 272 of the Treaty on the Functioning of the European Union,
+— any litigation arising between other parties and resulting from the interpretation of this License, will be subject to
+the exclusive jurisdiction of the competent court where the Licensor resides or conducts its primary business.
+
+15.Applicable Law
+Without prejudice to specific agreement between parties,
+— this Licence shall be governed by the law of the European Union Member State where the Licensor has his seat,
+resides or has his registered office,
+— this licence shall be governed by Belgian law if the Licensor has no seat, residence or registered office inside
+a European Union Member State.
+
+
+                                                         Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+— GNU General Public License (GPL) v. 2, v. 3
+— GNU Affero General Public License (AGPL) v. 3
+— Open Software License (OSL) v. 2.1, v. 3.0
+— Eclipse Public License (EPL) v. 1.0
+— CeCILL v. 2.0, v. 2.1
+— Mozilla Public Licence (MPL) v. 2
+— GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+— Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for works other than software
+— European Union Public Licence (EUPL) v. 1.1, v. 1.2
+— Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong Reciprocity (LiLiQ-R+)
+
+The European Commission may update this Appendix to later versions of the above licences without producing
+a new version of the EUPL, as long as they provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+All other changes or additions to this Appendix require the production of a new EUPL version.

bsplot-0.0.6/MANIFEST.in

@@ -0,0 +1,20 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+recursive-include bsplot *.py
+recursive-include bsplot/styles *.mplstyle
+recursive-include bsplot/data *
+recursive-include bsplot/scientific_color_maps *
+
+prune docs
+prune dev
+prune manuscript
+prune img
+prune figures
+prune build
+prune bsplot.egg-info
+prune .github
+
+global-exclude __pycache__
+global-exclude *.py[cod]

bsplot-0.0.6/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: bsplot
+Version: 0.0.6
+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: nibabel
+Requires-Dist: nilearn
+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"
+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
+
+![alt text](docs/figures/brain_network_with_insets.png)
+
+
+## Installation
+
+```bash
+pip install bsplot
+```
+
+## Dependencies
+
+- `matplotlib`
+- `nibabel`
+- `nilearn`
+- `templateflow`
+- `scikit-image`
+

bsplot-0.0.6/README.md

@@ -0,0 +1,35 @@
+<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
+
+![alt text](docs/figures/brain_network_with_insets.png)
+
+
+## Installation
+
+```bash
+pip install bsplot
+```
+
+## Dependencies
+
+- `matplotlib`
+- `nibabel`
+- `nilearn`
+- `templateflow`
+- `scikit-image`
+

bsplot-0.0.6/bsplot/__init__.py

@@ -0,0 +1,24 @@
+# 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.6"
+
+ROOT = abspath(dirname(__file__))
+datadir = join(ROOT, "data")
+
+from . import volume, anat, animate, brain, colors, data, figure, streamlines, style, timeseries, surface, templates, utils
+from .surface import vol_to_mesh, LabeledMeshes, project_vol_to_surf, plot_surf
+from .brain import glass_brain
+from .volume import plot_slice, apply_brain_mask
+from .colors import explore_colormaps
+from .bioicons import (
+    BioIcons,
+    plot_icon,
+    plot_icons_grid,
+    IconAnnotation,
+    search_icons,
+    list_categories,
+    list_licenses,
+)
+
+style.use("tvbo")

bsplot-0.0.6/bsplot/anat.py

@@ -0,0 +1,56 @@
+# Copyright © Charité Universitätsmedizin Berlin. This software is licensed under the terms of the European Union Public Licence (EUPL) version 1.2 or later.
+"""Backwards compatibility module. Use bsplot.volume instead."""
+
+import warnings
+import inspect
+
+# Only warn if imported directly by user code, not by bsplot's __init__.py
+_stack = inspect.stack()
+if len(_stack) >= 2:
+    _caller_filename = _stack[1].filename
+    if "bsplot/__init__.py" not in _caller_filename and "bsplot\\__init__.py" not in _caller_filename:
+        warnings.warn(
+            "bsplot.anat is deprecated, use bsplot.volume instead. "
+            "Also note that plot_img has been renamed to plot_slice.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+del _stack, inspect
+
+from bsplot.volume import (
+    get_center_of_mass,
+    get_cut_coords,
+    get_com_slice_index,
+    get_slice_index,
+    get_world_coords,
+    get_view_index,
+    get_plane_indices,
+    plot_slice,
+    plot_img,
+    translate_com,
+    get_com_view,
+    plot_img_on_bg,
+    plot_brain_schematics,
+    get_world_extent,
+    plot_image_extent,
+    apply_brain_mask,
+)
+
+__all__ = [
+    "get_center_of_mass",
+    "get_cut_coords",
+    "get_com_slice_index",
+    "get_slice_index",
+    "get_world_coords",
+    "get_view_index",
+    "get_plane_indices",
+    "plot_slice",
+    "plot_img",
+    "translate_com",
+    "get_com_view",
+    "plot_img_on_bg",
+    "plot_brain_schematics",
+    "get_world_extent",
+    "plot_image_extent",
+    "apply_brain_mask",
+]

bsplot-0.0.6/bsplot/animate.py

@@ -0,0 +1,195 @@
+# Copyright © Charité Universitätsmedizin Berlin. This software is licensed under the terms of the European Union Public Licence (EUPL) version 1.2 or later.
+"""Composable animation utilities for 4D neuroimaging data (matplotlib-only).
+
+The core abstraction is :class:`AnimationComposer`, which manages a shared
+timeline and lets you plug in per-axis animation callbacks. All higher-level
+patterns (single view, multi-view, multi-image comparison) can be expressed
+via this composer and a small generic helper.
+"""
+
+import matplotlib.pyplot as plt
+import nibabel as nib
+import numpy as np
+from matplotlib.animation import FuncAnimation
+
+
+class AnimationComposer:
+    """Composable multi-axes animation helper (matplotlib-only).
+
+    This class lets you register per-axis update functions that are called for
+    every frame with the same frame index, so you can build complex, modular
+    animations across several axes.
+
+    Each registered callback should have the signature::
+
+        func(frame_index: int, ax: matplotlib.axes.Axes) -> list[Artist] | Artist | None
+
+    and is expected to draw on the provided axis.
+    """
+
+    def __init__(self, fig, axes, n_frames, interval=100, blit=False):
+        """Create a new AnimationComposer.
+
+        Parameters
+        ----------
+        fig : matplotlib.figure.Figure
+            Parent figure for the animation.
+        axes : Axes or sequence of Axes
+            One or more axes to animate.
+        n_frames : int
+            Number of frames (time points).
+        interval : int, default 100
+            Delay between frames in milliseconds.
+        blit : bool, default False
+            Whether to use blitting.
+        """
+
+        self.fig = fig
+        if hasattr(axes, "__iter__") and not isinstance(axes, (list, tuple)):
+            self.axes = list(axes)
+        elif hasattr(axes, "__iter__"):
+            self.axes = list(axes)
+        else:
+            self.axes = [axes]
+
+        self.n_frames = int(n_frames)
+        self.interval = interval
+        self.blit = blit
+        self._callbacks = []  # list of (ax, func)
+
+    def add_axis_animation(self, ax, func):
+        """Register an animation callback for a given axis.
+
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes
+            Axis that ``func`` will draw on.
+        func : callable
+            Function with signature ``func(frame_index: int, ax)`` that returns
+            a Matplotlib Artist or a list of Artists (optional).
+        """
+
+        if ax not in self.axes:
+            self.axes.append(ax)
+        self._callbacks.append((ax, func))
+
+    def _update(self, frame):
+        artists = []
+        for ax, func in self._callbacks:
+            res = func(frame, ax)
+            if res is None:
+                continue
+            if isinstance(res, (list, tuple)):
+                artists.extend(res)
+            else:
+                artists.append(res)
+        return artists
+
+    def to_animation(self):
+        """Create and return the underlying FuncAnimation object."""
+
+        anim = FuncAnimation(
+            self.fig,
+            self._update,
+            frames=self.n_frames,
+            interval=self.interval,
+            blit=self.blit,
+        )
+        return anim
+
+
+def _ensure_4d(img_4d):
+    """Load and validate a 4D NIfTI-like image."""
+    if isinstance(img_4d, str):
+        img_4d = nib.load(img_4d)
+    if len(img_4d.shape) != 4:
+        raise ValueError(f"Expected 4D image, got shape {img_4d.shape}")
+    return img_4d
+
+
+def _global_scale_kwargs(img_4d, threshold=0, **plot_kwargs):
+    """Compute global vmin/vmax across time, unless user provided scaling.
+
+    Returns a dict with optional ``vmin``/``vmax`` to forward into ``plot_img``.
+    """
+    if "vmin" in plot_kwargs or "norm" in plot_kwargs:
+        return {}
+
+    data_4d = img_4d.get_fdata()
+    if threshold > 0:
+        masked = np.where(np.abs(data_4d) <= threshold, np.nan, data_4d)
+        vmin = np.nanmin(masked)
+        vmax = np.nanmax(masked)
+    else:
+        nonzero = data_4d[data_4d != 0]
+        vmin = np.nanmin(nonzero) if nonzero.size else np.nanmin(data_4d)
+        vmax = np.nanmax(data_4d)
+
+    contains_negative = np.any(data_4d < 0)
+    if contains_negative:
+        vmax_abs = max(abs(vmin), abs(vmax))
+        vmin, vmax = -vmax_abs, vmax_abs
+
+    return {"vmin": vmin, "vmax": vmax}
+
+
+def animate_axes(fig, axes, n_frames, update_fn, context=None, interval=100, blit=False):
+    """Convenience wrapper to build an animation over one or many axes.
+
+    This captures the common pattern used in the docs: one timeline, multiple
+    axes, and a single user-defined ``update_fn`` that can branch on the axis
+    index and/or shared ``context``.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        Parent figure for the animation.
+    axes : Axes or sequence of Axes
+        Axes to animate. Can be a single axis, a list/tuple, or any iterable
+        of axes as returned by ``plt.subplots``.
+    n_frames : int
+        Number of frames in the animation.
+    update_fn : callable
+        Function with signature::
+
+            update_fn(frame: int, ax, axis_idx: int, context: dict | None)
+
+        It should draw the desired state for the given ``frame`` on ``ax`` and
+        return a Matplotlib Artist or list of Artists (or ``None``).
+    context : dict or None, optional
+        Arbitrary, user-defined state shared across axes and frames.
+    interval : int, default 100
+        Delay between frames in milliseconds.
+    blit : bool, default False
+        Whether to use blitting.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+        The constructed animation object.
+    """
+
+    # Normalize axes into a flat list
+    if hasattr(axes, "__iter__") and not isinstance(axes, (list, tuple)):
+        axes_list = list(axes)
+    elif hasattr(axes, "__iter__"):
+        axes_list = list(axes)
+    else:
+        axes_list = [axes]
+
+    composer = AnimationComposer(fig, axes_list, n_frames=n_frames, interval=interval, blit=blit)
+
+    for axis_idx, ax in enumerate(axes_list):
+
+        def make_cb(idx_):
+            def _cb(frame, ax_cb):
+                return update_fn(frame, ax_cb, idx_, context)
+
+            return _cb
+
+        composer.add_axis_animation(ax, make_cb(axis_idx))
+
+    return composer.to_animation()
+
+
+