TI-Toolbox API Reference¶

Welcome to the Python API reference for TI-Toolbox (tit) — a platform for temporal interference (TI) brain stimulation simulation, optimization, and analysis.

The TI-Toolbox Pipeline¶

TI-Toolbox follows a structured pipeline with one-time preprocessing and an iterative research cycle:

graph TD
    PRE["`**1. Preprocessing**
    DICOM → NIfTI → recon-all → CHARM
    *(one-time setup)*`"]

    OPT["`**2. Optimization**
    Flex-search · Ex-search
    *(find optimal electrodes)*`"]

    SIM["`**3. Simulation**
    TI (2-pair) · mTI (4-pair)
    *(run FEM simulations)*`"]

    ANA["`**4. Analysis**
    ROI stats · field analysis
    *(evaluate results)*`"]

    REP["`**5. Reporting**
    HTML reports · plots
    *(visualize & document)*`"]

    PRE -->|head mesh| OPT
    PRE -->|head mesh| SIM
    OPT -->|optimal montage| SIM
    SIM -->|field data| ANA
    ANA -->|metrics| REP
    ANA -->|refine parameters| OPT
    SIM -->|outputs| REP
    OPT -->|results| REP

    style PRE fill:#2d5a27,stroke:#4a8,color:#fff
    style OPT fill:#1a3a5c,stroke:#48a,color:#fff
    style SIM fill:#1a3a5c,stroke:#48a,color:#fff
    style ANA fill:#1a3a5c,stroke:#48a,color:#fff
    style REP fill:#1a3a5c,stroke:#48a,color:#fff

Iterative Workflow

Preprocessing is a one-time setup per subject. After that, steps 2-5 form an iterative cycle: optimize electrode placements, simulate fields, analyze results, generate reports, then refine and repeat.

Quick Start¶

from tit import init, get_path_manager
from tit.sim import SimulationConfig, Montage
from tit.sim import run_simulation, load_montages
from tit.analyzer import Analyzer
from tit.opt import FlexConfig, run_flex_search

# Initialize (configures logging with terminal output)
init("INFO")
pm = get_path_manager("/path/to/project")

# Run a simulation
montages = load_montages(["my_montage"], "/path/to/project", "GSN-HydroCel-185")
config = SimulationConfig(
    subject_id="001",
    project_dir="/path/to/project",
    montages=montages,
    conductivity="scalar",
    intensities=[1.0, 1.0],
)
results = run_simulation(config)

# Analyze results
analyzer = Analyzer(subject_id="001", simulation="my_montage", space="mesh")
result = analyzer.analyze_sphere(center=(-42, -20, 55), radius=10)
print(f"ROI Mean: {result.roi_mean:.4f} V/m")
print(f"Focality: {result.roi_focality:.2f}")

For a full walkthrough, see the Getting Started guide.

Pipeline Modules¶

Step	Module	Description	Guide
1. Preprocessing	`tit.pre`	DICOM conversion, FreeSurfer recon-all, CHARM head mesh	Preprocessing
2. Optimization	`tit.opt`	Flex-search (differential evolution) and exhaustive search	Optimization
3. Simulation	`tit.sim`	TI and multi-channel TI (mTI) simulation engine	Simulation
4. Analysis	`tit.analyzer`	Field analysis with spherical and cortical ROIs	Analysis
5. Reporting	`tit.reporting`	HTML report generation and visualization	Reporting

Supporting Modules¶

Module	Description	Guide
`tit`	Path management, constants, logging, config IO, error handling	Core Utilities
`tit.stats`	Cluster-based permutation testing and group-level statistics	Statistics
`tit.atlas`	Surface and volumetric atlas discovery, overlap analysis	Atlas
`tit.plotting`	Visualization utilities (histograms, overlays, statistical plots)	Plotting
`tit.tools`	Standalone mesh/NIfTI conversion and electrode mapping utilities	Utility Tools

Build Locally¶

cd /path/to/TI-Toolbox
pip install -r docs/api_mkdocs/requirements.txt
mkdocs build -f docs/api_mkdocs/mkdocs.yml --clean
# Open docs/api/index.html