deepordinal 0.2.0__tar.gz

deepordinal-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas Hirons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deepordinal-0.2.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: deepordinal
+Version: 0.2.0
+Summary: Ordinal output layers and loss functions (Rennie & Srebro, 2005) for PyTorch and TF/Keras
+Author: Nicholas Hirons
+License-Expression: MIT
+Project-URL: Repository, https://github.com/nhirons/deepordinal
+Keywords: ordinal-regression,deep-learning,pytorch,tensorflow,keras
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: tf
+Requires-Dist: tensorflow>=2.0; extra == "tf"
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Dynamic: license-file
+
+# DeepOrdinal
+
+Ordinal output layers and loss functions ([Rennie & Srebro, 2005](https://ttic.uchicago.edu/~nati/Publications/RennieSrebroIJCAI05.pdf)) for PyTorch and TF/Keras.
+
+DeepOrdinal provides an `OrdinalOutput` layer that converts a learned logit into ordinal class probabilities via sorted thresholds, plus loss functions designed specifically for ordinal regression.
+
+## Installation
+
+```bash
+pip install deepordinal
+```
+
+With a specific backend:
+
+```bash
+pip install ".[tf]"     # TensorFlow/Keras
+pip install ".[torch]"  # PyTorch
+```
+
+For development:
+
+```bash
+pip install -e ".[tf,torch]"
+```
+
+## Backends
+
+DeepOrdinal supports two backends with identical APIs:
+
+| | PyTorch | TensorFlow/Keras |
+|---|---|---|
+| Module | `deepordinal.torch` | `deepordinal.tf` |
+| Layer | `OrdinalOutput(input_dim=D, output_dim=K)` | `OrdinalOutput(output_dim=K)` |
+| Loss functions | `ordinal_loss`, `ordistic_loss` | `ordinal_loss`, `ordistic_loss` |
+
+## OrdinalOutput Layer
+
+The `OrdinalOutput` layer accepts any input size, projects to a single logit, and converts it into K class probabilities using K-1 learned, sorted thresholds:
+
+```
+P(y = k | x) = sigmoid(t(k+1) - logit) - sigmoid(t(k) - logit)
+```
+
+where `t(0) = -inf` and `t(K) = inf` are fixed, and interior thresholds are initialized sorted.
+
+```python
+from deepordinal.torch import OrdinalOutput  # or deepordinal.tf
+layer = OrdinalOutput(input_dim=16, output_dim=4)  # TF omits input_dim
+```
+
+## Loss Functions
+
+DeepOrdinal implements the threshold-based ordinal loss functions from Rennie & Srebro, "Loss Functions for Preference Levels" (IJCAI 2005). These operate on raw logits and thresholds rather than probability output.
+
+### `ordinal_loss`
+
+```python
+ordinal_loss(logits, targets, thresholds, construction='all', penalty='logistic')
+```
+
+- **logits**: `(batch,)` or `(batch, 1)` — raw predictor output
+- **targets**: `(batch,)` — integer labels in `[0, K)`
+- **thresholds**: `(K-1,)` — sorted interior thresholds
+- **construction**: `'all'` or `'immediate'`
+- **penalty**: `'hinge'`, `'smooth_hinge'`, `'modified_least_squares'`, or `'logistic'`
+- **Returns**: scalar mean loss over the batch
+
+#### Constructions
+
+- **All-threshold** (default, eq 13): penalizes violations of every threshold, weighted by direction. Bounds mean absolute error. Best performer in the paper's experiments.
+- **Immediate-threshold** (eq 12): only penalizes violations of the two thresholds bounding the correct class segment.
+
+#### Penalty functions
+
+| Name | Formula | Reference |
+|---|---|---|
+| `'hinge'` | `max(0, 1-z)` | eq 5 |
+| `'smooth_hinge'` | 0 if z≥1, (1-z)²/2 if 0<z<1, 0.5-z if z≤0 | eq 6 |
+| `'modified_least_squares'` | 0 if z≥1, (1-z)² if z<1 | eq 7 |
+| `'logistic'` | `log(1 + exp(-z))` | eq 9 |
+
+The paper recommends **all-threshold + logistic** as the best-performing combination.
+
+### `ordistic_loss`
+
+Probabilistic generalization of logistic regression to K-class ordinal problems (Section 4).
+
+```python
+ordistic_loss(logits, targets, means, log_priors=None)
+```
+
+- **logits**: `(batch,)` or `(batch, 1)` — raw predictor output
+- **targets**: `(batch,)` — integer labels in `[0, K)`
+- **means**: `(K,)` — class means (convention: μ₁=-1, μ_K=1; interior means learned)
+- **log_priors**: `(K,)` or `None` — optional log-prior terms π_i
+- **Returns**: scalar mean negative log-likelihood over the batch
+
+### Example usage
+
+#### PyTorch
+
+```python
+import torch
+from deepordinal.torch import OrdinalOutput, ordinal_loss
+
+layer = OrdinalOutput(input_dim=16, output_dim=4)
+h = torch.randn(8, 16)
+targets = torch.randint(0, 4, (8,))
+
+probs = layer(h)
+loss = ordinal_loss(layer.linear(h), targets, layer.interior_thresholds)
+loss.backward()
+```
+
+#### TensorFlow
+
+```python
+import tensorflow as tf
+from deepordinal.tf import OrdinalOutput, ordinal_loss
+
+layer = OrdinalOutput(output_dim=4)
+h = tf.random.normal((8, 16))
+targets = tf.random.uniform((8,), 0, 4, dtype=tf.int32)
+
+with tf.GradientTape() as tape:
+    probs = layer(h)
+    logit = tf.matmul(h, layer.kernel) + layer.bias
+    loss = ordinal_loss(logit, targets, tf.squeeze(layer.interior_thresholds))
+grads = tape.gradient(loss, layer.trainable_variables)
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[tf,torch]"
+pytest -v
+```
+
+## Changelog
+
+### 0.2.0
+
+- Added `ordinal_loss` — Rennie & Srebro threshold-based ordinal loss with two constructions (all-threshold, immediate-threshold) and four penalty functions (hinge, smooth hinge, modified least squares, logistic)
+- Added `ordistic_loss` — ordistic negative log-likelihood loss (Rennie & Srebro, Section 4)
+- Both loss functions available in `deepordinal.torch` and `deepordinal.tf`
+
+### 0.1.0
+
+- Added PyTorch backend (`deepordinal.torch`) with `OrdinalOutput` module
+- Modernized TensorFlow backend to `tf.keras` with self-contained `OrdinalOutput` layer and `SortedInitializer`
+- Dual-backend support (TensorFlow/Keras and PyTorch) with matching APIs
+- `pyproject.toml` build configuration with optional `[tf]` and `[torch]` extras
+
+### Initial
+
+- `OrdinalOutput` Keras layer for deep ordinal regression
+- Example notebook with synthetic ordinal data
+
+## Examples
+
+- `examples/example_tf.ipynb` — TensorFlow/Keras with `ordinal_loss` and `GradientTape` training loop
+- `examples/example_torch.ipynb` — PyTorch with `ordinal_loss` and standard training loop
+

deepordinal-0.2.0/README.md

@@ -0,0 +1,163 @@
+# DeepOrdinal
+
+Ordinal output layers and loss functions ([Rennie & Srebro, 2005](https://ttic.uchicago.edu/~nati/Publications/RennieSrebroIJCAI05.pdf)) for PyTorch and TF/Keras.
+
+DeepOrdinal provides an `OrdinalOutput` layer that converts a learned logit into ordinal class probabilities via sorted thresholds, plus loss functions designed specifically for ordinal regression.
+
+## Installation
+
+```bash
+pip install deepordinal
+```
+
+With a specific backend:
+
+```bash
+pip install ".[tf]"     # TensorFlow/Keras
+pip install ".[torch]"  # PyTorch
+```
+
+For development:
+
+```bash
+pip install -e ".[tf,torch]"
+```
+
+## Backends
+
+DeepOrdinal supports two backends with identical APIs:
+
+| | PyTorch | TensorFlow/Keras |
+|---|---|---|
+| Module | `deepordinal.torch` | `deepordinal.tf` |
+| Layer | `OrdinalOutput(input_dim=D, output_dim=K)` | `OrdinalOutput(output_dim=K)` |
+| Loss functions | `ordinal_loss`, `ordistic_loss` | `ordinal_loss`, `ordistic_loss` |
+
+## OrdinalOutput Layer
+
+The `OrdinalOutput` layer accepts any input size, projects to a single logit, and converts it into K class probabilities using K-1 learned, sorted thresholds:
+
+```
+P(y = k | x) = sigmoid(t(k+1) - logit) - sigmoid(t(k) - logit)
+```
+
+where `t(0) = -inf` and `t(K) = inf` are fixed, and interior thresholds are initialized sorted.
+
+```python
+from deepordinal.torch import OrdinalOutput  # or deepordinal.tf
+layer = OrdinalOutput(input_dim=16, output_dim=4)  # TF omits input_dim
+```
+
+## Loss Functions
+
+DeepOrdinal implements the threshold-based ordinal loss functions from Rennie & Srebro, "Loss Functions for Preference Levels" (IJCAI 2005). These operate on raw logits and thresholds rather than probability output.
+
+### `ordinal_loss`
+
+```python
+ordinal_loss(logits, targets, thresholds, construction='all', penalty='logistic')
+```
+
+- **logits**: `(batch,)` or `(batch, 1)` — raw predictor output
+- **targets**: `(batch,)` — integer labels in `[0, K)`
+- **thresholds**: `(K-1,)` — sorted interior thresholds
+- **construction**: `'all'` or `'immediate'`
+- **penalty**: `'hinge'`, `'smooth_hinge'`, `'modified_least_squares'`, or `'logistic'`
+- **Returns**: scalar mean loss over the batch
+
+#### Constructions
+
+- **All-threshold** (default, eq 13): penalizes violations of every threshold, weighted by direction. Bounds mean absolute error. Best performer in the paper's experiments.
+- **Immediate-threshold** (eq 12): only penalizes violations of the two thresholds bounding the correct class segment.
+
+#### Penalty functions
+
+| Name | Formula | Reference |
+|---|---|---|
+| `'hinge'` | `max(0, 1-z)` | eq 5 |
+| `'smooth_hinge'` | 0 if z≥1, (1-z)²/2 if 0<z<1, 0.5-z if z≤0 | eq 6 |
+| `'modified_least_squares'` | 0 if z≥1, (1-z)² if z<1 | eq 7 |
+| `'logistic'` | `log(1 + exp(-z))` | eq 9 |
+
+The paper recommends **all-threshold + logistic** as the best-performing combination.
+
+### `ordistic_loss`
+
+Probabilistic generalization of logistic regression to K-class ordinal problems (Section 4).
+
+```python
+ordistic_loss(logits, targets, means, log_priors=None)
+```
+
+- **logits**: `(batch,)` or `(batch, 1)` — raw predictor output
+- **targets**: `(batch,)` — integer labels in `[0, K)`
+- **means**: `(K,)` — class means (convention: μ₁=-1, μ_K=1; interior means learned)
+- **log_priors**: `(K,)` or `None` — optional log-prior terms π_i
+- **Returns**: scalar mean negative log-likelihood over the batch
+
+### Example usage
+
+#### PyTorch
+
+```python
+import torch
+from deepordinal.torch import OrdinalOutput, ordinal_loss
+
+layer = OrdinalOutput(input_dim=16, output_dim=4)
+h = torch.randn(8, 16)
+targets = torch.randint(0, 4, (8,))
+
+probs = layer(h)
+loss = ordinal_loss(layer.linear(h), targets, layer.interior_thresholds)
+loss.backward()
+```
+
+#### TensorFlow
+
+```python
+import tensorflow as tf
+from deepordinal.tf import OrdinalOutput, ordinal_loss
+
+layer = OrdinalOutput(output_dim=4)
+h = tf.random.normal((8, 16))
+targets = tf.random.uniform((8,), 0, 4, dtype=tf.int32)
+
+with tf.GradientTape() as tape:
+    probs = layer(h)
+    logit = tf.matmul(h, layer.kernel) + layer.bias
+    loss = ordinal_loss(logit, targets, tf.squeeze(layer.interior_thresholds))
+grads = tape.gradient(loss, layer.trainable_variables)
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[tf,torch]"
+pytest -v
+```
+
+## Changelog
+
+### 0.2.0
+
+- Added `ordinal_loss` — Rennie & Srebro threshold-based ordinal loss with two constructions (all-threshold, immediate-threshold) and four penalty functions (hinge, smooth hinge, modified least squares, logistic)
+- Added `ordistic_loss` — ordistic negative log-likelihood loss (Rennie & Srebro, Section 4)
+- Both loss functions available in `deepordinal.torch` and `deepordinal.tf`
+
+### 0.1.0
+
+- Added PyTorch backend (`deepordinal.torch`) with `OrdinalOutput` module
+- Modernized TensorFlow backend to `tf.keras` with self-contained `OrdinalOutput` layer and `SortedInitializer`
+- Dual-backend support (TensorFlow/Keras and PyTorch) with matching APIs
+- `pyproject.toml` build configuration with optional `[tf]` and `[torch]` extras
+
+### Initial
+
+- `OrdinalOutput` Keras layer for deep ordinal regression
+- Example notebook with synthetic ordinal data
+
+## Examples
+
+- `examples/example_tf.ipynb` — TensorFlow/Keras with `ordinal_loss` and `GradientTape` training loop
+- `examples/example_torch.ipynb` — PyTorch with `ordinal_loss` and standard training loop
+

deepordinal-0.2.0/deepordinal/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.2.0"
+__all__ = ["tf", "torch"]

deepordinal-0.2.0/deepordinal/tf.py

@@ -0,0 +1,163 @@
+import tensorflow as tf
+from tensorflow.keras import initializers
+from tensorflow.keras.layers import Layer
+
+__all__ = ["OrdinalOutput", "SortedInitializer", "ordinal_loss", "ordistic_loss"]
+
+_INF = tf.constant(float("inf"))
+
+
+def _penalty(z, name):
+    if name == "hinge":
+        return tf.maximum(0.0, 1.0 - z)
+    elif name == "smooth_hinge":
+        return tf.where(
+            z >= 1.0,
+            tf.zeros_like(z),
+            tf.where(z > 0.0, (1.0 - z) ** 2 / 2.0, 0.5 - z),
+        )
+    elif name == "modified_least_squares":
+        return tf.where(z >= 1.0, tf.zeros_like(z), (1.0 - z) ** 2)
+    elif name == "logistic":
+        return tf.math.softplus(-z)
+    else:
+        raise ValueError(f"Unknown penalty: {name}")
+
+
+def ordinal_loss(logits, targets, thresholds, construction="all", penalty="logistic"):
+    """Rennie & Srebro ordinal loss (IJCAI 2005).
+
+    Args:
+        logits: (batch,) or (batch, 1) — raw predictor output z(x).
+        targets: (batch,) — integer labels in [0, K).
+        thresholds: (K-1,) — sorted interior thresholds.
+        construction: ``'all'`` or ``'immediate'``.
+        penalty: ``'hinge'``, ``'smooth_hinge'``, ``'modified_least_squares'``,
+            or ``'logistic'``.
+
+    Returns:
+        Scalar mean loss over the batch.
+    """
+    logits = tf.cast(tf.reshape(logits, [-1]), tf.float32)
+    targets = tf.cast(targets, tf.int32)
+    thresholds = tf.cast(thresholds, tf.float32)
+    K = thresholds.shape[0] + 1
+    y = targets + 1  # 1-indexed
+
+    if construction == "all":
+        l_idx = tf.cast(tf.range(1, K), tf.float32)  # (K-1,)
+        y_f = tf.cast(y, tf.float32)
+        signs = tf.where(
+            tf.expand_dims(l_idx, 0) < tf.expand_dims(y_f, 1), -1.0, 1.0
+        )  # (batch, K-1)
+        diff = tf.expand_dims(thresholds, 0) - tf.expand_dims(logits, 1)  # (batch, K-1)
+        loss = tf.reduce_sum(_penalty(signs * diff, penalty), axis=1)
+    elif construction == "immediate":
+        t_low = tf.concat([[float("-inf")], thresholds], axis=0)
+        t_high = tf.concat([thresholds, [float("inf")]], axis=0)
+        theta_low = tf.gather(t_low, targets)
+        theta_high = tf.gather(t_high, targets)
+        loss = _penalty(logits - theta_low, penalty) + _penalty(theta_high - logits, penalty)
+    else:
+        raise ValueError(f"Unknown construction: {construction}")
+
+    return tf.reduce_mean(loss)
+
+
+def ordistic_loss(logits, targets, means, log_priors=None):
+    """Ordistic loss (Rennie & Srebro, Section 4).
+
+    Args:
+        logits: (batch,) or (batch, 1) — raw predictor output z(x).
+        targets: (batch,) — integer labels in [0, K).
+        means: (K,) — class means.
+        log_priors: (K,) or None — log-prior terms. Defaults to zeros.
+
+    Returns:
+        Scalar mean negative log-likelihood over the batch.
+    """
+    logits = tf.cast(tf.reshape(logits, [-1]), tf.float32)
+    targets = tf.cast(targets, tf.int32)
+    means = tf.cast(means, tf.float32)
+    K = means.shape[0]
+    if log_priors is None:
+        log_priors = tf.zeros([K], dtype=tf.float32)
+    else:
+        log_priors = tf.cast(log_priors, tf.float32)
+    energy = (
+        tf.expand_dims(means, 0) * tf.expand_dims(logits, 1)
+        + tf.expand_dims(log_priors, 0)
+        - tf.expand_dims(means, 0) ** 2 / 2.0
+    )
+    batch_idx = tf.range(tf.shape(targets)[0])
+    indices = tf.stack([batch_idx, targets], axis=1)
+    target_energy = tf.gather_nd(energy, indices)
+    log_partition = tf.reduce_logsumexp(energy, axis=1)
+    return tf.reduce_mean(log_partition - target_energy)
+
+
+class SortedInitializer(initializers.Initializer):
+    """Wraps a Keras initializer and returns its output sorted along the last axis."""
+
+    def __init__(self, base="glorot_uniform"):
+        self.base = initializers.get(base)
+
+    def __call__(self, shape, dtype=None):
+        values = self.base(shape, dtype=dtype)
+        return tf.sort(values, axis=-1)
+
+    def get_config(self):
+        return {"base": initializers.serialize(self.base)}
+
+
+class OrdinalOutput(Layer):
+    """Ordinal regression output layer.
+
+    Projects an arbitrary input down to a single logit and converts it
+    into *output_dim* class probabilities via learned, sorted thresholds.
+
+    The layer learns ``output_dim - 1`` interior thresholds ``t(1)…t(K-1)``
+    (with ``t(0) = -∞`` and ``t(K) = +∞`` fixed) and computes::
+
+        P(y = k | x) = σ(t(k+1) - logit) - σ(t(k) - logit)
+    """
+
+    def __init__(self, output_dim, **kwargs):
+        super().__init__(**kwargs)
+        self.output_dim = output_dim
+
+    def build(self, input_shape):
+        self.kernel = self.add_weight(
+            name="kernel",
+            shape=(input_shape[-1], 1),
+            initializer="glorot_uniform",
+            trainable=True,
+        )
+        self.bias = self.add_weight(
+            name="bias",
+            shape=(1,),
+            initializer="zeros",
+            trainable=True,
+        )
+        self.interior_thresholds = self.add_weight(
+            name="thresholds",
+            shape=(1, self.output_dim - 1),
+            initializer=SortedInitializer("glorot_uniform"),
+            trainable=True,
+        )
+        super().build(input_shape)
+
+    def call(self, inputs):
+        logit = tf.matmul(inputs, self.kernel) + self.bias
+        t_low = tf.fill([1, 1], -_INF)
+        t_high = tf.fill([1, 1], _INF)
+        thresholds = tf.concat([t_low, self.interior_thresholds, t_high], axis=-1)
+        return tf.sigmoid(thresholds[:, 1:] - logit) - tf.sigmoid(thresholds[:, :-1] - logit)
+
+    def compute_output_shape(self, input_shape):
+        return (input_shape[0], self.output_dim)
+
+    def get_config(self):
+        config = super().get_config()
+        config["output_dim"] = self.output_dim
+        return config

deepordinal-0.2.0/deepordinal/torch.py

@@ -0,0 +1,123 @@
+import torch
+import torch.nn as nn
+
+__all__ = ["OrdinalOutput", "ordinal_loss", "ordistic_loss"]
+
+
+def _penalty(z, name):
+    if name == "hinge":
+        return torch.clamp(1 - z, min=0)
+    elif name == "smooth_hinge":
+        return torch.where(
+            z >= 1,
+            torch.zeros_like(z),
+            torch.where(z > 0, (1 - z) ** 2 / 2, 0.5 - z),
+        )
+    elif name == "modified_least_squares":
+        return torch.where(z >= 1, torch.zeros_like(z), (1 - z) ** 2)
+    elif name == "logistic":
+        return torch.nn.functional.softplus(-z)
+    else:
+        raise ValueError(f"Unknown penalty: {name}")
+
+
+def ordinal_loss(logits, targets, thresholds, construction="all", penalty="logistic"):
+    """Rennie & Srebro ordinal loss (IJCAI 2005).
+
+    Args:
+        logits: (batch,) or (batch, 1) — raw predictor output z(x).
+        targets: (batch,) — integer labels in [0, K).
+        thresholds: (K-1,) — sorted interior thresholds.
+        construction: ``'all'`` or ``'immediate'``.
+        penalty: ``'hinge'``, ``'smooth_hinge'``, ``'modified_least_squares'``,
+            or ``'logistic'``.
+
+    Returns:
+        Scalar mean loss over the batch.
+    """
+    logits = logits.reshape(-1)
+    targets = targets.long()
+    K = thresholds.shape[0] + 1
+    # Paper uses 1-indexed labels; convert 0-indexed targets
+    y = targets + 1  # (batch,) in [1, K]
+
+    if construction == "all":
+        # eq 13: sum over l=1..K-1 of f(s(l;y) * (theta_l - z))
+        # s(l;y) = -1 if l < y, +1 if l >= y
+        l_idx = torch.arange(1, K, device=logits.device).float()  # (K-1,)
+        signs = torch.where(l_idx.unsqueeze(0) < y.unsqueeze(1), -1.0, 1.0)  # (batch, K-1)
+        diff = thresholds.unsqueeze(0) - logits.unsqueeze(1)  # (batch, K-1)
+        loss = _penalty(signs * diff, penalty).sum(dim=1)  # (batch,)
+    elif construction == "immediate":
+        # eq 12: f(z - theta_{y-1}) + f(theta_y - z)
+        t_low = torch.cat([torch.tensor([float("-inf")], device=thresholds.device), thresholds])
+        t_high = torch.cat([thresholds, torch.tensor([float("inf")], device=thresholds.device)])
+        theta_low = t_low[targets]   # theta_{y-1} (0-indexed: targets maps to y-1)
+        theta_high = t_high[targets]  # theta_y
+        loss = _penalty(logits - theta_low, penalty) + _penalty(theta_high - logits, penalty)
+    else:
+        raise ValueError(f"Unknown construction: {construction}")
+
+    return loss.mean()
+
+
+def ordistic_loss(logits, targets, means, log_priors=None):
+    """Ordistic loss (Rennie & Srebro, Section 4).
+
+    Args:
+        logits: (batch,) or (batch, 1) — raw predictor output z(x).
+        targets: (batch,) — integer labels in [0, K).
+        means: (K,) — class means (mu_1=-1, mu_K=1 by convention; interior learned).
+        log_priors: (K,) or None — log-prior terms pi_i. Defaults to zeros.
+
+    Returns:
+        Scalar mean negative log-likelihood over the batch.
+    """
+    logits = logits.reshape(-1)
+    targets = targets.long()
+    K = means.shape[0]
+    if log_priors is None:
+        log_priors = torch.zeros(K, device=logits.device, dtype=logits.dtype)
+    # energy_ik = mu_k * z_i + pi_k - mu_k^2 / 2
+    energy = means.unsqueeze(0) * logits.unsqueeze(1) + log_priors.unsqueeze(0) - means.unsqueeze(0) ** 2 / 2
+    # loss = -log P(y|z) = -energy[y] + log(sum_k exp(energy[k]))
+    target_energy = energy[torch.arange(len(targets), device=targets.device), targets]
+    log_partition = torch.logsumexp(energy, dim=1)
+    return (log_partition - target_energy).mean()
+
+
+class OrdinalOutput(nn.Module):
+    """Ordinal regression output layer.
+
+    Projects an arbitrary input down to a single logit and converts it
+    into *output_dim* class probabilities via learned, sorted thresholds.
+
+    The layer learns ``output_dim - 1`` interior thresholds ``t(1)…t(K-1)``
+    (with ``t(0) = -∞`` and ``t(K) = +∞`` fixed) and computes::
+
+        P(y = k | x) = σ(t(k+1) - logit) - σ(t(k) - logit)
+
+    Args:
+        input_dim: Size of the input feature dimension.
+        output_dim: Number of ordinal classes.
+    """
+
+    def __init__(self, input_dim, output_dim):
+        super().__init__()
+        self.input_dim = input_dim
+        self.output_dim = output_dim
+        self.linear = nn.Linear(input_dim, 1)
+        self.interior_thresholds = nn.Parameter(torch.empty(output_dim - 1))
+        self._init_thresholds()
+
+    def _init_thresholds(self):
+        nn.init.xavier_uniform_(self.interior_thresholds.unsqueeze(0))
+        with torch.no_grad():
+            self.interior_thresholds.copy_(self.interior_thresholds.sort().values)
+
+    def forward(self, x):
+        logit = self.linear(x)  # (batch, 1)
+        t_low = torch.full((1,), float("-inf"), device=logit.device, dtype=logit.dtype)
+        t_high = torch.full((1,), float("inf"), device=logit.device, dtype=logit.dtype)
+        thresholds = torch.cat([t_low, self.interior_thresholds, t_high])  # (K+1,)
+        return torch.sigmoid(thresholds[1:] - logit) - torch.sigmoid(thresholds[:-1] - logit)

deepordinal-0.2.0/deepordinal.egg-info/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: deepordinal
+Version: 0.2.0
+Summary: Ordinal output layers and loss functions (Rennie & Srebro, 2005) for PyTorch and TF/Keras
+Author: Nicholas Hirons
+License-Expression: MIT
+Project-URL: Repository, https://github.com/nhirons/deepordinal
+Keywords: ordinal-regression,deep-learning,pytorch,tensorflow,keras
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: tf
+Requires-Dist: tensorflow>=2.0; extra == "tf"
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Dynamic: license-file
+
+# DeepOrdinal
+
+Ordinal output layers and loss functions ([Rennie & Srebro, 2005](https://ttic.uchicago.edu/~nati/Publications/RennieSrebroIJCAI05.pdf)) for PyTorch and TF/Keras.
+
+DeepOrdinal provides an `OrdinalOutput` layer that converts a learned logit into ordinal class probabilities via sorted thresholds, plus loss functions designed specifically for ordinal regression.
+
+## Installation
+
+```bash
+pip install deepordinal
+```
+
+With a specific backend:
+
+```bash
+pip install ".[tf]"     # TensorFlow/Keras
+pip install ".[torch]"  # PyTorch
+```
+
+For development:
+
+```bash
+pip install -e ".[tf,torch]"
+```
+
+## Backends
+
+DeepOrdinal supports two backends with identical APIs:
+
+| | PyTorch | TensorFlow/Keras |
+|---|---|---|
+| Module | `deepordinal.torch` | `deepordinal.tf` |
+| Layer | `OrdinalOutput(input_dim=D, output_dim=K)` | `OrdinalOutput(output_dim=K)` |
+| Loss functions | `ordinal_loss`, `ordistic_loss` | `ordinal_loss`, `ordistic_loss` |
+
+## OrdinalOutput Layer
+
+The `OrdinalOutput` layer accepts any input size, projects to a single logit, and converts it into K class probabilities using K-1 learned, sorted thresholds:
+
+```
+P(y = k | x) = sigmoid(t(k+1) - logit) - sigmoid(t(k) - logit)
+```
+
+where `t(0) = -inf` and `t(K) = inf` are fixed, and interior thresholds are initialized sorted.
+
+```python
+from deepordinal.torch import OrdinalOutput  # or deepordinal.tf
+layer = OrdinalOutput(input_dim=16, output_dim=4)  # TF omits input_dim
+```
+
+## Loss Functions
+
+DeepOrdinal implements the threshold-based ordinal loss functions from Rennie & Srebro, "Loss Functions for Preference Levels" (IJCAI 2005). These operate on raw logits and thresholds rather than probability output.
+
+### `ordinal_loss`
+
+```python
+ordinal_loss(logits, targets, thresholds, construction='all', penalty='logistic')
+```
+
+- **logits**: `(batch,)` or `(batch, 1)` — raw predictor output
+- **targets**: `(batch,)` — integer labels in `[0, K)`
+- **thresholds**: `(K-1,)` — sorted interior thresholds
+- **construction**: `'all'` or `'immediate'`
+- **penalty**: `'hinge'`, `'smooth_hinge'`, `'modified_least_squares'`, or `'logistic'`
+- **Returns**: scalar mean loss over the batch
+
+#### Constructions
+
+- **All-threshold** (default, eq 13): penalizes violations of every threshold, weighted by direction. Bounds mean absolute error. Best performer in the paper's experiments.
+- **Immediate-threshold** (eq 12): only penalizes violations of the two thresholds bounding the correct class segment.
+
+#### Penalty functions
+
+| Name | Formula | Reference |
+|---|---|---|
+| `'hinge'` | `max(0, 1-z)` | eq 5 |
+| `'smooth_hinge'` | 0 if z≥1, (1-z)²/2 if 0<z<1, 0.5-z if z≤0 | eq 6 |
+| `'modified_least_squares'` | 0 if z≥1, (1-z)² if z<1 | eq 7 |
+| `'logistic'` | `log(1 + exp(-z))` | eq 9 |
+
+The paper recommends **all-threshold + logistic** as the best-performing combination.
+
+### `ordistic_loss`
+
+Probabilistic generalization of logistic regression to K-class ordinal problems (Section 4).
+
+```python
+ordistic_loss(logits, targets, means, log_priors=None)
+```
+
+- **logits**: `(batch,)` or `(batch, 1)` — raw predictor output
+- **targets**: `(batch,)` — integer labels in `[0, K)`
+- **means**: `(K,)` — class means (convention: μ₁=-1, μ_K=1; interior means learned)
+- **log_priors**: `(K,)` or `None` — optional log-prior terms π_i
+- **Returns**: scalar mean negative log-likelihood over the batch
+
+### Example usage
+
+#### PyTorch
+
+```python
+import torch
+from deepordinal.torch import OrdinalOutput, ordinal_loss
+
+layer = OrdinalOutput(input_dim=16, output_dim=4)
+h = torch.randn(8, 16)
+targets = torch.randint(0, 4, (8,))
+
+probs = layer(h)
+loss = ordinal_loss(layer.linear(h), targets, layer.interior_thresholds)
+loss.backward()
+```
+
+#### TensorFlow
+
+```python
+import tensorflow as tf
+from deepordinal.tf import OrdinalOutput, ordinal_loss
+
+layer = OrdinalOutput(output_dim=4)
+h = tf.random.normal((8, 16))
+targets = tf.random.uniform((8,), 0, 4, dtype=tf.int32)
+
+with tf.GradientTape() as tape:
+    probs = layer(h)
+    logit = tf.matmul(h, layer.kernel) + layer.bias
+    loss = ordinal_loss(logit, targets, tf.squeeze(layer.interior_thresholds))
+grads = tape.gradient(loss, layer.trainable_variables)
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[tf,torch]"
+pytest -v
+```
+
+## Changelog
+
+### 0.2.0
+
+- Added `ordinal_loss` — Rennie & Srebro threshold-based ordinal loss with two constructions (all-threshold, immediate-threshold) and four penalty functions (hinge, smooth hinge, modified least squares, logistic)
+- Added `ordistic_loss` — ordistic negative log-likelihood loss (Rennie & Srebro, Section 4)
+- Both loss functions available in `deepordinal.torch` and `deepordinal.tf`
+
+### 0.1.0
+
+- Added PyTorch backend (`deepordinal.torch`) with `OrdinalOutput` module
+- Modernized TensorFlow backend to `tf.keras` with self-contained `OrdinalOutput` layer and `SortedInitializer`
+- Dual-backend support (TensorFlow/Keras and PyTorch) with matching APIs
+- `pyproject.toml` build configuration with optional `[tf]` and `[torch]` extras
+
+### Initial
+
+- `OrdinalOutput` Keras layer for deep ordinal regression
+- Example notebook with synthetic ordinal data
+
+## Examples
+
+- `examples/example_tf.ipynb` — TensorFlow/Keras with `ordinal_loss` and `GradientTape` training loop
+- `examples/example_torch.ipynb` — PyTorch with `ordinal_loss` and standard training loop
+

deepordinal-0.2.0/deepordinal.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+deepordinal/__init__.py
+deepordinal/tf.py
+deepordinal/torch.py
+deepordinal.egg-info/PKG-INFO
+deepordinal.egg-info/SOURCES.txt
+deepordinal.egg-info/dependency_links.txt
+deepordinal.egg-info/requires.txt
+deepordinal.egg-info/top_level.txt
+tests/test_tf.py
+tests/test_torch.py

deepordinal-0.2.0/deepordinal.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

deepordinal-0.2.0/deepordinal.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy
+
+[tf]
+tensorflow>=2.0
+
+[torch]
+torch>=2.0

deepordinal-0.2.0/deepordinal.egg-info/top_level.txt

@@ -0,0 +1 @@
+deepordinal

deepordinal-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "deepordinal"
+version = "0.2.0"
+description = "Ordinal output layers and loss functions (Rennie & Srebro, 2005) for PyTorch and TF/Keras"
+requires-python = ">=3.10"
+dependencies = ["numpy"]
+license = "MIT"
+authors = [
+    { name = "Nicholas Hirons" },
+]
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["ordinal-regression", "deep-learning", "pytorch", "tensorflow", "keras"]
+
+[project.optional-dependencies]
+tf = ["tensorflow>=2.0"]
+torch = ["torch>=2.0"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["deepordinal*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+
+[project.urls]
+Repository = "https://github.com/nhirons/deepordinal"

deepordinal-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deepordinal-0.2.0/tests/test_tf.py

@@ -0,0 +1,220 @@
+import pytest
+
+tf = pytest.importorskip("tensorflow")
+
+from deepordinal.tf import OrdinalOutput, SortedInitializer, ordinal_loss, ordistic_loss
+
+
+def test_output_shape():
+    layer = OrdinalOutput(output_dim=5)
+    x = tf.random.normal((4, 8))
+    out = layer(x)
+    assert out.shape == (4, 5)
+
+
+def test_probabilities_sum_to_one():
+    layer = OrdinalOutput(output_dim=3)
+    x = tf.random.normal((16, 4))
+    out = layer(x)
+    sums = tf.reduce_sum(out, axis=-1)
+    tf.debugging.assert_near(sums, tf.ones(16), atol=1e-5)
+
+
+def test_probabilities_non_negative():
+    layer = OrdinalOutput(output_dim=6)
+    x = tf.random.normal((32, 4))
+    out = layer(x)
+    assert tf.reduce_all(out >= 0).numpy()
+
+
+def test_thresholds_initialized_sorted():
+    layer = OrdinalOutput(output_dim=5)
+    layer.build((None, 4))
+    t = layer.interior_thresholds.numpy().flatten()
+    assert list(t) == sorted(t)
+
+
+def test_gradients_flow():
+    layer = OrdinalOutput(output_dim=3)
+    x = tf.random.normal((8, 4))
+    with tf.GradientTape() as tape:
+        out = layer(x)
+        loss = tf.reduce_sum(out)
+    grads = tape.gradient(loss, layer.trainable_variables)
+    assert all(g is not None for g in grads)
+
+
+def test_sorted_initializer():
+    init = SortedInitializer("glorot_uniform")
+    values = init((1, 10))
+    v = values.numpy().flatten()
+    assert list(v) == sorted(v)
+
+
+def test_get_config_roundtrip():
+    layer = OrdinalOutput(output_dim=4)
+    config = layer.get_config()
+    assert config["output_dim"] == 4
+    restored = OrdinalOutput.from_config(config)
+    assert restored.output_dim == 4
+
+
+def test_single_sample():
+    layer = OrdinalOutput(output_dim=4)
+    x = tf.random.normal((1, 2))
+    out = layer(x)
+    assert out.shape == (1, 4)
+    tf.debugging.assert_near(tf.reduce_sum(out), 1.0, atol=1e-5)
+
+
+# --- Loss function tests ---
+
+import numpy as np
+
+
+class TestPenaltyFunctions:
+    def test_hinge_values(self):
+        from deepordinal.tf import _penalty
+        z = tf.constant([-1.0, 0.0, 0.5, 1.0, 2.0])
+        expected = [2.0, 1.0, 0.5, 0.0, 0.0]
+        np.testing.assert_allclose(_penalty(z, "hinge").numpy(), expected)
+
+    def test_smooth_hinge_values(self):
+        from deepordinal.tf import _penalty
+        z = tf.constant([-1.0, 0.0, 0.5, 1.0, 2.0])
+        expected = [1.5, 0.5, 0.125, 0.0, 0.0]
+        np.testing.assert_allclose(_penalty(z, "smooth_hinge").numpy(), expected)
+
+    def test_modified_least_squares_values(self):
+        from deepordinal.tf import _penalty
+        z = tf.constant([-1.0, 0.0, 0.5, 1.0, 2.0])
+        expected = [4.0, 1.0, 0.25, 0.0, 0.0]
+        np.testing.assert_allclose(_penalty(z, "modified_least_squares").numpy(), expected)
+
+    def test_logistic_values(self):
+        from deepordinal.tf import _penalty
+        z = tf.constant([0.0])
+        result = _penalty(z, "logistic").numpy()
+        np.testing.assert_allclose(result, [0.6931471805599453], atol=1e-5)
+
+    def test_all_penalties_non_negative(self):
+        from deepordinal.tf import _penalty
+        z = tf.linspace(-3.0, 3.0, 100)
+        for name in ["hinge", "smooth_hinge", "modified_least_squares", "logistic"]:
+            assert tf.reduce_all(_penalty(z, name) >= -1e-7).numpy(), f"{name} produced negative values"
+
+    def test_unknown_penalty_raises(self):
+        from deepordinal.tf import _penalty
+        with pytest.raises(ValueError, match="Unknown penalty"):
+            _penalty(tf.constant([0.0]), "bad")
+
+
+class TestOrdinalLoss:
+    def _make_inputs(self):
+        thresholds = tf.constant([-1.0, 0.0, 1.0])
+        logits = tf.constant([0.5, -0.5])
+        targets = tf.constant([1, 2])
+        return logits, targets, thresholds
+
+    def test_all_threshold_runs(self):
+        logits, targets, thresholds = self._make_inputs()
+        loss = ordinal_loss(logits, targets, thresholds, construction="all", penalty="logistic")
+        assert loss.shape == ()
+        assert loss.numpy() >= 0
+
+    def test_immediate_threshold_runs(self):
+        logits, targets, thresholds = self._make_inputs()
+        loss = ordinal_loss(logits, targets, thresholds, construction="immediate", penalty="logistic")
+        assert loss.shape == ()
+        assert loss.numpy() >= 0
+
+    def test_all_penalties_work(self):
+        logits, targets, thresholds = self._make_inputs()
+        for penalty in ["hinge", "smooth_hinge", "modified_least_squares", "logistic"]:
+            loss = ordinal_loss(logits, targets, thresholds, penalty=penalty)
+            assert loss.numpy() >= 0, f"{penalty} loss is negative"
+
+    def test_perfect_prediction_low_loss(self):
+        thresholds = tf.constant([-2.0, 0.0, 2.0])
+        logits = tf.constant([-3.0])
+        targets = tf.constant([0])
+        loss_correct = ordinal_loss(logits, targets, thresholds, penalty="hinge")
+        targets_wrong = tf.constant([3])
+        loss_wrong = ordinal_loss(logits, targets_wrong, thresholds, penalty="hinge")
+        assert loss_correct.numpy() < loss_wrong.numpy()
+
+    def test_gradients_flow_through_loss(self):
+        thresholds = tf.Variable([-1.0, 0.0, 1.0])
+        logits = tf.Variable([0.5])
+        targets = tf.constant([1])
+        with tf.GradientTape() as tape:
+            loss = ordinal_loss(logits, targets, thresholds, penalty="logistic")
+        grads = tape.gradient(loss, [logits, thresholds])
+        assert all(g is not None for g in grads)
+
+    def test_batch_reduction(self):
+        thresholds = tf.constant([-1.0, 0.0, 1.0])
+        logits = tf.constant([0.5, -0.5, 0.0, 1.5])
+        targets = tf.constant([0, 1, 2, 3])
+        loss = ordinal_loss(logits, targets, thresholds)
+        assert loss.shape == ()
+
+    def test_unknown_construction_raises(self):
+        logits, targets, thresholds = self._make_inputs()
+        with pytest.raises(ValueError, match="Unknown construction"):
+            ordinal_loss(logits, targets, thresholds, construction="bad")
+
+    def test_logits_2d(self):
+        thresholds = tf.constant([-1.0, 0.0, 1.0])
+        logits = tf.constant([[0.5], [-0.5]])
+        targets = tf.constant([1, 2])
+        loss = ordinal_loss(logits, targets, thresholds)
+        assert loss.shape == ()
+
+    def test_hand_worked_all_threshold_hinge(self):
+        thresholds = tf.constant([0.0, 2.0])
+        logits = tf.constant([1.0])
+        targets = tf.constant([1])
+        loss = ordinal_loss(logits, targets, thresholds, construction="all", penalty="hinge")
+        np.testing.assert_allclose(loss.numpy(), 0.0, atol=1e-6)
+
+    def test_hand_worked_immediate_hinge(self):
+        thresholds = tf.constant([0.0, 2.0])
+        logits = tf.constant([1.0])
+        targets = tf.constant([1])
+        loss = ordinal_loss(logits, targets, thresholds, construction="immediate", penalty="hinge")
+        np.testing.assert_allclose(loss.numpy(), 0.0, atol=1e-6)
+
+
+class TestOrdisticLoss:
+    def test_runs(self):
+        means = tf.constant([-1.0, 0.0, 1.0])
+        logits = tf.constant([0.5, -0.5])
+        targets = tf.constant([0, 2])
+        loss = ordistic_loss(logits, targets, means)
+        assert loss.shape == ()
+        assert loss.numpy() >= 0
+
+    def test_with_log_priors(self):
+        means = tf.constant([-1.0, 0.0, 1.0])
+        log_priors = tf.constant([0.0, 0.1, -0.1])
+        logits = tf.constant([0.5])
+        targets = tf.constant([1])
+        loss = ordistic_loss(logits, targets, means, log_priors=log_priors)
+        assert loss.shape == ()
+
+    def test_gradients_flow(self):
+        means = tf.Variable([-1.0, 0.0, 1.0])
+        logits = tf.Variable([0.5])
+        targets = tf.constant([1])
+        with tf.GradientTape() as tape:
+            loss = ordistic_loss(logits, targets, means)
+        grads = tape.gradient(loss, [logits, means])
+        assert all(g is not None for g in grads)
+
+    def test_non_negative(self):
+        means = tf.constant([-1.0, 0.0, 1.0])
+        logits = tf.random.normal([20])
+        targets = tf.random.uniform([20], 0, 3, dtype=tf.int32)
+        loss = ordistic_loss(logits, targets, means)
+        assert loss.numpy() >= 0

deepordinal-0.2.0/tests/test_torch.py

@@ -0,0 +1,223 @@
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from deepordinal.torch import OrdinalOutput, ordinal_loss, ordistic_loss
+
+
+def test_output_shape():
+    layer = OrdinalOutput(input_dim=8, output_dim=5)
+    x = torch.randn(4, 8)
+    out = layer(x)
+    assert out.shape == (4, 5)
+
+
+def test_probabilities_sum_to_one():
+    layer = OrdinalOutput(input_dim=4, output_dim=3)
+    x = torch.randn(16, 4)
+    out = layer(x)
+    torch.testing.assert_close(out.sum(dim=-1), torch.ones(16), atol=1e-5, rtol=0)
+
+
+def test_probabilities_non_negative():
+    layer = OrdinalOutput(input_dim=4, output_dim=6)
+    x = torch.randn(32, 4)
+    out = layer(x)
+    assert (out >= 0).all()
+
+
+def test_thresholds_initialized_sorted():
+    layer = OrdinalOutput(input_dim=4, output_dim=5)
+    t = layer.interior_thresholds.detach()
+    sorted_t, _ = t.sort()
+    torch.testing.assert_close(t, sorted_t)
+
+
+def test_gradients_flow():
+    layer = OrdinalOutput(input_dim=4, output_dim=3)
+    x = torch.randn(8, 4)
+    out = layer(x)
+    loss = out.sum()
+    loss.backward()
+    assert layer.linear.weight.grad is not None
+    assert layer.interior_thresholds.grad is not None
+
+
+def test_seed_reproducibility():
+    torch.manual_seed(42)
+    a = OrdinalOutput(input_dim=4, output_dim=3)
+    torch.manual_seed(42)
+    b = OrdinalOutput(input_dim=4, output_dim=3)
+    x = torch.randn(4, 4)
+    torch.testing.assert_close(a(x), b(x))
+
+
+def test_single_sample():
+    layer = OrdinalOutput(input_dim=2, output_dim=4)
+    x = torch.randn(1, 2)
+    out = layer(x)
+    assert out.shape == (1, 4)
+    torch.testing.assert_close(out.sum(), torch.tensor(1.0), atol=1e-5, rtol=0)
+
+
+# --- Loss function tests ---
+
+
+class TestPenaltyFunctions:
+    """Test each penalty function for known input/output values."""
+
+    def test_hinge_values(self):
+        z = torch.tensor([-1.0, 0.0, 0.5, 1.0, 2.0])
+        expected = torch.tensor([2.0, 1.0, 0.5, 0.0, 0.0])
+        from deepordinal.torch import _penalty
+        torch.testing.assert_close(_penalty(z, "hinge"), expected)
+
+    def test_smooth_hinge_values(self):
+        z = torch.tensor([-1.0, 0.0, 0.5, 1.0, 2.0])
+        expected = torch.tensor([1.5, 0.5, 0.125, 0.0, 0.0])
+        from deepordinal.torch import _penalty
+        torch.testing.assert_close(_penalty(z, "smooth_hinge"), expected)
+
+    def test_modified_least_squares_values(self):
+        z = torch.tensor([-1.0, 0.0, 0.5, 1.0, 2.0])
+        expected = torch.tensor([4.0, 1.0, 0.25, 0.0, 0.0])
+        from deepordinal.torch import _penalty
+        torch.testing.assert_close(_penalty(z, "modified_least_squares"), expected)
+
+    def test_logistic_values(self):
+        z = torch.tensor([0.0])
+        from deepordinal.torch import _penalty
+        result = _penalty(z, "logistic")
+        torch.testing.assert_close(result, torch.tensor([0.6931471805599453]), atol=1e-5, rtol=0)
+
+    def test_all_penalties_non_negative(self):
+        from deepordinal.torch import _penalty
+        z = torch.linspace(-3, 3, 100)
+        for name in ["hinge", "smooth_hinge", "modified_least_squares", "logistic"]:
+            assert (_penalty(z, name) >= -1e-7).all(), f"{name} produced negative values"
+
+    def test_unknown_penalty_raises(self):
+        from deepordinal.torch import _penalty
+        with pytest.raises(ValueError, match="Unknown penalty"):
+            _penalty(torch.tensor([0.0]), "bad")
+
+
+class TestOrdinalLoss:
+    """Test ordinal_loss with both constructions."""
+
+    def _make_inputs(self):
+        thresholds = torch.tensor([-1.0, 0.0, 1.0])  # K=4 classes
+        logits = torch.tensor([0.5, -0.5])
+        targets = torch.tensor([1, 2])  # 0-indexed
+        return logits, targets, thresholds
+
+    def test_all_threshold_runs(self):
+        logits, targets, thresholds = self._make_inputs()
+        loss = ordinal_loss(logits, targets, thresholds, construction="all", penalty="logistic")
+        assert loss.shape == ()
+        assert loss.item() >= 0
+
+    def test_immediate_threshold_runs(self):
+        logits, targets, thresholds = self._make_inputs()
+        loss = ordinal_loss(logits, targets, thresholds, construction="immediate", penalty="logistic")
+        assert loss.shape == ()
+        assert loss.item() >= 0
+
+    def test_all_penalties_work(self):
+        logits, targets, thresholds = self._make_inputs()
+        for penalty in ["hinge", "smooth_hinge", "modified_least_squares", "logistic"]:
+            loss = ordinal_loss(logits, targets, thresholds, penalty=penalty)
+            assert loss.item() >= 0, f"{penalty} loss is negative"
+
+    def test_perfect_prediction_low_loss(self):
+        # Logit perfectly in the middle of its segment should have low loss
+        thresholds = torch.tensor([-2.0, 0.0, 2.0])
+        logits = torch.tensor([-3.0])  # class 0: should be below -2
+        targets = torch.tensor([0])
+        loss_correct = ordinal_loss(logits, targets, thresholds, penalty="hinge")
+        # Now misclassify
+        targets_wrong = torch.tensor([3])
+        loss_wrong = ordinal_loss(logits, targets_wrong, thresholds, penalty="hinge")
+        assert loss_correct < loss_wrong
+
+    def test_gradients_flow_through_loss(self):
+        thresholds = torch.tensor([-1.0, 0.0, 1.0], requires_grad=True)
+        logits = torch.tensor([0.5], requires_grad=True)
+        targets = torch.tensor([1])
+        loss = ordinal_loss(logits, targets, thresholds, penalty="logistic")
+        loss.backward()
+        assert logits.grad is not None
+        assert thresholds.grad is not None
+
+    def test_batch_reduction(self):
+        thresholds = torch.tensor([-1.0, 0.0, 1.0])
+        logits = torch.tensor([0.5, -0.5, 0.0, 1.5])
+        targets = torch.tensor([0, 1, 2, 3])
+        loss = ordinal_loss(logits, targets, thresholds)
+        assert loss.shape == ()
+
+    def test_unknown_construction_raises(self):
+        logits, targets, thresholds = self._make_inputs()
+        with pytest.raises(ValueError, match="Unknown construction"):
+            ordinal_loss(logits, targets, thresholds, construction="bad")
+
+    def test_logits_2d(self):
+        thresholds = torch.tensor([-1.0, 0.0, 1.0])
+        logits = torch.tensor([[0.5], [-0.5]])
+        targets = torch.tensor([1, 2])
+        loss = ordinal_loss(logits, targets, thresholds)
+        assert loss.shape == ()
+
+    def test_hand_worked_all_threshold_hinge(self):
+        # K=3 (classes 0,1,2), thresholds=[0, 2], logit=1, target=1 (paper y=2)
+        # s(l=1;y=2)=-1, s(l=2;y=2)=+1
+        # f(-1*(0-1)) + f(+1*(2-1)) = f(1) + f(1) = 0 + 0 = 0
+        thresholds = torch.tensor([0.0, 2.0])
+        logits = torch.tensor([1.0])
+        targets = torch.tensor([1])
+        loss = ordinal_loss(logits, targets, thresholds, construction="all", penalty="hinge")
+        torch.testing.assert_close(loss, torch.tensor(0.0))
+
+    def test_hand_worked_immediate_hinge(self):
+        # K=3, thresholds=[0, 2], logit=1, target=1 (0-indexed)
+        # theta_low = thresholds[1] = 0, theta_high = thresholds[1] = 2
+        # f(1-0) + f(2-1) = f(1) + f(1) = 0 + 0 = 0
+        thresholds = torch.tensor([0.0, 2.0])
+        logits = torch.tensor([1.0])
+        targets = torch.tensor([1])
+        loss = ordinal_loss(logits, targets, thresholds, construction="immediate", penalty="hinge")
+        torch.testing.assert_close(loss, torch.tensor(0.0))
+
+
+class TestOrdisticLoss:
+    def test_runs(self):
+        means = torch.tensor([-1.0, 0.0, 1.0])
+        logits = torch.tensor([0.5, -0.5])
+        targets = torch.tensor([0, 2])
+        loss = ordistic_loss(logits, targets, means)
+        assert loss.shape == ()
+        assert loss.item() >= 0
+
+    def test_with_log_priors(self):
+        means = torch.tensor([-1.0, 0.0, 1.0])
+        log_priors = torch.tensor([0.0, 0.1, -0.1])
+        logits = torch.tensor([0.5])
+        targets = torch.tensor([1])
+        loss = ordistic_loss(logits, targets, means, log_priors=log_priors)
+        assert loss.shape == ()
+
+    def test_gradients_flow(self):
+        means = torch.tensor([-1.0, 0.0, 1.0], requires_grad=True)
+        logits = torch.tensor([0.5], requires_grad=True)
+        targets = torch.tensor([1])
+        loss = ordistic_loss(logits, targets, means)
+        loss.backward()
+        assert logits.grad is not None
+        assert means.grad is not None
+
+    def test_non_negative(self):
+        means = torch.tensor([-1.0, 0.0, 1.0])
+        logits = torch.randn(20)
+        targets = torch.randint(0, 3, (20,))
+        loss = ordistic_loss(logits, targets, means)
+        assert loss.item() >= 0