Continuous distributions¶

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

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

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

    Returns a column with one variate per input row, in the distribution's element dtype
    (`Float64`, `UInt64` or `Boolean`). Output length follows the surrounding context (frame length
    under `select` / `with_columns`, partition length under `over` / `group_by`), and each row's draw
    is derived from a per-row sub-seed mixed from `seed` and the row's position, so the result is
    independent of Polars 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 (the fast path); with any column-valued
    parameter the name follows the first parameter expression (polars root-name semantics, so
    `.name.*` modifiers keep working).
    """
    if self._scalar_kwargs is not None:
        return register_plugin(
            f"{self._plugin_prefix}_sample_scalar",
            (ROW_INDEX_EXPR,),
            kwargs={"seed": seed, **self._scalar_kwargs},
        ).alias("sample")
    return register_plugin(
        f"{self._plugin_prefix}_sample", (*self._param_exprs, ROW_INDEX_EXPR), kwargs={"seed": seed}
    )

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

    Each row's `size` draws are consecutive values from one per-row random stream keyed by `seed` and the
    row's position, so the result is reproducible for a fixed `seed` and independent of Polars chunking and
    thread scheduling. `samples(size=1)` matches `sample` for the same seed, and growing `size` extends each
    row's array without changing the existing draws.

    A row with a null parameter yields a null array (not an array of null elements), produced natively by
    the plugin via the output's outer validity; an invalid parameterisation raises.

    Naming follows `sample`: `"samples"` with all-constant parameters, the first parameter
    expression's root name otherwise.
    """
    if size <= 0:
        msg = f"size must be a positive integer, got {size}"
        raise ValueError(msg)
    out = self._samples(size=size, seed=seed)
    return out.alias("samples") if self._scalar_kwargs is not None else out

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

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

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

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

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.
    """
    q = as_expr(quantile)
    return propagate_null_and_nan(q, self._ppf(q))

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`.
    """
    q = as_expr(quantile)
    return propagate_null_and_nan(q, self._isf(q))

@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(0.5)

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

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

    Returns a column with one variate per input row, in the distribution's element dtype
    (`Float64`, `UInt64` or `Boolean`). Output length follows the surrounding context (frame length
    under `select` / `with_columns`, partition length under `over` / `group_by`), and each row's draw
    is derived from a per-row sub-seed mixed from `seed` and the row's position, so the result is
    independent of Polars 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 (the fast path); with any column-valued
    parameter the name follows the first parameter expression (polars root-name semantics, so
    `.name.*` modifiers keep working).
    """
    if self._scalar_kwargs is not None:
        return register_plugin(
            f"{self._plugin_prefix}_sample_scalar",
            (ROW_INDEX_EXPR,),
            kwargs={"seed": seed, **self._scalar_kwargs},
        ).alias("sample")
    return register_plugin(
        f"{self._plugin_prefix}_sample", (*self._param_exprs, ROW_INDEX_EXPR), kwargs={"seed": seed}
    )

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

    Each row's `size` draws are consecutive values from one per-row random stream keyed by `seed` and the
    row's position, so the result is reproducible for a fixed `seed` and independent of Polars chunking and
    thread scheduling. `samples(size=1)` matches `sample` for the same seed, and growing `size` extends each
    row's array without changing the existing draws.

    A row with a null parameter yields a null array (not an array of null elements), produced natively by
    the plugin via the output's outer validity; an invalid parameterisation raises.

    Naming follows `sample`: `"samples"` with all-constant parameters, the first parameter
    expression's root name otherwise.
    """
    if size <= 0:
        msg = f"size must be a positive integer, got {size}"
        raise ValueError(msg)
    out = self._samples(size=size, seed=seed)
    return out.alias("samples") if self._scalar_kwargs is not None else out

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

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

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

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

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.
    """
    q = as_expr(quantile)
    return propagate_null_and_nan(q, self._ppf(q))

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`.
    """
    q = as_expr(quantile)
    return propagate_null_and_nan(q, self._isf(q))

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(0.5)

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

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

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)``."""
    # Unlike ``mean`` / ``variance`` there is no elementary closed form (log-Beta and digamma), so the
    # formula is evaluated by ``beta_entropy`` in Rust. For column parameters that runs once per row; for
    # scalar parameters it is computed **once** on length-1 inputs and broadcast to length-n behind the
    # ``_moment`` validity gate, so a constant's entropy is not re-evaluated on every row.
    if self._scalar_kwargs is None:
        return register_plugin("beta_entropy", (self._a, self._b))
    return self._moment(register_plugin("beta_entropy", self._scalar_lit_args()))

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

    Returns a column with one variate per input row, in the distribution's element dtype
    (`Float64`, `UInt64` or `Boolean`). Output length follows the surrounding context (frame length
    under `select` / `with_columns`, partition length under `over` / `group_by`), and each row's draw
    is derived from a per-row sub-seed mixed from `seed` and the row's position, so the result is
    independent of Polars 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 (the fast path); with any column-valued
    parameter the name follows the first parameter expression (polars root-name semantics, so
    `.name.*` modifiers keep working).
    """
    if self._scalar_kwargs is not None:
        return register_plugin(
            f"{self._plugin_prefix}_sample_scalar",
            (ROW_INDEX_EXPR,),
            kwargs={"seed": seed, **self._scalar_kwargs},
        ).alias("sample")
    return register_plugin(
        f"{self._plugin_prefix}_sample", (*self._param_exprs, ROW_INDEX_EXPR), kwargs={"seed": seed}
    )

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

    Each row's `size` draws are consecutive values from one per-row random stream keyed by `seed` and the
    row's position, so the result is reproducible for a fixed `seed` and independent of Polars chunking and
    thread scheduling. `samples(size=1)` matches `sample` for the same seed, and growing `size` extends each
    row's array without changing the existing draws.

    A row with a null parameter yields a null array (not an array of null elements), produced natively by
    the plugin via the output's outer validity; an invalid parameterisation raises.

    Naming follows `sample`: `"samples"` with all-constant parameters, the first parameter
    expression's root name otherwise.
    """
    if size <= 0:
        msg = f"size must be a positive integer, got {size}"
        raise ValueError(msg)
    out = self._samples(size=size, seed=seed)
    return out.alias("samples") if self._scalar_kwargs is not None else out

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

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

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

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

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.
    """
    q = as_expr(quantile)
    return propagate_null_and_nan(q, self._ppf(q))

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`.
    """
    q = as_expr(quantile)
    return propagate_null_and_nan(q, self._isf(q))

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

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

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

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

def std(self) -> pl.Expr:
    """Standard deviation, ``1 / rate``, the same expression as ``mean``.

    Overrides the base-class ``variance().sqrt()``, which squares the rate and then unsquares
    it: the round trip saturates about 300 decades before ``1 / rate`` does.
    """
    return 1 / self._checked_rate

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

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

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

    Returns a column with one variate per input row, in the distribution's element dtype
    (`Float64`, `UInt64` or `Boolean`). Output length follows the surrounding context (frame length
    under `select` / `with_columns`, partition length under `over` / `group_by`), and each row's draw
    is derived from a per-row sub-seed mixed from `seed` and the row's position, so the result is
    independent of Polars 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 (the fast path); with any column-valued
    parameter the name follows the first parameter expression (polars root-name semantics, so
    `.name.*` modifiers keep working).
    """
    if self._scalar_kwargs is not None:
        return register_plugin(
            f"{self._plugin_prefix}_sample_scalar",
            (ROW_INDEX_EXPR,),
            kwargs={"seed": seed, **self._scalar_kwargs},
        ).alias("sample")
    return register_plugin(
        f"{self._plugin_prefix}_sample", (*self._param_exprs, ROW_INDEX_EXPR), kwargs={"seed": seed}
    )

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

    Each row's `size` draws are consecutive values from one per-row random stream keyed by `seed` and the
    row's position, so the result is reproducible for a fixed `seed` and independent of Polars chunking and
    thread scheduling. `samples(size=1)` matches `sample` for the same seed, and growing `size` extends each
    row's array without changing the existing draws.

    A row with a null parameter yields a null array (not an array of null elements), produced natively by
    the plugin via the output's outer validity; an invalid parameterisation raises.

    Naming follows `sample`: `"samples"` with all-constant parameters, the first parameter
    expression's root name otherwise.
    """
    if size <= 0:
        msg = f"size must be a positive integer, got {size}"
        raise ValueError(msg)
    out = self._samples(size=size, seed=seed)
    return out.alias("samples") if self._scalar_kwargs is not None else out

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

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

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

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

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.
    """
    q = as_expr(quantile)
    return propagate_null_and_nan(q, self._ppf(q))

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`.
    """
    q = as_expr(quantile)
    return propagate_null_and_nan(q, self._isf(q))

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

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

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 is spelled ``2 * exp(t / 2) * sinh(t / 2)``, which is ``expm1(t)``
    identically. Polars has no ``expm1``, and the literal ``exp(t) - 1`` cancels for a small
    ``sigma``. The identity holds full precision on both sides and overflows no earlier than the
    result does.
    """
    half = self._half_sigma_sq
    return self._moment(2 * half.exp() * half.sinh() * (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)``.

    Overrides the base-class ``variance().sqrt()``, which inherits an overflow the square root
    would have undone: the variance genuinely exceeds ``f64`` above ``sigma ~ 18.8`` (so ``inf``
    is right *there*), but the standard deviation only does above ``sigma ~ 26.6``.

    Consequence worth knowing: ``std() ** 2`` and ``variance()`` are no longer interchangeable
    at a large ``sigma``, because one is representable and the other is not.
    """
    half = self._half_sigma_sq
    return self._moment((0.5 * (_LN_2 + half + half.sinh().log()) + self._mu + half).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 * (_TWO_PI_E * self._sigma**2).log())

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

    Returns a column with one variate per input row, in the distribution's element dtype
    (`Float64`, `UInt64` or `Boolean`). Output length follows the surrounding context (frame length
    under `select` / `with_columns`, partition length under `over` / `group_by`), and each row's draw
    is derived from a per-row sub-seed mixed from `seed` and the row's position, so the result is
    independent of Polars 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 (the fast path); with any column-valued
    parameter the name follows the first parameter expression (polars root-name semantics, so
    `.name.*` modifiers keep working).
    """
    if self._scalar_kwargs is not None:
        return register_plugin(
            f"{self._plugin_prefix}_sample_scalar",
            (ROW_INDEX_EXPR,),
            kwargs={"seed": seed, **self._scalar_kwargs},
        ).alias("sample")
    return register_plugin(
        f"{self._plugin_prefix}_sample", (*self._param_exprs, ROW_INDEX_EXPR), kwargs={"seed": seed}
    )

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

    Each row's `size` draws are consecutive values from one per-row random stream keyed by `seed` and the
    row's position, so the result is reproducible for a fixed `seed` and independent of Polars chunking and
    thread scheduling. `samples(size=1)` matches `sample` for the same seed, and growing `size` extends each
    row's array without changing the existing draws.

    A row with a null parameter yields a null array (not an array of null elements), produced natively by
    the plugin via the output's outer validity; an invalid parameterisation raises.

    Naming follows `sample`: `"samples"` with all-constant parameters, the first parameter
    expression's root name otherwise.
    """
    if size <= 0:
        msg = f"size must be a positive integer, got {size}"
        raise ValueError(msg)
    out = self._samples(size=size, seed=seed)
    return out.alias("samples") if self._scalar_kwargs is not None else out