Source code for pyrockfall.stats._func

from __future__ import annotations
import numpy as np

from numbers import Real
from typing import Protocol, runtime_checkable, TypeAlias, overload

from ._distribution import (
    Distribution,
    DistributionID,
    DistributionParameters,
)
from ._affine import Affine
from ._truncate import Truncate
from ._deterministic import Deterministic
from ._normal import Normal
from ._uniform import Uniform
from ._triangular import Triangular
from ._beta import Beta
from ._exponential import Exponential
from ._lognormal import Lognormal
from ._gamma import Gamma


# ===============================================================
# COERCE
# ===============================================================

[docs] @runtime_checkable class SupportsToDistribution(Protocol):
[docs] def to_distribution(self) -> "Distribution": ...
DistributionLike: TypeAlias = ( "Distribution | SupportsToDistribution | Real | np.floating | np.integer | float | int" ) @overload def asDistribution(value: "Distribution") -> "Distribution": ... @overload def asDistribution(value: SupportsToDistribution) -> "Distribution": ... @overload def asDistribution(value: Real) -> "Distribution": ... @overload def asDistribution(value: np.floating) -> "Distribution": ... @overload def asDistribution(value: np.integer) -> "Distribution": ... @overload def asDistribution(value: float) -> "Distribution": ... @overload def asDistribution(value: int) -> "Distribution": ...
[docs] def asDistribution(value): # runtime """Coerce a value into a Distribution instance. If `value` is already a Distribution, it is returned as-is. If `value` is a scalar (float or int), it is wrapped as a Deterministic. Args: value: A Distribution instance or a scalar. Returns: Distribution: The corresponding Distribution instance. """ # Already a Distribution if isinstance(value, Distribution): return value # Custom objects that declare a converter if isinstance(value, SupportsToDistribution): return value.to_distribution() # Numpy scalars (float64/int64/etc.) if isinstance(value, (np.floating, np.integer)): return Deterministic(float(value)) # Python numeric scalars (exclude bool) if isinstance(value, Real) and not isinstance(value, bool): return Deterministic(float(value)) if isinstance(value, (float, int)): return Deterministic(float(value)) raise TypeError(f"Cannot convert type {type(value)} to Distribution.")
# =============================================================== # FACTORY # ===============================================================
[docs] def makeDistribution(p: DistributionParameters) -> Distribution: """ Reconstruct a Distribution from generic parameters: p.id, p.loc, p.scale, p.rel_min, p.rel_max Then apply Affine (when needed) and Truncate to [a,b] if finite. """ did = int(p.id) a, b = p.a, p.b fin_a, fin_b = np.isfinite(a), np.isfinite(b) def _truncate_if_needed(rv: Distribution) -> Distribution: lo = a if fin_a else None hi = b if fin_b else None if lo is None and hi is None: return rv return Truncate(rv, lower=lo, upper=hi) # ---------------- Deterministic ---------------- if did == int(DistributionID.NONE): return Deterministic(p.loc) # ---------------- Normal ---------------- if did == int(DistributionID.NORMAL): if p.scale <= 0: return Deterministic(p.loc) base = Normal(mu=p.loc, sigma=p.scale) return _truncate_if_needed(base) # ---------------- Uniform ---------------- if did == int(DistributionID.UNIFORM): if not (fin_a and fin_b): raise ValueError("Uniform requires finite [a, b].") if not (a < b): raise ValueError("Uniform needs a < b.") # generic mapping: a,b are exactly (lower, upper) return Uniform(lower=a, upper=b) # ---------------- Triangular ---------------- if did == int(DistributionID.TRIANGULAR): if not (fin_a and fin_b): raise ValueError("Triangular requires finite [a, b].") if not (a < p.loc < b): raise ValueError("Triangular needs a < mode(loc) < b.") return Triangular(lower=a, mode=p.loc, upper=b) # ---------------- Beta ---------------- if did == int(DistributionID.BETA): # Natural support is [0,1]. If [a,b] != [0,1], we treat it as an affine map # y = s*x + t, with s=b-a, t=a; invert mean/std to base, then re-apply affine. if not (fin_a and fin_b) or not (a < b): raise ValueError("Beta requires finite interval [a, b] with a < b.") s = b - a t = a # Map generic loc/scale to the base on [0,1] loc0 = (p.loc - t) / s scale0 = p.scale / abs(s) if s != 0 else 0.0 if not (0.0 < loc0 < 1.0): raise ValueError("Beta: inferred base mean(loc0) must be in (0,1).") max_sd0 = np.sqrt(loc0 * (1.0 - loc0)) if not (0.0 < scale0 < max_sd0): raise ValueError("Beta: inferred base std(scale0) must be in (0, sqrt(loc0*(1-loc0))).") S = loc0 * (1.0 - loc0) / (scale0 * scale0) - 1.0 alpha = loc0 * S beta_ = (1.0 - loc0) * S base = Beta(alpha=alpha, beta=beta_) # The affine exactly restores [a,b], so truncation is not needed beyond that return Affine(base, scale=s, translate=t) # ---------------- Exponential ---------------- if did == int(DistributionID.EXPONENTIAL): # Your generic mapping: loc = 1/λ, scale = 0, rel_min = 1/λ, rel_max = +inf. if p.loc <= 0: raise ValueError("Exponential requires loc > 0 (loc = 1/λ).") lam = 1.0 / p.loc base = Exponential(lam=lam) # If bounds differ from natural [0, +inf), truncate accordingly. return _truncate_if_needed(base) # ---------------- Lognormal ---------------- if did == int(DistributionID.LOGNORMAL): # Your generic mapping uses mean (loc) and std (scale) of X. if p.loc <= 0 or p.scale < 0: raise ValueError("Lognormal requires loc > 0 and scale >= 0.") if p.scale == 0.0: return Deterministic(p.loc) sigma2 = np.log(1.0 + (p.scale * p.scale) / (p.loc * p.loc)) sigma = np.sqrt(sigma2) mu = np.log(p.loc) - 0.5 * sigma2 base = Lognormal(mu=mu, sigma=sigma) return _truncate_if_needed(base) # ---------------- Gamma ---------------- if did == int(DistributionID.GAMMA): # Your generic mapping uses mean (loc) and std (scale). if p.loc <= 0 or p.scale <= 0: raise ValueError("Gamma requires loc > 0 and scale > 0.") alpha = (p.loc / p.scale) ** 2 lam = p.loc / (p.scale * p.scale) base = Gamma(alpha=alpha, lam=lam) return _truncate_if_needed(base) raise ValueError(f"Unknown distribution id {p.id}")