Continuous distributions¶

def pdf(self, value: float | IntoExprColumn) -> pl.Expr:
    """Probability density function evaluated at `value`. Nulls and NaNs in `value` are propagated."""
    return self._pdf(as_expr(value))

def log_pdf(self, value: float | IntoExprColumn) -> pl.Expr:
    """Natural logarithm of the pdf. Nulls and NaNs in `value` are propagated."""
    return self._log_pdf(as_expr(value))

def sample(self, seed: int | None = None) -> pl.Expr:
    """Draw one random variate per row.

    Output length follows the surrounding context (frame length under `select` / `with_columns`,
    partition length under `over` / `group_by`). Each row's draw derives from a sub-seed mixed from
    `seed` and the row's position, so the result is independent of chunking and thread scheduling.

    A row with an invalid parameter raises; a row with a null parameter yields null. The output is
    named `"sample"` when every parameter is constant; otherwise it follows the first parameter
    expression (polars root-name semantics, so `.name.*` modifiers keep working).
    """
    return self._draw("sample", seed=_checked_seed(seed))

def samples(self, size: int, seed: int | None = None) -> pl.Expr:
    """Draw `size` random variates per row, as `Array(inner=<element dtype>, shape=size)`.

    Each row's draws are consecutive values from one per-row stream keyed by `seed` and the row's
    position, so `samples(size=1)` matches `sample` for the same seed and growing `size` extends
    each row's array without changing the existing draws. A null-parameter row yields a null array
    (outer validity), an invalid parameterisation raises. Named like `sample`, as `"samples"`.
    """
    return self._draw("samples", size=_checked_size(size), seed=_checked_seed(seed))

def cdf(self, value: float | IntoExprColumn) -> pl.Expr:
    """Cumulative distribution function, `P(X <= value)`. Nulls and NaNs in `value` are propagated."""
    return self._cdf(as_expr(value))

def log_cdf(self, value: float | IntoExprColumn) -> pl.Expr:
    """Natural logarithm of the cdf. Nulls and NaNs in `value` are propagated."""
    return self._log_cdf(as_expr(value))

def sf(self, value: float | IntoExprColumn) -> pl.Expr:
    """Survival function, `P(X > value) = 1 - cdf(value)`. Nulls and NaNs in `value` are propagated."""
    return self._sf(as_expr(value))

def log_sf(self, value: float | IntoExprColumn) -> pl.Expr:
    """Natural logarithm of the survival function. Nulls and NaNs in `value` are propagated."""
    return self._log_sf(as_expr(value))

def ppf(self, quantile: float | IntoExprColumn) -> pl.Expr:
    """Percent point function (inverse cdf).

    A `quantile` outside `[0, 1]` yields **null**. Nulls are propagated and a `NaN` quantile yields
    `NaN`, matching scipy.
    """
    return self._ppf(as_expr(quantile))

def isf(self, quantile: float | IntoExprColumn) -> pl.Expr:
    """Inverse survival function, the value `x` with `sf(x) == quantile`.

    Same domain contract as `ppf`, with the endpoints reversed: `quantile` outside `[0, 1]` yields
    null, nulls propagate, `NaN` yields `NaN`.
    """
    return self._isf(as_expr(quantile))

@abstractmethod
def mean(self) -> pl.Expr:
    """Expected value `E[X]`."""

@abstractmethod
def variance(self) -> pl.Expr:
    """Variance `Var[X] = E[(X - E[X])^2]`."""

def std(self) -> pl.Expr:
    """Standard deviation, `sqrt(variance)`."""
    return self.variance().sqrt()

def median(self) -> pl.Expr:
    """Median, `ppf(0.5)`."""
    return self._ppf(as_expr(0.5))

@abstractmethod
def entropy(self) -> pl.Expr:
    """Differential or Shannon entropy, in nats."""

def mean(self) -> pl.Expr:
    """Expected value, ``a / (a + b)``."""
    return self._moment(self._a / (self._a + self._b))

def variance(self) -> pl.Expr:
    """Variance, ``a * b / ((a + b)^2 * (a + b + 1))``."""
    return self._moment(self._a * self._b / ((self._a + self._b) ** 2 * (self._a + self._b + 1)))

def entropy(self) -> pl.Expr:
    """Differential entropy in nats, ``ln B(a, b) - (a - 1) psi(a) - (b - 1) psi(b) + (a + b - 2) psi(a + b)``.

    Log-Beta and digamma have no elementary closed form, so ``beta_entropy`` evaluates it in Rust.
    """
    return self._param_plugin("entropy")

def mean(self) -> pl.Expr:
    """Undefined, so **null** on every valid row; an invalid ``scale`` still raises."""
    return self._moment(_UNDEFINED_MOMENT)

def variance(self) -> pl.Expr:
    """Undefined, so **null** on every valid row; an invalid ``scale`` still raises."""
    return self._moment(_UNDEFINED_MOMENT)

def median(self) -> pl.Expr:
    """Median, ``loc``."""
    return self._moment(self._loc)

def entropy(self) -> pl.Expr:
    """Differential entropy, ``log(4 * pi * scale)``."""
    return self._moment(_LOG_FOUR_PI + self._scale.log())

def mean(self) -> pl.Expr:
    """Expected value, ``1 / rate``."""
    return 1 / self._validated_params

def variance(self) -> pl.Expr:
    """Variance, ``1 / rate**2``."""
    return 1 / self._validated_params**2

def std(self) -> pl.Expr:
    """Standard deviation, ``1 / rate``.

    Not ``variance().sqrt()``: squaring and unsquaring the rate saturates about 300 decades earlier.
    """
    return 1 / self._validated_params

def median(self) -> pl.Expr:
    """Median, ``log(2) / rate``."""
    return math.log(2) / self._validated_params

def entropy(self) -> pl.Expr:
    """Differential entropy, ``1 - log(rate)``."""
    return 1 - self._validated_params.log()

def mean(self) -> pl.Expr:
    """Expected value, ``exp(mu + sigma ** 2 / 2)``."""
    return self._moment((self._mu + self._half_sigma_sq).exp())

def variance(self) -> pl.Expr:
    """Variance, ``(exp(sigma ** 2) - 1) * exp(2 * mu + sigma ** 2)``.

    The leading factor goes through `expm1`: the literal ``exp(sigma ** 2) - 1`` cancels for a small
    ``sigma``. No cut-over is needed, the argument is positive.
    """
    return self._moment(expm1(self._sigma**2) * (2 * self._mu + self._sigma**2).exp())

def std(self) -> pl.Expr:
    """Standard deviation, ``exp(0.5 * log(exp(sigma ** 2) - 1) + mu + sigma ** 2 / 2)``.

    Not ``variance().sqrt()``: the variance overflows ``f64`` above ``sigma ~ 18.8`` (so ``inf`` is right
    *there*), the standard deviation only above ``sigma ~ 26.6``. ``std() ** 2`` and ``variance()`` are
    therefore not interchangeable at a large ``sigma``.
    """
    return self._moment((0.5 * log_abs_expm1(self._sigma**2) + self._mu + self._half_sigma_sq).exp())

def median(self) -> pl.Expr:
    """Median, ``exp(mu)``."""
    return self._moment(self._mu.exp())

def entropy(self) -> pl.Expr:
    """Differential entropy, ``mu + 0.5 * log(2 * pi * e * sigma ** 2)``."""
    return self._moment(self._mu + 0.5 * (math.tau * math.e * self._sigma**2).log())

def mean(self) -> pl.Expr:
    """Expected value, ``mu``."""
    return self._moment(self._mu)

def variance(self) -> pl.Expr:
    """Variance, ``sigma ** 2``."""
    return self._moment(self._sigma**2)

def std(self) -> pl.Expr:
    """Standard deviation, ``sigma``.

    Not ``variance().sqrt()``: squaring and unsquaring ``sigma`` saturates across roughly 300 decades.
    """
    return self._moment(self._sigma)

def median(self) -> pl.Expr:
    """Median, ``mu``."""
    return self._moment(self._mu)

def entropy(self) -> pl.Expr:
    """Differential entropy, ``0.5 * log(2 * pi * e * sigma ** 2)``."""
    return self._moment(0.5 * (math.tau * math.e * self._sigma**2).log())

def mean(self) -> pl.Expr:
    """Expected value, ``shape * scale / (shape - 1)`` for ``shape > 1``, else ``+inf``."""
    finite = self._scale * (self._shape / (self._shape - 1))
    return self._moment(pl.when(self._shape > _MEAN_DIVERGES_AT).then(finite).otherwise(math.inf))

def variance(self) -> pl.Expr:
    """Variance, ``scale**2 * shape / ((shape - 1)**2 * (shape - 2))`` for ``shape > 2``, else ``+inf``."""
    finite = (self._scale / (self._shape - 1)) ** 2 * (self._shape / (self._shape - 2))
    return self._moment(pl.when(self._shape > _VARIANCE_DIVERGES_AT).then(finite).otherwise(math.inf))

def std(self) -> pl.Expr:
    """Standard deviation, ``scale / (shape - 1) * sqrt(shape / (shape - 2))`` for ``shape > 2``, else ``+inf``.

    Not ``variance().sqrt()``: squaring and unsquaring the scale saturates about 300 decades earlier.
    """
    finite = self._scale / (self._shape - 1) * (self._shape / (self._shape - 2)).sqrt()
    return self._moment(pl.when(self._shape > _VARIANCE_DIVERGES_AT).then(finite).otherwise(math.inf))

def entropy(self) -> pl.Expr:
    """Differential entropy, ``log(scale / shape) + 1 / shape + 1``.

    Summed as ``log(scale) - log(shape)``: the ratio over- and underflows where neither log does.
    """
    return self._moment(self._scale.log() - self._shape.log() + 1 / self._shape + 1)

def mean(self) -> pl.Expr:
    """Expected value, ``(min + max) / 2``."""
    return self._min + self.range / 2

def variance(self) -> pl.Expr:
    """Variance, ``(max - min)^2 / 12``."""
    return self.range**2 * ONE_TWELFTH

def std(self) -> pl.Expr:
    """Standard deviation, ``(max - min) / sqrt(12)``.

    Not ``variance().sqrt()``: squaring and unsquaring the span saturates about 300 decades earlier.
    """
    return self.range / math.sqrt(12)

def median(self) -> pl.Expr:
    """Median, ``(min + max) / 2``."""
    return self._min + self.range / 2

def entropy(self) -> pl.Expr:
    """Differential entropy, ``log(max - min)``."""
    return self.range.log()

def mean(self) -> pl.Expr:
    """Expected value, ``scale * Gamma(1 + 1 / shape)``."""
    return self._param_plugin("mean")

def variance(self) -> pl.Expr:
    """Variance, ``scale**2 * (Gamma(1 + 2 / shape) - Gamma(1 + 1 / shape)**2)``.

    Squared from ``std()``, which saturates about 300 decades later than the gamma function does.
    """
    return self._param_plugin("variance")

def std(self) -> pl.Expr:
    """Standard deviation, ``scale * sqrt(Gamma(1 + 2 / shape) - Gamma(1 + 1 / shape)**2)``."""
    return self._param_plugin("std")

def entropy(self) -> pl.Expr:
    """Differential entropy, ``euler_gamma * (1 - 1 / shape) + log(scale / shape) + 1``.

    Summed as ``log(scale) - log(shape)``: the ratio over- and underflows where neither log does.
    """
    return self._moment(_EULER_GAMMA * (1 - 1 / self._shape) + self._scale.log() - self._shape.log() + 1)