Source code for thesis.workflows.atlas._params

"""Constants and runtime parameter dataclass for the atlas workflow.

Simplified to compute only essential statistics: mean, std, std_error, cov, prob_threshold.
"""

from dataclasses import dataclass
from typing import Dict, Tuple

# Re-export enum from validators for backwards compatibility and convenience
from thesis.core.config.validators import NormalizationMethod

# ---------------------------------------------------------------------------
# Tuning constants
# ---------------------------------------------------------------------------

DEFAULT_PRESENCE_VALUE: float = 0.10
"""Default presence threshold fraction.

A voxel is considered 'present' when its normalised density exceeds this value.
With waytotal normalization, 0.10 means the voxel must carry at least 10% of
the total streamline count to be counted as present in prob_threshold.
"""

DEFAULT_NORMALIZATION_METHOD: NormalizationMethod = NormalizationMethod.WAYTOTAL
"""Default normalization method for streamline density volumes."""

DEFAULT_COV_MEAN_THRESHOLD_PCT: float = 0.01
"""Default atlas mean threshold fraction for CV computation.

CV is computed only where the voxel mean exceeds this fraction of the
global maximum of the atlas mean map. Lower-signal voxels are set to 0.
"""


# ---------------------------------------------------------------------------
# Output specification
# ---------------------------------------------------------------------------


# Five essential statistics
ATLAS_STATISTIC_NAMES: Tuple[str, ...] = (
    "mean",
    "std",
    "std_error",
    "cov",
    "prob_threshold",
)

ATLAS_FILENAME_MAP: Dict[str, str] = {
    "mean": "atlas_mean.nii.gz",
    "std": "atlas_std.nii.gz",
    "std_error": "atlas_std_error.nii.gz",
    "cov": "atlas_cov.nii.gz",
    "prob_threshold": "atlas_prob_threshold.nii.gz",
}


# ---------------------------------------------------------------------------
# Runtime parameters dataclass
# ---------------------------------------------------------------------------




@dataclass(frozen=True)
class AtlasParams:
    """Runtime parameters for atlas generation.

    Attributes:
        presence_value: Threshold for prob_threshold calculation.
        cov_mean_threshold_pct: Global atlas mean threshold fraction used to
            suppress low-signal voxels when computing cov.
        normalization_method: Method for normalizing streamline volumes before
            combining (waytotal, max, or softmax).
    """

    presence_value: float = DEFAULT_PRESENCE_VALUE
    cov_mean_threshold_pct: float = DEFAULT_COV_MEAN_THRESHOLD_PCT
    normalization_method: NormalizationMethod = DEFAULT_NORMALIZATION_METHOD