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') -> 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".

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" or "voxel".

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
def select_field_file(
    subject_id: str,
    simulation: str,
    space: str,
    tissue_type: str = "GM",
) -> 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"``.

    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"`` or ``"voxel"``.

    See Also
    --------
    Analyzer : Consumes the resolved path to load and analyze fields.
    """
    pm = get_path_manager()
    sim_dir = Path(pm.simulation(subject_id, simulation))
    is_mti = (sim_dir / "mTI" / "mesh").is_dir()

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