Distribution Showcase¶

bossanova distributions are rich objects that visualize themselves, support algebra, and answer probability queries — all from a single import.

Visual Representation¶

Creating a distribution and displaying it renders an inline PDF (or PMF) plot:

d = normal(0, 1)
d

Moments & Properties¶

Every distribution exposes its moments and quantile-based summaries:

print(f"Mean:     {d.mean:.4f}")
print(f"Std dev:  {d.std:.4f}")
print(f"Variance: {d.var:.4f}")
print(f"Median:   {d.median:.4f}")
print(f"95% CI:   {d.interval(0.95)}")

Mean:     0.0000
Std dev:  1.0000
Variance: 1.0000
Median:   0.0000
95% CI:   (-1.959963984540054, 1.959963984540054)

Probability Queries¶

Use comparison operators and named methods for tail and interval probabilities:

d > 1.96        # P(X > 1.96)

d.between(-1, 1)   # P(-1 < X < 1)

d.outside(-1.96, 1.96)  # P(|X| > 1.96)

Distribution Algebra¶

Scalar operations and convolution produce new distributions:

shifted = d + 5          # shift mean
scaled  = d * 2          # scale
conv    = d + normal(3, 2)  # convolution → Normal(3, √5)
conv

Truncation¶

Restrict the support of any distribution:

import numpy as np

half_normal = d.truncate(0, np.inf)
half_normal

Hypothesis Testing¶

Evaluate observed statistics against a reference distribution:

d.p_value(2.3, tail="two")

d.critical(alpha=0.05, tail="two")

(-1.9599639845400545, 1.959963984540054)

d.reject(2.3, alpha=0.05, tail="two")

True

Discrete Distributions¶

Discrete distributions display PMF bar charts:

pois = poisson(rate=3)
pois

binom = binomial(n=10, p=0.3)
binom

bossanova.distributions¶

Distribution factories for simulation and probability queries.

Users get rich Distribution objects with plotting, algebra, and probability::

d = normal(0, 1)
d               # In notebooks: renders PDF plot
d + normal(3, 2)  # Convolution -> Normal(3, sqrt(5))
d > 1.96        # P(X > 1.96) = 0.025
d.pdf(0)        # 0.3989

Functions:

Name	Description
`beta`	Beta distribution.
`binomial`	Create a binomial distribution.
`categorical`	Create a categorical distribution.
`chi2`	Chi-squared distribution.
`exponential`	Exponential distribution (rate parameterization).
`f_dist`	F distribution.
`gamma`	Create a gamma distribution (scale parameterization only).
`normal`	Normal (Gaussian) distribution.
`poisson`	Create a Poisson distribution.
`t`	Student’s t distribution (location-scale parameterization).
`t_dist`	Student’s t distribution.
`uniform`	Uniform distribution.

Functions¶

beta¶

beta(a: float, b: float) -> Distribution

Beta distribution.

Parameters:

Name	Type	Description	Default
`a`	`float`	Shape parameter alpha (must be positive).	required
`b`	`float`	Shape parameter beta (must be positive).	required

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

d = beta(a=2, b=5)
d.mean
# 0.285...

binomial¶

binomial(n: int = 1, p: float = 0.5) -> Distribution

Create a binomial distribution.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of trials. Must be >= 1. Default is 1 (Bernoulli).	`1`
`p`	`float`	Probability of success. Must be in [0, 1]. Default is 0.5.	`0.5`

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

dist = binomial()              # Bernoulli(0.5)
dist = binomial(n=10, p=0.3)   # Binomial(10, 0.3), mean = 3

categorical¶

categorical(levels: list[str] | None = None, *, p: list[float] | None = None, k: int | None = None) -> Categorical

Create a categorical distribution.

Parameters:

Name	Type	Description	Default
`levels`	`list[str] \| None`	Category names. Either provide explicit levels or use k= for auto-naming (level_1, level_2, ...). Mutually exclusive with k.	`None`
`p`	`list[float] \| None`	Probabilities for each level. Must sum to 1. Length must match levels. If None, a uniform distribution over levels is used. Requires levels to be specified.	`None`
`k`	`int \| None`	Number of levels for auto-naming (level_1, level_2, ...). Mutually exclusive with levels.	`None`

Returns:

Type	Description
`Categorical`	Categorical distribution object.

Examples:

categorical(["A", "B", "C"])
# Categorical(levels=('A', 'B', 'C'), p=None, k=None)

categorical(["A", "B"], p=[0.7, 0.3])
# Categorical(levels=('A', 'B'), p=(0.7, 0.3), k=None)

categorical(k=4)  # level_1, level_2, level_3, level_4
# Categorical(levels=None, p=None, k=4)

chi2¶

chi2(df: float) -> Distribution

Chi-squared distribution.

Parameters:

Name	Type	Description	Default
`df`	`float`	Degrees of freedom (must be positive).	required

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

c = chi2(df=5)
c.ppf(0.95)  # Critical value
# 11.07...

exponential¶

exponential(rate: float = 1.0) -> Distribution

Exponential distribution (rate parameterization).

Parameters:

Name	Type	Description	Default
`rate`	`float`	Rate parameter lambda (must be positive). Mean = 1/rate. Default 1.0.	`1.0`

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

d = exponential(rate=0.5)
d.mean
# 2.0

f_dist¶

f_dist(df1: float, df2: float) -> Distribution

F distribution.

Parameters:

Name	Type	Description	Default
`df1`	`float`	Numerator degrees of freedom (must be positive).	required
`df2`	`float`	Denominator degrees of freedom (must be positive).	required

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

f = f_dist(df1=5, df2=20)
f.ppf(0.95)  # Critical value
# 2.71...

gamma¶

gamma(shape: float, scale: float = 1.0) -> Distribution

Create a gamma distribution (scale parameterization only).

Parameters:

Name	Type	Description	Default
`shape`	`float`	Shape parameter (must be positive).	required
`scale`	`float`	Scale parameter (must be positive). Default is 1.0.	`1.0`

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

g = gamma(shape=2.0)  # Gamma(2, 1), mean = 2
g = gamma(shape=2.0, scale=0.5)  # Gamma(2, 0.5), mean = 1

normal¶

normal(mean: float = 0, sd: float = 1) -> Distribution

Normal (Gaussian) distribution.

Parameters:

Name	Type	Description	Default
`mean`	`float`	Mean of the distribution. Default 0.	`0`
`sd`	`float`	Standard deviation (must be positive). Default 1.	`1`

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

d = normal()  # Standard normal: mean=0, sd=1
d = normal(mean=100, sd=15)
d.cdf(115)  # P(X <= 115)
# 0.8413...

poisson¶

poisson(rate: float = 1.0) -> Distribution

Create a Poisson distribution.

Parameters:

Name	Type	Description	Default
`rate`	`float`	Rate parameter (lambda). Must be > 0. Default is 1.0.	`1.0`

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

dist = poisson()           # Poisson(1)
dist = poisson(rate=5.0)   # Poisson(5), mean = 5

t¶

t(df: float, loc: float = 0.0, scale: float = 1.0) -> Distribution

Student’s t distribution (location-scale parameterization).

Student’s t-distribution using loc/scale parameter names (scipy convention), as an alternative to t_dist() which uses mean/sd naming.

Parameters:

Name	Type	Description	Default
`df`	`float`	Degrees of freedom (must be positive).	required
`loc`	`float`	Location parameter. Default 0.0.	`0.0`
`scale`	`float`	Scale parameter (must be positive). Default 1.0.	`1.0`

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

d = t(df=10)
d.ppf(0.975)  # Critical value for 95% CI

t_dist¶

t_dist(df: float, mean: float = 0, sd: float = 1) -> Distribution

Student’s t distribution.

Parameters:

Name	Type	Description	Default
`df`	`float`	Degrees of freedom (must be positive).	required
`mean`	`float`	Location parameter. Default 0.	`0`
`sd`	`float`	Scale parameter (must be positive). Default 1.	`1`

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

t = t_dist(df=29)
t.ppf(0.975)  # Critical value for 95% CI
# 2.045...

uniform¶

uniform(low: float = 0, high: float = 1) -> Distribution

Uniform distribution.

Parameters:

Name	Type	Description	Default
`low`	`float`	Lower bound. Default 0.	`0`
`high`	`float`	Upper bound (must be > low). Default 1.	`1`

Returns:

Type	Description
`Distribution`	Distribution object.

Examples:

d = uniform(low=0, high=10)
d.mean
# 5.0