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

select_field_file

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

Return (field_path, field_name) for a given subject/simulation/space.

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

Parameters:

Name	Type	Description	Default
subject_id	str	Subject identifier (without sub- prefix).	required
simulation	str	Simulation (montage) folder name.	required
space	str	"mesh" or "voxel".	required

Returns:

Type	Description
tuple[Path, str]	Tuple of (resolved field path, SimNIBS field name).

Raises:

Type	Description
FileNotFoundError	If the expected field file does not exist.
ValueError	If space is not "mesh" or "voxel".

Source code in tit/analyzer/field_selector.py

def select_field_file(
    subject_id: str,
    simulation: str,
    space: str,
    tissue_type: str = "GM",
) -> tuple[Path, str]:
    """Return (field_path, field_name) for a given subject/simulation/space.

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

    Args:
        subject_id: Subject identifier (without ``sub-`` prefix).
        simulation: Simulation (montage) folder name.
        space: ``"mesh"`` or ``"voxel"``.

    Returns:
        Tuple of (resolved field path, SimNIBS field name).

    Raises:
        FileNotFoundError: If the expected field file does not exist.
        ValueError: If *space* is not ``"mesh"`` or ``"voxel"``.
    """
    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')")