mixle.stats.univariate.continuous.logistic module¶

Location-scale logistic distributions over real values.

Reference: Johnson, Kotz & Balakrishnan, Continuous Univariate Distributions (2nd ed., Wiley, 1994/95).

class LogisticDistribution(loc=0.0, scale=1.0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Logistic distribution with location loc and scale > 0.

Parameters:

loc (float)
scale (float)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Describe backend support for generated logistic kernels.

classmethod compute_declaration()[source]: Return the structured compute declaration for logistic distributions.

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

Return per-row Logistic sufficient statistics in accumulator order.

Parameters:

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

Return type:

tuple[Any, …]

density(x)[source]

Return the probability density or mass at a single observation.

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

log_density(x)[source]

Return the log-density or log-mass at a single observation.

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

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

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

static backend_log_density_from_params(x, loc, scale, engine)[source]

Engine-neutral logistic log-density from explicit parameters.

Parameters:

x (Any)
loc (Any)
scale (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]

Return stacked logistic parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[LogisticDistribution])
engine (Any)

Return type:

dict[str, Any]

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

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

Parameters:

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

Return type:

Any

cdf(x)[source]

Cumulative distribution function P(X <= x) (exact). The continuous ‘index of’ a value.

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

quantile(q)[source]

Inverse CDF F^{-1}(q): the value at cumulative-probability index q (continuous unranking).

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

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

entropy()[source]

Differential entropy log(scale) + 2.

Return type:: float

skewness()[source]

Skewness (0).

Return type:: float

kurtosis()[source]

Excess kurtosis (6/5).

Return type:: float

mode()[source]

Mode (= the location loc).

Return type:: float

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: LogisticDataEncoder

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

Bases: DistributionSampler

Draw iid logistic observations.

Parameters:

dist (LogisticDistribution)
seed (int | None)

sample(size=None, *, batched=True)[source]

Draw one sample or an array of iid samples.

Parameters:

size (int | None)
batched (bool)

Return type:

float | ndarray

class LogisticSuffStat(sum_, sum2_, count_, anchored=None)[source]

Bases: tuple

A (sum, sum2, count) sufficient statistic that also carries a shift-anchored side payload.

Behaves exactly like the plain 3-tuple everywhere it is indexed, unpacked, or iterated (it is one); anchored is the shift-anchored moment payload (anchor, sum_i w_i*(x_i - anchor), sum_i w_i*(x_i - anchor)^2) that LogisticAccumulator maintains alongside the raw moments so the M-step’s variance survives large-offset data. Code that doesn’t know about the payload (generic scale_suff_stat, engine kernels, …) sees an ordinary tuple and the estimate falls back to the historical raw path.

Parameters:

sum_ (float)
sum2_ (float)
count_ (float)
anchored (tuple[float, float, float] | None)

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

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted first and second moments for logistic estimation.

Alongside the raw (sum, sum2, count) the accumulator keeps a CONDITIONING-GATED shift-anchored moment track. The naive E[x^2]-E[x]^2 form the M-step needs loses ~2*log2(abs(mean)/sd) bits to cancellation, so data with sd ~0.99 at offset 1.7e9 fits a scale 12.6x too large with no warning. Anchoring at a data value keeps every term of the scatter O(count * spread^2), making the M-step variance shift-invariant.

The track is CONDITIONING-GATED: a chunk whose abs(mean)/spread ratio the raw form handles to ~1e-9 relative error (see _needs_anchor()) accumulates exactly the historical single-pass way – bit-identical statistics, no second pass – and the anchor activates only when a chunk (or a scalar update) would corrupt the variance. The raw moments remain the exchange format – (sum, sum2, count) is the declared StatisticSpec tuple consumed by engine kernels – so the anchored track rides along as a payload on LogisticSuffStat.

Parameters:

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

update(x, weight, estimate)[source]

Accumulate weighted first and second moments for one observation.

Parameters:

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

Return type:

None

initialize(x, weight, rng)[source]

Initialize statistics from one observation.

Parameters:

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

Return type:

None

seq_update(x, weights, estimate)[source]

Accumulate weighted first and second moments from encoded data.

Parameters:

x (ndarray)
weights (ndarray)
estimate (LogisticDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize statistics from encoded observations.

Parameters:

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

Return type:

None

combine(suff_stat)[source]

Merge another logistic sufficient-statistic tuple.

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

value()[source]

Return accumulated sum, second moment sum, and count.

The returned object is a plain 3-tuple for every consumer that treats it as one; once the shift-anchored moment track is live it is a LogisticSuffStat that additionally carries the anchored moments in its .anchored attribute, so combine() can fold them in and LogisticEstimator.estimate() can compute a shift-invariant variance.

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

from_value(x)[source]

Replace accumulator contents from a sufficient-statistic tuple.

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

scale(c)[source]

Scale the accumulated statistics in place by c, anchored track included.

The structural default round-trips through value() and from_value(), and scale_suff_stat rebuilds the payload as a PLAIN tuple – which drops the anchored attribute, so from_value sees raw-only statistics and restarts the track unactivated. Uniform weight scaling is exactly linear in both anchored moments and leaves the anchor (a data value, not a statistic) alone, so the track scales as the raw moments do.

The moment arithmetic lives in scale_anchored_triple; this method is pure attribute wiring, and its body is byte-identical to the Logistic/Gaussian sibling accumulator’s – flagged by the duplicate-body scanner and accepted in the manifest deliberately, because de-duplicating the wiring itself would mean a mixin coupling both classes’ private attribute names, a bigger structural change than the release stage warrants for zero remaining bug-risk (the shared math is what could drift; this cannot).

Parameters:: c (float)
Return type:: LogisticAccumulator

acc_to_encoder()[source]

Return the encoder used by this accumulator.

Return type:: LogisticDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for LogisticAccumulator.

Parameters:

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

make()[source]

Create a fresh logistic accumulator.

Return type:: LogisticAccumulator

class LogisticEstimator(pseudo_count=None, suff_stat=None, min_scale=1.0e-8, name=None, keys=None)[source]

Bases: ParameterEstimator

Moment estimator for logistic location and scale.

The likelihood MLE has no closed-form M-step. The EM estimator uses the identities mean=loc and var=pi^2 scale^2 / 3; torch gradient MLE can refine both parameters when exact likelihood optimization is desired.

The variance moment is formed from shift-anchored statistics whenever the accumulated sufficient statistics carry that payload (see LogisticAccumulator), which makes the fit shift-equivariant: estimating on x + c returns loc + c with scale unchanged. With a plain raw tuple – statistics the conditioning gate never needed to anchor, or ones restored from an older serialization – the historical raw path is used, bit-identically.

Parameters:

pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_scale (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for logistic moment statistics.

Return type:: LogisticAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate location and scale from weighted moments.

Parameters:

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

Return type:

LogisticDistribution

class LogisticDataEncoder[source]

Bases: DataSequenceEncoder

Encode logistic observations as a float array.

seq_encode(x)[source]

Encode observations as a floating-point array.

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