scoringrules 0.2.0__tar.gz → 0.3.0__tar.gz

{scoringrules-0.2.0 → scoringrules-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: scoringrules
-Version: 0.2.0
+Version: 0.3.0
 Summary: Scoring rules for probabilistic forecast evaluation.
 Home-page: https://github.com/frazane/scoringrules
 Keywords: probabilistic,forecasting,verification

{scoringrules-0.2.0 → scoringrules-0.3.0}/pyproject.toml

@@ -1,8 +1,11 @@
 [tool.poetry]
 name = "scoringrules"
-version = "0.2.0"
+version = "0.3.0"
 description = "Scoring rules for probabilistic forecast evaluation."
-authors = ["Francesco Zanetta <zanetta.francesco@gmail.com>"]
+authors = [
+  "Francesco Zanetta <zanetta.francesco@gmail.com>",
+  "Sam Allen <sam.allen@unibe.ch>",
+]
 homepage = "https://github.com/frazane/scoringrules"
 documentation = "https://frazane.github.io/scoringrules/"
 keywords = ["probabilistic", "forecasting", "verification"]
@@ -35,6 +38,7 @@ pre-commit = "^3.3.1"
 pytest = "^7.3.1"
 mypy = "^1.3.0"
 jax = { extras = ["cpu"], version = "^0.4.10" }
+dask = "^2023.7.1"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

scoringrules-0.3.0/scoringrules/__init__.py

@@ -0,0 +1,35 @@
+from importlib.metadata import version
+
+from scoringrules._brier import brier_score
+from scoringrules._crps import crps_ensemble, crps_lognormal, crps_normal, crps_logistic
+from scoringrules._wcrps import owcrps_ensemble, twcrps_ensemble, vrcrps_ensemble
+from scoringrules._energy import energy_score
+from scoringrules._wenergy import owenergy_score, twenergy_score, vrenergy_score
+from scoringrules._logs import logs_normal
+from scoringrules._variogram import variogram_score
+from scoringrules._wvariogram import owvariogram_score, twvariogram_score, vrvariogram_score
+from scoringrules.backend import register_backend
+
+__version__ = version("scoringrules")
+
+
+__all__ = [
+    "register_backend",
+    "crps_ensemble",
+    "crps_normal",
+    "crps_lognormal",
+    "crps_logistic",
+    "owcrps_ensemble",
+    "twcrps_ensemble",
+    "vrcrps_ensemble",
+    "logs_normal",
+    "brier_score",
+    "energy_score",
+    "owenergy_score",
+    "twenergy_score",
+    "vrenergy_score",
+    "variogram_score",
+    "owvariogram_score",
+    "twvariogram_score",
+    "vrvariogram_score",
+]

{scoringrules-0.2.0 → scoringrules-0.3.0}/scoringrules/_crps.py

@@ -138,8 +138,49 @@ def crps_lognormal(
     return srb[backend].crps_lognormal(mulog, sigmalog, observation)
 
 
+def crps_logistic(
+    mu: ArrayLike,
+    sigma: ArrayLike,
+    observation: ArrayLike,
+    /,
+    *,
+    backend: str = "numpy",
+) -> ArrayLike:
+    r"""Compute the closed form of the CRPS for the logistic distribution.
+
+    It is based on the following formulation from
+    [Jordan et al. (2019)](https://www.jstatsoft.org/article/view/v090i12):
+
+    $$ \mathrm{CRPS}(\mathcal{L}(\mu, \sigma), y) = \sigma \left\{ \omega - 2 \log F(\omega) - 1 \right\}, $$
+
+    where $F(\omega)$ is the CDF of the standard logistic distribution at the 
+    normalized prediction error $\omega = \frac{y - \mu}{\sigma}$.
+
+    Parameters
+    ----------
+    mu: ArrayLike
+        Location parameter of the forecast logistic distribution.
+    sigma: ArrayLike
+        Scale parameter of the forecast logistic distribution.
+    observation: ArrayLike
+        Observed values.
+
+    Returns
+    -------
+    crps: array_like
+        The CRPS for the Logistic(mu, sigma) forecasts given the observations.
+
+    Examples
+    --------
+    >>> from scoringrules import crps
+    >>> crps.logistic(0.1, 0.4, 0.0)
+    """
+    return srb[backend].crps_logistic(mu, sigma, observation)
+
+
 __all__ = [
     "crps_ensemble",
     "crps_normal",
     "crps_lognormal",
+    "crps_logistic",
 ]

scoringrules-0.3.0/scoringrules/_logs.py

@@ -0,0 +1,43 @@
+import typing as tp
+
+from scoringrules.backend import backends as srb
+from scoringrules.backend.arrayapi import Array
+
+ArrayLike = tp.TypeVar("ArrayLike", Array, float)
+
+
+def logs_normal(
+    mu: ArrayLike,
+    sigma: ArrayLike,
+    observation: ArrayLike,
+    /,
+    *,
+    backend: tp.Literal["numba", "numpy", "jax"] = "numpy",
+) -> Array:
+    r"""Compute the logarithmic score (LS) for the normal distribution.
+
+    This score is equivalent to the negative log likelihood.
+
+    Parameters
+    ----------
+    mu: ArrayLike
+        Mean of the forecast normal distribution.
+    sigma: ArrayLike
+        Standard deviation of the forecast normal distribution.
+    observation: ArrayLike
+        The observed values.
+    backend: str, optional
+        The backend used for computations.
+
+    Returns
+    -------
+    ls: array_like
+        The LS between Normal(mu, sigma) and obs.
+
+    Examples
+    --------
+    >>> import scoringrules as sr
+    >>> sr.logs_normal(0.1, 0.4, 0.0)
+    >>> 0.033898
+    """
+    return srb[backend].logs_normal(mu, sigma, observation)

scoringrules-0.3.0/scoringrules/_wcrps.py

@@ -0,0 +1,187 @@
+import numpy as np
+import typing as tp
+
+from scoringrules.backend import backends as srb
+from scoringrules.backend.arrayapi import Array
+
+ArrayLike = tp.TypeVar("ArrayLike", Array, float)
+
+
+def twcrps_ensemble(
+    forecasts: Array,
+    observations: ArrayLike,
+    /,
+    v_func: tp.Callable = lambda x, *args: x,
+    v_funcargs: tuple = (),
+    *,
+    axis: int = -1,
+    backend: str = "numba",
+) -> Array:
+    r"""Estimate the Threshold-Weighted Continuous Ranked Probability Score (twCRPS) for a finite ensemble.
+
+    Computation is performed using the ensemble representation of the twCRPS in
+    [Allen et al. (2022)](https://arxiv.org/abs/2202.12732):
+
+    $$ \mathrm{twCRPS}(F_{ens}, y) = \frac{1}{M} \sum_{m = 1}^{M} |v(x_{m}) - v(y)| - \frac{1}{2 M^{2}} \sum_{m = 1}^{M} \sum_{j = 1}^{M} |v(x_{m}) - v(x_{j})|,$$
+
+    where $F_{ens}(x) = \sum_{m=1}^{M} 1 \{ x_{m} \leq x \}/M$ is the empirical 
+    distribution function associated with an ensemble forecast $x_{1}, \dots, x_{M}$ with
+    $M$ members, and $v$ is the chaining function used to target particular outcomes.
+
+    Parameters
+    ----------
+    forecasts: ArrayLike
+        The predicted forecast ensemble, where the ensemble dimension is by default
+        represented by the last axis.
+    observations: ArrayLike
+        The observed values.
+    v_func: tp.Callable
+        Chaining function used to emphasise particular outcomes.
+    v_funcargs: tuple
+        Additional arguments to the chaining function.
+    axis: int
+        The axis corresponding to the ensemble. Default is the last axis.
+    backend: str
+        The name of the backend used for computations. Defaults to 'numba' if available, else 'numpy'.
+
+    Returns
+    -------
+    twcrps: ArrayLike
+        The twCRPS between the forecast ensemble and obs for the chosen chaining function.
+
+    Examples
+    --------
+    >>> from scoringrules import crps
+    >>> twcrps.ensemble(pred, obs)
+    """
+    return srb[backend].twcrps_ensemble(
+        forecasts,
+        observations,
+        v_func,
+        v_funcargs,
+        axis=axis,
+    )
+    
+
+def owcrps_ensemble(
+    forecasts: Array,
+    observations: ArrayLike,
+    /,
+    w_func: tp.Callable = lambda x, *args: np.ones_like(x),
+    w_funcargs: tuple = (),
+    *,
+    axis: int = -1,
+    backend: str = "numba",
+) -> Array:
+    r"""Estimate the Outcome-Weighted Continuous Ranked Probability Score (owCRPS) for a finite ensemble.
+    
+    Computation is performed using the ensemble representation of the owCRPS in
+    [Allen et al. (2022)](https://arxiv.org/abs/2202.12732):
+
+    $$ \mathrm{owCRPS}(F_{ens}, y) = \frac{1}{M \bar{w}} \sum_{m = 1}^{M} |x_{m} - y|w(x_{m})w(y) - \frac{1}{2 M^{2} \bar{w}^{2}} \sum_{m = 1}^{M} \sum_{j = 1}^{M} |x_{m} - x_{j}|w(x_{m})w(x_{j})w(y),$$
+
+    where $F_{ens}(x) = \sum_{m=1}^{M} 1\{ x_{m} \leq x \}/M$ is the empirical 
+    distribution function associated with an ensemble forecast $x_{1}, \dots, x_{M}$ with
+    $M$ members, $w$ is the chosen weight function, and $\bar{w} = \sum_{m=1}^{M}w(x_{m})/M$.
+
+    Parameters
+    ----------
+    forecasts: ArrayLike
+        The predicted forecast ensemble, where the ensemble dimension is by default
+        represented by the last axis.
+    observations: ArrayLike
+        The observed values.
+    w_func: tp.Callable
+        Weight function used to emphasise particular outcomes.
+    w_funcargs: tuple
+        Additional arguments to the weight function.
+    axis: int
+        The axis corresponding to the ensemble. Default is the last axis.
+    backend: str
+        The name of the backend used for computations. Defaults to 'numba' if available, else 'numpy'.
+
+    Returns
+    -------
+    owcrps: ArrayLike
+        The owCRPS between the forecast ensemble and obs for the chosen weight function.
+
+    Examples
+    --------
+    >>> from scoringrules import crps
+    >>> owcrps.ensemble(pred, obs)
+    """
+    return srb[backend].owcrps_ensemble(
+        forecasts,
+        observations,
+        w_func,
+        w_funcargs,
+        axis=axis,
+    )
+    
+    
+def vrcrps_ensemble(
+    forecasts: Array,
+    observations: ArrayLike,
+    /,
+    w_func: tp.Callable = lambda x, *args: np.ones_like(x),
+    w_funcargs: tuple = (),
+    *,
+    axis: int = -1,
+    backend: str = "numba",
+) -> Array:
+    r"""Estimate the Vertically Re-scaled Continuous Ranked Probability Score (vrCRPS) for a finite ensemble.
+
+    Computation is performed using the ensemble representation of the vrCRPS in
+    [Allen et al. (2022)](https://arxiv.org/abs/2202.12732):
+
+    \[
+    \begin{split}
+        \mathrm{vrCRPS}(F_{ens}, y) = & \frac{1}{M} \sum_{m = 1}^{M} |x_{m} - y|w(x_{m})w(y) - \frac{1}{2 M^{2}} \sum_{m = 1}^{M} \sum_{j = 1}^{M} |x_{m} - x_{j}|w(x_{m})w(x_{j}) \\
+            & + \left( \frac{1}{M} \sum_{m = 1}^{M} |x_{m}| w(x_{m}) - |y| w(y) \right) \left( \frac{1}{M} \sum_{m = 1}^{M} w(x_{m}) - w(y) \right),
+    \end{split}
+    \] 
+
+    where $F_{ens}(x) = \sum_{m=1}^{M} 1 \{ x_{m} \leq x \}/M$ is the empirical 
+    distribution function associated with an ensemble forecast $x_{1}, \dots, x_{M}$ with
+    $M$ members, $w$ is the chosen weight function, and $\bar{w} = \sum_{m=1}^{M}w(x_{m})/M$.
+
+    Parameters
+    ----------
+    forecasts: ArrayLike
+        The predicted forecast ensemble, where the ensemble dimension is by default
+        represented by the last axis.
+    observations: ArrayLike
+        The observed values.
+    w_func: tp.Callable
+        Weight function used to emphasise particular outcomes.
+    w_funcargs: tuple
+        Additional arguments to the weight function.
+    axis: int
+        The axis corresponding to the ensemble. Default is the last axis.
+    backend: str
+        The name of the backend used for computations. Defaults to 'numba' if available, else 'numpy'.
+
+    Returns
+    -------
+    vrcrps: ArrayLike
+        The vrCRPS between the forecast ensemble and obs for the chosen weight function.
+
+    Examples
+    --------
+    >>> from scoringrules import crps
+    >>> vrcrps.ensemble(pred, obs)
+    """
+    return srb[backend].vrcrps_ensemble(
+        forecasts,
+        observations,
+        w_func,
+        w_funcargs,
+        axis=axis,
+    )
+    
+    
+__all__ = [
+    "twcrps_ensemble",
+    "owcrps_ensemble",
+    "vrcrps_ensemble",
+]

scoringrules-0.3.0/scoringrules/_wenergy.py

@@ -0,0 +1,182 @@
+import typing as tp
+
+from scoringrules.backend import backends as srb
+from scoringrules.backend.arrayapi import Array
+
+ArrayLike = tp.TypeVar("ArrayLike", Array, float)
+
+
+def owenergy_score(
+    forecasts: Array,
+    observations: Array,
+    /,
+    w_func: tp.Callable = lambda x, *args: 1.0,
+    w_funcargs: tuple = (),
+    *,
+    m_axis: int = -2,
+    v_axis: int = -1,
+    backend="numba",
+) -> Array:
+    r"""Compute the Outcome-Weighted Energy Score (owES) for a finite multivariate ensemble.
+
+    Computation is performed using the ensemble representation of the owES in
+    [Allen et al. (2022)](https://arxiv.org/abs/2202.12732):
+
+    \[
+        \mathrm{owES}(F_{ens}, \mathbf{y}) = \frac{1}{M \bar{w}} \sum_{m = 1}^{M} \| \mathbf{x}_{m} - \mathbf{y} \| w(\mathbf{x}_{m}) w(\mathbf{y}) - \frac{1}{2 M^{2} \bar{w}^{2}} \sum_{m = 1}^{M} \sum_{j = 1}^{M} \| \mathbf{x}_{m} - \mathbf{x}_{j} \| w(\mathbf{x}_{m}) w(\mathbf{x}_{j}) w(\mathbf{y}),
+    \] 
+
+    where $F_{ens}$ is the ensemble forecast $\mathbf{x}_{1}, \dots, \mathbf{x}_{M}$ with
+    $M$ members, $\| \cdotp \|$ is the Euclidean distance, $w$ is the chosen weight function, 
+    and $\bar{w} = \sum_{m=1}^{M}w(\mathbf{x}_{m})/M$.
+
+
+    Parameters
+    ----------
+    forecasts: ArrayLike of shape (..., M, D)
+        The predicted forecast ensemble, where the ensemble dimension is by default
+        represented by the second last axis and the variables dimension by the last axis.
+    observations: ArrayLike of shape (...,D)
+        The observed values, where the variables dimension is by default the last axis.
+    w_func: tp.Callable
+        Weight function used to emphasise particular outcomes.
+    w_funcargs: tuple
+        Additional arguments to the weight function.
+    m_axis: int
+        The axis corresponding to the ensemble dimension. Defaults to -2.
+    v_axis: int or tuple(int)
+        The axis corresponding to the variables dimension. Defaults to -1.
+    backend: str
+        The name of the backend used for computations. Defaults to 'numba' if available, else 'numpy'.
+
+    Returns
+    -------
+    owenergy_score: ArrayLike of shape (...)
+        The computed Outcome-Weighted Energy Score.
+    """
+    return srb[backend].owenergy_score(
+        forecasts, 
+        observations, 
+        w_func, 
+        w_funcargs, 
+        m_axis=m_axis, 
+        v_axis=v_axis
+    )
+
+
+def twenergy_score(
+    forecasts: Array,
+    observations: Array,
+    /,
+    v_func: tp.Callable = lambda x, *args: x,
+    v_funcargs: tuple = (),
+    *,
+    m_axis: int = -2,
+    v_axis: int = -1,
+    backend="numba",
+) -> Array:
+    r"""Compute the Threshold-Weighted Energy Score (twES) for a finite multivariate ensemble.
+
+    Computation is performed using the ensemble representation of the twES in
+    [Allen et al. (2022)](https://arxiv.org/abs/2202.12732):
+
+    \[
+        \mathrm{twES}(F_{ens}, \mathbf{y}) = \frac{1}{M} \sum_{m = 1}^{M} \| v(\mathbf{x}_{m}) - v(\mathbf{y}) \| - \frac{1}{2 M^{2}} \sum_{m = 1}^{M} \sum_{j = 1}^{M} \| v(\mathbf{x}_{m}) - v(\mathbf{x}_{j}) \|,
+    \] 
+
+    where $F_{ens}$ is the ensemble forecast $\mathbf{x}_{1}, \dots, \mathbf{x}_{M}$ with
+    $M$ members, $\| \cdotp \|$ is the Euclidean distance, and $v$ is the chaining function 
+    used to target particular outcomes.
+
+
+    Parameters
+    ----------
+    forecasts: ArrayLike of shape (..., M, D)
+        The predicted forecast ensemble, where the ensemble dimension is by default
+        represented by the second last axis and the variables dimension by the last axis.
+    observations: ArrayLike of shape (...,D)
+        The observed values, where the variables dimension is by default the last axis.
+    v_func: tp.Callable
+        Chaining function used to emphasise particular outcomes.
+    v_funcargs: tuple
+        Additional arguments to the chaining function.
+    m_axis: int
+        The axis corresponding to the ensemble dimension. Defaults to -2.
+    v_axis: int or tuple(int)
+        The axis corresponding to the variables dimension. Defaults to -1.
+    backend: str
+        The name of the backend used for computations. Defaults to 'numba' if available, else 'numpy'.
+
+    Returns
+    -------
+    twenergy_score: ArrayLike of shape (...)
+        The computed Threshold-Weighted Energy Score.
+    """
+    return srb[backend].twenergy_score(
+        forecasts, 
+        observations, 
+        v_func, 
+        v_funcargs, 
+        m_axis=m_axis, 
+        v_axis=v_axis
+    )
+
+
+def vrenergy_score(
+    forecasts: Array,
+    observations: Array,
+    /,
+    w_func: tp.Callable = lambda x, *args: 1.0,
+    w_funcargs: tuple = (),
+    *,
+    m_axis: int = -2,
+    v_axis: int = -1,
+    backend="numba",
+) -> Array:
+    r"""Compute the Vertically Re-scaled Energy Score (vrES) for a finite multivariate ensemble.
+
+    Computation is performed using the ensemble representation of the twES in
+    [Allen et al. (2022)](https://arxiv.org/abs/2202.12732):
+
+    \[
+    \begin{split}
+        \mathrm{vrES}(F_{ens}, \mathbf{y}) = & \frac{1}{M} \sum_{m = 1}^{M} \| \mathbf{x}_{m} - \mathbf{y} \| w(\mathbf{x}_{m}) w(\mathbf{y}) - \frac{1}{2 M^{2}} \sum_{m = 1}^{M} \sum_{j = 1}^{M} \| \mathbf{x}_{m} - \mathbf{x}_{j} \| w(\mathbf{x}_{m}) w(\mathbf{x_{j}}) \\
+            & + \left( \frac{1}{M} \sum_{m = 1}^{M} \| \mathbf{x}_{m} \| w(\mathbf{x}_{m}) - \| \mathbf{y} \| w(\mathbf{y}) \right) \left( \frac{1}{M} \sum_{m = 1}^{M} w(\mathbf{x}_{m}) - w(\mathbf{y}) \right),
+    \end{split}
+    \] 
+
+    where $F_{ens}$ is the ensemble forecast $\mathbf{x}_{1}, \dots, \mathbf{x}_{M}$ with
+    $M$ members, and $v$ is the chaining function used to target particular outcomes.
+
+
+    Parameters
+    ----------
+    forecasts: ArrayLike of shape (..., M, D)
+        The predicted forecast ensemble, where the ensemble dimension is by default
+        represented by the second last axis and the variables dimension by the last axis.
+    observations: ArrayLike of shape (...,D)
+        The observed values, where the variables dimension is by default the last axis.
+    w_func: tp.Callable
+        Weight function used to emphasise particular outcomes.
+    w_funcargs: tuple
+        Additional arguments to the weight function.
+    m_axis: int
+        The axis corresponding to the ensemble dimension. Defaults to -2.
+    v_axis: int or tuple(int)
+        The axis corresponding to the variables dimension. Defaults to -1.
+    backend: str
+        The name of the backend used for computations. Defaults to 'numba' if available, else 'numpy'.
+
+    Returns
+    -------
+    vrenergy_score: ArrayLike of shape (...)
+        The computed Vertically Re-scaled Energy Score.
+    """
+    return srb[backend].vrenergy_score(
+        forecasts, 
+        observations, 
+        w_func, 
+        w_funcargs, 
+        m_axis=m_axis, 
+        v_axis=v_axis
+    )