tomojax.evaluation

This module neither fits a model nor chooses a projector. Predictions must use exactly the fit's discretisation, geometry and intensity convention. Exclude test and guard observations from all fitted stages, including initialisation and corrections; a mask on the final loss alone does not establish independence.

ScoreCopy Anchor Link

class Score(squared_error: float, target_energy: float, weight_sum: float, count: int)

Additive squared-error statistics, with no fitted intensity scale.

Parameters

• squared_error (float): Sum of precision times squared prediction error.
• target_energy (float): Sum of precision times squared observed values, for relative error.
• weight_sum (float): Sum of positive precisions.
• count (int): Number of test observations with positive precision.

Score.mseCopy Anchor Link

@property
mse: float

Weighted mean squared error; NaN for an empty scored batch.

Returns

• float: Squared error divided by precision sum.

Score.relative_l2Copy Anchor Link

@property
relative_l2: float

Relative weighted L2 error; NaN if the target has no energy.

Returns

• float: Square root of squared error divided by weighted target energy.

SplitCopy Anchor Link

class Split(
    *,
    shape: tuple[int, int, int],
    train: np.ndarray,
    test: np.ndarray,
    specification: str,
)

Immutable training/test masks in acquisition coordinates.

Masks are broadcastable to shape and may omit detector rows or columns by using singleton axes. False in both masks means excluded (a guard band). The fingerprint identifies this split, not the data: archive it with the source, selected frame IDs, geometry, correction settings and fit settings.

Parameters

• shape (tuple of int): Full projection shape, (views, rows, columns).
• train (numpy.ndarray): Boolean training mask, broadcastable to shape.
• test (numpy.ndarray): Disjoint boolean held-out mask, broadcastable to shape.
• specification (str): JSON description of how the split was frozen, without fitted values.

Raises

• ValueError: If masks overlap, cannot broadcast, or leave no training/test data.

Split.fingerprintCopy Anchor Link

@property
fingerprint: str

SHA256 of shape, specification and the compact masks.

Returns

• str: Hexadecimal digest identifying this frozen split.

Split.interleavedCopy Anchor Link

@classmethod
interleaved(shape: tuple[int, int, int], *, stride: int, offset: int = 0) -> Split

Hold every stride-th view out for reconstruction selection.

Parameters

• shape (tuple of int): Full projection shape (views, rows, columns).
• stride (int): At least two; repeat at several strides to test angular sampling bias.
• offset (int, optional): Held-out residue in [0, stride).

Returns

• Split: View masks with singleton detector axes.

Split.angularCopy Anchor Link

@classmethod
angular(
    shape: tuple[int, int, int],
    angles: np.ndarray,
    *,
    start: float,
    width: float,
    guard: float = 0,
    period: float = 360,
) -> Split

Hold a periodic angular block out for global or smooth parameters.

Parameters

• shape (tuple of int): Full projection shape (views, rows, columns).
• angles (numpy.ndarray): One recorded angle per view in degrees; acquisition order is retained.
• start (float): First test angle in degrees, modulo period.
• width (float): Test interval width in degrees; its upper endpoint is excluded.
• guard (float, optional): Excluded angular margin on either side of each test block.
• period (float, optional): Block repetition period in degrees, default 360.

Returns

• Split: Angular test block and guarded training views, never per-view pose validation.

Split.detectorCopy Anchor Link

@classmethod
detector(
    shape: tuple[int, int, int],
    *,
    start: int,
    width: int,
    period: int,
    guard: int = 0,
    offsets: np.ndarray | float = 0,
) -> Split

Hold detector-column blocks out within each view for per-view poses.

Parameters

• shape (tuple of int): Full projection shape (views, rows, columns).
• start (int): First test column, modulo period, before adding offsets.
• width (int): Number of consecutive test columns in each block.
• period (int): Block repetition period in detector pixels.
• guard (int, optional): Columns excluded on each side of a test block. Choose this from the support of preprocessing and permitted motion, before fitting.
• offsets (numpy.ndarray or float, optional): Frozen offset per view or a common offset, in detector pixels.

Returns

• Split: Masks with a singleton row axis and a test block in each view.

Split.scoreCopy Anchor Link

score(
    prediction: np.ndarray,
    target: np.ndarray,
    *,
    weights: np.ndarray | float = 1,
    views: slice | None = None,
) -> Score

Score a complete prediction or a view batch without refitting anything.

Parameters

• prediction (numpy.ndarray): Matched forward prediction (batch views, rows, columns).
• target (numpy.ndarray): Held-out observations with the same shape and intensity convention.
• weights (numpy.ndarray or float, optional): Nonnegative precision, broadcastable to the batch; not square-root precision. Freeze data-adaptive weights using training data only.
• views (slice or None, optional): Batch's original view indices; default is the complete acquisition.

Returns

• Score: Additive float64 statistics; sum batches before forming ratios.

Raises

• ValueError: If shapes disagree, weights are negative, or scored values are nonfinite.