Rstats - Rust Stats

Crates.io GitHub last commit (branch)

Usage

Insert into your Cargo.toml file [dependencies] section:

rust rstats = "^0.8"

and import into your source file(s) any of these functions and/or traits that you want:

rust use rstats::{functions,Stats,Vecf64,Vecu8,VecVecf64,VecVecu8,Mutvectors};

Introduction

Rstats is primarily about characterising multidimensional sets of points, with applications to Machine Learning and Data Analysis. It begins with statistical measures and vector algebra, which provide some basic self-contained tools for the more interesting algorithms but can also be used in their own right.

Our treatment of multidimensional sets of points is constructed from the first principles. Some original concepts, not found elsewhere, are introduced and implemented here. Specifically, the new multidimensional (geometric) median algorithm. Also, the comediance matrix; a replacement for the covariance matrix. It is obtained simply by supplying covar with the geometric median instead of the centroid.

Zero median vectors are generally preferable to the commonly used zero mean vectors.

Most authors 'cheat' by using quasi medians (1-d medians along each axis). Quasi medians are a poor start to stable characterisation of multidimensional data. In a highly dimensional space, they are not even any easier to compute.

Specifically, all such 1-d measures are sensitive to the choice of axis.

Our methods based on the True Geometric Median, computed here by gmedian, are axis (rotation) independent from the first step.

Implementation

The constituent parts of Rstats are Rust traits grouping together functions applicable to vectors of data of relevant end types.End type f64 is most commonly used. Facilities for other end types are limited. For lots of data of other end types, it is always possible to clone to f64, see for example the included utility function vecu8asvecf64.

Documentation

Follow the documentation link. Then select a trait of interest to see the skeletal comments on the prototype function declarations in lib.rs. To see more detailed comments, plus some examples from the implementation files, scroll to the bottom of the trait and unclick [+] to the left of the implementations of the trait. To see the tests, consult tests.rs.

To run the tests, use single thread. It will be slower but will produce the results in the right order:

rust cargo test --release -- --test-threads=1 --nocapture --color always

Macro, structs and functions

Traits

Stats

One dimensional statistical measures implemented for &[i64] and &[f64].

All these methods operate on one vector of data and take no arguments. For example, s.amean() returns the arithmetic mean of slice s of either type. This is the only attempt at genericity.
This trait is carefully checked and will report all kinds of errors, such as empty input. This means you have to call .unwrap() or something similar on its results.

Included in this trait are:

Vecf64

Vector algebra implemented on one or two &[f64] slices of any length (dimensionality):

This trait is sometimes unchecked (for speed), so some caution with data is advisable.

Vecu8

MutVectors

Some of the above functions are for memory efficiency reasons reimplemented in this trait so that they mutate self in place, instead of creating a new Vec. Clearly, they can only be applied to a mutable variable. They are useful in vector iterative methods. Beware that they work by side-effect and do not return anything, so they can not be chained.

VecVec

Relationships of one vector to a set of vectors (of &[f64] end types):

Trait VecVec is entirely unchecked, so check your data upfront. This is the more sophisticated part of the library. The true geometric median is found iteratively.

VecVecu8

Some of the above for vectors of vectors of bytes.

Appendix I: Terminology (and some new definitions) for sets of nD points

Appendix II: Recent Releases