constants

tit.constants

Project-wide constants for TI-Toolbox.

Centralises all hard-coded values, magic numbers, and configuration defaults used across the TI-Toolbox codebase. Constants are grouped by domain:

Sections

Directory Names BIDS-compliant directory structure names (DIR_*). File Names and Extensions Configuration filenames (FILE_*), NIfTI filenames, and common extensions (EXT_*). Subject and Naming Patterns BIDS prefixes (PREFIX_*). Environment Variables Expected os.environ keys (ENV_*). Docker and Mount Paths Container-specific path constants. Analysis Constants Field names (FIELD_*), default percentiles, and focality cutoffs. Simulation Constants Simulation types (SIM_TYPE_*), modes, electrode shapes, and default electrode parameters. Atlas Names Cortical (ATLAS_DK40, ATLAS_A2009S) and subcortical atlas identifiers. Logging Constants Log levels (LOG_LEVEL_*) and format strings (LOG_FORMAT_*). Numerical Constants Floating-point tolerances and tissue conductivities (S/m) with literature references. Tissue Conductivity Table TISSUE_PROPERTIES lookup list mapping SimNIBS tissue tag numbers to names, conductivities, and references. GUI Constants Window dimensions, tab names, and console buffer sizes. QSI Integration QSIPrep / QSIRecon Docker images, recon specs, atlases, and resource defaults. Validation Bounds Min/max ranges for frontend and API input validation. Default Parameters DEFAULT_ELECTRODE, DEFAULT_OPTIMIZATION, DEFAULT_STATISTICS dictionaries. Telemetry Constants GA4 Measurement Protocol settings and operation event names.

See Also

tit.paths : Uses many of these constants for BIDS path resolution.

FieldSpec dataclass

FieldSpec(name: str, label: str, kind: str, units: str, description: str)

Metadata for one output field quantity (mesh/NIfTI field name).

Attributes

name : str Exact on-disk / in-mesh field name (matches a FIELD_* constant). label : str Short label for UI widgets (checkboxes, combo boxes). kind : str FIELD_KIND_FUNCTIONAL or FIELD_KIND_SAFETY. units : str Physical units of the field values. description : str One-line tooltip text.

get_field_names

get_field_names(kind: str | None = None) -> tuple[str, ...]

Return registered field names in registry order.

Parameters

kind : str, optional If given, restrict to FIELD_KIND_FUNCTIONAL or FIELD_KIND_SAFETY.

Source code in tit/constants.py

def get_field_names(kind: str | None = None) -> tuple[str, ...]:
    """Return registered field names in registry order.

    Parameters
    ----------
    kind : str, optional
        If given, restrict to ``FIELD_KIND_FUNCTIONAL`` or ``FIELD_KIND_SAFETY``.
    """
    if kind is None:
        return tuple(spec.name for spec in FIELD_REGISTRY)
    return tuple(spec.name for spec in FIELD_REGISTRY if spec.kind == kind)

get_fields_by_kind

get_fields_by_kind(kind: str) -> tuple[FieldSpec, ...]

Return all :class:FieldSpec entries with the given kind.

Source code in tit/constants.py

def get_fields_by_kind(kind: str) -> tuple[FieldSpec, ...]:
    """Return all :class:`FieldSpec` entries with the given ``kind``."""
    return tuple(spec for spec in FIELD_REGISTRY if spec.kind == kind)

output_fields_help_text

output_fields_help_text() -> str

Compose the output-field help popup text.

States each field's definition, equation and reference. Deliberately does not group the fields into "functional" and "safety" -- which of them bear on efficacy and which on exposure is still debated, so the popup gives the definitions and leaves the interpretation to the reader.

Source code in tit/constants.py

def output_fields_help_text() -> str:
    """Compose the output-field help popup text.

    States each field's definition, equation and reference. Deliberately does
    not group the fields into "functional" and "safety" -- which of them bear
    on efficacy and which on exposure is still debated, so the popup gives the
    definitions and leaves the interpretation to the reader.
    """
    body = "\n\n".join(
        f"{name} [{units}]\n{definition}\nEquation: {equation}\n"
        f"Reference: {reference}"
        for name, units, definition, equation, reference in OUTPUT_FIELD_DEFINITIONS
    )
    return (
        "Which volume fields to compute and write for each simulation.\n\n"
        + body
        + "\n\nCost: TI_avg adds a direction sweep; hf_peak and hf_sar are "
        "effectively free alongside a field that is already being computed."
    )

get_selectable_output_field_specs

get_selectable_output_field_specs() -> tuple[FieldSpec, ...]

Return :class:FieldSpec entries for the four selectable output fields.

Order matches :data:SELECTABLE_OUTPUT_FIELDS (registry order). Used by the GUI to build output-field checkboxes without hardcoding labels.

Source code in tit/constants.py

def get_selectable_output_field_specs() -> tuple[FieldSpec, ...]:
    """Return :class:`FieldSpec` entries for the four selectable output fields.

    Order matches :data:`SELECTABLE_OUTPUT_FIELDS` (registry order). Used by
    the GUI to build output-field checkboxes without hardcoding labels.
    """
    return tuple(get_field_spec(name) for name in SELECTABLE_OUTPUT_FIELDS)

get_field_spec

get_field_spec(name: str) -> FieldSpec

Look up a :class:FieldSpec by its exact field name.

Raises

KeyError If name is not in :data:FIELD_REGISTRY.

Source code in tit/constants.py

def get_field_spec(name: str) -> FieldSpec:
    """Look up a :class:`FieldSpec` by its exact field name.

    Raises
    ------
    KeyError
        If ``name`` is not in :data:`FIELD_REGISTRY`.
    """
    for spec in FIELD_REGISTRY:
        if spec.name == name:
            return spec
    raise KeyError(f"Unknown field name: {name!r}")