[API] Rename distributions module to soft_labelling

dlordinal/losses/beta_loss.py

@@ -3,7 +3,7 @@
 import torch
 from torch import Tensor
 
-from ..distributions import get_beta_softlabels
+from ..soft_labelling import get_beta_soft_labels
 from .custom_targets_loss import CustomTargetsCrossEntropyLoss
 
 # Params [a,b] for beta distribution
@@ -177,7 +177,7 @@ def __init__(
         # Precompute class probabilities for each label
         cls_probs = torch.tensor(
             [
-                get_beta_softlabels(
+                get_beta_soft_labels(
                     num_classes,
                     self.params[num_classes][i][0],
                     self.params[num_classes][i][1],

dlordinal/losses/binomial_loss.py

@@ -3,7 +3,7 @@
 import torch
 from torch import Tensor
 
-from ..distributions import get_binomial_softlabels
+from ..soft_labelling import get_binomial_soft_labels
 from .custom_targets_loss import CustomTargetsCrossEntropyLoss
 
 
@@ -59,7 +59,7 @@ def __init__(
         label_smoothing: float = 0.0,
     ):
         # Precompute class probabilities for each label
-        cls_probs = torch.tensor(get_binomial_softlabels(num_classes)).float()
+        cls_probs = torch.tensor(get_binomial_soft_labels(num_classes)).float()
 
         super().__init__(
             cls_probs=cls_probs,

dlordinal/losses/exponential_loss.py

@@ -3,7 +3,7 @@
 import torch
 from torch import Tensor
 
-from ..distributions import get_exponential_softlabels
+from ..soft_labelling import get_exponential_soft_labels
 from .custom_targets_loss import CustomTargetsCrossEntropyLoss
 
 
@@ -63,7 +63,7 @@ def __init__(
         label_smoothing: float = 0.0,
     ):
         # Precompute class probabilities for each label
-        cls_probs = torch.tensor(get_exponential_softlabels(num_classes, p)).float()
+        cls_probs = torch.tensor(get_exponential_soft_labels(num_classes, p)).float()
 
         super().__init__(
             cls_probs=cls_probs,

dlordinal/losses/general_triangular_loss.py

@@ -4,7 +4,7 @@
 import torch
 from torch import Tensor
 
-from ..distributions import get_general_triangular_softlabels
+from ..soft_labelling import get_general_triangular_soft_labels
 from .custom_targets_loss import CustomTargetsCrossEntropyLoss
 
 
@@ -63,7 +63,7 @@ def __init__(
         label_smoothing: float = 0.0,
     ):
         # Precompute class probabilities for each label
-        r = get_general_triangular_softlabels(num_classes, alphas, verbose=0)
+        r = get_general_triangular_soft_labels(num_classes, alphas, verbose=0)
         cls_probs = torch.tensor(r)
 
         super().__init__(

dlordinal/losses/poisson_loss.py

@@ -3,7 +3,7 @@
 import torch
 from torch import Tensor
 
-from ..distributions import get_poisson_probabilities
+from ..soft_labelling import get_poisson_soft_labels
 from .custom_targets_loss import CustomTargetsCrossEntropyLoss
 
 
@@ -59,7 +59,7 @@ def __init__(
         label_smoothing: float = 0.0,
     ):
         # Precompute class probabilities for each label
-        cls_probs = torch.tensor(get_poisson_probabilities(num_classes)).float()
+        cls_probs = torch.tensor(get_poisson_soft_labels(num_classes)).float()
 
         super().__init__(
             cls_probs=cls_probs,

dlordinal/losses/triangular_loss.py

@@ -3,7 +3,7 @@
 import torch
 from torch import Tensor
 
-from ..distributions import get_triangular_softlabels
+from ..soft_labelling import get_triangular_soft_labels
 from .custom_targets_loss import CustomTargetsCrossEntropyLoss
 
 
@@ -62,7 +62,7 @@ def __init__(
         label_smoothing: float = 0.0,
     ):
         # Precompute class probabilities for each label
-        cls_probs = torch.tensor(get_triangular_softlabels(num_classes, alpha2))
+        cls_probs = torch.tensor(get_triangular_soft_labels(num_classes, alpha2))
         super().__init__(
             cls_probs=cls_probs,
             eta=eta,

dlordinal/soft_labelling/__init__.py

@@ -0,0 +1,19 @@
+from .beta_distribution import get_beta_soft_labels
+from .binomial_distribution import get_binomial_soft_labels
+from .exponential_distribution import get_exponential_soft_labels
+from .general_triangular_distribution import (
+    get_general_triangular_params,
+    get_general_triangular_soft_labels,
+)
+from .poisson_distribution import get_poisson_soft_labels
+from .triangular_distribution import get_triangular_soft_labels
+
+__all__ = [
+    "get_beta_soft_labels",
+    "get_exponential_soft_labels",
+    "get_binomial_soft_labels",
+    "get_poisson_soft_labels",
+    "get_triangular_soft_labels",
+    "get_general_triangular_params",
+    "get_general_triangular_soft_labels",
+]

dlordinal/distributions/beta_distribution.py → dlordinal/soft_labelling/beta_distribution.py

@@ -57,8 +57,8 @@ def beta_dist(x, p, q, a=1.0):
     return (x ** (a * p)) / (p * beta_func(p, q)) * hyp2f1(p, 1 - q, p + 1, x**a)
 
 
-def get_beta_softlabels(J, p, q, a=1.0):
-    """Get probabilities from a beta distribution :math:`B(p,q,a)` for ``J`` splits.
+def get_beta_soft_labels(J, p, q, a=1.0):
+    """Get soft labels from a beta distribution :math:`B(p,q,a)` for ``J`` splits.
     The :math:`[0,1]` interval is split into ``J`` intervals and the probability for
     each interval is computed as the difference between the value of the distribution
     function in the upper limit of the interval and the value of the distribution
@@ -90,10 +90,10 @@ class or split.
 
     Example
     -------
-    >>> from dlordinal.distributions import get_beta_probabilities
-    >>> get_beta_probabilities(3, 2, 3)
+    >>> from dlordinal.soft_labelling import get_beta_soft_labels
+    >>> get_beta_soft_labels(3, 2, 3)
     [0.4074074080000002, 0.48148148059259255, 0.11111111140740726]
-    >>> get_beta_probabilities(5, 5, 1, a=2)
+    >>> get_beta_soft_labels(5, 5, 1, a=2)
     [1.0240000307200007e-07, 0.00010475520052121611, 0.005941759979320316,
       0.10132756401484902, 0.8926258084053067]
     """

dlordinal/distributions/binomial_distribution.py → dlordinal/soft_labelling/binomial_distribution.py

@@ -2,8 +2,8 @@
 from scipy.stats import binom
 
 
-def get_binomial_softlabels(J):
-    """Get probabilities for the binomial distribution for ``J`` classes or splits
+def get_binomial_soft_labels(J):
+    """Get soft labels for the binomial distribution for ``J`` classes or splits
     using the approach described in :footcite:t:`liu2020unimodal`.
     The :math:`[0,1]` interval is split into ``J`` intervals and the probability for
     each interval is computed as the difference between the value of the binomial
@@ -34,8 +34,8 @@ def get_binomial_softlabels(J):
 
     Example
     -------
-    >>> from dlordinal.distributions import get_binominal_probabilities
-    >>> get_binominal_probabilities(5)
+    >>> from dlordinal.soft_labelling import get_binomial_soft_labels
+    >>> get_binomial_soft_labels(5)
     array([[6.561e-01, 2.916e-01, 4.860e-02, 3.600e-03, 1.000e-04],
             [2.401e-01, 4.116e-01, 2.646e-01, 7.560e-02, 8.100e-03],
             [6.250e-02, 2.500e-01, 3.750e-01, 2.500e-01, 6.250e-02],

dlordinal/distributions/exponential_distribution.py → dlordinal/soft_labelling/exponential_distribution.py

@@ -2,8 +2,8 @@
 from scipy.special import softmax
 
 
-def get_exponential_softlabels(J, p=1.0, tau=1.0):
-    """Get probabilities from exponential distribution for ``J`` classes or splits as
+def get_exponential_soft_labels(J, p=1.0, tau=1.0):
+    """Get soft labels from exponential distribution for ``J`` classes or splits as
     described in :footcite:t:`liu2020unimodal` and :footcite:t:`vargas2023exponential`.
     The :math:`[0,1]` interval is split into ``J`` intervals and the probability for
     each interval is computed as the difference between the value of the exponential
@@ -39,8 +39,8 @@ def get_exponential_softlabels(J, p=1.0, tau=1.0):
 
     Example
     -------
-    >>> from dlordinal.distributions import get_exponential_probabilities
-    >>> get_exponential_probabilities(5)
+    >>> from dlordinal.soft_labelling import get_exponential_soft_labels
+    >>> get_exponential_soft_labels(5)
     array([[0.63640865, 0.23412166, 0.08612854, 0.03168492, 0.01165623],
     [0.19151597, 0.52059439, 0.19151597, 0.07045479, 0.02591887],
     [0.06745081, 0.1833503 , 0.49839779, 0.1833503 , 0.06745081],

dlordinal/distributions/general_triangular_distribution.py → dlordinal/soft_labelling/general_triangular_distribution.py

@@ -47,7 +47,7 @@ def get_general_triangular_params(J: int, alphas: np.ndarray, verbose: int = 0):
 
     Example
     -------
-    >>> from dlordinal.distributions import get_general_triangular_params
+    >>> from dlordinal.soft_labelling import get_general_triangular_params
     >>> get_general_triangular_params(5, [0, 0.1, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.1, 0])
     [{'alpha2j_1': 0, 'alpha2j': 0.05, 'a': 0, 'b': 0.25760143110525874, 'c': 0}, {'alpha2j_1': 0.05, 'alpha2j': 0.05, 'a': 0.153752470442574, 'b': 0.446247529557426, 'c': 0.3}, {'alpha2j_1': 0.05, 'alpha2j': 0.05, 'a': 0.353752470442574, 'b': 0.646247529557426, 'c': 0.5}, {'alpha2j_1': 0.05, 'alpha2j': 0.1, 'a': 0.550779686438060, 'b': 0.875486049708105, 'c': 0.7}, {'alpha2j_1': 0.0, 'alpha2j': 0, 'a': 0.8, 'b': 1, 'c': 1}]
 
@@ -158,8 +158,8 @@ def abcj(J, j, alpha2j_1, alpha2j):
     return params
 
 
-def get_general_triangular_softlabels(J: int, alphas: np.ndarray, verbose: int = 0):
-    """Get probabilities from triangular distributions for ``J`` classes or splits.
+def get_general_triangular_soft_labels(J: int, alphas: np.ndarray, verbose: int = 0):
+    """Get soft labels using triangular distributions for ``J`` classes or splits.
     The :math:`[0,1]` interval is split into ``J`` intervals and the probability for
     each interval is computed as the difference between the value of the triangular
     distribution function for the interval boundaries. The probability for the first
@@ -193,8 +193,8 @@ def get_general_triangular_softlabels(J: int, alphas: np.ndarray, verbose: int =
 
     Example
     -------
-    >>> from dlordinal.distributions import get_general_triangular_probabilities
-    >>> get_general_triangular_probabilities(
+    >>> from dlordinal.soft_labelling import get_general_triangular_soft_labels
+    >>> get_general_triangular_soft_labels(
     ...     5,
     ...     [0, 0.1, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.1, 0]
     ... )

dlordinal/distributions/poisson_distribution.py → dlordinal/soft_labelling/poisson_distribution.py

@@ -3,8 +3,8 @@
 from scipy.stats import poisson
 
 
-def get_poisson_probabilities(J):
-    """Get probabilities from poisson distribution for ``J`` classes or splits using the
+def get_poisson_soft_labels(J):
+    """Get soft labels using poisson distributions for ``J`` classes or splits using the
     methodology described in :footcite:t:`liu2020unimodal`.
     The :math:`[0,1]` interval is split into ``J`` intervals and the probability for
     each interval is computed as the difference between the value of the poisson
@@ -36,8 +36,8 @@ def get_poisson_probabilities(J):
 
     Example
     -------
-    >>> from dlordinal.distributions import get_poisson_probabilities
-    >>> get_poisson_probabilities(5)
+    >>> from dlordinal.soft_labelling import get_poisson_soft_labels
+    >>> get_poisson_soft_labels(5)
     array([[0.23414552, 0.23414552, 0.19480578, 0.17232403, 0.16457916],
         [0.18896888, 0.21635436, 0.21635436, 0.19768881, 0.18063359],
         [0.17822335, 0.19688341, 0.21214973, 0.21214973, 0.20059378],

dlordinal/distributions/tests/test_beta_distribution.py → dlordinal/soft_labelling/tests/test_beta_distribution.py

@@ -1,8 +1,8 @@
 import numpy as np
 import pytest
 
-from dlordinal.distributions import get_beta_softlabels
-from dlordinal.distributions.beta_distribution import beta_dist, beta_func
+from dlordinal.soft_labelling import get_beta_soft_labels
+from dlordinal.soft_labelling.beta_distribution import beta_dist, beta_func
 
 
 def test_beta_inc():
@@ -23,7 +23,7 @@ def test_beta_inc_negative_values(a, b):
         beta_func(a, b)
 
 
-def test_beta_distribution():
+def test_beta_soft_label():
     # Case 1: Valid input
     x = 0.5
     p = 2.0
@@ -52,13 +52,13 @@ def test_beta_distribution_negative_x(x):
         beta_dist(x, 2.0, 3.0, 1.0)
 
 
-def test_beta_probabilities():
+def test_beta_soft_labels():
     # Case 1: Valid input
     n = 5
     p = 2.0
     q = 3.0
     a = 1.0
-    result = get_beta_softlabels(n, p, q, a)
+    result = get_beta_soft_labels(n, p, q, a)
     expected_result = [
         0.1808000009216,
         0.34399999942400017,
@@ -75,7 +75,7 @@ def test_beta_probabilities():
     p = 1.5
     q = 2.5
     a = 2.0
-    result = get_beta_softlabels(n, p, q, a)
+    result = get_beta_soft_labels(n, p, q, a)
     expected_result = [
         0.05010107325697135,
         0.283232260076362,

dlordinal/distributions/tests/test_binomial_distribution.py → dlordinal/soft_labelling/tests/test_binomial_distribution.py

@@ -1,13 +1,13 @@
 import numpy as np
 import pytest
 
-from dlordinal.distributions import get_binomial_softlabels
+from dlordinal.soft_labelling import get_binomial_soft_labels
 
 
-def test_get_binomial_probabilities():
+def test_get_binomial_soft_labels():
     # Case 1: n = 5
     n = 5
-    result = get_binomial_softlabels(n)
+    result = get_binomial_soft_labels(n)
     expected_result = np.array(
         [
             [6.561e-01, 2.916e-01, 4.860e-02, 3.600e-03, 1.000e-04],

dlordinal/distributions/tests/test_exponential_distribution.py → dlordinal/soft_labelling/tests/test_exponential_distribution.py

@@ -1,14 +1,14 @@
 import numpy as np
 import pytest
 
-from dlordinal.distributions import get_exponential_softlabels
+from dlordinal.soft_labelling import get_exponential_soft_labels
 
 
-def test_get_exponential_probabilities():
+def test_get_exponential_soft_labels():
     n = 5
     p = 1.0
     tau = 1.0
-    result = get_exponential_softlabels(n, p, tau)
+    result = get_exponential_soft_labels(n, p, tau)
     expected_result = np.array(
         [
             [0.63640865, 0.23412166, 0.08612854, 0.03168492, 0.01165623],
@@ -35,7 +35,7 @@ def test_exponential_probabilities():
     n = 4
     p = 2.0
     tau = 1.0
-    result = get_exponential_softlabels(n, p, tau)
+    result = get_exponential_soft_labels(n, p, tau)
     expected_result = np.array(
         [
             [7.21334965e-01, 2.65364304e-01, 1.32117107e-02, 8.90198068e-05],

dlordinal/distributions/tests/test_general_triangular_distribution.py → dlordinal/soft_labelling/tests/test_general_triangular_distribution.py

@@ -3,7 +3,10 @@
 import numpy as np
 import pytest
 
-from dlordinal.distributions import get_general_triangular_params
+from dlordinal.soft_labelling import (
+    get_general_triangular_params,
+    get_general_triangular_soft_labels,
+)
 
 
 def test_get_general_triangular_params():
@@ -115,3 +118,22 @@ def test_wrong_alpha_shape():
         match=re.escape("alphas must be a numpy array of shape (2 * n,), but got (7,)"),
     ):
         get_general_triangular_params(n, alphas)
+
+
+def test_general_triangular_soft_labels():
+    n = 3
+    alphas = np.array(
+        [0.05518804, 0.14000449, 0.0586412, 0.03018706, 0.15230179, 0.03493327]
+    )
+    result = get_general_triangular_soft_labels(n, alphas)
+    expected_result = [
+        [0.9413588, 0.0586412, 0.0],
+        [0.03018706, 0.81751114, 0.15230179],
+        [0.0, 0.03493327, 0.96506673],
+    ]
+
+    assert len(result.shape) == 2
+    assert result.shape[0] == n
+    assert result.shape[1] == n
+
+    assert np.allclose(result, expected_result, rtol=1e-6)