README.md
1# Stats - Golang Statistics Package
2
3[![][travis-svg]][travis-url] [![][coveralls-svg]][coveralls-url] [![][goreport-svg]][goreport-url] [![][godoc-svg]][godoc-url] [![][pkggodev-svg]][pkggodev-url] [![][license-svg]][license-url]
4
5A well tested and comprehensive Golang statistics library / package / module with no dependencies.
6
7If you have any suggestions, problems or bug reports please [create an issue](https://github.com/montanaflynn/stats/issues) and I'll do my best to accommodate you. In addition simply starring the repo would show your support for the project and be very much appreciated!
8
9## Installation
10
11```
12go get github.com/montanaflynn/stats
13```
14
15## Example Usage
16
17All the functions can be seen in [examples/main.go](examples/main.go) but here's a little taste:
18
19```go
20// start with some source data to use
21data := []float64{1.0, 2.1, 3.2, 4.823, 4.1, 5.8}
22
23// you could also use different types like this
24// data := stats.LoadRawData([]int{1, 2, 3, 4, 5})
25// data := stats.LoadRawData([]interface{}{1.1, "2", 3})
26// etc...
27
28median, _ := stats.Median(data)
29fmt.Println(median) // 3.65
30
31roundedMedian, _ := stats.Round(median, 0)
32fmt.Println(roundedMedian) // 4
33```
34
35## Documentation
36
37The entire API documentation is available on [GoDoc.org](http://godoc.org/github.com/montanaflynn/stats) or [pkg.go.dev](https://pkg.go.dev/github.com/montanaflynn/stats).
38
39You can also view docs offline with the following commands:
40
41```
42# Command line
43godoc . # show all exported apis
44godoc . Median # show a single function
45godoc -ex . Round # show function with example
46godoc . Float64Data # show the type and methods
47
48# Local website
49godoc -http=:4444 # start the godoc server on port 4444
50open http://localhost:4444/pkg/github.com/montanaflynn/stats/
51```
52
53The exported API is as follows:
54
55```go
56var (
57 ErrEmptyInput = statsError{"Input must not be empty."}
58 ErrNaN = statsError{"Not a number."}
59 ErrNegative = statsError{"Must not contain negative values."}
60 ErrZero = statsError{"Must not contain zero values."}
61 ErrBounds = statsError{"Input is outside of range."}
62 ErrSize = statsError{"Must be the same length."}
63 ErrInfValue = statsError{"Value is infinite."}
64 ErrYCoord = statsError{"Y Value must be greater than zero."}
65)
66
67func Round(input float64, places int) (rounded float64, err error) {}
68
69type Float64Data []float64
70
71func LoadRawData(raw interface{}) (f Float64Data) {}
72
73func AutoCorrelation(data Float64Data, lags int) (float64, error) {}
74func ChebyshevDistance(dataPointX, dataPointY Float64Data) (distance float64, err error) {}
75func Correlation(data1, data2 Float64Data) (float64, error) {}
76func Covariance(data1, data2 Float64Data) (float64, error) {}
77func CovariancePopulation(data1, data2 Float64Data) (float64, error) {}
78func CumulativeSum(input Float64Data) ([]float64, error) {}
79func Entropy(input Float64Data) (float64, error) {}
80func EuclideanDistance(dataPointX, dataPointY Float64Data) (distance float64, err error) {}
81func GeometricMean(input Float64Data) (float64, error) {}
82func HarmonicMean(input Float64Data) (float64, error) {}
83func InterQuartileRange(input Float64Data) (float64, error) {}
84func ManhattanDistance(dataPointX, dataPointY Float64Data) (distance float64, err error) {}
85func Max(input Float64Data) (max float64, err error) {}
86func Mean(input Float64Data) (float64, error) {}
87func Median(input Float64Data) (median float64, err error) {}
88func MedianAbsoluteDeviation(input Float64Data) (mad float64, err error) {}
89func MedianAbsoluteDeviationPopulation(input Float64Data) (mad float64, err error) {}
90func Midhinge(input Float64Data) (float64, error) {}
91func Min(input Float64Data) (min float64, err error) {}
92func MinkowskiDistance(dataPointX, dataPointY Float64Data, lambda float64) (distance float64, err error) {}
93func Mode(input Float64Data) (mode []float64, err error) {}
94func NormBoxMullerRvs(loc float64, scale float64, size int) []float64 {}
95func NormCdf(x float64, loc float64, scale float64) float64 {}
96func NormEntropy(loc float64, scale float64) float64 {}
97func NormFit(data []float64) [2]float64{}
98func NormInterval(alpha float64, loc float64, scale float64 ) [2]float64 {}
99func NormIsf(p float64, loc float64, scale float64) (x float64) {}
100func NormLogCdf(x float64, loc float64, scale float64) float64 {}
101func NormLogPdf(x float64, loc float64, scale float64) float64 {}
102func NormLogSf(x float64, loc float64, scale float64) float64 {}
103func NormMean(loc float64, scale float64) float64 {}
104func NormMedian(loc float64, scale float64) float64 {}
105func NormMoment(n int, loc float64, scale float64) float64 {}
106func NormPdf(x float64, loc float64, scale float64) float64 {}
107func NormPpf(p float64, loc float64, scale float64) (x float64) {}
108func NormPpfRvs(loc float64, scale float64, size int) []float64 {}
109func NormSf(x float64, loc float64, scale float64) float64 {}
110func NormStats(loc float64, scale float64, moments string) []float64 {}
111func NormStd(loc float64, scale float64) float64 {}
112func NormVar(loc float64, scale float64) float64 {}
113func Pearson(data1, data2 Float64Data) (float64, error) {}
114func Percentile(input Float64Data, percent float64) (percentile float64, err error) {}
115func PercentileNearestRank(input Float64Data, percent float64) (percentile float64, err error) {}
116func PopulationVariance(input Float64Data) (pvar float64, err error) {}
117func Sample(input Float64Data, takenum int, replacement bool) ([]float64, error) {}
118func SampleVariance(input Float64Data) (svar float64, err error) {}
119func Sigmoid(input Float64Data) ([]float64, error) {}
120func SoftMax(input Float64Data) ([]float64, error) {}
121func StableSample(input Float64Data, takenum int) ([]float64, error) {}
122func StandardDeviation(input Float64Data) (sdev float64, err error) {}
123func StandardDeviationPopulation(input Float64Data) (sdev float64, err error) {}
124func StandardDeviationSample(input Float64Data) (sdev float64, err error) {}
125func StdDevP(input Float64Data) (sdev float64, err error) {}
126func StdDevS(input Float64Data) (sdev float64, err error) {}
127func Sum(input Float64Data) (sum float64, err error) {}
128func Trimean(input Float64Data) (float64, error) {}
129func VarP(input Float64Data) (sdev float64, err error) {}
130func VarS(input Float64Data) (sdev float64, err error) {}
131func Variance(input Float64Data) (sdev float64, err error) {}
132
133type Coordinate struct {
134 X, Y float64
135}
136
137type Series []Coordinate
138
139func ExponentialRegression(s Series) (regressions Series, err error) {}
140func LinearRegression(s Series) (regressions Series, err error) {}
141func LogarithmicRegression(s Series) (regressions Series, err error) {}
142
143type Outliers struct {
144 Mild Float64Data
145 Extreme Float64Data
146}
147
148type Quartiles struct {
149 Q1 float64
150 Q2 float64
151 Q3 float64
152}
153
154func Quartile(input Float64Data) (Quartiles, error) {}
155func QuartileOutliers(input Float64Data) (Outliers, error) {}
156```
157
158## Contributing
159
160Pull request are always welcome no matter how big or small. I've included a [Makefile](https://github.com/montanaflynn/stats/blob/master/Makefile) that has a lot of helper targets for common actions such as linting, testing, code coverage reporting and more.
161
1621. Fork the repo and clone your fork
1632. Create new branch (`git checkout -b some-thing`)
1643. Make the desired changes
1654. Ensure tests pass (`go test -cover` or `make test`)
1665. Run lint and fix problems (`go vet .` or `make lint`)
1676. Commit changes (`git commit -am 'Did something'`)
1687. Push branch (`git push origin some-thing`)
1698. Submit pull request
170
171To make things as seamless as possible please also consider the following steps:
172
173- Update `examples/main.go` with a simple example of the new feature
174- Update `README.md` documentation section with any new exported API
175- Keep 100% code coverage (you can check with `make coverage`)
176- Squash commits into single units of work with `git rebase -i new-feature`
177
178## Releasing
179
180To release a new version we should update the [CHANGELOG.md](/CHANGELOG.md) and [DOCUMENTATION.md](/DOCUMENTATION.md).
181
182First install the tools used to generate the markdown files:
183
184```
185go get github.com/davecheney/godoc2md
186go get github.com/golangci/golangci-lint/cmd/golangci-lint
187```
188
189Then you can run these `make` directives:
190
191```
192# Generate DOCUMENTATION.md
193make docs
194```
195
196Then we can create a [CHANGELOG.md](/CHANGELOG.md) a new git tag and a github release:
197
198```
199make release TAG=v0.x.x
200```
201
202## MIT License
203
204Copyright (c) 2014-2021 Montana Flynn (https://montanaflynn.com)
205
206Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
207
208The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
209
210THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORpublicS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
211
212[travis-url]: https://travis-ci.org/montanaflynn/stats
213[travis-svg]: https://img.shields.io/travis/montanaflynn/stats.svg
214
215[coveralls-url]: https://coveralls.io/r/montanaflynn/stats?branch=master
216[coveralls-svg]: https://img.shields.io/coveralls/montanaflynn/stats.svg
217
218[goreport-url]: https://goreportcard.com/report/github.com/montanaflynn/stats
219[goreport-svg]: https://goreportcard.com/badge/github.com/montanaflynn/stats
220
221[godoc-url]: https://godoc.org/github.com/montanaflynn/stats
222[godoc-svg]: https://godoc.org/github.com/montanaflynn/stats?status.svg
223
224[pkggodev-url]: https://pkg.go.dev/github.com/montanaflynn/stats
225[pkggodev-svg]: https://gistcdn.githack.com/montanaflynn/b02f1d78d8c0de8435895d7e7cd0d473/raw/17f2a5a69f1323ecd42c00e0683655da96d9ecc8/badge.svg
226
227[license-url]: https://github.com/montanaflynn/stats/blob/master/LICENSE
228[license-svg]: https://img.shields.io/badge/license-MIT-blue.svg
229