1 vin.ordinal

vin.ordinal

CORAL ordinal regression and continuous decoding for RRI-derived labels.

This module uses the MIT-licensed reference implementation from coral-pytorch.

This module owns the VIN-side conversion between \(K\) ordinal RRI bins and the \(K-1\) cumulative thresholds \(P(y>k)\). It provides cumulative-target loss, threshold-to-class decoding, monotonicity diagnostics, and the shared-weight CORAL output layer. For monotone cumulative probabilities \(p_k\),

\[ P(y=0)=1-p_0,\quad P(y=k)=p_{k-1}-p_k,\quad P(y=K-1)=p_{K-2}. \]

Decoded ranks and learnable bin expectations are actor-side prediction proxies. Oracle RRI and endpoint target-quality metrics remain geometry-grounded evaluation signals. Hard-invalid candidates must be masked before loss or decoding; they are not encoded as the lowest ordinal class.

1.1 Classes

Name	Description
CoralLayer	Map actor features to shared-weight cumulative threshold logits.
MonotoneBinValues	Parameterize learnable continuous bin representatives monotonically.

1.1.1 CoralLayer

vin.ordinal.CoralLayer(in_dim, num_classes, *, preinit_bias=True)

Map actor features to shared-weight cumulative threshold logits.

The layer implements

\[ \operatorname{logit}_k=w^\top x+b_k,\qquad k=0,\ldots,K-2, \]

using the upstream coral_pytorch layer. Optional MonotoneBinValues decode the resulting class probabilities into a continuous actor-side RRI proxy.

1.1.1.1 Attributes

Name	Description
num_classes	Return the configured ordinal class count K.
has_bin_values	Report whether continuous monotone bin representatives are initialized.

1.1.1.2 Methods

Name	Description
forward	Compute threshold logits.
init_bin_values	Initialize Tensor["K", float32] monotone bin representatives u_k.
init_bias_from_priors	Initialize CORAL biases from class priors.
expected_from_probs	Decode Tensor["... K", float32] class probabilities to a continuous RRI proxy.
expected_from_logits	Repair Tensor["... K-1", float32] logits to marginals and decode their RRI proxy.
bin_value_regularizer	Return scalar mean-squared deviation from Tensor["K", float32] target bin values.

1.1.1.2.1 forward

vin.ordinal.CoralLayer.forward(x)

Compute threshold logits.

1.1.1.2.1.1 Parameters

Name	Type	Description	Default
x	Tensor	Tensor["... in_dim"].	required

1.1.1.2.1.2 Returns

Name	Type	Description
	Tensor	Tensor["... K-1"].

1.1.1.2.2 init_bin_values

vin.ordinal.CoralLayer.init_bin_values(values, *, overwrite=False)

Initialize Tensor["K", float32] monotone bin representatives u_k.

1.1.1.2.3 init_bias_from_priors

vin.ordinal.CoralLayer.init_bias_from_priors(priors, *, overwrite=True)

Initialize CORAL biases from class priors.

1.1.1.2.3.1 Parameters

Name	Type	Description	Default
priors Tensor["K", float32]		Non-negative class priors; values are normalized internally before cumulative conversion.	required
overwrite	bool	If True, overwrite the current bias values.	True

1.1.1.2.4 expected_from_probs

vin.ordinal.CoralLayer.expected_from_probs(probs)

Decode Tensor["... K", float32] class probabilities to a continuous RRI proxy.

1.1.1.2.5 expected_from_logits

vin.ordinal.CoralLayer.expected_from_logits(logits)

Repair Tensor["... K-1", float32] logits to marginals and decode their RRI proxy.

1.1.1.2.6 bin_value_regularizer

vin.ordinal.CoralLayer.bin_value_regularizer(target_values)

Return scalar mean-squared deviation from Tensor["K", float32] target bin values.

1.1.2 MonotoneBinValues

vin.ordinal.MonotoneBinValues(num_classes, init_values, *, min_delta=1e-06)

Parameterize learnable continuous bin representatives monotonically.

We parameterize u_k via a base value and positive deltas:

\[ u_k=u_0+\sum_{j=1}^{k}\operatorname{softplus}(\delta_j), \qquad k=1,\ldots,K-1. \]

This guarantees \(u_0\leq\cdots\leq u_{K-1}\). These values decode actor class probabilities into a continuous RRI proxy; they do not replace geometry-grounded oracle RRI.

1.1.2.1 Attributes

Name	Description
num_classes	Return the fixed number K of monotone representatives.

1.1.2.2 Methods

Name	Description
values	Return Tensor["K", float32] monotone representatives u_k.
reset_from_values	Reset from Tensor["K", float32] targets while preserving strict positive deltas.

1.1.2.2.1 values

vin.ordinal.MonotoneBinValues.values()

Return Tensor["K", float32] monotone representatives u_k.

1.1.2.2.2 reset_from_values

vin.ordinal.MonotoneBinValues.reset_from_values(values, *, min_delta=1e-06)

Reset from Tensor["K", float32] targets while preserving strict positive deltas.

1.2 Functions

Name	Description
coral_expected_from_logits	Decode CORAL logits into expected ordinal rank and normalized rank.
coral_logits_to_label	Decode CORAL logits into ordinal class labels via threshold counting.
coral_logits_to_prob	Convert cumulative CORAL logits to repaired class marginals.
coral_loss	Compute cumulative-link BCE across all CORAL thresholds.
coral_monotonicity_violation_rate	Compute the fraction of monotonicity violations in CORAL probabilities.
coral_random_loss	Return the loss baseline for uninformative zero threshold logits.

1.2.1 coral_expected_from_logits

vin.ordinal.coral_expected_from_logits(logits)

Decode CORAL logits into expected ordinal rank and normalized rank.

1.2.1.1 Parameters

Name	Type	Description	Default
logits Tensor["... K-1", float32]		Cumulative threshold logits.	required

1.2.1.2 Returns

Name	Type	Description
	Tensor	Tuple of actor-side ranking proxies:
	Tensor	- expected Tensor["...", float32]: \(E[y]=\sum_k P(y>k)\) in [0, K-1].
	tuple[Tensor, Tensor]	- expected_normalized Tensor["...", float32]: Expected rank divided by K-1, in [0, 1].

1.2.1.3 Notes

This function does not use fitted RRI bin representatives and therefore does not return a continuous RRI estimate.

1.2.2 coral_logits_to_label

vin.ordinal.coral_logits_to_label(logits, *, threshold=0.5)

Decode CORAL logits into ordinal class labels via threshold counting.

CORAL models the probabilities P(y > k) for thresholds k=0..K-2. The predicted label is therefore the number of thresholds whose probability exceeds threshold (default 0.5).

1.2.2.1 Parameters

Name	Type	Description	Default
logits Tensor["... K-1", float32]		Threshold logits.	required
threshold	float	Probability threshold for counting P(y > k).	0.5

1.2.2.2 Returns

Name	Type	Description
	Tensor	Tensor["...", int64] actor-predicted ordinal labels in
	Tensor	[0, K-1].

1.2.3 coral_logits_to_prob

vin.ordinal.coral_logits_to_prob(logits)

Convert cumulative CORAL logits to repaired class marginals.

1.2.3.1 Parameters

Name	Type	Description	Default
logits Tensor["... K-1", float32]		Threshold logits for P(y > k).	required

1.2.3.2 Returns

Name	Type	Description
	Tensor	Tensor["... K", float32] non-negative class probabilities that
	Tensor	sum to one along the last axis.

1.2.3.3 Notes

Independent threshold logits can violate the required monotone order, making adjacent marginal differences negative. This decoder clamps those differences and renormalizes; use coral_monotonicity_violation_rate to report the discarded inconsistency rather than treating the repaired distribution as proof of monotonic logits.

1.2.4 coral_loss

vin.ordinal.coral_loss(
    logits,
    labels,
    *,
    num_classes,
    importance_weights=None,
    reduction='mean',
)

Compute cumulative-link BCE across all CORAL thresholds.

1.2.4.1 Parameters

Name	Type	Description	Default
logits Tensor["... K-1", float32]		Actor-predicted logits for \(P(y>k)\), ordered from the lowest to highest threshold.	required
labels Tensor["...", int64]		Oracle-derived ordinal labels in [0, K-1]. The leading shape must match logits.	required
num_classes	int	Number of ordinal classes K.	required
importance_weights Tensor["K-1", float32]		Optional threshold weights passed to coral_pytorch.	required
reduction	Literal['mean', 'sum', 'none']	"mean" or "sum" for a scalar, or "none" to retain the leading label shape.	'mean'

1.2.4.2 Returns

Name	Type	Description
	Tensor	Tensor["", float32] for reduced loss or
	Tensor	Tensor["...", float32] when reduction="none".

1.2.4.3 Theory

Each label produces levels \(l_k=\mathbb{1}[y>k]\). The per-example loss is the sum of binary cross-entropies between logits[..., k] and \(l_k\). Candidate validity is not inferred here; callers must exclude hard-invalid rows before constructing labels.

1.2.5 coral_monotonicity_violation_rate

vin.ordinal.coral_monotonicity_violation_rate(logits)

Compute the fraction of monotonicity violations in CORAL probabilities.

CORAL expects P(y > k) to be non-increasing with k. This returns the per-sample fraction of threshold pairs that violate this ordering.

1.2.5.1 Parameters

Name	Type	Description	Default
logits Tensor["... K-1", float32]		Threshold logits.	required

1.2.5.2 Returns

Name	Type	Description
	Tensor	Tensor["...", float32] fraction of adjacent violations in
	Tensor	[0, 1]. K=2 has no adjacent pair and returns zero.

1.2.6 coral_random_loss

vin.ordinal.coral_random_loss(num_classes)

Return the loss baseline for uninformative zero threshold logits.

A zero logit assigns probability 0.5 to every cumulative threshold, yielding binary cross-entropy log(2) for each of K-1 thresholds.

1.2.6.1 Parameters

Name	Type	Description	Default
num_classes	int	Number of ordinal classes K.	required

1.2.6.2 Returns

Name	Type	Description
	float	Scalar baseline (K-1) * log(2) under the summed-threshold loss.