Electrode Mapping

Overview

The map_electrodes.py tool maps optimized electrode positions to the nearest available positions in an EEG net using the Hungarian algorithm (linear sum assignment) for optimal matching.

Usage

In the Simulator, choose a Flex montage source and enable mapping to an EEG net. The same mapping helpers can be used from a script:

import os
from tit.tools.map_electrodes import (
    load_electrode_positions_json,
    read_csv_positions,
    map_electrodes_to_net,
    save_mapping_result,
    log_mapping_summary,
)

opt_pos, ch_arr_idx = load_electrode_positions_json("flex-search/<run>/electrode_positions.json")
net_pos, net_labels = read_csv_positions("m2m_ernie/eeg_positions/GSN-HydroCel-185.csv")
result = map_electrodes_to_net(opt_pos, net_pos, net_labels, ch_arr_idx)
save_mapping_result(result, "electrode_mapping.json",
                    eeg_net_name="GSN-HydroCel-185.csv")
log_mapping_summary(result)    # per-electrode distances, via the tit.tools logger

save_mapping_result needs an explicit output path; the eeg_net key only appears in the JSON when eeg_net_name is given.

Input Format

electrode_positions.json

{
  "optimized_positions": [
    [-85.61, -29.0, -8.56],
    [72.81, -44.38, -16.95]
  ],
  "channel_array_indices": [
    [0, 0],
    [0, 1]
  ]
}

EEG Net CSV

The tool supports multiple CSV formats commonly used in neuroimaging:

SimNIBS format:

Type,X,Y,Z,Name,Extra
Electrode,-85.5,-28.9,-8.4,E1,
ReferenceElectrode,0.0,85.0,0.0,REF,

Simple format:

Label,X,Y,Z
E1,-85.5,-28.9,-8.4
E2,72.9,-44.5,-17.1
REF,0.0,85.0,0.0

Notes:

  • The tool automatically detects the format based on the first column
  • Only Electrode and ReferenceElectrode types are included (Fiducials are ignored)
  • Empty lines and lines starting with # are skipped

Output Format

The tool generates a JSON file with the following structure:

{
  "optimized_positions": [
    [-85.61, -29.0, -8.56],
    [72.81, -44.38, -16.95]
  ],
  "mapped_positions": [
    [-85.5, -28.9, -8.4],
    [72.9, -44.5, -17.1]
  ],
  "mapped_labels": ["E1", "E2"],
  "distances": [0.15, 0.12],
  "channel_array_indices": [
    [0, 0],
    [0, 1]
  ],
  "eeg_net": "EGI_template.csv"
}

Features

  • Optimal Assignment: Uses the Hungarian algorithm to find the globally optimal mapping that minimizes total distance
  • Detailed Reporting: log_mapping_summary() logs a per-electrode distance summary
  • Flexible Input: Supports multiple CSV formats commonly used in neuroimaging
  • Error Handling: Validates input files and provides clear error messages

Integration with TI-Toolbox

This module is called when a flex-search result is simulated with electrodes mapped onto an EEG net (see tit/sim/montage_sources.py). It can also be used standalone for post-hoc analysis or custom workflows.

EEG Net Density Impact on Optimization Performance

Network Density Impact on TImax

Impact of EEG net density on TImax intensity: This analysis demonstrates the progressive decline in achievable TImax intensity as electrode density decreases. Starting from fully optimized electrode positions (theoretical maximum), the study shows how mapping to standardized EEG nets progressively reduces field strength: fully optimized positions achieve maximum intensity, followed by 10:5 density (high coverage), 10:10 system (standard density), and finally 10:20 system showing the greatest reduction. This highlights the trade-off between practical electrode accessibility and theoretical optimization performance.

Example Workflow

  1. Run flex-search optimization to generate electrode_positions.json
  2. Save the Python example above in a script, replace its input/output paths, and run it with simnibs_python your_mapping_script.py. The mapping module exposes Python functions; it does not provide -i / -n / -o command-line flags.
  3. Use the mapped positions for simulation or analysis

Notes

  • If there are more optimized electrodes than available net positions, the assignment can cover only as many electrodes as there are net positions. Inspect the returned indices and ensure every required electrode is mapped before simulation; the selected subset is not necessarily the first N electrodes.
  • Distances are reported in millimeters
  • The tool preserves the channel and array indices from the optimization for downstream processing