bsplot

Neuroscience plotting utilities built on matplotlib.

Overview

• 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").

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

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 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.

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()

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. Reading tvbo result files needs pip install "bsplot[tvbo]".

Installation

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:

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]")