statrs

Added

• let callers choose the binomial sampling algorithm

Fixed

• Correct exact distribution boundaries
• Beta::sf returning exactly 1.0 for tiny x
• order the selection fast paths by total_cmp, not <=
• replace hand-rolled quickselect with select_nth_unstable_by
• address review on the BINV/BTPE sampler

Other

• Alias f64 constants
• Fix nightly f64 deprecation warnings
• add a selection benchmark, and ordered fast paths it exposed
• build the NaN order-statistic test under no_std
• move binomial sampling into its own module
• split the sampler's branch selection out of the RNG path
• require std for the BTPE chi-square test
• sample Binomial via BINV/BTPE instead of n Bernoulli trials
• Bound the Newton iteration count and cover the quantile guards
• Add safeguarded-Newton inverse_cdf for Chi and InverseGamma

Added

• let callers choose the binomial sampling algorithm

Fixed

• Correct exact distribution boundaries
• Beta::sf returning exactly 1.0 for tiny x
• order the selection fast paths by total_cmp, not <=
• replace hand-rolled quickselect with select_nth_unstable_by
• address review on the BINV/BTPE sampler

Other

• Alias f64 constants
• Fix nightly f64 deprecation warnings
• add a selection benchmark, and ordered fast paths it exposed
• build the NaN order-statistic test under no_std
• move binomial sampling into its own module
• split the sampler's branch selection out of the RNG path
• require std for the BTPE chi-square test
• sample Binomial via BINV/BTPE instead of n Bernoulli trials
• Bound the Newton iteration count and cover the quantile guards
• Add safeguarded-Newton inverse_cdf for Chi and InverseGamma

Added

• Add initial no_std support
• gate density estimation behind a "kde" feature
• add first implementation of kernel density estimation.
• add bandwith support for knn density estimation.
• add a more generic implementation of knn density estimation.
• add knn density estimation with kdtree rs tree.
• add OnlineMoments accumulator using Welford
• Add WebAssembly RNG support and update nalgebra
• (distribution) narrow error type to avoid trait object
• (distribution) add non-panicking try_inverse_cdf
• autofix.ci for lint and fmt
• (geometric) finer panic bounds
• (function) add comprehensive kernel suite for KDE and smoothing (#193)
• update to 2024 edition, apply formatting and fix new clippy lints
• [breaking] rely on prec module for precision needs and consts for math constants
• use crate::prec macro assertions in tests instead of approx directly
• (prec) write macros that delegate to approx using our defaults
• add std feature
• rename cov_chol_decomp to clone_cov_chol_decomp and return a cloned matrix
• add methods for covariance decomposition, mean, covariance, and precision in MultivariateNormal
• add accessor methods to various distribution
• (stats_tests) implement KS test
• enhance Levy distribution with comprehensive documentation and methods
• add Levy distribution
• (stats_tests) implement chisquare
• (stats_tests) implement skewtest
• (stats_tests) implement mannwhitneyu
• (stats_tests) implement ttest_onesample
• (stats_tests) implement f_oneway

Fixed

• format assertion message with precision
• fail autofix when clippy --fix can't clear every lint
• drop PAT from autofix-ci.yml
• make autofix clippy match other parts of ci
• Automate MSRV lockfile updates
• update to rand 0.10 and use seeded rng for tests
• fix imports and add some tests.
• kernel density computation.
• drop excess precision requirements
• wrap online stats with iter_statistics for #376
• Refresh MSRV lockfile
• Leave getrandom backend selection to applications
• Use valid order statistics benchmark inputs
• correct entropy formulas for Pareto, Geometric, StudentsT, and Dirichlet
• safeguard Gamma::inverse_cdf Newton step for shape < 1
• compute Multinomial pmf/ln_pmf in log space to avoid NaN for large n
• post updates to rand
• update usage after rand dep update
• restore missing normalization of Dirichlet samples
• unblock PR 364 CI
• remove unused testing imports
• use core instead of std in KDE
• (fmt) apply 2024 formatting to KDE
• (clippy) use constants provided by core
• (clippy) fix clippy failures in CI
• (distribution_tests) pass if only one numerical relationship between pdf and cdf numerically close
• change tests to rely on relative precision for math lib independence
• Gate some stats_tests behind std feature
• Use core over std where possible
• update examples in mu and cov methods to use correct types from nalgebra
• exact implementation of Bernoulli cdf
• one more condition in inverse_cdf to account for small enough probabilities.
• feature gate exact KS test one-sample method

Other

• add some geometric pathological tests
• enable autofix to use same clippy as other ci
• Verify df one density integral
• Cover chi-squared boundary behavior
• update lock MSRV for kde deps change
• module docs and feature doc
• add paper reference and simple usage docs
• document DensityError variants and mark non_exhaustive
• add use of one dimensional gaussian kernel function.
• density functions borrowing evaluation pointS instead of owning them.
• some refactoring.
• add performance bench.
• add performance bench.
• [autofix.ci] apply automated fixes
• sample Multinomial via sequential conditional Binomial instead of categorical-style draw-and-scan
• add characterization tests for Multinomial::sample before algorithm change
• share binary-search lookup between Categorical::sample and inverse_cdf
• derive Categorical::sf from cdf instead of storing it
• Categorical now stores normalized values
• Update dependencies and GitHub Actions
• Converge the default continuous inverse_cdf
• Align autofix toolchain with MSRV
• Cover geometric inverse CDF overflow guards
• how to release
• wire up release-plz for crates.io publishing
• remove fast-fail semantics of test ci
• update branch refs from master to main
• Add test for Dirichlet sample normalization
• Add clippy fixes
• more clippy lints
• update lockfile after updating rand
• Format with cargo fmt
• update rand 0.9 -> 0.10
• Fixed redundant word "may"
• use core panic instead of std
• add comments
• add tests for coverage
• add specialised inverse cdf implementation for geometric distribution
• Simplify polynomial evaluation function
• Add a MultivariateNormal constructor from the Cholesky decomposition
• Make documented value of DEFAULT_RELATIVE_ACC match actual value.
• don't fail fast when testing on different OSs
• Bumped MSRV to 1.87.0.
• Bumped rand to 0.9.0 and mechanically modified the code to accommodate the changes in that dependency.
• Use -x instead of -1.0 * x
• Merge pull request #336 from FreezyLemon/optimize-chisquare-test
• Fix merge from master
• Merge branch 'master' into optimize-chisquare-test
• lint
• use functionality from prec module outside tests
• doctests should use approx instead of statrs::prec
• update precision docs
• update to not use macro_use directives
• update readme to regard precision, open to updates
• [breaking] define precision consts within mod prec
• add "std" feature-gate where needed
• Remove catch_unwind from test code
• add no_std testing
• only implement Error with feature "std"
• use panic! with msg instead of println!
• some tests do not need Vec
• prefer core imports over std
• more tests for inverse cdf of discrete distributions.
• more efficient calculation for KS one-sample exact
• remove ks_twosample usage of nalgebra
• cfg wrap for rand
• Fix gamma parameterization for negative binomial sampling
• (deps) bump codecov/codecov-action from 4 to 5
• update docs and result chaining idioms
• enhance checks for continuous distributions with panic safety
• improve numerical stability in CDF derivative check
• add check for derivative of CDF to ensure it matches PDF
• (stats_test) better attribution of sources
• more coverage for f_oneway
• more coverage for mannwhitneyu
• mut in function header instead of in function

Added

• Add initial no_std support
• gate density estimation behind a "kde" feature
• add first implementation of kernel density estimation.
• add bandwith support for knn density estimation.
• add a more generic implementation of knn density estimation.
• add knn density estimation with kdtree rs tree.
• add OnlineMoments accumulator using Welford
• Add WebAssembly RNG support and update nalgebra
• (distribution) narrow error type to avoid trait object
• (distribution) add non-panicking try_inverse_cdf
• autofix.ci for lint and fmt
• (geometric) finer panic bounds
• (function) add comprehensive kernel suite for KDE and smoothing (#193)
• update to 2024 edition, apply formatting and fix new clippy lints
• [breaking] rely on prec module for precision needs and consts for math constants
• use crate::prec macro assertions in tests instead of approx directly
• (prec) write macros that delegate to approx using our defaults
• add std feature
• rename cov_chol_decomp to clone_cov_chol_decomp and return a cloned matrix
• add methods for covariance decomposition, mean, covariance, and precision in MultivariateNormal
• add accessor methods to various distribution
• (stats_tests) implement KS test
• enhance Levy distribution with comprehensive documentation and methods
• add Levy distribution
• (stats_tests) implement chisquare
• (stats_tests) implement skewtest
• (stats_tests) implement mannwhitneyu
• (stats_tests) implement ttest_onesample
• (stats_tests) implement f_oneway

Fixed

• format assertion message with precision
• fail autofix when clippy --fix can't clear every lint
• drop PAT from autofix-ci.yml
• make autofix clippy match other parts of ci
• Automate MSRV lockfile updates
• update to rand 0.10 and use seeded rng for tests
• fix imports and add some tests.
• kernel density computation.
• drop excess precision requirements
• wrap online stats with iter_statistics for #376
• Refresh MSRV lockfile
• Leave getrandom backend selection to applications
• Use valid order statistics benchmark inputs
• correct entropy formulas for Pareto, Geometric, StudentsT, and Dirichlet
• safeguard Gamma::inverse_cdf Newton step for shape < 1
• compute Multinomial pmf/ln_pmf in log space to avoid NaN for large n
• post updates to rand
• update usage after rand dep update
• restore missing normalization of Dirichlet samples
• unblock PR 364 CI
• remove unused testing imports
• use core instead of std in KDE
• (fmt) apply 2024 formatting to KDE
• (clippy) use constants provided by core
• (clippy) fix clippy failures in CI
• (distribution_tests) pass if only one numerical relationship between pdf and cdf numerically close
• change tests to rely on relative precision for math lib independence
• Gate some stats_tests behind std feature
• Use core over std where possible
• update examples in mu and cov methods to use correct types from nalgebra
• exact implementation of Bernoulli cdf
• one more condition in inverse_cdf to account for small enough probabilities.
• feature gate exact KS test one-sample method

Other

• add some geometric pathological tests
• enable autofix to use same clippy as other ci
• Verify df one density integral
• Cover chi-squared boundary behavior
• update lock MSRV for kde deps change
• module docs and feature doc
• add paper reference and simple usage docs
• document DensityError variants and mark non_exhaustive
• add use of one dimensional gaussian kernel function.
• density functions borrowing evaluation pointS instead of owning them.
• some refactoring.
• add performance bench.
• add performance bench.
• [autofix.ci] apply automated fixes
• sample Multinomial via sequential conditional Binomial instead of categorical-style draw-and-scan
• add characterization tests for Multinomial::sample before algorithm change
• share binary-search lookup between Categorical::sample and inverse_cdf
• derive Categorical::sf from cdf instead of storing it
• Categorical now stores normalized values
• Update dependencies and GitHub Actions
• Converge the default continuous inverse_cdf
• Align autofix toolchain with MSRV
• Cover geometric inverse CDF overflow guards
• how to release
• wire up release-plz for crates.io publishing
• remove fast-fail semantics of test ci
• update branch refs from master to main
• Add test for Dirichlet sample normalization
• Add clippy fixes
• more clippy lints
• update lockfile after updating rand
• Format with cargo fmt
• update rand 0.9 -> 0.10
• Fixed redundant word "may"
• use core panic instead of std
• add comments
• add tests for coverage
• add specialised inverse cdf implementation for geometric distribution
• Simplify polynomial evaluation function
• Add a MultivariateNormal constructor from the Cholesky decomposition
• Make documented value of DEFAULT_RELATIVE_ACC match actual value.
• don't fail fast when testing on different OSs
• Bumped MSRV to 1.87.0.
• Bumped rand to 0.9.0 and mechanically modified the code to accommodate the changes in that dependency.
• Use -x instead of -1.0 * x
• Merge pull request #336 from FreezyLemon/optimize-chisquare-test
• Fix merge from master
• Merge branch 'master' into optimize-chisquare-test
• lint
• use functionality from prec module outside tests
• doctests should use approx instead of statrs::prec
• update precision docs
• update to not use macro_use directives
• update readme to regard precision, open to updates
• [breaking] define precision consts within mod prec
• add "std" feature-gate where needed
• Remove catch_unwind from test code
• add no_std testing
• only implement Error with feature "std"
• use panic! with msg instead of println!
• some tests do not need Vec
• prefer core imports over std
• more tests for inverse cdf of discrete distributions.
• more efficient calculation for KS one-sample exact
• remove ks_twosample usage of nalgebra
• cfg wrap for rand
• Fix gamma parameterization for negative binomial sampling
• (deps) bump codecov/codecov-action from 4 to 5
• update docs and result chaining idioms
• enhance checks for continuous distributions with panic safety
• improve numerical stability in CDF derivative check
• add check for derivative of CDF to ensure it matches PDF
• (stats_test) better attribution of sources
• more coverage for f_oneway
• more coverage for mannwhitneyu
• mut in function header instead of in function

ci: update lockfile to use [email protected]

✨ Added

• Added more inverse cumulative distribution functions.
• Introduced feature flags: rand and nalgebra.
• Added the std_dev method to the Distribution trait explicitly.
• Supported sampling integers from discrete distributions.
• Added support for the Gumbel distribution.

⚠️ Breaking Changes

• Migrated multivariate distributions to generic dimensions.
• Replaced StatsError with module-level error types in distribution and its children.
• Changed checked_logit, checked_multinomial, and similar methods to return Option to handle invalid inputs.
• Changed Chi distribution to use u64 for degrees of freedom.

🛠️ Changed

• Upgraded nalgebra to version 0.33.
  • Upgrades MSRV to 1.65+
• Improved documentation and added examples (e.g., for Hypergeometric distribution).
• Added MSRV (Minimum Supported Rust Version) metadata to Cargo.toml and documentation.
• Introduced coverage reporting with llvm-cov.
• Updated CI to check all feature combinations and ensure MSRV compliance.
• Added an MSRV badge to crates.io.

✅ Fixed

• Corrected formatting issues in documentation.
• Fixed several rustdoc warnings.
• Expanded test coverage for Dirichlet and Multinomial distributions.
• Improved ergonomics at cli for tests and ensured compatibility with updated NIST data.

❌ Removed

• Replaced StatsError with module-level error types.
• Deprecated the error module and preformatted NIST data.
• Removed rustfmt.toml as part of CI clean-up.

🎉 New Contributors

• @SabrinaJewson and @alimf17 made their first contributions!

Revival!

A few fixes, some dependency updates, most notably nalgebra.
Breaking changes in statrs::StatsError, expect more changes later.

Details

Changed

• Release statrs version 0.17.1 by @YeungOnion

Fixed

• Code in benches still needs criterion by @YeungOnion

<!-- generated by git-cliff -->

chore: Release statrs version 0.17.0

Added

• specializes inverse_cdf() for Uniform (#166)
• Add way to get standard normal distribution easily. (#228)
• reject constructing Uniform of infinite support (#218)
• extend StatsError for finiteness (#218)
• default implementation of survival function with generics (#179)
• update MultivariateNormal API
  • construct from nalgebra with MultivariateNormal::new_from_nalgebra (#177)
  • support std::vec vector input in addition to nalgebra vectors (#199)

Fixed

• Update nalgebra to 0.32 (#187)
• for Gamma with shape<1 there is no mode, returns None instead of some negative number (#212)
• fix precision of <Gamma as ContinuousCDF>::inverse_cdf with some newton raphson steps (#227)
  • adds test case from #200
• fix integer bisection for default implementation of <D as DiscreteCDF>::inverse_cdf (#220)
  • also add tests from (#185)

Other

• Remove "nightly" feature and drop testing requirement for nightly (#234)
• Allow some imprecision in specific test case (#215)
• Update CI (#215)
  • Check formatting in CI via rustfmt
  • Expand CI test job
  • Add clippy job to CI
• update README with formatting and adding to "Contributing" (#213)
• Add test asserting that StatsError is Sync & Send (#226)
• Rename private struct NonNAN<T> to NonNan<T> (#222)
• Remove lazy-static dependency and make FCACHE a proper const (#211)
• crate examples shall be in docstrings instead of README (#213)
• alias inverse_cdf as "quantile function" in docs (#213)
• docstrings with math shall be text instead of ignore (#213)

fixed integer bisection, see issue #185

Bumping nalgebra due to RUSTSEC-2021-0070 advisory.

• upgrade nalgebra to 0.27.1 to avoid RUSTSEC-2021-0070

Merge pull request #139 from vks/fix-doctests

Fix doctests

• upgrade rand dependency to 0.8
• fix inaccurate sampling of Gamma
• Implemented Empirical distribution
• Implemented Laplace distribution
• Removed Checked* traits
• Almost clippy-clean
• Almost fully enabled rustfmt
• Begin applying consistent numeric relative-accuracy targets with the approx crate
• Introduce macro to generate testing boilerplate, yet not all tests use this yet
• Moved to dynamic vectors in the MultivariateNormal distribution
• Reduced a number of distribution-specific traits into the Distribution and DiscreteDistribution traits

• Implemented MultivariateNormal distribution (depends on nalgebra 0.19)
• Implemented Dirac distribution
• Implemented Negative Binomial distribution

• upgrade rand dependency to 0.7

• upgrade rand dependency to 0.6
• Implement CheckedInverseCDF and InverseCDF for Normal distribution

• upgrade rand dependency to 0.5
• Removes the Distribution trait in favor of the rand::distributions::Distribution trait
• Removed functions deprecated in 0.8.0 (periodic, periodic_custom, sinusoidal, sinusoidal_custom)

• implemented infinite sequence generator for periodic sequence
• implemented infinite sequence generator for sinusoidal sequence
• implemented infinite sequence generator for square sequence
• implemented infinite sequence generator for triangle sequence
• implemented infinite sequence generator for sawtooth sequence
• deprecate old non-infinite iterators in favor of new infinite iterators with take
• Implemented Pareto distribution
• Implemented Entropy trait for the Categorical distribution
• Add a checked_ interface to all distribution methods and functions that may panic

• cdf(x), pdf(x) and pmf(x) now return the correct value instead of panicking when x is outside the range of values that the distribution can attain.
• Fixed a bug in the Uniform distribution implementation where samples were drawn from range [min, max + 1) instead of [min, max]. The samples are now drawn correctly from the range [min, max].
• Implement generate::log_spaced function
• Implement generate::Periodic iterator
• Implement generate::Sinusoidal iterator
• Implement generate::Square iterator
• Implement generate::Triangle iterator
• Implement generate::Sawtooth iterator
• Deprecate generate::periodic and generate::periodic_custom
• Deprecate generate::sinusoidal and generate::sinusoidal_custom

Note: A recent commit to the Rust nightly build causes compile errors when using empty slices with the Statistics trait, specifically the Statistics::min and Statistics::max methods. This only affects the case where the compiler must infer the type of the empty slice:

use statrs::statistics::Statistics;

// compile error! Assumes the use of Ord::min rather than
// Statistcs::min
let x = [];
assert!(x.min().is_nan());

The fix is to pin the type of the empty slice:

// no compile error
let x: [f64; 0] = [];
assert!(x.min().is_nan());

Since the regression affects a very slim edge-case and the fix is very simple, no breaking changes to the Statistics API was deemed necessary

• Implemented Categorical distribution
• Implemented Erlang distribution
• Implemented Multinomial distribution
• New InverseCDF trait for distributions that implement the inverse cdf function

• gamma::gamma_ur, gamma::gamma_ui, gamma::gamma_lr, and gamma::gamma_li now follow strict gamma function domain, panicking if a or x are not in (0, +inf)
• beta::beta_reg no longer allows 0.0 for a or b arguments
• InverseGamma distribution no longer accepts f64::INFINITY as valid arguments for shape or rate as the value is nonsense
• Binomial::cdf no longer accepts arguments outside the domain of [0, n]
• Bernoulli::cdf no longer accepts arguments outside the domain of [0, 1]
• DiscreteUniform::cdf no longer accepts arguments outside the domain of [min, max]
• Uniform::cdf no longer accepts arguments outside the domain of [min, max]
• Triangular::cdf no longer accepts arguments outside the domain of [min, max]
• FisherSnedecor no longer accepts f64::INFINITY as a valid argument for freedom_1 or freedom_2
• FisherSnedecor::cdf no longer accepts arguments outside the domain of [0, +inf)
• Geometric::cdf no longer accepts non-positive arguments
• Normal now uses the Ziggurat method to generate random samples. This also affects all distributions depending on Normal for sampling including Chi, LogNormal, Gamma, and StudentsT
• Exponential now uses the Ziggurat methd to generate random samples.
• Binomial now implements Univariate<u64, f64> rather than Univariate<i64, f64>, meaning Binomial::min and Binomial::max now return u64
• Bernoulli now implements Univariate<u64, f64> rather than Univariate<i64, f64>, meaning Bernoulli::min and Bernoulli::min now return u64
• Geometric now implements Univariate<u64, f64> rather than Univariate<i64, f64>, meaning Geometric::min and Geometric::min now return u64
• Poisson now implements Univariate<u64, f64> rather than Univariate<i64, f64>, meaning Poisson::min and Poisson::min now return u64
• Binomial now implements Mode<u64> instead of Mode<i64>
• Bernoulli now implements Mode<u64> instead of Mode<i64>
• Poisson now implements Mode<u64> instead of Mode<i64>
• Geometric now implements Mode<u64> instead of Mode<i64>
• Hypergeometric now implements Mode<u64> instead of Mode<i64>
• Binomial now implements Discrete<u64, f64> rather than Discrete<i64, f64>
• Bernoulli now implements Discrete<u64, f64> rather than Discrete<i64, f64>
• Geometric now implements Discrete<u64, f64> rather than Discrete<i64, f64>
• Hypergeometric now implements Discrete<u64, f64> rather than Discrete<i64, f64>
• Poisson now implements Discrete<u64, f64> rather than Discrete<i64, f64>

• Fixed critical bug in normal::sample_unchecked where it was returning NaN

• Implemented the logistic::logistic special function
• Implemented the logistic::logit special function
• Implemented the factorial::multinomial special function
• Implemented the harmonic::harmonic special function
• Implemented the harmonic::gen_harmonic special function
• Implemented the InverseGamma distribution
• Implemented the Geometric distribution
• Implemented the Hypergeometric distribution
• gamma::gamma_ur now panics when x > 0 or a == f64::NEG_INFINITY. In addition, it also returns f64::NAN when a == f64::INFINITY and 0.0 when x == f64::INFINITY
• Gamma::pdf and Gamma::ln_pdf now return f64::NAN if any of shape, rate, or x are f64::INFINITY
• Binomial::pdf and Binomial::ln_pdf now panic if x > n or x < 0
• Bernoulli::pdf and Bernoulli::ln_pdf now panic if x > 1 or x < 0