Skip to main content

Crate deep_causality_stats

Crate deep_causality_stats 

Source
Expand description

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

§Why this crate exists

Not to remove duplication. It adds more source than it removes, and says so in its own change notes. It exists because shipped implementations of the same statistic disagree about what they compute.

Shannon entropy is the case that decides it. Three implementations in this workspace differ on three axes at once — the base, whether the input is normalised, and where the cutoff for a negligible entry sits. Two of them return answers in different units for the same input: one in bits, one in nats, a factor of ln 2 apart. That is not a rounding difference to be tidied away, it is a semantic disagreement, and one parameterised function that can reproduce each is the resolution.

So the parameters here are not configurability for its own sake. Each combination named in EntropyConfig has a caller in this workspace today.

§Scope

The crate implements only functions something calls. That rule is what keeps a new crate from becoming a survey of the field, and it excludes several things a statistics library conventionally carries: cross-entropy, mutual information, Kullback–Leibler divergence, Jensen–Shannon divergence, the Hellinger distance and a general Bhattacharyya coefficient.

Mutual information is the one that most invites an exception, because the causal-discovery code computes information quantities. What it computes is specific mutual information and information leak over marginalised tensor axes, which is not the slice-shaped general function; building the general one would leave that version in place beside it. The Bhattacharyya case is the same shape: the quantum crate computes the two-outcome Bernoulli coefficient in bits, inline, which is not the general slice coefficient.

Each is a short addition whenever a caller appears.

§Why the distributions live here

A distribution is mathematics. Normal, Exponential, Cauchy and the rest are defined by their densities and their moments, and every one of those is a statistic — which is what this crate is for. Putting them beside the densities is what makes importance sampling, sequential Monte Carlo and MCMC diagnostics short to write: each needs a sampler and a density in the same place, and separating them by a crate boundary is what made them long.

The entropy crate below keeps what is genuinely entropy: generators, the raw machine word, the Boolean draw, the Sobol sequence and the range sampler. It makes no claim about how a number is distributed beyond “uniform over the bits”, and it does not name a density anywhere. The dependency runs stats -> rand, downhill, so nothing circles back.

§A lazy sampler is Arrow-shaped, not witness-shaped

A carrier that stores a sampling closure — draw-on-demand rather than draw-now — cannot take the container traits in deep_causality_haft, and the reason is worth recording so it is not rediscovered as a gap.

Those traits carry no 'static bound: zero occurrences across Functor, Pure, Applicative, Monad, Traversable and LaxMonoidal. That absence is deliberate. A functor receives a function, applies it and drops it, so the function never outlives the call. Profunctor, which does store its functions, carries 'static on every parameter.

A stored closure needs bounds the container traits do not provide, and an implementation cannot add them — error[E0276]: impl has stricter requirements than trait. The container traits are for data. A lazy sampler is a program, and haft’s home for programs is the Arrow layer.

An ensemble of realised draws has no such problem: it is a Vec with a witness, which CausalTensor already is, and drawing into one is an ordinary generic function needing no witness of its own.

§Precision

Functions are generic over their scalar under the algebra tower’s bounds, with the exceptions below.

Four signatures name a concrete float. The unit coordinate of an inverse-CDF transform is f64 because it is a position on [0, 1) rather than a value in the caller’s scalar, and rounding it into a narrow scalar before the transform is destructive at the endpoints — see standard_normal_inverse_cdf_at. Beside it, standard_normal_inverse_cdf and standard_normal_inverse_cdf_f106 are the same transform at one fixed precision each. bernoulli_inverse_cdf compares an f64 coordinate with an f64 probability.

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, so probability detail finer than f64 is lost at Float106. 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.

§Shape

The surface is over slices. Anything with axes — marginalising a joint distribution, reducing a tensor — belongs with the container that has them, and this crate sits below those containers so they can delegate to it without a cycle.

Re-exports§

pub use crate::algorithms::binning::bin_equal_frequency;
pub use crate::algorithms::binning::bin_equal_width;
pub use crate::algorithms::correlation::pearson;
pub use crate::algorithms::correlation::pearson_pairwise_complete;
pub use crate::algorithms::covariance::column_means;
pub use crate::algorithms::covariance::conditional_variance;
pub use crate::algorithms::covariance::covariance_matrix;
pub use crate::algorithms::density::gaussian_log_density;
pub use crate::algorithms::entropy::conditional_entropy;
pub use crate::algorithms::entropy::entropy;
pub use crate::algorithms::log_sum_exp::log_add_exp;
pub use crate::algorithms::log_sum_exp::log_sum_exp;
pub use crate::algorithms::logistic::fit_logistic;
pub use crate::algorithms::logistic::sigmoid;
pub use crate::algorithms::moments::mean;
pub use crate::algorithms::moments::population_std_dev;
pub use crate::algorithms::moments::population_variance;
pub use crate::algorithms::moments::std_dev;
pub use crate::algorithms::moments::variance;
pub use crate::algorithms::proportion::bernoulli_proportion;
pub use crate::algorithms::proportion::bernoulli_standard_error;
pub use crate::algorithms::ridge::fit_ridge;
pub use crate::algorithms::ridge::fit_ridge_streaming;
pub use crate::errors::stats_error::StatsError;
pub use crate::errors::stats_error::StatsErrorEnum;
pub use crate::types::entropy_config::EntropyConfig;
pub use crate::types::log_base::LogBase;
pub use crate::types::logistic_config::LogisticConfig;
pub use crate::types::logistic_fit::LogisticFit;
pub use crate::types::mean_accumulator::MeanAccumulator;
pub use crate::types::normalisation::Normalisation;
pub use crate::types::penalisation::Penalisation;
pub use crate::types::ridge_config::RidgeConfig;
pub use crate::types::ridge_fit::RidgeFit;
pub use crate::types::zero_policy::ZeroPolicy;
pub use crate::errors::bernoulli_error::BernoulliDistributionError;
pub use crate::errors::normal_error::NormalDistributionError;
pub use crate::types::distr::bernoulli::Bernoulli;
pub use crate::types::distr::categorical::Categorical;
pub use crate::types::distr::cauchy::Cauchy;
pub use crate::types::distr::exponential::Exponential;
pub use crate::types::distr::log_normal::LogNormal;
pub use crate::types::distr::normal::Normal;
pub use crate::types::distr::normal::standard_normal::StandardNormal;
pub use crate::types::distr::poisson::MAX_ITERATIONS;
pub use crate::types::distr::poisson::MAX_RATE;
pub use crate::types::distr::poisson::Poisson;
pub use crate::types::distr::uniform_int::UniformInt;
pub use crate::types::distr::unit_interval::standard_uniform::StandardUniform;
pub use crate::types::distr::weibull::Weibull;
pub use crate::types::range::Open01;
pub use crate::types::range::OpenClosed01;
pub use crate::utils::inverse_cdf::bernoulli_inverse_cdf;
pub use crate::utils::inverse_cdf::standard_normal_inverse_cdf;
pub use crate::utils::inverse_cdf::standard_normal_inverse_cdf_at;
pub use crate::utils::inverse_cdf::standard_normal_inverse_cdf_f106;
pub use crate::utils::inverse_cdf::uniform_inverse_cdf;
pub use crate::traits::random_ext::RandomExt;

Modules§

algorithms
errors
traits
types
utils

Structs§

Xoshiro256

Traits§

Distribution
RandScalar
Every scalar the sampling layer works at.
Rng
RngCore

Functions§

rng
Returns a new random number generator. Which one depends on the enabled features: