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