pynibs

name

pynibs

description

pyNIBS skill for non-invasive brain stimulation (TMS/NIBS) analysis workflows including subject/session containers, HDF5 mesh I/O, ROI structures, stimulation optimization, nonlinear regression mapping, and experiment import/cleanup utilities. Use when working with pynibs.subject, pynibs.hdf5_io, pynibs.mesh, pynibs.roi, pynibs.optimization, pynibs.regression, pynibs.expio, or dosing utilities; keywords: TMS, e-field, coil placement, MEP, SimNIBS, ROI, HDF5, cortical mapping.

pyNIBS

pyNIBS is a research toolbox for TMS/NIBS workflows centered on electric-field simulation outputs, experiment logs, and cortical localization models.

Version

Built against: pynibs==0.2026.1 Python: 3.13

This build used install_permission: no; runtime-dependent claims are marked when needed.

Environment Gate

Install policy and selected environment are recorded in assets/version.txt. Current build used docs/source-first fallback because import of full pynibs requires optional dependencies (for example h5py).

Installation

# requires explicit install permission
pip install pynibs

# optional scientific stack commonly needed by pyNIBS workflows
pip install h5py nibabel scipy pandas

---

Subject and Session I/O

# tested against pynibs==0.2026.1
try:
    from pynibs.subject import Subject, save_subject, load_subject
    print(Subject.__name__, save_subject.__name__, load_subject.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/subject-and-session-io.md for Subject, save_subject_hdf5, and load/save routing details.

---

Mesh and ROI Structures

# tested against pynibs==0.2026.1
try:
    from pynibs.mesh.mesh_struct import Mesh, ROI
    print(Mesh.__name__, ROI.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/mesh-and-roi-structures.md for Mesh.fill_defaults, ROI containers, and structural assumptions.

---

HDF5 and Data Layout

# tested against pynibs==0.2026.1
try:
    from pynibs.hdf5_io.hdf5_io import split_hdf5, read_data_hdf5
    print(split_hdf5.__name__, read_data_hdf5.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/hdf5-and-xdmf.md for geometry/data group conventions and file-splitting behavior.

---

Optimization Workflows

# tested against pynibs==0.2026.1
try:
    from pynibs.optimization.coil_opt import get_optimal_coil_positions
    from pynibs.optimization.multichannel import get_score_raw
    print(get_optimal_coil_positions.__name__, get_score_raw.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/optimization-workflows.md for optimization criteria, input matrix shapes, and multichannel scoring.

---

Regression and Localization

# tested against pynibs==0.2026.1
try:
    from pynibs.regression.regression import regress_data
    print(regress_data.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/regression-and-localization.md for nonlinear fit workflow and score semantics.

---

Experiment Import and QC

# tested against pynibs==0.2026.1
try:
    from pynibs.expio.exp import read_exp_stimulations, coil_distance_correction
    print(read_exp_stimulations.__name__, coil_distance_correction.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/experiment-import-and-qc.md for navigator CSV ingestion and trial quality filtering hooks.

---

Verification (Medium+)

python ".opencode/skills/opensci-skill/scripts/verify-snippets.py" --root ".opencode/skills/pynibs" --fail-fast

Dictionary Assets (Hybrid)

Use dictionary assets for broad API lookup before deep source reads:

• assets/symbol-index.md (module-level index and retrieval contract)
• assets/symbol-index.jsonl (machine-readable exact symbol registry)
• assets/symbol-cards/ (per-module cards with signatures and source anchors)

Quick Reference

Function / Class	Purpose
subject.Subject	In-memory container for MRI/mesh/ROI/experiment metadata.
subject.save_subject_hdf5()	Persist subject-level dictionaries into pyNIBS HDF5 layout.
subject.load_subject()	Route to HDF5/PKL loaders based on filename or explicit filetype.
hdf5_io.split_hdf5()	Split geometry (/mesh, /nodes) from data (/data, /fields, /coil).
mesh.mesh_struct.Mesh	Structured mesh metadata object with defaults per meshing approach.
mesh.mesh_struct.ROI	ROI metadata object serialized under roi/<mesh>/<roi>.
optimization.coil_opt.get_optimal_coil_positions()	Select coil placements under criterion-driven optimization goals.
optimization.multichannel.get_score_raw()	Compute decorrelation score for multichannel current optimization.
regression.regression.regress_data()	Mass-univariate nonlinear MEP~E fitting across ROI elements.
expio.exp.read_exp_stimulations()	Parse experiment CSV inputs into coil matrices, conditions, and MEP vectors.

---

Module Map

Submodule	Contents	Notes
pynibs.subject	Subject object + save/load wrappers	Imports h5py
pynibs.hdf5_io	HDF5 read/write + XDMF helpers	Large (hdf5_io.py, xdmf.py)
pynibs.mesh	Mesh/ROI classes + geometric transforms	Multiple [LARGE] modules
pynibs.roi	Surface/volume ROI structure logic	Heavy geometry data workflows
pynibs.optimization	Coil-placement and multichannel optimization	Research-focused objective functions
pynibs.regression	Nonlinear element-wise regression and dual-node methods	Core mapping algorithms
pynibs.expio	Import/clean experimental logs and navigator exports	Includes trial QC helpers
pynibs.visualization	2D/3D rendering helpers	mayavi often required

Import style: mixed eager star-imports + lazy __getattr__ at top-level (pynibs/__init__.py), plus explicit __all__ submodule list.

See assets/module-map.md for full inventory, line counts, and large-module flags.

---

References

• references/subject-and-session-io.md - subject object schema, HDF5 save/load contracts, and plot-settings helper.
• references/mesh-and-roi-structures.md - mesh defaults, ROI containers, and structural metadata write path.
• references/hdf5-and-xdmf.md - HDF5 group layout, split/read helpers, and file-level pitfalls.
• references/optimization-workflows.md - coil optimization and multichannel scoring semantics.
• references/regression-and-localization.md - mass-univariate nonlinear regression API and fit controls.
• references/experiment-import-and-qc.md - experiment CSV import, filtering, and correction workflow entrypoints.