Pynibs

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

Module Map

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.