Skip to content

field_selector

tit.analyzer.field_selector

Field selection utilities for automatic field file determination.

Resolves the correct field file path and SimNIBS field name for a given subject, simulation, and analysis space (mesh or voxel).

Public API

select_field_file Resolve the field path and SimNIBS field name for a subject/simulation.

See Also

tit.analyzer.analyzer : Analyzer class that consumes the resolved paths.

select_field_file 

select_field_file(subject_id: str, simulation: str, space: str, tissue_type: str = 'GM', field: str | None = None) -> tuple[Path, str]

Return the field file path and SimNIBS field name.

Detects whether the simulation is TI (2-pair) or mTI (4-pair) by checking for the existence of the mTI mesh directory.

Parameters

subject_id : str Subject identifier (without sub- prefix). simulation : str Simulation (montage) folder name. space : str "mesh" or "voxel". tissue_type : str, optional "GM", "WM", or "both" (voxel only). Default "GM". field : str or None, optional Field name from constants.FIELD_REGISTRY (e.g. "hf_peak"). Default None resolves TI_max (TI) or mTI_max (mTI). "TI_max"/"mTI_max" are treated as aliases for the same quantity; the on-disk spelling is always chosen by the detected simulation type, regardless of which alias is passed.

Returns

field_path : pathlib.Path Resolved absolute path to the field file. field_name : str SimNIBS field name (e.g. "TI_max", "mTI_max").

Raises

FileNotFoundError If the expected field file does not exist. ValueError If space is not "mesh"/"voxel", field is unknown, or TI_normal is requested in voxel space (it has no NIfTI export).

See Also

Analyzer : Consumes the resolved path to load and analyze fields.

Source code in tit/analyzer/field_selector.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def select_field_file(
    subject_id: str,
    simulation: str,
    space: str,
    tissue_type: str = "GM",
    field: str | None = None,
) -> tuple[Path, str]:
    """Return the field file path and SimNIBS field name.

    Detects whether the simulation is TI (2-pair) or mTI (4-pair) by checking
    for the existence of the mTI mesh directory.

    Parameters
    ----------
    subject_id : str
        Subject identifier (without ``sub-`` prefix).
    simulation : str
        Simulation (montage) folder name.
    space : str
        ``"mesh"`` or ``"voxel"``.
    tissue_type : str, optional
        ``"GM"``, ``"WM"``, or ``"both"`` (voxel only). Default ``"GM"``.
    field : str or None, optional
        Field name from ``constants.FIELD_REGISTRY`` (e.g. ``"hf_peak"``).
        Default ``None`` resolves ``TI_max`` (TI) or ``mTI_max`` (mTI).
        ``"TI_max"``/``"mTI_max"`` are treated as aliases for the same
        quantity; the on-disk spelling is always chosen by the detected
        simulation type, regardless of which alias is passed.

    Returns
    -------
    field_path : pathlib.Path
        Resolved absolute path to the field file.
    field_name : str
        SimNIBS field name (e.g. ``"TI_max"``, ``"mTI_max"``).

    Raises
    ------
    FileNotFoundError
        If the expected field file does not exist.
    ValueError
        If *space* is not ``"mesh"``/``"voxel"``, *field* is unknown, or
        ``TI_normal`` is requested in voxel space (it has no NIfTI export).

    See Also
    --------
    Analyzer : Consumes the resolved path to load and analyze fields.
    """
    if field is not None:
        try:
            const.get_field_spec(field)
        except KeyError as exc:
            valid = ", ".join(const.get_field_names())
            raise ValueError(
                f"Unknown field: {field!r}. Valid fields: {valid}."
            ) from exc

    pm = get_path_manager()
    sim_dir = Path(pm.simulation(subject_id, simulation))
    is_mti = is_mti_simulation(subject_id, simulation)

    if space == "mesh":
        return _select_mesh(sim_dir, simulation, is_mti, field)
    if space == "voxel":
        return _select_voxel(sim_dir, is_mti, tissue_type, field)
    raise ValueError(f"Unsupported space: {space!r} (expected 'mesh' or 'voxel')")

is_mti_simulation 

is_mti_simulation(subject_id: str, simulation: str) -> bool

Whether simulation is an mTI (multipolar) run.

The only signal is whether the simulation wrote an mTI/mesh/ directory; there is no flag stored anywhere else.

Parameters

subject_id : str Subject identifier (without sub- prefix). simulation : str Simulation (montage) folder name.

Returns

bool True for an mTI simulation, False for 2-pair TI.

Source code in tit/analyzer/field_selector.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def is_mti_simulation(subject_id: str, simulation: str) -> bool:
    """Whether *simulation* is an mTI (multipolar) run.

    The only signal is whether the simulation wrote an ``mTI/mesh/``
    directory; there is no flag stored anywhere else.

    Parameters
    ----------
    subject_id : str
        Subject identifier (without ``sub-`` prefix).
    simulation : str
        Simulation (montage) folder name.

    Returns
    -------
    bool
        ``True`` for an mTI simulation, ``False`` for 2-pair TI.
    """
    sim_dir = Path(get_path_manager().simulation(subject_id, simulation))
    return (sim_dir / "mTI" / "mesh").is_dir()