A consolidated system of statistical functions

statistics

[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MS-PL License][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]




<br />
<p align="center">
  <a href="https://github.com/lisp-stat/statistics">
    <img src="https://lisp-stat.dev/images/stats-image.svg" alt="Logo" width="80" height="80">
  </a>

  <h3 align="center">Lisp-Stat Statistics</h3>

  <p align="center">
	A consolidation of Common Lisp statistics libraries
	<br />
    <a href="https://lisp-stat.dev/docs/"><strong>Explore the docs »</strong></a>
    <br />
    <br />
    <a href="https://github.com/lisp-stat/statistics/issues">Report Bug</a>
    ·
    <a href="https://github.com/lisp-stat/statistics/issues">Request Feature</a>
    ·
    <a href="https://lisp-stat.github.io/statistics/">Reference Manual</a>
  </p>
</p>




<details open="open">
  <summary><h2 style="display: inline-block">Table of Contents</h2></summary>
  <ol>
    <li>
      <a href="#about-the-project">About the Project</a>
    </li>
	<li><a href="#installation">Installation</a></li>
    <li><a href="#usage">Usage</a></li>
    <li><a href="#functions">Functions</a></li>
	<li><a href="#roadmap">Roadmap</a></li>
	<li><a href="#resources">Resources</a></li>
    <li><a href="#contributing">Contributing</a></li>
    <li><a href="#license">License</a></li>
    <li><a href="#contact">Contact</a></li>
  </ol>
</details>




## About the Project

There are three statistics libraries that can be considered relatively complete and well written:

- The statistics library from numerical-utilities
- Larry Hunter's cl-statistics
- Gary Warren King's cl-mathstats

There are a few challenges in using these as independent systems on projects though:

- There is a good amount of overlap.  Everyone implements, for example `mean` (as does alexandria, cephes, and others)
- In the case of `mean`, `variance`, etc., the functions deal only with samples, not distributions

This library brings these three systems under a single 'umbrella', and adds a few missing ones.  To do this we use Tim Bradshaw's [conduit-packages](https://github.com/tfeb/conduit-packages).  For the few functions that require dispatch on type (sample data vs. a distribution), we use `typecase` because of its simplicity and not needing another system.  There's a slight performance hit here in the case of run-time determination of types, but until it's a problem prefer it.  Some alternatives considered for dispatch was https://github.com/pcostanza/filtered-functions.

### nu-statistics
These functions cover sample moments in detail, and are accurate.  They include up to forth moments, and are well suited to the work of an econometrist (and were written by one).

### cl-statistics
These were written by Larry Hunter, based on the methods described in Bernard Rosner's book, *Fundamentals of Biostatistics* 5th Edition, along with some from the [CLASP](https://www.cs.cmu.edu/afs/cs/project/ai-repository/ai/lang/lisp/code/math/clasp/0.html) system.  They cover a wide range of statistical applications.

### gwk-statistics
These are from Gary Warren King, and also partially based on CLASP.  It is well written, and the functions have excellent documentation.  The major reason we don't include it by default is because it uses an older ecosystem of libraries that duplicate more widely used system (for example, numerical utilities, alexandria).  If you want to use these, you'll need to uncomment the appropriate code in the ASDF and `pkgdcl.lisp` files.

### Accuracy
LH and GWK statistics compute quantiles, CDF, PDF, etc. using routines from CLASP, that in turn are based on algorithms from Numerical Recipes.  These are known to be accurate to only about four decimal places.   This is probably accurate enough for many statistical problem, however should you need greater accuracy look at the [distributions](https://github.com/Lisp-Stat/distributions) system.  The computations there are based on [special-functions](https://github.com/Lisp-Stat/special-functions), which has accuracy around 15 digits.  Unfortunately documentation of distributions and the 'wrapping' of them here are incomplete, so you'll need to know the pattern, e.g. pdf-gamma, cdf-gamma, etc., which is described in the link above.

### Versions
Because this system is likely to change rapidly, we have adopted a system of versioning proposed in [defpackage+](https://github.com/rpav/defpackage-plus#versioning).  This is also the system `alexandria` uses where a version number is appended to the API.  So, `statistics-1` is our current package name.  `statistics-2` will be the next and so on.  If you don't like these names, you can always change it locally using a [package local nickname](https://lispcookbook.github.io/cl-cookbook/packages.html#package-local-nicknames-pln).



## Installation
To get a local copy up and running follow these steps:

```lisp
(ql:quickload :statistics)
```
_or_

```lisp
(asdf:load-system :statistics)
```

If you already have the system downloaded to your local machine.

If you are using SBCL you will see a large number of notes printed
about the inability to optimise.  This was the subject of issue #1 and
the short answer is that the functions all take arbitrary inputs, do
input tests specific to the calculation, and then coerce and provide
declarations so that the actual calculations can be optimized.  So,
you should be able to ignore the notes.



## Usage

Create a data frame of weather data:

```lisp
(load #P"LS:DATA;sg-weather")
```
and take the mean maximum temperature:
```lisp
LS-USER> (statistics-1:mean sg-weather:max-temps)
```

For more examples, please refer to the [Documentation](https://lisp-stat.dev/docs/).

You can use a [package local
nickname](https://lispcookbook.github.io/cl-cookbook/packages.html#package-local-nicknames-pln)
to give the package a shorter name, e.g. "stats" if you like.

Often times all you'll need is lh-stats for general statistical
analysis.  You can load that with:
```
(asdf:load-system :statistics/lh)
```

**NB** You can expect to see many warnings when loading lh-stats.  These are expected and nothing to worry about.


## LH-Stat Functions

These abbreviations are used in function and variable names:
| abbreviation | meaning |
| --- | --- |
| ci  | confidence interval          |
| cdf | cumulative density function  |
| ge  | greater than or equal to     |
| le  | less than or equal to        |
| pdf | probability density function |
| sd  | standard deviation           |
| rxc | rows by columns              |
| sse | sample size estimate         |


### Descriptive statistics

- mean
- median
- mode
- geometric mean
- range
- percentile
- variance
- standard-deviation (sd)
- coefficient-of-variation
- standard-error-of-the-mean

### Distribution functions

- Poisson & Binomial
- binomial-probability
- binomial-cumulative-probability
- binomial-ge-probability
- poisson-probability
- poisson-cumulative-probability
- poisson-ge-probability
- normal
- normal-pdf
- convert-to-standard-normal
- phi
- z
- t-distribution
- chi-square
- chi-square-cdf

### Confidence Intervals

- binomial-probability-ci
- poisson-mu-ci
- normal-mean-ci
- normal-mean-ci-on-sequences
- normal-variance-ci
- normal-variance-ci-on-sequence
- normal-sd-ci

### Hypothesis tests (parametric)

- z-test
- z-test-on-sequence
- t-test-one-sample
- t-test-one-sample-on-sequence
- t-test-paired
- t-test-paired-on-sequences
- t-test-two-sample
- t-test-two-sample-on-sequences
- chi-square-test-one-sample
- f-test
- binomial-test-one-sample
- binomial-test-two-sample
- fisher-exact-test
- mcnemars-test
- poisson-test-one-sample

### Hypothesis tests (non-parametric)

- sign-test
- sign-test-on-sequence
- wilcoxon-signed-rank-test
- chi-square-test-rxc
- chi-square-test-for-trend

### Sample size estimates

- t-test-one-sample-sse
- t-test-two-sample-sse
- t-test-paired-sse
- binomial-test-one-sample-sse
- binomial-test-two-sample-sse
- binomial-test-paired-sse
- correlation-sse

### Correlation and Regression

- linear-regression
- correlation-coefficient
- correlation-test-two-sample
- spearman-rank-correlation

### Significance test functions

- t-significance
- f-significance (chi square significance is calculated from chi-square-cdf in various ways depending on the problem)

### Utilities

- random-sample
- random-pick
- bin-and-count
- fishers-z-transform
- mean-sd-n
- square
- choose
- permutations
- round-float



## Roadmap
gwk-stats has many useful functions. We'd like to port them to use the Lisp-Stat ecosystem of utilities.


## Resources

This system is part of the [Lisp-Stat](https://lisp-stat.dev/)
project; that should be your first stop for information. Also see the
[resources](https://lisp-stat.dev/resources) and
[community](https://lisp-stat.dev/community) pages for more
information.


## Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**. Please see [CONTRIBUTING](CONTRIBUTING.md) for details on the code of conduct and the process for submitting pull requests.


## Licenses

- Lisp-Stat: Microsoft Public License. See [LICENSE](LICENSE)
- LH Stats: MIT License. See [LH-LICENSE](LH-LICENSE)
- GWK-Stats: BSD-3-Clause. See [GWK-LICENSE](https://github.com/gwkkwg/cl-mathstats/blob/master/COPYING)

## CLASP Copyright
Copyright (c) 1990 - 1994 University of Massachusetts
Department of Computer Science
Experimental Knowledge Systems Laboratory
Professor Paul Cohen, Director.
All rights reserved.

Permission to use, copy, modify and distribute this software and its
documentation is hereby granted without fee, provided that the above
copyright notice of EKSL, this paragraph and the one following appear
in all copies and in supporting documentation.

EKSL makes no representation about the suitability of this software for any
purposes.  It is provided "AS IS", without express or implied warranties
including (but not limited to) all implied warranties of merchantability
and fitness for a particular purpose, and notwithstanding any other
provision contained herein.  In no event shall EKSL be liable for any
special, indirect or consequential damages whatsoever resulting from loss
of use, data or profits, whether in an action of contract, negligence or
other tortuous action, arising out of or in connection with the use or
performance of this software, even if EKSL is advised of the possibility of
such damages.



## Contact

Project Link: [https://github.com/lisp-stat/statistics](https://github.com/lisp-stat/statistics)





[contributors-shield]: https://img.shields.io/github/contributors/lisp-stat/statistics.svg?style=for-the-badge
[contributors-url]: https://github.com/lisp-stat/statistics/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/lisp-stat/statistics.svg?style=for-the-badge
[forks-url]: https://github.com/lisp-stat/statistics/network/members
[stars-shield]: https://img.shields.io/github/stars/lisp-stat/statistics.svg?style=for-the-badge
[stars-url]: https://github.com/lisp-stat/statistics/stargazers
[issues-shield]: https://img.shields.io/github/issues/lisp-stat/statistics.svg?style=for-the-badge
[issues-url]: https://github.com/lisp-stat/statistics/issues
[license-shield]: https://img.shields.io/github/license/lisp-stat/statistics.svg?style=for-the-badge
[license-url]: https://github.com/lisp-stat/statistics/blob/master/LICENSE
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://www.linkedin.com/company/symbolics/

alexandria

anaphora

distributions

let-plus

num-utils

org.tfeb.conduit-packages

This system is a consolidation of three Common Lisp statistics libraries:

- Tamas Papp's library, focusing on central moments
- Larry Hungers general statistical library
- Gary Warren King's (GWK) general statistical library, cl-mathstats

As of Q3 2022, CL-MATHSTATS is usable with Lisp-Stat, but not
incorporated.  This is due to it being rather deeply embedded into its
own ecosystem of utilities libraries (metatilities-base and
cl-containers and the lift test framework) that have in some cases
been superseded by alexandria, anaphora or numerical-utilities.  In
short, we recommend using CL-MATHSTATS when you need to, recognising
that you'll be hauling in a parallel system of math, statistics and
utilities.  Long term, we're working to port CL-MATHSTATS on a
case-by-case basis.


This is Larry Hunters statistics library.  It is a single file
system with no dependencies.  The formulas and methods used are
largely taken from Bernard Rosner, *Fundamentals of Biostatistics*,
5th edition.  "Rosner x" is a page number.  Some numeric functions
were taken from CLASP, a 1994 common lisp package that implemented
some of the statistical functions from "Numeric recipes in C".

Functions provided:

Descriptive statistics
 Mean, median, mode, geometric mean, range, percentile, variance,
 standard-deviation (sd), coefficient-of-variation,
 standard-error-of-the-mean

Distributional functions
 Poisson & Binomial
  binomial-probability, binomial-cumulative-probability,
  binomial-ge-probability, poisson-probability,
  poisson-cumulative-probability, poisson-ge-probability, Normal
  normal-pdf, convert-to-standard-normal, phi, z, t-distribution,
  chi-square, chi-square-cdf

Confidence Intervals

 binomial-probability-ci, poisson-mu-ci, normal-mean-ci,
 normal-mean-ci-on-sequences, normal-variance-ci,
 normal-variance-ci-on-sequence, normal-sd-ci

Hypothesis tests (parametric)
 z-test, z-test-on-sequence, t-test-one-sample,
 t-test-one-sample-on-sequence, t-test-paired,
 t-test-paired-on-sequences, t-test-two-sample,
 t-test-two-sample-on-sequences, chi-square-test-one-sample, f-test,
 binomial-test-one-sample, binomial-test-two-sample, fisher-exact-test,
 mcnemars-test, poisson-test-one-sample

Hypothesis tests (non-parametric)
 sign-test, sign-test-on-sequence, wilcoxon-signed-rank-test,
 chi-square-test-rxc, chi-square-test-for-trend

Sample size estimates
 t-test-one-sample-sse, t-test-two-sample-sse
 t-test-paired-sse, binomial-test-one-sample-sse,
 binomial-test-two-sample-sse,
 binomial-test-paired-sse, correlation-sse

Correlation and Regression
 linear-regression, correlation-coefficient,
 correlation-test-two-sample, spearman-rank-correlation

Significance test functions
 t-significance, f-significance (chi square significance is calculated
 from chi-square-cdf in various ways depending on the problem).

Utilities
 random-sample, random-pick, bin-and-count, fishers-z-transform,
 mean-sd-n, square, choose, permutations, round-float


statistics/lh

clunit2

Unit tests for Lisp-Stat's statistics system

statistics

Upstream URL

Author

License

statistics

Version:

License:

Authors:

Dependencies:

statistics/lh

Version:

License:

Authors:

Dependencies:

statistics/tests

Version:

License:

Authors:

Dependencies:

Dependencies (7)

Dependents (4)