1 rri_metrics.ordinal

rri_metrics.ordinal

Fit and persist global quantile bins for CORAL RRI supervision.

VIN trains an ordinal regressor (CORAL) rather than directly regressing oracle RRI values. We therefore map continuous RRIs to ordinal labels via empirical quantile edges (equal-mass bins):

  • fit \(K-1\) quantiles on finite, hard-valid oracle RRIs,
  • assign \(y=\operatorname{bucketize}(r; e_0,\ldots,e_{K-2})\),
  • expand \(y\) into the cumulative CORAL levels \(\mathbb{1}[y>k]\).

1.1 Design goals

  • Accumulate fit data on CPU.
  • Persist fit data to resume after Ctrl-C / crashes.
  • Avoid overwriting JSON outputs by default.

1.2 File formats

  • Fit data: .pt (torch.save state with rri_chunks)
  • Fitted binner: .json (num_classes + edges)

The binner owns label discretization and dataset priors, not candidate validity. Invalid actions must be removed with their hard mask before fitting or transformation; mapping them to class 0 would conflate invalidity with valid but low utility. CORAL predictions decoded through these bins are actor-side proxies, while the input RRI values are oracle supervision.

1.3 Classes

Name Description
RriOrdinalBinner Map finite oracle RRI values to globally fitted ordinal classes.

1.3.1 RriOrdinalBinner

rri_metrics.ordinal.RriOrdinalBinner(
    num_classes=0,
    edges=(lambda: torch.empty((0,), dtype=torch.float32))(),
    midpoints=None,
    bin_means=None,
    bin_stds=None,
    bin_counts=None,
    _rri_chunks=list(),
)

Map finite oracle RRI values to globally fitted ordinal classes.

K classes are separated by K-1 nondecreasing empirical quantile edges. The fitted statistics are dimensionless because RRI is normalized. Fitting accumulates transient CPU chunks; JSON persistence stores the compact fitted artifact used by training and evaluation.

1.3.1.1 Attributes

Name Description
num_classes Number of ordinal classes K; fitted binners require K >= 2.
edges Tensor["K-1", float32] dimensionless quantile edges in ascending order.
midpoints Optional Tensor["K", float32] dimensionless extrapolated class midpoints.
bin_means Optional Tensor["K", float32] empirical oracle-RRI mean per class.
bin_stds Optional Tensor["K", float32] empirical oracle-RRI standard deviation per class.
bin_counts Optional Tensor["K", float32] finite sample counts used to derive priors.
is_fitted Report whether K and the required K-1 edges are present.

1.3.1.2 Methods

Name Description
transform Bucketize oracle RRI values into a flat candidate/sample axis.
labels_to_levels Expand Tensor["...", int64] labels to Tensor["... K-1", float32] levels.
rri_to_levels Flatten RRI values and return Tensor["N K-1", float32] CORAL levels.
class_midpoints Return dimensionless class representatives derived from quantile edges.
class_priors Return Tensor["K", float32] empirical class priors or a uniform fallback.
threshold_priors Return Tensor["K-1", float32] cumulative priors P(y > k).
expected_from_probs Compute expected RRI proxy from class probabilities.
to_dict Return the fitted JSON payload with CPU-native edges and optional statistics.
from_dict Construct a CPU binner from a payload produced by :meth:to_dict.
save Atomically save a fitted JSON artifact and return its resolved path.
load Load a fitted CPU binner from a resolved JSON artifact path.
load_fit_data Load flattened RRI samples from a saved binner fit-data file.
fit_from_iterable Fit global quantile edges from a stream of finite oracle RRI chunks.
1.3.1.2.1 transform
rri_metrics.ordinal.RriOrdinalBinner.transform(rri)

Bucketize oracle RRI values into a flat candidate/sample axis.

1.3.1.2.1.1 Parameters
Name Type Description Default
rri Tensor["...", float32] Finite, hard-valid, dimensionless oracle RRI values. required
1.3.1.2.1.2 Returns
Name Type Description
Tensor Tensor["N", int64] flattened labels in [0, K-1]. A value
Tensor equal to an edge is assigned to the lower adjacent class because
Tensor torch.bucketize(..., right=False) is used.
1.3.1.2.2 labels_to_levels
rri_metrics.ordinal.RriOrdinalBinner.labels_to_levels(labels)

Expand Tensor["...", int64] labels to Tensor["... K-1", float32] levels.

1.3.1.2.3 rri_to_levels
rri_metrics.ordinal.RriOrdinalBinner.rri_to_levels(rri)

Flatten RRI values and return Tensor["N K-1", float32] CORAL levels.

1.3.1.2.4 class_midpoints
rri_metrics.ordinal.RriOrdinalBinner.class_midpoints()

Return dimensionless class representatives derived from quantile edges.

1.3.1.2.4.1 Returns
Name Type Description
Tensor Tensor["K", float32] class midpoints. Interior values average
Tensor adjacent edges; endpoint values extrapolate half an edge spacing.
1.3.1.2.4.2 Notes

If midpoints is not already stored, extrapolation requires at least two edges, corresponding to K >= 3.

1.3.1.2.5 class_priors
rri_metrics.ordinal.RriOrdinalBinner.class_priors()

Return Tensor["K", float32] empirical class priors or a uniform fallback.

1.3.1.2.6 threshold_priors
rri_metrics.ordinal.RriOrdinalBinner.threshold_priors()

Return Tensor["K-1", float32] cumulative priors P(y > k).

1.3.1.2.7 expected_from_probs
rri_metrics.ordinal.RriOrdinalBinner.expected_from_probs(probs)

Compute expected RRI proxy from class probabilities.

1.3.1.2.7.1 Parameters
Name Type Description Default
probs Tensor["... K", float32] Actor-predicted class probabilities aligned with this binner’s class order. required
1.3.1.2.7.2 Returns
Name Type Description
Tensor Tensor["...", float32] dimensionless continuous RRI proxies
Tensor using empirical bin means when present, otherwise midpoints.
1.3.1.2.8 to_dict
rri_metrics.ordinal.RriOrdinalBinner.to_dict()

Return the fitted JSON payload with CPU-native edges and optional statistics.

1.3.1.2.9 from_dict
rri_metrics.ordinal.RriOrdinalBinner.from_dict(data)

Construct a CPU binner from a payload produced by :meth:to_dict.

1.3.1.2.10 save
rri_metrics.ordinal.RriOrdinalBinner.save(path, *, overwrite=False)

Atomically save a fitted JSON artifact and return its resolved path.

Relative paths are resolved through aria_nbv.configs.PathConfig. Unless overwrite is true, an existing target receives a numeric suffix instead of being replaced.

1.3.1.2.11 load
rri_metrics.ordinal.RriOrdinalBinner.load(path)

Load a fitted CPU binner from a resolved JSON artifact path.

1.3.1.2.12 load_fit_data
rri_metrics.ordinal.RriOrdinalBinner.load_fit_data(path)

Load flattened RRI samples from a saved binner fit-data file.

1.3.1.2.12.1 Parameters
Name Type Description Default
path str | Path Path to a .pt file that stores rri_chunks. required
1.3.1.2.12.2 Returns
Name Type Description
Tensor Tensor["N", float32] of finite RRI samples.
1.3.1.2.13 fit_from_iterable
rri_metrics.ordinal.RriOrdinalBinner.fit_from_iterable(
    iterable,
    *,
    num_classes=15,
    target_items=None,
    max_skips=0,
    fit_data_path=None,
    resume=False,
    save_every=1,
    on_progress=None,
)

Fit global quantile edges from a stream of finite oracle RRI chunks.

1.3.1.2.13.1 Parameters
Name Type Description Default
iterable Iterable[Tensor | tuple[Tensor, Any]] Stream of RRI tensors or (rri, metadata) pairs. Each yielded tensor counts as one successful item after finite filtering, regardless of its number of scalar samples. required
num_classes int Requested class count K >= 2. 15
target_items int | None Optional number of successful yielded items to collect before fitting; this is not a scalar-sample count. None
max_skips int Maximum all-nonfinite items before failure; 0 allows unlimited skips until the iterable is exhausted. 0
fit_data_path str | Path | None Optional .pt checkpoint for CPU RRI chunks. None
resume bool Load existing fit chunks from fit_data_path before consuming iterable. False
save_every int Successful-item interval for atomic fit-data writes; non-positive values disable periodic writes but not the final or exception write. 1
on_progress Callable[[int, int, Tensor | None, Any | None], None] | None Optional callback receiving successful-item count, skip count, the latest finite tensor on its input device, and yielded metadata. None
1.3.1.2.13.2 Returns
Name Type Description
Fitted RriOrdinalBinner class:RriOrdinalBinner with CPU edges, means, standard
RriOrdinalBinner deviations, and counts.
1.3.1.2.13.3 Notes
  • All fit data is stored on CPU.
  • Fit data is saved on Ctrl-C / exceptions when fit_data_path is provided.
  • The iterable may yield either rri tensors or (rri, meta) tuples.
  • Callers must apply hard candidate validity before yielding; this function removes non-finite values but has no validity mask.

1.4 Functions

Name Description
ordinal_labels_to_levels Expand ordinal labels into cumulative CORAL threshold targets.

1.4.1 ordinal_labels_to_levels

rri_metrics.ordinal.ordinal_labels_to_levels(labels, *, num_classes)

Expand ordinal labels into cumulative CORAL threshold targets.

CORAL represents a K-class ordinal label y ∈ {0, ..., K-1} as K-1 binary targets:

levels[k] = 1  if y > k
          = 0  otherwise

1.4.1.1 Parameters

Name Type Description Default
labels Tensor["...", int64] Ordinal class ids in [0, num_classes-1]. required
num_classes int Number of ordinal classes K. required

1.4.1.2 Returns

Name Type Description
Tensor Tensor["... K-1", float32] binary levels
Tensor \(\mathbb{1}[y>k]\).
Back to top