deep_causality_stats 0.2.5

Descriptive and information statistics over slices, generic in the scalar.
Documentation

deep_causality_stats

Crates.io Docs.rs MIT licensed

Summary

Descriptive and information statistics and the shaped distributions for the DeepCausality project, over slices, generic in the scalar. The crate owns Shannon entropy and its conditional form, the log-sum-exp reduction, the moments, covariance, Pearson correlation, ridge and logistic regression, the Gaussian log-density, two binning strategies, and the distributions (normal, exponential, Cauchy, Weibull, log-normal, Poisson, Bernoulli, categorical) with their inverse CDFs. It depends on deep_causality_num, deep_causality_algebra, deep_causality_linear and deep_causality_rand, and on nothing else. It re-exports the generator traits of deep_causality_rand by name, so a caller that draws from a distribution needs no second dependency.

One crate holds one implementation of each statistic, so two call sites cannot disagree about what it computes.

Surface

Information entropy, conditional_entropy, log_sum_exp, log_add_exp
Descriptive mean, variance, std_dev, pearson, pearson_pairwise_complete
Regression fit_ridge, fit_ridge_streaming, fit_logistic, sigmoid
Density gaussian_log_density
Binning bin_equal_width, bin_equal_frequency
Distributions Normal, Exponential, Cauchy, Weibull, LogNormal, Poisson, Bernoulli, Categorical

Anything with axes (marginalising a joint distribution, reducing a tensor) belongs with the container that has them. This crate sits below those containers so they can delegate to it without a cycle; its surface is over slices.

Precision as a parameter

Functions are generic over their scalar under the algebra tower's bounds, with the exceptions listed here.

Four public functions name a concrete float:

  • standard_normal_inverse_cdf_at::<R>(u: f64) takes the unit coordinate as f64, because it is a position on [0, 1) and rounding it into a narrow scalar before the transform is destructive at the endpoints. The result is in R.
  • standard_normal_inverse_cdf (f64) and standard_normal_inverse_cdf_f106 (Float106) are the same transform at one fixed precision each.
  • bernoulli_inverse_cdf(u: f64, p: f64) compares two f64 values.

Three generic paths pass through f64 internally:

  • Bernoulli::new lowers p to f64 and quantises it to a multiple of 2^-64, and Bernoulli::p returns that value through f64. At Float106, probability detail finer than f64 is lost.
  • Poisson::new lowers the rate to f64 only to compare it with MAX_RATE; the stored rate stays in the caller's scalar.
  • bernoulli_proportion divides in the caller's scalar when both counts are exact there, and otherwise divides in f64 and rounds the quotient once into the scalar.

The suites run at four scalars, from ~2 to ~32 decimal digits:

Scalar Epsilon Decimal digits Integers exact to
BFloat16 7.8e-3 ~2 256
f32 1.19e-7 ~7 2²⁴
f64 2.22e-16 ~16 2⁵³
Float106 4.93e-32 ~32 2¹⁰⁶

BFloat16 is a truncated f32 (the same eight exponent bits, the mantissa cut from 23 to 7), so it has f32's reach at a hundred-thousandth of its resolution and half its memory footprint.

sigmoid is bounded on Scalar rather than RealField: the quotient needs division, which Real does not carry, but not field invertibility. Scalar names exactly that middle, so a dual number flows through sigmoid and carries its derivative.

Conventions worth knowing before you call it

Three of these are deliberate and would otherwise look like defects.

Zero variance in pearson returns Ok((0, n)), not an error. The correlation is undefined there (the denominator vanishes), but callers rank features by |r|, and a rank of zero says "carries no information", the right answer for a constant column.

A one-element sample refuses variance with InsufficientSamples. No sentinel value takes the place of the undefined corrected variance, so none can feed a Gaussian density.

gaussian_log_density takes a variance, not a standard deviation. Both are plausible readings of a scale argument and they agree only at σ = 1. The suite pins the choice at σ² = 4, where they differ.

Two more are less surprising. Binning uses [lower, upper) for every bin except the last, which is closed, so the maximum falls inside the range rather than one bin past its end; a constant column is not an error and every observation lands in bin 0. And log_sum_exp is total: the empty slice is −∞, the identity of that reduction, rather than an error.

Errors

StatsError wraps StatsErrorEnum and offers a named constructor per variant, so a call site reads as the failure it reports:

return Err(StatsError::InsufficientSamples(
    "the corrected variance needs two observations: with one the divisor n − 1 is zero",
));

The variants separate three kinds of cause: an input the mathematics does not admit (EmptyInput, NegativeProbability, NonPositiveScale, NonFiniteInput), a shape the caller got wrong (DimensionMismatch, InvalidBinCount, InsufficientSamples), and a computation that could not reach an answer (RankDeficient, NotConverged, ConversionFailed). A caller can act on the second and third; the first is a statement about the data.

NotConverged carries its iteration count, so a cap that is merely too low is distinguishable from a problem that does not converge at all.

Dependency

[dependencies]
deep_causality_stats = "0.1"

Build configurations

Configuration Cargo features Supported
std, hosted default ✓
no-std with a heap default-features = false, features = ["no-std"] ✓
no-std on core alone, no heap – –

Without std the crate needs a heap: the program must define a #[global_allocator]. os-random is host-only.

CI builds every supported bare-metal configuration for thumbv7em-none-eabihf. README_NO_STD.md describes the build configuration of every crate in the workspace.

Licence

MIT. See LICENSE.