pySimpleBrainPlot creates compact line-art brain plots as self-contained SVG
files. It is a Python adaptation of the MATLAB
Simple-Brain-Plot
project by Scholtens, de Lange, and van den Heuvel.
- Six bundled human and macaque brain atlases.
- One value per atlas region with explicit, validated color limits.
- Self-contained SVG output: the colorbar is embedded and cannot become detached or overwritten.
- No mutation of the input array.
- Support for Python sequences and NumPy arrays.
- A browser viewer that is opt-in and disabled by default.
Install the published package:
python -m pip install pySimpleBrainPlotInstall the current checkout:
python -m pip install .Python 3.10 or newer is required.
from pathlib import Path
import numpy as np
import pySimpleBrainPlot as sbp
rng = np.random.default_rng(0)
values = rng.uniform(-1, 1, 128)
output = sbp.plot_brain(
"lausanne120_aseg",
values,
vmin=-1,
vmax=1,
save_path=Path("figures"),
)
print(output)This creates figures/figure_lausanne120_aseg.svg. Missing output directories
are created automatically.
The original camel-case API remains available:
sbp.plotBrain("lausanne120_aseg", values, viewer=False)| Atlas | Regions | Description |
|---|---|---|
aparc |
68 | Desikan-Killiany cortical atlas |
aparc_aseg |
82 | Desikan-Killiany plus partial ASEG |
lausanne120 |
114 | Cammoun 120-scale cortical parcellation |
lausanne120_aseg |
128 | Cammoun 120-scale plus partial ASEG |
lausanne250 |
219 | Cammoun 250-scale cortical parcellation |
wbb47 |
39 | Walker-von Bonin and Bailey macaque atlas |
Array values must follow the package's region order. Retrieve it before joining your own measurements:
regions = sbp.get_region_descriptions("aparc")
for index, region in enumerate(regions):
print(index, region)Call sbp.get_region_descriptions() without an atlas to retrieve all region
lists.
vmin and vmax define both clipping and color normalization. Reusing the
same limits therefore produces comparable colors across figures:
limit = max(abs(values.min()), abs(values.max()))
output = sbp.plot_brain(
"lausanne120_aseg",
values,
vmin=-limit,
vmax=limit,
cm="RdBu_r",
)If both limits are omitted, the finite data minimum and maximum are used. Constant data are mapped to the center of the colormap. NaN and infinite values are rejected with a clear error.
atlas: one of the six names in the table above.values: a one-dimensional finite numeric sequence with one value per region.vmin,vmax: optional color limits.save_path: output directory; default is the current directory.save_file: output prefix; default isfigure.cm: Matplotlib colormap name or object; default isRdYlGn.scaling: positive SVG dimension scale; default is0.1.viewer: open the result in a browser; default isFalse.cmap_range: fraction of the source colormap to use; default is(0.15, 0.85).
plot_brain returns the generated pathlib.Path.
Run the regression tests:
python -m unittest discover -s tests -vBuild the wheel and source distribution:
python -m buildIf this software is useful in your research, cite:
Scholtens, Lianne H., de Lange, Siemon C., and van den Heuvel, Martijn P. (2021). Simple Brain Plot. Zenodo. https://doi.org/10.5281/zenodo.5346593
Atlas references:
- Desikan et al. (2006), NeuroImage 31(3), 968–980. https://doi.org/10.1016/j.neuroimage.2006.01.021
- Cammoun et al. (2012), Journal of Neuroscience Methods 203(2), 386–397. https://doi.org/10.1016/j.jneumeth.2011.09.031
- Scholtens et al. (2014), Journal of Neuroscience 34(36), 12192–12205. https://doi.org/10.1523/JNEUROSCI.0752-14.2014
- Stephan et al. (2000), Philosophical Transactions of the Royal Society B 355, 111–126. https://doi.org/10.1098/rstb.2000.0552
- von Bonin and Bailey (1947), The Neocortex of Macaca Mulatta.
- Walker (1940), Journal of Comparative Neurology 73, 59–86. https://doi.org/10.1002/cne.900730106
pySimpleBrainPlot is distributed under the MIT License. See LICENSE. The atlas and template references above are retained for scientific attribution.