mixle.stats.univariate.continuous.rician module¶

Rician (Rice) distribution – the envelope of a sinusoid in additive Gaussian noise.

The amplitude X = sqrt((nu + sigma Z1)^2 + (sigma Z2)^2) of a 2-D Gaussian offset from the origin by nu (the line-of-sight / signal component), Z1, Z2 ~ N(0, 1). Models fading envelopes with a dominant path (wireless/radar/sonar), MRI magnitude noise, and wind speed. With nu >= 0 and scale sigma > 0,

f(x; nu, sigma) = (x / sigma^2) exp(-(x^2 + nu^2) / (2 sigma^2)) I0(x nu / sigma^2), x > 0,

where I0 is the modified Bessel function (evaluated stably via the exponentially scaled ive). At nu = 0 it reduces to the Rayleigh; for large nu/sigma it approaches a Gaussian. It samples exactly from the 2-D Gaussian envelope and has a closed-form method-of-moments fit from the second and fourth moments: sigma^2 = (m2 - sqrt(2 m2^2 - m4))/2 and nu^2 = m2 - 2 sigma^2.

Reference: Rice, “Mathematical analysis of random noise”, Bell System Tech. J. (1944/1945).

class RicianDistribution(nu, sigma, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Rician distribution with non-centrality nu >= 0 and scale sigma > 0.

Parameters:

nu (float)
sigma (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability density at x.

Parameters:: x (float)
Return type:: float

log_density(x)[source]

Return the log-density at x (-inf for x <= 0).

Parameters:: x (float)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-density for a sequence-encoded array of observations.

Parameters:: x (ndarray)
Return type:: ndarray

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

static backend_legacy_sufficient_statistics(x, params, engine)[source]

Per-row Rician power sums in accumulator order (count, sum x^2, sum x^4).

Parameters:

x (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static backend_log_density_from_params(x, nu, sigma, engine)[source]

Engine-neutral Rician log-density (-inf for x <= 0).

Parameters:

x (Any)
nu (Any)
sigma (Any)
engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Stacked Rician parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[RicianDistribution])
engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Rician log densities.

Parameters:

x (ndarray)
params (dict[str, Any])
engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Stacked Rician power sums (count, sum x^2, sum x^4) using engine-resident arrays.

Parameters:

x (ndarray)
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, Any, Any]

cdf(x)[source]

Cumulative distribution function P(X <= x) (Marcum-Q, via scipy rice).

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) (via scipy rice).

Parameters:: q (float)
Return type:: float

mean()[source]

Mean sigma sqrt(pi/2) L_{1/2}(-nu^2/(2 sigma^2)) (stable via the scaled Bessel ive).

Return type:: float

variance()[source]

Variance E[X^2] - mean^2 with E[X^2] = nu^2 + 2 sigma^2.

Return type:: float

sampler(seed=None)[source]

Return a sampler (the envelope of a 2-D Gaussian offset by nu).

Parameters:: seed (int | None)
Return type:: RicianSampler

estimator(pseudo_count=None)[source]

Return a closed-form method-of-moments estimator.

Parameters:: pseudo_count (float | None)
Return type:: RicianEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution (the raw value).

Return type:: RicianDataEncoder

class RicianSampler(dist, seed=None)[source]

Bases: DistributionSampler

Draw X = sqrt((nu + sigma Z1)^2 + (sigma Z2)^2) for Z1, Z2 ~ N(0, 1).

Parameters:

dist (RicianDistribution)
seed (int | None)

sample(size=None)[source]

Draw observations.

Combinator samplers (mixture/sequence/…) accept batched. With batched=True (the default) each child stream is drawn in one vectorized call instead of a per-draw Python loop – far faster. Because every child sampler owns an independent RandomState, batching consumes each stream in the same order as the loop, so the draws are identical to the legacy path. batched=False forces that legacy per-draw loop as a guaranteed- stable reference. Leaf samplers are already vectorized and ignore the flag.

Parameters:: size (int | None)
Return type:: float | ndarray

class RicianAccumulator(name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate the weighted power sums (count, sum x^2, sum x^4) for the moment fit.

Parameters:

name (str | None)
keys (str | None)

update(x, weight, estimate)[source]

Parameters:

x (float)
weight (float)
estimate (RicianDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]

Parameters:

x (float)
weight (float)
rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)[source]

Parameters:

x (ndarray)
weights (ndarray)
estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)[source]

Parameters:

x (ndarray)
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Parameters:: suff_stat (tuple[float, float, float])
Return type:: RicianAccumulator

value()[source]

Return type:: tuple[float, float, float]

from_value(x)[source]

Parameters:: x (tuple[float, float, float])
Return type:: RicianAccumulator

key_merge(stats_dict)[source]

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

key_replace(stats_dict)[source]

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:: stats_dict (dict[str, Any])
Return type:: None

acc_to_encoder()[source]

Return type:: RicianDataEncoder

class RicianAccumulatorFactory(name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for RicianAccumulator.

Parameters:

name (str | None)
keys (str | None)

make()[source]

Return type:: RicianAccumulator

class RicianEstimator(name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator from E[X^2] and E[X^4] (closed-form quadratic in sigma^2).

Parameters:

name (str | None)
keys (str | None)

accumulator_factory()[source]

Return type:: RicianAccumulatorFactory

estimate(nobs, suff_stat)[source]

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

RicianDistribution

class RicianDataEncoder[source]

Bases: DataSequenceEncoder

Encode observations as a float array.

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

Parameters:: x (Sequence[float])
Return type:: ndarray