# Pynibs

> pyNIBS

- Skill: `hughyau/pynibs` (Agent Skill, multi-file: 76 files)
- Install (CLI): `npx skillmds@latest add hughyau/pynibs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hughyau/pynibs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HughYau (https://skillmd.com/u/hughyau)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hughyau/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.