distributions

Probability distributions with expressive algebra and automatic visualization.

This package wraps scipy.stats distributions to provide:

• User-friendly parameterization (mean/sd instead of loc/scale)

• Automatic plotting in Jupyter notebooks via repr_html()

• Algebraic composition: affine transforms, convolution, truncation

• Probability queries: comparison operators returning rich Probability objects

• Hypothesis testing helpers: p-values, critical values, rejection decisions

Distribution Algebra¶

Distributions support algebraic operations::

d = 2 * normal(5, 1) + 3  # Affine transform → Normal(13, 2)
z = normal() + normal()   # Sum of RVs → Normal(0, √2)
p = normal() > 1.96       # Probability query → P(X > 1.96) = 0.025

Probability Queries¶

Comparison operators return rich Probability objects::

d = normal(100, 15)
d > 130              # P(X > 130) = 0.0228
d.between(85, 115)   # P(85 ≤ X ≤ 115) = 0.6827

Fluent API¶

Chain transformations for readable code::

normal(100, 15).standardize()  # → Normal(0, 1)
normal().truncate(0, inf)      # Half-normal

Hypothesis Testing¶

Built-in methods for common testing tasks::

t = t_dist(df=29)
t.p_value(2.3, tail="two")     # → P(|X| > 2.3) = 0.0285
t.critical(alpha=0.05)         # → (-2.045, 2.045)
t.reject(2.3, alpha=0.05)      # → True

Available Distributions¶

Continuous: normal, t_dist, chi2, f_dist, beta, exponential, gamma, uniform Discrete: binomial, poisson

See Also¶

api/distributions : Tutorial with comprehensive examples

Classes:

Functions:

Modules:

Classes¶

ConvolvedDistribution¶

ConvolvedDistribution(dist1: Distribution, dist2: Distribution, n_samples: int = MC_SAMPLES) -> None

Bases: Distribution

Distribution representing the sum of two independent random variables.

Uses Monte Carlo simulation for CDF/PPF computations when no closed-form solution is available.

Parameters:

Functions:

Attributes:

Attributes¶

iqr¶

iqr: float

Interquartile range (Q3 - Q1).

is_discrete¶

is_discrete: bool

Whether this is a discrete distribution.

mean¶

mean: float

Mean of sum: E[X] + E[Y].

median¶

median: float

Median estimated from samples.

name¶

name: str

Distribution name.

params¶

params: dict[str, float]

Distribution parameters.

q1¶

q1: float

First quartile (25th percentile).

q3¶

q3: float

Third quartile (75th percentile).

std¶

std: float

Standard deviation of sum.

var¶

var: float

Variance of sum (independent): Var[X] + Var[Y].

Functions¶

abs¶

abs() -> FoldedDistribution

Absolute value distribution: |X|.

Returns:

Examples:

d = normal().abs()  # Half-normal (folded at 0)
d.mean  # Approximately 0.798

add_distribution¶

add_distribution(other: Distribution) -> Distribution

Add two independent random variables: X + Y.

Uses closed-form solutions when available, otherwise falls back to simulation-backed ConvolvedDistribution.

Parameters:

Returns:

affine_transform¶

affine_transform(scale: float, shift: float) -> Distribution

Apply affine transformation: scale*X + shift.

Dispatches to closed-form solutions for location-scale families, otherwise returns TransformedDistribution.

Parameters:

Returns:

between¶

between(low: float, high: float) -> Probability

P(low <= X <= high) - probability within an interval.

Parameters:

Returns:

Examples:

d = normal(100, 15)
d.between(85, 115)
# P(85 <= X <= 115) = 0.6827

cdf¶

cdf(x: ArrayLike) -> np.ndarray

CDF estimated from empirical distribution.

Parameters:

Returns:

compute_x_range¶

compute_x_range() -> tuple[float, float]

Compute sensible x-range for plotting.

Returns:

critical¶

critical(alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> float | tuple[float, float]

Compute critical value(s) for hypothesis testing.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.critical(alpha=0.05, tail="two")
# (-2.045, 2.045)

get_samples¶

get_samples() -> np.ndarray

Get or generate cached samples.

Returns:

interval¶

interval(confidence: float = 0.95) -> tuple[float, float]

Central confidence interval containing given probability mass.

Parameters:

Returns:

lik¶

lik(data: ArrayLike) -> float

Compute likelihood of data under this distribution.

Warning: For numerical stability, prefer loglik() for inference.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.lik([0])
# 0.3989...

loglik¶

loglik(data: ArrayLike) -> float

Compute log-likelihood of data under this distribution.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.loglik([0, 0.5, -0.5])
# -3.112...

make_prob¶

make_prob(value: float, expr: str) -> Probability

Helper to create Probability with distribution context.

Parameters:

Returns:

outside¶

outside(low: float, high: float) -> Probability

P(X < low or X > high) - probability outside an interval.

Parameters:

Returns:

Examples:

d = normal()
d.outside(-1.96, 1.96)
# P(X < -1.96 or X > 1.96) = 0.05

p¶

p(q: float) -> float

Quantile function alias for ppf.

Parameters:

Returns:

Examples:

d = normal()
d.p(0.975)  # Same as d.ppf(0.975)
# 1.96

p_value¶

p_value(x: float, tail: Literal['two', 'left', 'right'] = 'two') -> Probability

Compute p-value for observed statistic.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.p_value(2.3, tail="two")
# P(|X| > 2.3) = 0.0285

parse_shade_region¶

parse_shade_region(shade_region: tuple[float, float] | str | None) -> tuple[float, float] | None

Parse shade_region argument to actual bounds.

Parameters:

Returns:

pdf¶

pdf(x: ArrayLike) -> np.ndarray

PDF estimated via kernel density estimation.

Parameters:

Returns:

plot¶

plot(*, ax: Axes | None = None, shade_region: tuple[float, float] | str | None = None, shade_direction: Literal['between', 'outside', 'left', 'right'] = 'between', shade_alpha: float = 0.3, shade_color: str | None = None, show_mean: bool = False, show_median: bool = False, x_range: tuple[float, float] | None = None, figsize: tuple[float, float] = (6, 4), color: str | None = None, title: str | None = None) -> Figure

Plot the distribution.

Parameters:

Returns:

pmf¶

pmf(x: ArrayLike) -> np.ndarray

PMF estimated from sample frequencies.

Parameters:

Returns:

ppf¶

ppf(q: ArrayLike) -> np.ndarray

PPF (quantile function) estimated from samples.

Parameters:

Returns:

prob¶

prob(x: ArrayLike) -> np.ndarray

Unified probability function (pdf or pmf based on type).

Parameters:

Returns:

reject¶

reject(x: float, alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> bool

Determine if null hypothesis should be rejected.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.reject(2.3, alpha=0.05)
# True

rvs¶

rvs(size: int | tuple[int, ...] = 1, seed: int | np.random.Generator | None = None) -> np.ndarray

Generate random samples from convolved distribution.

Parameters:

Returns:

sample¶

sample(n: int, rng: np.random.Generator) -> np.ndarray

Generate n random samples using a numpy Generator.

Compatible with the simulation Distribution protocol, allowing internal Distribution objects to be used in model.simulate().

Parameters:

Returns:

scale¶

scale(factor: float) -> Distribution

Scale distribution by multiplying by factor.

Parameters:

Returns:

Examples:

d = normal(0, 1).scale(2)
d.std
# 2.0

sf¶

sf(x: ArrayLike) -> np.ndarray

Survival function.

Parameters:

Returns:

shift¶

shift(delta: float) -> Distribution

Shift distribution by adding delta to all values.

Parameters:

Returns:

Examples:

d = normal(0, 1).shift(5)
d.mean
# 5.0

standardize¶

standardize() -> Distribution

Standardize to mean=0, sd=1.

Returns:

Examples:

d = normal(100, 15).standardize()
d.mean
# 0.0
d.std
# 1.0

truncate¶

truncate(low: float = float('-inf'), high: float = float('inf')) -> TruncatedDistribution

Truncate distribution to an interval.

Parameters:

Returns:

Examples:

d = normal().truncate(0, np.inf)  # Half-normal
d.mean  # Approximately 0.798

Distribution¶

Distribution(dist: rv_frozen, name: str, params: dict[str, float]) -> None

Bases: DistributionPlotMixin, DistributionAlgebraMixin

Wrapper for scipy.stats distributions with visualization.

Provides a unified interface for probability distributions with:

• Probability functions (pdf/pmf, cdf, ppf)

• Random sampling (rvs)

• Moments (mean, var, std)

• Visualization with shading support

• Automatic notebook rendering

• Algebraic composition (affine transforms, convolution, truncation)

• Probability queries via comparison operators

• Hypothesis testing helpers

Parameters:

Examples:

# Use factory functions instead of direct instantiation
from distributions import normal, t_dist
d = normal(mean=0, sd=1)
d.cdf(1.96)  # 0.975
d.ppf(0.975)  # 1.96

Functions:

Attributes:

Attributes¶

iqr¶

iqr: float

Interquartile range (Q3 - Q1).

is_discrete¶

is_discrete: bool

Whether this is a discrete distribution.

mean¶

mean: float

Distribution mean (expected value).

median¶

median: float

Distribution median.

name¶

name: str

Distribution name.

params¶

params: dict[str, float]

Distribution parameters.

q1¶

q1: float

First quartile (25th percentile).

q3¶

q3: float

Third quartile (75th percentile).

std¶

std: float

Distribution standard deviation.

var¶

var: float

Distribution variance.

Functions¶

abs¶

abs() -> FoldedDistribution

Absolute value distribution: |X|.

Returns:

Examples:

d = normal().abs()  # Half-normal (folded at 0)
d.mean  # Approximately 0.798

add_distribution¶

add_distribution(other: Distribution) -> Distribution

Add two independent random variables: X + Y.

Uses closed-form solutions when available, otherwise falls back to simulation-backed ConvolvedDistribution.

Parameters:

Returns:

affine_transform¶

affine_transform(scale: float, shift: float) -> Distribution

Apply affine transformation: scale*X + shift.

Dispatches to closed-form solutions for location-scale families, otherwise returns TransformedDistribution.

Parameters:

Returns:

between¶

between(low: float, high: float) -> Probability

P(low <= X <= high) - probability within an interval.

Parameters:

Returns:

Examples:

d = normal(100, 15)
d.between(85, 115)
# P(85 <= X <= 115) = 0.6827

cdf¶

cdf(x: ArrayLike) -> np.ndarray

Cumulative distribution function.

Parameters:

Returns:

compute_x_range¶

compute_x_range() -> tuple[float, float]

Compute sensible x-range for plotting.

Returns:

critical¶

critical(alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> float | tuple[float, float]

Compute critical value(s) for hypothesis testing.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.critical(alpha=0.05, tail="two")
# (-2.045, 2.045)

interval¶

interval(confidence: float = 0.95) -> tuple[float, float]

Central confidence interval containing given probability mass.

Parameters:

Returns:

lik¶

lik(data: ArrayLike) -> float

Compute likelihood of data under this distribution.

Warning: For numerical stability, prefer loglik() for inference.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.lik([0])
# 0.3989...

loglik¶

loglik(data: ArrayLike) -> float

Compute log-likelihood of data under this distribution.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.loglik([0, 0.5, -0.5])
# -3.112...

make_prob¶

make_prob(value: float, expr: str) -> Probability

Helper to create Probability with distribution context.

Parameters:

Returns:

outside¶

outside(low: float, high: float) -> Probability

P(X < low or X > high) - probability outside an interval.

Parameters:

Returns:

Examples:

d = normal()
d.outside(-1.96, 1.96)
# P(X < -1.96 or X > 1.96) = 0.05

p¶

p(q: float) -> float

Quantile function alias for ppf.

Parameters:

Returns:

Examples:

d = normal()
d.p(0.975)  # Same as d.ppf(0.975)
# 1.96

p_value¶

p_value(x: float, tail: Literal['two', 'left', 'right'] = 'two') -> Probability

Compute p-value for observed statistic.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.p_value(2.3, tail="two")
# P(|X| > 2.3) = 0.0285

parse_shade_region¶

parse_shade_region(shade_region: tuple[float, float] | str | None) -> tuple[float, float] | None

Parse shade_region argument to actual bounds.

Parameters:

Returns:

pdf¶

pdf(x: ArrayLike) -> np.ndarray

Probability density function (continuous distributions only).

Parameters:

Returns:

plot¶

plot(*, ax: Axes | None = None, shade_region: tuple[float, float] | str | None = None, shade_direction: Literal['between', 'outside', 'left', 'right'] = 'between', shade_alpha: float = 0.3, shade_color: str | None = None, show_mean: bool = False, show_median: bool = False, x_range: tuple[float, float] | None = None, figsize: tuple[float, float] = (6, 4), color: str | None = None, title: str | None = None) -> Figure

Plot the distribution.

Parameters:

Returns:

pmf¶

pmf(x: ArrayLike) -> np.ndarray

Probability mass function (discrete distributions only).

Parameters:

Returns:

ppf¶

ppf(q: ArrayLike) -> np.ndarray

Percent point function (inverse CDF / quantile function).

Parameters:

Returns:

prob¶

prob(x: ArrayLike) -> np.ndarray

Unified probability function (pdf or pmf based on type).

Parameters:

Returns:

reject¶

reject(x: float, alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> bool

Determine if null hypothesis should be rejected.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.reject(2.3, alpha=0.05)
# True

rvs¶

rvs(size: int | tuple[int, ...] = 1, seed: int | np.random.Generator | None = None) -> np.ndarray

Generate random variates.

Parameters:

Returns:

sample¶

sample(n: int, rng: np.random.Generator) -> np.ndarray

Generate n random samples using a numpy Generator.

Compatible with the simulation Distribution protocol, allowing internal Distribution objects to be used in model.simulate().

Parameters:

Returns:

scale¶

scale(factor: float) -> Distribution

Scale distribution by multiplying by factor.

Parameters:

Returns:

Examples:

d = normal(0, 1).scale(2)
d.std
# 2.0

sf¶

sf(x: ArrayLike) -> np.ndarray

Survival function (1 - CDF).

Parameters:

Returns:

shift¶

shift(delta: float) -> Distribution

Shift distribution by adding delta to all values.

Parameters:

Returns:

Examples:

d = normal(0, 1).shift(5)
d.mean
# 5.0

standardize¶

standardize() -> Distribution

Standardize to mean=0, sd=1.

Returns:

Examples:

d = normal(100, 15).standardize()
d.mean
# 0.0
d.std
# 1.0

truncate¶

truncate(low: float = float('-inf'), high: float = float('inf')) -> TruncatedDistribution

Truncate distribution to an interval.

Parameters:

Returns:

Examples:

d = normal().truncate(0, np.inf)  # Half-normal
d.mean  # Approximately 0.798

FoldedDistribution¶

FoldedDistribution(base: Distribution, n_samples: int = MC_SAMPLES) -> None

Bases: Distribution

Distribution of |X| - the absolute value of X.

Uses simulation for CDF/PPF computations.

Parameters:

Functions:

Attributes:

Attributes¶

iqr¶

iqr: float

Interquartile range (Q3 - Q1).

is_discrete¶

is_discrete: bool

Whether this is a discrete distribution.

mean¶

mean: float

Mean of folded distribution.

median¶

median: float

Median of folded distribution.

name¶

name: str

Distribution name.

params¶

params: dict[str, float]

Distribution parameters.

q1¶

q1: float

First quartile (25th percentile).

q3¶

q3: float

Third quartile (75th percentile).

std¶

std: float

Standard deviation of folded distribution.

var¶

var: float

Variance of folded distribution.

Functions¶

abs¶

abs() -> FoldedDistribution

Absolute value distribution: |X|.

Returns:

Examples:

d = normal().abs()  # Half-normal (folded at 0)
d.mean  # Approximately 0.798

add_distribution¶

add_distribution(other: Distribution) -> Distribution

Add two independent random variables: X + Y.

Uses closed-form solutions when available, otherwise falls back to simulation-backed ConvolvedDistribution.

Parameters:

Returns:

affine_transform¶

affine_transform(scale: float, shift: float) -> Distribution

Apply affine transformation: scale*X + shift.

Dispatches to closed-form solutions for location-scale families, otherwise returns TransformedDistribution.

Parameters:

Returns:

between¶

between(low: float, high: float) -> Probability

P(low <= X <= high) - probability within an interval.

Parameters:

Returns:

Examples:

d = normal(100, 15)
d.between(85, 115)
# P(85 <= X <= 115) = 0.6827

cdf¶

cdf(x: ArrayLike) -> np.ndarray

CDF of folded distribution.

Parameters:

Returns:

compute_x_range¶

compute_x_range() -> tuple[float, float]

Compute sensible x-range for plotting.

Returns:

critical¶

critical(alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> float | tuple[float, float]

Compute critical value(s) for hypothesis testing.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.critical(alpha=0.05, tail="two")
# (-2.045, 2.045)

get_samples¶

get_samples() -> np.ndarray

Get or generate cached samples.

Returns:

interval¶

interval(confidence: float = 0.95) -> tuple[float, float]

Central confidence interval containing given probability mass.

Parameters:

Returns:

lik¶

lik(data: ArrayLike) -> float

Compute likelihood of data under this distribution.

Warning: For numerical stability, prefer loglik() for inference.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.lik([0])
# 0.3989...

loglik¶

loglik(data: ArrayLike) -> float

Compute log-likelihood of data under this distribution.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.loglik([0, 0.5, -0.5])
# -3.112...

make_prob¶

make_prob(value: float, expr: str) -> Probability

Helper to create Probability with distribution context.

Parameters:

Returns:

outside¶

outside(low: float, high: float) -> Probability

P(X < low or X > high) - probability outside an interval.

Parameters:

Returns:

Examples:

d = normal()
d.outside(-1.96, 1.96)
# P(X < -1.96 or X > 1.96) = 0.05

p¶

p(q: float) -> float

Quantile function alias for ppf.

Parameters:

Returns:

Examples:

d = normal()
d.p(0.975)  # Same as d.ppf(0.975)
# 1.96

p_value¶

p_value(x: float, tail: Literal['two', 'left', 'right'] = 'two') -> Probability

Compute p-value for observed statistic.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.p_value(2.3, tail="two")
# P(|X| > 2.3) = 0.0285

parse_shade_region¶

parse_shade_region(shade_region: tuple[float, float] | str | None) -> tuple[float, float] | None

Parse shade_region argument to actual bounds.

Parameters:

Returns:

pdf¶

pdf(x: ArrayLike) -> np.ndarray

PDF of folded distribution: f_|X|(y) = f_X(y) + f_X(-y) for y >= 0.

Parameters:

Returns:

plot¶

plot(*, ax: Axes | None = None, shade_region: tuple[float, float] | str | None = None, shade_direction: Literal['between', 'outside', 'left', 'right'] = 'between', shade_alpha: float = 0.3, shade_color: str | None = None, show_mean: bool = False, show_median: bool = False, x_range: tuple[float, float] | None = None, figsize: tuple[float, float] = (6, 4), color: str | None = None, title: str | None = None) -> Figure

Plot the distribution.

Parameters:

Returns:

pmf¶

pmf(x: ArrayLike) -> np.ndarray

PMF of folded distribution.

Parameters:

Returns:

ppf¶

ppf(q: ArrayLike) -> np.ndarray

PPF of folded distribution.

Parameters:

Returns:

prob¶

prob(x: ArrayLike) -> np.ndarray

Unified probability function (pdf or pmf based on type).

Parameters:

Returns:

reject¶

reject(x: float, alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> bool

Determine if null hypothesis should be rejected.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.reject(2.3, alpha=0.05)
# True

rvs¶

rvs(size: int | tuple[int, ...] = 1, seed: int | np.random.Generator | None = None) -> np.ndarray

Generate random samples from folded distribution.

Parameters:

Returns:

sample¶

sample(n: int, rng: np.random.Generator) -> np.ndarray

Generate n random samples using a numpy Generator.

Compatible with the simulation Distribution protocol, allowing internal Distribution objects to be used in model.simulate().

Parameters:

Returns:

scale¶

scale(factor: float) -> Distribution

Scale distribution by multiplying by factor.

Parameters:

Returns:

Examples:

d = normal(0, 1).scale(2)
d.std
# 2.0

sf¶

sf(x: ArrayLike) -> np.ndarray

Survival function of folded distribution.

Parameters:

Returns:

shift¶

shift(delta: float) -> Distribution

Shift distribution by adding delta to all values.

Parameters:

Returns:

Examples:

d = normal(0, 1).shift(5)
d.mean
# 5.0

standardize¶

standardize() -> Distribution

Standardize to mean=0, sd=1.

Returns:

Examples:

d = normal(100, 15).standardize()
d.mean
# 0.0
d.std
# 1.0

truncate¶

truncate(low: float = float('-inf'), high: float = float('inf')) -> TruncatedDistribution

Truncate distribution to an interval.

Parameters:

Returns:

Examples:

d = normal().truncate(0, np.inf)  # Half-normal
d.mean  # Approximately 0.798

Probability¶

Probability(value: float, expr: str, dist_name: str) -> None

Rich probability result from distribution queries.

Returned by comparison operators on distributions (e.g., normal() > 1.96). Behaves like a float for numeric operations while providing descriptive display.

Parameters:

Examples:

d = normal()
p = d > 1.96
p
# P(X > 1.96) = 0.025
float(p)
# 0.025
p < 0.05  # threshold check
# True

Attributes:

Attributes¶

dist_name¶

dist_name: str

expr¶

expr: str

value¶

value: float

TransformedDistribution¶

TransformedDistribution(base: Distribution, scale: float, shift: float) -> None

Bases: Distribution

Distribution resulting from an affine transformation: Y = scale*X + shift.

Used when closed-form parameters aren’t available. Delegates to the base distribution with appropriate transformations applied.

Parameters:

Functions:

Attributes:

Attributes¶

iqr¶

iqr: float

Interquartile range (Q3 - Q1).

is_discrete¶

is_discrete: bool

Whether this is a discrete distribution.

mean¶

mean: float

Transformed mean: scale * E[X] + shift.

median¶

median: float

Transformed median: scale * median[X] + shift.

name¶

name: str

Distribution name.

params¶

params: dict[str, float]

Distribution parameters.

q1¶

q1: float

First quartile (25th percentile).

q3¶

q3: float

Third quartile (75th percentile).

std¶

std: float

Transformed standard deviation: |scale| * SD[X].

var¶

var: float

Transformed variance: scale^2 * Var[X].

Functions¶

abs¶

abs() -> FoldedDistribution

Absolute value distribution: |X|.

Returns:

Examples:

d = normal().abs()  # Half-normal (folded at 0)
d.mean  # Approximately 0.798

add_distribution¶

add_distribution(other: Distribution) -> Distribution

Add two independent random variables: X + Y.

Uses closed-form solutions when available, otherwise falls back to simulation-backed ConvolvedDistribution.

Parameters:

Returns:

affine_transform¶

affine_transform(scale: float, shift: float) -> Distribution

Apply affine transformation: scale*X + shift.

Dispatches to closed-form solutions for location-scale families, otherwise returns TransformedDistribution.

Parameters:

Returns:

between¶

between(low: float, high: float) -> Probability

P(low <= X <= high) - probability within an interval.

Parameters:

Returns:

Examples:

d = normal(100, 15)
d.between(85, 115)
# P(85 <= X <= 115) = 0.6827

cdf¶

cdf(x: ArrayLike) -> np.ndarray

CDF of transformed distribution.

Parameters:

Returns:

compute_x_range¶

compute_x_range() -> tuple[float, float]

Compute sensible x-range for plotting.

Returns:

critical¶

critical(alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> float | tuple[float, float]

Compute critical value(s) for hypothesis testing.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.critical(alpha=0.05, tail="two")
# (-2.045, 2.045)

interval¶

interval(confidence: float = 0.95) -> tuple[float, float]

Central confidence interval containing given probability mass.

Parameters:

Returns:

lik¶

lik(data: ArrayLike) -> float

Compute likelihood of data under this distribution.

Warning: For numerical stability, prefer loglik() for inference.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.lik([0])
# 0.3989...

loglik¶

loglik(data: ArrayLike) -> float

Compute log-likelihood of data under this distribution.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.loglik([0, 0.5, -0.5])
# -3.112...

make_prob¶

make_prob(value: float, expr: str) -> Probability

Helper to create Probability with distribution context.

Parameters:

Returns:

outside¶

outside(low: float, high: float) -> Probability

P(X < low or X > high) - probability outside an interval.

Parameters:

Returns:

Examples:

d = normal()
d.outside(-1.96, 1.96)
# P(X < -1.96 or X > 1.96) = 0.05

p¶

p(q: float) -> float

Quantile function alias for ppf.

Parameters:

Returns:

Examples:

d = normal()
d.p(0.975)  # Same as d.ppf(0.975)
# 1.96

p_value¶

p_value(x: float, tail: Literal['two', 'left', 'right'] = 'two') -> Probability

Compute p-value for observed statistic.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.p_value(2.3, tail="two")
# P(|X| > 2.3) = 0.0285

parse_shade_region¶

parse_shade_region(shade_region: tuple[float, float] | str | None) -> tuple[float, float] | None

Parse shade_region argument to actual bounds.

Parameters:

Returns:

pdf¶

pdf(x: ArrayLike) -> np.ndarray

PDF of transformed distribution.

Parameters:

Returns:

plot¶

plot(*, ax: Axes | None = None, shade_region: tuple[float, float] | str | None = None, shade_direction: Literal['between', 'outside', 'left', 'right'] = 'between', shade_alpha: float = 0.3, shade_color: str | None = None, show_mean: bool = False, show_median: bool = False, x_range: tuple[float, float] | None = None, figsize: tuple[float, float] = (6, 4), color: str | None = None, title: str | None = None) -> Figure

Plot the distribution.

Parameters:

Returns:

pmf¶

pmf(x: ArrayLike) -> np.ndarray

PMF of transformed distribution.

Parameters:

Returns:

ppf¶

ppf(q: ArrayLike) -> np.ndarray

PPF of transformed distribution.

Parameters:

Returns:

prob¶

prob(x: ArrayLike) -> np.ndarray

Unified probability function (pdf or pmf based on type).

Parameters:

Returns:

reject¶

reject(x: float, alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> bool

Determine if null hypothesis should be rejected.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.reject(2.3, alpha=0.05)
# True

rvs¶

rvs(size: int | tuple[int, ...] = 1, seed: int | np.random.Generator | None = None) -> np.ndarray

Generate random samples from transformed distribution.

Parameters:

Returns:

sample¶

sample(n: int, rng: np.random.Generator) -> np.ndarray

Generate n random samples using a numpy Generator.

Compatible with the simulation Distribution protocol, allowing internal Distribution objects to be used in model.simulate().

Parameters:

Returns:

scale¶

scale(factor: float) -> Distribution

Scale distribution by multiplying by factor.

Parameters:

Returns:

Examples:

d = normal(0, 1).scale(2)
d.std
# 2.0

sf¶

sf(x: ArrayLike) -> np.ndarray

Survival function of transformed distribution.

Parameters:

Returns:

shift¶

shift(delta: float) -> Distribution

Shift distribution by adding delta to all values.

Parameters:

Returns:

Examples:

d = normal(0, 1).shift(5)
d.mean
# 5.0

standardize¶

standardize() -> Distribution

Standardize to mean=0, sd=1.

Returns:

Examples:

d = normal(100, 15).standardize()
d.mean
# 0.0
d.std
# 1.0

truncate¶

truncate(low: float = float('-inf'), high: float = float('inf')) -> TruncatedDistribution

Truncate distribution to an interval.

Parameters:

Returns:

Examples:

d = normal().truncate(0, np.inf)  # Half-normal
d.mean  # Approximately 0.798

TruncatedDistribution¶

TruncatedDistribution(base: Distribution, low: float = float('-inf'), high: float = float('inf')) -> None

Bases: Distribution

Distribution truncated to an interval [low, high].

The PDF is normalized to integrate to 1 over the truncation region.

Note: Truncation is exact for Normal bases. For other distributions, the truncated normal approximation is used, which may not match the true truncated distribution.

Parameters:

Functions:

Attributes:

Attributes¶

iqr¶

iqr: float

Interquartile range (Q3 - Q1).

is_discrete¶

is_discrete: bool

Whether this is a discrete distribution.

mean¶

mean: float

Mean of truncated distribution.

median¶

median: float

Median of truncated distribution.

name¶

name: str

Distribution name.

params¶

params: dict[str, float]

Distribution parameters.

q1¶

q1: float

First quartile (25th percentile).

q3¶

q3: float

Third quartile (75th percentile).

std¶

std: float

Standard deviation of truncated distribution.

var¶

var: float

Variance of truncated distribution.

Functions¶

abs¶

abs() -> FoldedDistribution

Absolute value distribution: |X|.

Returns:

Examples:

d = normal().abs()  # Half-normal (folded at 0)
d.mean  # Approximately 0.798

add_distribution¶

add_distribution(other: Distribution) -> Distribution

Add two independent random variables: X + Y.

Uses closed-form solutions when available, otherwise falls back to simulation-backed ConvolvedDistribution.

Parameters:

Returns:

affine_transform¶

affine_transform(scale: float, shift: float) -> Distribution

Apply affine transformation: scale*X + shift.

Dispatches to closed-form solutions for location-scale families, otherwise returns TransformedDistribution.

Parameters:

Returns:

between¶

between(low: float, high: float) -> Probability

P(low <= X <= high) - probability within an interval.

Parameters:

Returns:

Examples:

d = normal(100, 15)
d.between(85, 115)
# P(85 <= X <= 115) = 0.6827

cdf¶

cdf(x: ArrayLike) -> np.ndarray

CDF of truncated distribution.

Parameters:

Returns:

compute_x_range¶

compute_x_range() -> tuple[float, float]

Compute sensible x-range for plotting.

Returns:

critical¶

critical(alpha: float = 0.05, tail: Literal['two', 'left', 'right'] = 'two') -> float | tuple[float, float]

Compute critical value(s) for hypothesis testing.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.critical(alpha=0.05, tail="two")
# (-2.045, 2.045)

interval¶

interval(confidence: float = 0.95) -> tuple[float, float]

Central confidence interval containing given probability mass.

Parameters:

Returns:

lik¶

lik(data: ArrayLike) -> float

Compute likelihood of data under this distribution.

Warning: For numerical stability, prefer loglik() for inference.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.lik([0])
# 0.3989...

loglik¶

loglik(data: ArrayLike) -> float

Compute log-likelihood of data under this distribution.

Parameters:

Returns:

Examples:

d = normal(0, 1)
d.loglik([0, 0.5, -0.5])
# -3.112...

make_prob¶

make_prob(value: float, expr: str) -> Probability

Helper to create Probability with distribution context.

Parameters:

Returns:

outside¶

outside(low: float, high: float) -> Probability

P(X < low or X > high) - probability outside an interval.

Parameters:

Returns:

Examples:

d = normal()
d.outside(-1.96, 1.96)
# P(X < -1.96 or X > 1.96) = 0.05

p¶

p(q: float) -> float

Quantile function alias for ppf.

Parameters:

Returns:

Examples:

d = normal()
d.p(0.975)  # Same as d.ppf(0.975)
# 1.96

p_value¶

p_value(x: float, tail: Literal['two', 'left', 'right'] = 'two') -> Probability

Compute p-value for observed statistic.

Parameters:

Returns:

Examples:

t = t_dist(df=29)
t.p_value(2.3, tail="two")
# P(|X| > 2.3) = 0.0285

parse_shade_region¶

parse_shade_region(shade_region: tuple[float, float] | str | None) -> tuple[float, float] | None

Parse shade_region argument to actual bounds.

Parameters:

Returns:

pdf¶

pdf(x: ArrayLike) -> np.ndarray

PDF of truncated distribution.

Parameters:

Returns:

plot¶

plot(*, ax: Axes | None = None, shade_region: tuple[float, float] | str | None = None, shade_direction: Literal['between', 'outside', 'left', 'right'] = 'between', shade_alpha: float = 0.3, shade_color: str | None = None, show_mean: bool = False, show_median: bool = False, x_range: tuple[float, float] | None = None, figsize: tuple[float, float] = (6, 4), color: str | None = None, title: str | None = None) -> Figure

Plot the distribution.

Parameters: