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 --> 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 ```bash # 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 ```python # 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 ```python # 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 ```python # 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 ```python # 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 ```python # 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 ```python # 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+) ```bash 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.