utils

tit.sim.utils ¶

Shared utilities for TI/mTI simulations.

This module provides all non-class helpers consumed by the simulation package:

Montage file I/O -- CRUD operations on montage_list.json.
Montage loading -- resolve EEG-cap and flex/freehand montages.
Directory setup -- create the BIDS output directory tree.
Montage visualisation -- render 2-D montage diagrams.
Post-processing helpers -- field extraction, NIfTI conversion, T1-to-MNI transform, file moves.
Simulation orchestration -- sequential montage execution.

Public API¶

run_simulation Execute simulations for every montage in a configuration. load_montages Load named montages from montage_list.json. list_montage_names List montage names defined under an EEG net. load_montage_data Load the full montage_list.json as a dict. save_montage_data Write a montage dict to montage_list.json. ensure_montage_file Return (and optionally create) the montage_list.json path. upsert_montage Insert or update a montage definition.

ensure_montage_file ¶

ensure_montage_file(*, pm: PathManager | None = None) -> str

Return the path to montage_list.json, creating it if absent.

If the file does not exist, creates it with the default schema {"nets": {}}.

Returns¶

str Absolute path to the montage_list.json file.

load_montage_data ¶

load_montage_data(*, pm: PathManager | None = None) -> dict

Load the full montage_list.json as a dict.

Returns¶

dict Parsed JSON with top-level key "nets" mapping EEG net names to their uni/multi polar montage definitions.

save_montage_data ¶

save_montage_data(data: dict, *, pm: PathManager | None = None) -> None

Write data to montage_list.json, overwriting the file.

Parameters¶

data : dict Full montage dict (must contain a "nets" key).

ensure_eeg_net_entry ¶

ensure_eeg_net_entry(eeg_net: str) -> None

Ensure an entry for eeg_net exists in montage_list.json.

If the net is not yet present, creates it with empty uni_polar_montages and multi_polar_montages dicts.

Parameters¶

eeg_net : str EEG net identifier (e.g. "GSN-HydroCel-185.csv").

upsert_montage ¶

upsert_montage(*, eeg_net: str, montage_name: str, electrode_pairs: list[list[str]], mode: str, pm: PathManager | None = None) -> None

Insert or update a montage definition in montage_list.json.

Creates the EEG net entry if it does not already exist.

Parameters¶

eeg_net : str EEG-net CSV filename exactly as it appears in the subject's eeg_positions folder, e.g. "GSN-HydroCel-185.csv" or "EEG10-10_UI_Jurak_2007.csv". Created in the file if absent. montage_name : str Montage name; an existing montage of the same name under this net and mode is replaced. electrode_pairs : list[list[str]] Electrode pairs, each a two-element list of labels from that net (e.g. [["E010", "E011"], ["E012", "E013"]]). Two pairs for mode="U", four (or more, even) for mode="M". mode : str "U" for uni-polar montages (2-pair TI) or "M" for multi-polar montages (4+-pair mTI). Case-insensitive; anything other than "U" is treated as "M". pm : PathManager or None, optional Path manager to locate the project; None uses the global one.

Returns¶

None The file is rewritten in place.

Examples¶

from tit.sim import upsert_montage, list_montage_names upsert_montage( ... eeg_net="GSN-HydroCel-185.csv", ... montage_name="L_Insula", ... electrode_pairs=[["E010", "E011"], ["E012", "E013"]], ... mode="U", ... ) # doctest: +SKIP list_montage_names("GSN-HydroCel-185.csv", mode="U") # doctest: +SKIP ['L_Insula']

list_montage_names ¶

list_montage_names(eeg_net: str, *, mode: str) -> list[str]

List all montage names defined under an EEG net.

These are exactly the names :func:load_montages can resolve for that net; a name not in this list is silently skipped by :func:load_montages.

Parameters¶

eeg_net : str EEG-net CSV filename (e.g. "GSN-HydroCel-185.csv", "EEG10-10_UI_Jurak_2007.csv"), the key under montage_list.json["nets"]. mode : str "U" for uni-polar (2-pair TI) montage names or "M" for multi-polar (4+-pair mTI) montage names. Case-insensitive.

Returns¶

list[str] Sorted montage names. Returns an empty list if the net or mode key does not exist (never raises for an unknown net).

Examples¶

from tit.sim import list_montage_names list_montage_names("GSN-HydroCel-185.csv", mode="U") # doctest: +SKIP ['L_Insula', 'R_Insula'] list_montage_names("GSN-HydroCel-185.csv", mode="M") # doctest: +SKIP []

load_flex_montages ¶

load_flex_montages(flex_file: str | None = None) -> list[dict]

Load flex/freehand montage definitions from a JSON file.

Parameters¶

flex_file : str or None, optional Path to the flex montages JSON file. Falls back to the FLEX_MONTAGES_FILE environment variable if not provided.

Returns¶

list[dict] List of raw flex montage dicts. Returns an empty list if no file is found.

parse_flex_montage ¶

parse_flex_montage(flex: dict) -> Montage

Convert a raw flex montage dict into a Montage dataclass.

Parameters¶

flex : dict Dict with keys "name", "type", and either "pairs" (for flex_mapped) or "electrode_positions" (for flex_optimized / freehand_xyz).

Returns¶

Montage Populated Montage instance.

Raises¶

ValueError If flex["type"] is not a recognised montage type.

load_montages ¶

load_montages(montage_names: list[str], eeg_net: str, include_flex: bool = True) -> list[Montage]

Load the named montages from the project's montage_list.json.

Only the montages named in montage_names are returned, in that order -- this is not a listing of every montage under the net. load_montages(["L_Insula"], ...) returns a one-element list, so indexing [1] raises IndexError. Use :func:list_montage_names to see which names exist. A name that is not defined under eeg_net is silently skipped (no error), so the result can be shorter than montage_names; check len() or the returned .name values before relying on positions.

Reads the montage_list.json file (managed by :func:ensure_montage_file), looks up each name under the given EEG net's uni- and multi-polar sections, and returns them as :class:Montage instances. When include_flex is True and the FLEX_MONTAGES_FILE environment variable points at a file, any flex/freehand montages found via :func:load_flex_montages are appended after the named ones (nothing is appended when the variable is unset, the normal case for scripts).

The eeg_net value determines the montage mode:

"freehand" sets Montage.Mode.FREEHAND
"flex_mode" sets Montage.Mode.FLEX_FREE
Any other value (e.g. "GSN-HydroCel-185.csv") sets Montage.Mode.NET

Parameters¶

montage_names : list[str] Names to look up in the montage file, e.g. ["L_Insula"]. Order is preserved in the result. eeg_net : str EEG-net CSV filename (e.g. "GSN-HydroCel-185.csv", "EEG10-10_UI_Jurak_2007.csv") that selects the sub-dict inside montage_list.json["nets"]; it is also stored on each returned :class:Montage as eeg_net. include_flex : bool, optional If True (default), append flex/freehand montages loaded from the FLEX_MONTAGES_FILE environment variable.

Returns¶

list[Montage] One :class:Montage per found name, in montage_names order, ready to pass as SimulationConfig(montages=...).

Examples¶

from tit.sim import list_montage_names, load_montages list_montage_names("GSN-HydroCel-185.csv", mode="U") # doctest: +SKIP ['L_Insula', 'R_Insula'] montages = load_montages(["L_Insula"], eeg_net="GSN-HydroCel-185.csv") # doctest: +SKIP len(montages), montages[0].name # doctest: +SKIP (1, 'L_Insula') both = load_montages(["L_Insula", "R_Insula"], eeg_net="GSN-HydroCel-185.csv") # doctest: +SKIP [m.name for m in both] # doctest: +SKIP ['L_Insula', 'R_Insula']

setup_montage_directories ¶

setup_montage_directories(montage_dir: str, mode: SimulationMode) -> dict[str, str]

Create the BIDS-compliant output directory tree for one montage.

Creates sub-directories for high-frequency fields, TI fields, meshes, NIfTIs, surface overlays, montage images, and documentation. For mTI mode, additional mTI/ sub-directories are created.

Parameters¶

montage_dir : str Root output directory for this montage. mode : SimulationMode SimulationMode.TI or SimulationMode.MTI.

Returns¶

dict[str, str] Mapping of logical names (e.g. "ti_mesh", "hf_niftis") to their absolute paths.

run_montage_visualization ¶

run_montage_visualization(montage_name: str, simulation_mode: SimulationMode, eeg_net: str, output_dir: str, logger, electrode_pairs: list | None = None) -> None

Render a 2-D montage diagram for an EEG-cap montage.

Skips rendering for "freehand" and "flex_mode" montages (no cap layout available).

Parameters¶

montage_name : str Name of the montage to visualize. simulation_mode : SimulationMode SimulationMode.TI or SimulationMode.MTI. eeg_net : str EEG net identifier. Visualization is skipped when this is "freehand" or "flex_mode". output_dir : str Directory where the image file is saved. logger : logging.Logger Logger instance for status messages. electrode_pairs : list or None, optional Electrode pair list to annotate on the diagram. Defaults to an empty list.

resolve_montage_electrode_coordinates ¶

resolve_montage_electrode_coordinates(config: SimulationConfig, montage: Montage, logger=None) -> tuple[list[list[float]] | None, str | None]

Resolve every electrode in montage to XYZ coordinates when possible.

Source code in tit/sim/utils.py

def resolve_montage_electrode_coordinates(
    config: SimulationConfig, montage: Montage, logger=None
) -> tuple[list[list[float]] | None, str | None]:
    """Resolve every electrode in *montage* to XYZ coordinates when possible."""
    if montage.is_xyz:
        return (
            [_as_xyz(pos) for pair in montage.electrode_pairs for pos in pair],
            "config_xyz",
        )

    if not montage.eeg_net:
        if logger:
            logger.warning("No EEG net set; electrode coordinates not written")
        return None, None

    try:
        pm = get_path_manager()
        eeg_path = os.path.join(pm.eeg_positions(config.subject_id), montage.eeg_net)
        eeg_positions = _load_eeg_position_csv(eeg_path)
        coordinates = [
            eeg_positions[pos] for pair in montage.electrode_pairs for pos in pair
        ]
    except (OSError, RuntimeError, KeyError, ValueError) as exc:
        if logger:
            logger.warning("Could not resolve electrode coordinates: %s", exc)
        return None, None

    return coordinates, os.path.join("eeg_positions", montage.eeg_net)

create_simulation_config_file ¶

create_simulation_config_file(config: SimulationConfig, montage: Montage, documentation_dir: str, logger) -> None

Write a JSON snapshot of the simulation configuration to disk.

Serialises subject ID, montage details, electrode geometry, mapping options, and a timestamp into config.json inside documentation_dir.

Parameters¶

config : SimulationConfig The full simulation configuration. montage : Montage The specific montage being simulated. documentation_dir : str Directory to write config.json into. logger : logging.Logger Logger instance for status messages.

extract_fields ¶

extract_fields(input_mesh: str, output_dir: str, base_name: str, m2m_dir: str, subject_id: str, logger) -> None

Extract grey-matter and white-matter meshes from a full-head mesh.

Crops the input mesh by SimNIBS tissue tags (tag 2 = GM, tag 1 = WM) and writes the results as separate .msh files.

Parameters¶

input_mesh : str Path to the full-head .msh file. output_dir : str Directory to write the cropped meshes into. base_name : str Stem used for output filenames (e.g. "grey_{base_name}.msh"). m2m_dir : str Path to the subject's m2m directory (unused but kept for interface consistency). subject_id : str Subject identifier (unused but kept for interface consistency). logger : logging.Logger Logger instance for status messages.

transform_to_nifti ¶

transform_to_nifti(mesh_dir: str, output_dir: str, subject_id: str, m2m_dir: str, logger, fields: list[str] | None = None, skip_patterns: list[str] | None = None) -> None

Convert mesh files in a directory to NIfTI volumes.

Delegates to tit.tools.mesh2nii.convert_mesh_dir which transforms each .msh file into subject-space (and optionally MNI-space) NIfTI images.

Parameters¶

mesh_dir : str Directory containing .msh files to convert. output_dir : str Directory to write the resulting NIfTI files. subject_id : str Subject identifier (unused but kept for interface consistency). m2m_dir : str Path to the subject's m2m directory, used for coordinate transforms. logger : logging.Logger Logger instance for status messages. fields : list[str] or None, optional Mesh field names to convert. Converts all fields if None. skip_patterns : list[str] or None, optional Filename patterns to skip during conversion.

transform_dirs_to_nifti ¶

transform_dirs_to_nifti(specs: list[dict], m2m_dir: str, logger, *, map_to_mni: bool = False) -> None

Convert several mesh directories to NIfTI in a single process pool.

Thin wrapper over tit.tools.mesh2nii.convert_mesh_dirs. Overlaps directories that would otherwise be converted one after another (e.g. the TI-mesh and HF-mesh directories) by submitting every conversion task to one shared pool.

Parameters¶

specs : list[dict] One dict per directory with keys mesh_dir and output_dir (required) and optional fields / skip_patterns. m2m_dir : str Path to the subject's m2m directory, used for coordinate transforms. logger : logging.Logger Logger instance for status messages.

start_t1_to_mni ¶

start_t1_to_mni(m2m_dir: str, subject_id: str) -> Popen

Launch the subject T1-to-MNI warp and return the running process.

The subject2mni transform is independent of the simulation field meshes, so it can run concurrently with the mesh-to-NIfTI conversions. Pair this with :func:finish_t1_to_mni to wait for completion.

Parameters¶

m2m_dir : str Path to the subject's m2m directory containing T1.nii.gz. subject_id : str Subject identifier, used for the output filename.

Returns¶

subprocess.Popen The running subject2mni process.

Source code in tit/sim/utils.py

def start_t1_to_mni(m2m_dir: str, subject_id: str) -> subprocess.Popen:
    """Launch the subject T1-to-MNI warp and return the running process.

    The ``subject2mni`` transform is independent of the simulation field
    meshes, so it can run concurrently with the mesh-to-NIfTI conversions.
    Pair this with :func:`finish_t1_to_mni` to wait for completion.

    Parameters
    ----------
    m2m_dir : str
        Path to the subject's m2m directory containing ``T1.nii.gz``.
    subject_id : str
        Subject identifier, used for the output filename.

    Returns
    -------
    subprocess.Popen
        The running ``subject2mni`` process.
    """
    t1 = os.path.join(m2m_dir, "T1.nii.gz")
    out = os.path.join(m2m_dir, f"T1_{subject_id}")
    return subprocess.Popen(
        ["subject2mni", "-i", t1, "-m", m2m_dir, "-o", out],
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
    )

finish_t1_to_mni ¶

finish_t1_to_mni(proc: Popen, logger, timeout: int = 300) -> None

Wait for a :func:start_t1_to_mni process and log any failure.

Logs a warning (but does not raise) if the conversion fails or times out, matching the previous best-effort behaviour.

Parameters¶

proc : subprocess.Popen Process returned by :func:start_t1_to_mni. logger : logging.Logger Logger instance for warning messages. timeout : int Seconds to wait before killing the process.

Source code in tit/sim/utils.py

def finish_t1_to_mni(proc: subprocess.Popen, logger, timeout: int = 300) -> None:
    """Wait for a :func:`start_t1_to_mni` process and log any failure.

    Logs a warning (but does not raise) if the conversion fails or times
    out, matching the previous best-effort behaviour.

    Parameters
    ----------
    proc : subprocess.Popen
        Process returned by :func:`start_t1_to_mni`.
    logger : logging.Logger
        Logger instance for warning messages.
    timeout : int
        Seconds to wait before killing the process.
    """
    try:
        _, stderr = proc.communicate(timeout=timeout)
    except subprocess.TimeoutExpired:
        proc.kill()
        proc.communicate()
        logger.warning("T1 MNI conversion timed out")
        return
    if proc.returncode != 0:
        logger.warning(f"T1 MNI conversion warning: {stderr}")

convert_t1_to_mni ¶

convert_t1_to_mni(m2m_dir: str, subject_id: str, logger) -> None

Convert the subject's T1 image to MNI space via subject2mni.

Blocking convenience wrapper around :func:start_t1_to_mni / :func:finish_t1_to_mni. Logs a warning (but does not raise) if the conversion fails.

Parameters¶

m2m_dir : str Path to the subject's m2m directory containing T1.nii.gz. subject_id : str Subject identifier, used for the output filename. logger : logging.Logger Logger instance for status/warning messages.

safe_move ¶

safe_move(src: str, dest: str) -> None

Move a file or directory from src to dest.

Ignore a missing AppleDouble sidecar only after its data file has moved.

Parameters¶

src : str Source path. dest : str Destination path.

build_simulation_config_for_job ¶

build_simulation_config_for_job(subject_id: str, montage: Montage, current_str: str, conductivity: str, electrode_shape: str, electrode_dimensions: list[float], gel_thickness: float, output_fields: list[str] | None = None) -> SimulationConfig

Build the backend config for one subject/montage job.

Source code in tit/sim/utils.py

def build_simulation_config_for_job(
    subject_id: str,
    montage: Montage,
    current_str: str,
    conductivity: str,
    electrode_shape: str,
    electrode_dimensions: list[float],
    gel_thickness: float,
    output_fields: list[str] | None = None,
) -> SimulationConfig:
    """Build the backend config for one subject/montage job."""
    kwargs = {}
    if output_fields is not None:
        kwargs["output_fields"] = output_fields
    return SimulationConfig(
        subject_id=subject_id,
        montages=[montage],
        conductivity=conductivity,
        intensities=parse_intensities(current_str),
        electrode_shape=electrode_shape,
        electrode_dimensions=electrode_dimensions,
        gel_thickness=gel_thickness,
        **kwargs,
    )

run_simulation ¶

run_simulation(config: SimulationConfig, logger: Logger | None = None, progress_callback: Callable[[int, int, str], None] | None = None, *, overwrite: bool = False) -> list[dict]

Run TI or mTI simulations for every montage in config.

For each montage in config.montages, this function:

Auto-detects TI (2 pairs) vs mTI (4+ pairs) from the montage.
Builds a SimNIBS SESSION with electrode geometry and conductivity settings from config.
Runs the FEM solver to compute electric-field distributions.
Computes temporal-interference envelope fields: TI_max/TI_avg plus TI_normal (2-pair TI only), or the multi-channel superposition for mTI.
Writes output meshes, surface overlays, and NIfTIs to the BIDS-compliant simulation directory.

Montages are processed sequentially. If no logger is provided, a file logger is created under the subject's log directory.

Parameters¶

config : SimulationConfig Full simulation configuration including subject ID, montage list, electrode geometry, and conductivity model. logger : logging.Logger or None, optional Logger instance. If None, a file logger is created automatically in the subject's BIDS logs directory. progress_callback : callable or None, optional Optional callback invoked before each montage as callback(current_index, total, montage_name) and once more with (total, total, "Complete") when finished.

bool, optional

Explicitly allow SimNIBS to rerun in the montage output directory. Defaults to False; existing-result protection stays enabled unless confirmed.

Returns¶

list[dict] One result dict per montage with keys montage_name, montage_type, status, and output_mesh.

Raises¶

ValueError If config.montages is empty, the subject's m2m_<id> directory does not exist, a montage has an invalid pair count (must be an even number >= 2), too few intensities are given for a montage, a label-based montage has no eeg_net or its EEG-net CSV is missing from the subject's eeg_positions folder, or an XYZ montage holds a malformed coordinate. OSError Raised by SimNIBS when a montage output directory already holds results and overwrite is False.

Examples¶

from tit.sim import SimulationConfig, load_montages, run_simulation montages = load_montages(["L_Insula"], eeg_net="GSN-HydroCel-185.csv") # doctest: +SKIP cfg = SimulationConfig(subject_id="ernie", montages=montages, ... intensities=[1.0, 1.0], output_fields=["TI_max"]) # doctest: +SKIP results = run_simulation(cfg) # doctest: +SKIP results[0]["status"], results[0]["output_mesh"] # doctest: +SKIP ('completed', '.../Simulations/L_Insula/TI/mesh/ernie_L_Insula_TI.msh')

utils

tit.sim.utils ¶

Public API¶

See Also¶

ensure_montage_file ¶

Returns¶

See Also¶

load_montage_data ¶

Returns¶

See Also¶

save_montage_data ¶

Parameters¶

See Also¶

ensure_eeg_net_entry ¶

Parameters¶

See Also¶

upsert_montage ¶

Parameters¶

Returns¶

Examples¶

See Also¶

list_montage_names ¶

Parameters¶

Returns¶

Examples¶

See Also¶

load_flex_montages ¶

Parameters¶

Returns¶

See Also¶

parse_flex_montage ¶

Parameters¶

Returns¶

Raises¶

See Also¶

load_montages ¶

Parameters¶

Returns¶

Examples¶

See Also¶

setup_montage_directories ¶

Parameters¶

Returns¶

See Also¶

run_montage_visualization ¶

Parameters¶

See Also¶

resolve_montage_electrode_coordinates ¶

create_simulation_config_file ¶

Parameters¶

See Also¶

extract_fields ¶

Parameters¶

See Also¶

transform_to_nifti ¶

Parameters¶

See Also¶

transform_dirs_to_nifti ¶

Parameters¶

See Also¶

start_t1_to_mni ¶

Parameters¶

Returns¶

finish_t1_to_mni ¶

Parameters¶

convert_t1_to_mni ¶

Parameters¶

See Also¶

safe_move ¶

Parameters¶

See Also¶

build_simulation_config_for_job ¶

run_simulation ¶

Parameters¶

Returns¶

Raises¶

Examples¶

See Also¶