statrs

Statrs provides a host of statistical utilities for Rust scientific computing.

Included are a number of common distributions that can be sampled (i.e. Normal, Exponential, Student's T, Gamma, Uniform, etc.) plus common statistical functions like the gamma function, beta function, and error function.

This library began as port of the statistical capabilities in the C# Math.NET library. All unit tests in the library borrowed from Math.NET when possible and filled-in when not. Planned for future releases are continued implementations of distributions as well as porting over more statistical utilities.

Please check out the documentation here.

Usage

Add the most recent release to your Cargo.toml

[dependencies]
statrs = "*" # replace * by the latest version of the crate.

For examples, view the docs.

no_std

Disable the default features to use statrs without std:

[dependencies]
statrs = { version = "*", default-features = false }

No separate Cargo feature is required for allocation-backed APIs. To enable matrix-backed distributions without std, enable nalgebra directly:

[dependencies]
statrs = { version = "*", default-features = false, features = ["nalgebra"] }

Heap-backed APIs use Rust's alloc crate. A no_std application that calls these APIs must provide and initialize a global allocator suitable for its target:

#[global_allocator]
static ALLOCATOR: PlatformAllocator = PlatformAllocator::new(/* heap memory */);

The allocator type, heap memory, and initialization are platform-specific. statrs does not provide or select an allocator. When std is enabled, its global allocator is used and no setup is required.

WebAssembly randomness

On wasm32-unknown-unknown, sampling works with an explicitly seeded random number generator without a host entropy source. Applications that need JavaScript entropy, for example for rand::rng(), must select the getrandom backend themselves:

[dependencies]
statrs = "*"
rand = "0.10"
getrandom = { version = "0.4", features = ["wasm_js"] }

statrs does not select a randomness backend for downstream applications.

Running tests

If you'd like to run all suggested tests, you'll need to download some data from NIST, we have a script for this and formatting the data in the tests/ folder.

cargo test
./tests/gather_nist_data.sh && cargo test -- --include-ignored nist_

If you'd like to modify where the data is downloaded, you can use the environment variable, STATRS_NIST_DATA_DIR for running the script and the tests.

Minimum supported Rust version (MSRV)

This crate requires a Rust version of 1.89.0 or higher. Increases in MSRV will be considered a semver non-breaking API change and require a version increase (PATCH until 1.0.0, MINOR after 1.0.0).

Precision

Floating-point numbers cannot always represent decimal values exactly, which can introduce small (and in some cases catastrophically large) errors in computations. In statistical applications, these errors can accumulate, making careful precision control important.

For Users and Evaluators

The statrs crate takes precision seriously:

• We use standardized precision checks throughout the codebase
• Default precision levels are carefully chosen to balance correctness and performance
• Module-specific precision requirements are explicitly documented where they differ from defaults
• Our test suite verifies numerical accuracy against common reference libraries

Key precision constants in the crate are set by pub consts in the prec module:

• Default relative accuracy: pub const DEFAULT_RELATIVE_ACC
• Default epsilon: pub const DEFAULT_EPS
• Default ULPs (Units in Last Place): pub const DEFAULT_ULPS

Some modules/submodules have default precision that is different from the crate defaults, for searchability the names of such constants are the MODULE_RELATIVE_ACC, MODULE_EPS, and MODULE_ULPS.

[!IMPORTANT] Starting from v0.19.0, the prec module is no longer public (pub mod prec → mod prec). This change reflects that precision handling is an internal implementation detail.

The precision constants mentioned above remain stable and documented and will be reexported at the crate level, but direct access to the module's utilities is now restricted to maintain better API boundaries.

For Contributors

// express your sentiment about the intended use of prec module in this section. The reason is that this section is for contributors and the users need not know about internal functionality. To help maintain consistent precision checking, statrs provides:

1. A prec module that wraps and standardizes common approximation checks from the approx crate with crate-specific defaults
2. Macros for common precision comparison patterns
3. Helper functions for convergence testing

When contributing:

• Use the provided precision utilities rather than hard-coding values
• Maintain or improve precision in existing tests when making changes, new modules can start at lesser precision than the crate defaults if need be
  • when doing so, one should use the same names as defined in the prec module, this helps with searchabiliy.
• Document any module-specific precision requirements

Learning Resources

If you're new to floating-point precision, these resources provide helpful introductions:

• Comparing Floating Point Numbers, 2012 Edition
• The Floating Point Guide - Comparison
• What Every Computer Scientist Should Know About Floating-Point Arithmetic

Contributing

Thanks for your help to improve the project! No contribution is too small and all contributions are valued.

If you're not familiar with precision in floating point operations, please read the section on precision specifically, the For Contributors section.

Suggestions if you don't know where to start,

• if you're an existing user, file an issue or feature request.
• documentation is a great place to start, as you'll be able to identify the value of existing documentation better than its authors.
• tests are valuable in demonstrating correct behavior, you can review test coverage on the CodeCov Report
• check out some of the issues marked help wanted.
• look at features you'd like to see in statrs
  • Math.NET
    • Distributions
    • Statistics
  • scipy.stats
  • KDE, see (issue #193)[https://github.com/statrs-dev/statrs/issues/193]

How to contribute

Clone the repo:

git clone https://github.com/statrs-dev/statrs

Create a feature branch:

git checkout -b <feature_branch> main

Write your code and docs, then ensure it is formatted:

cargo fmt

Add --check to view the diff without making file changes. Our CI will check format without making changes.

After commiting your code:

git push -u <your_remote_name> <your_branch> # with `git`
gh pr create --head <your_branch> # with GitHub's cli

Then submit a PR, preferably referencing the relevant issue, if it exists.

Commit messages

Please be explicit and and purposeful with commit messages. Conventional Commits encouraged.

Communication Expectations

Please allow at least one week before pinging issues/pr's.