flesh out docs and pass golint

This commit is contained in:
Stephen McQuay 2016-07-31 22:41:04 -07:00
parent 78387b0284
commit 3ed4a9e467
No known key found for this signature in database
GPG Key ID: 1ABF428F71BAFC3D
1 changed files with 22 additions and 7 deletions

View File

@ -1,6 +1,6 @@
// ostat is a go package that implements the efficient, accurate, and stable
// calculation of online statistical quantities. The algorithm comes from *The
// Art of Computer Programing*, vol 2 by Knuth
// Package ostat is a go package that implements the efficient, accurate, and
// stable calculation of online statistical quantities. The algorithm comes
// from *The Art of Computer Programing*, vol 2 by Knuth
package ostat
import (
@ -20,6 +20,7 @@ const (
Sample
)
// OnlineStat keeps track of online statistics.
type OnlineStat struct {
n uint64
mean float64
@ -29,6 +30,10 @@ type OnlineStat struct {
typ uint64
}
// NewSampleStat returns a ready-to-use OnlineStat for calculating sample
// statistics.
//
// For the distinction between NewSampleStat and NewPopulationStat please refer to https://en.wikipedia.org/wiki/Statistical_population
func NewSampleStat() *OnlineStat {
return &OnlineStat{
Min: math.Inf(1),
@ -37,6 +42,10 @@ func NewSampleStat() *OnlineStat {
}
}
// NewPopulationStat returns a ready-to-use OnlineStat for calculating
// population statistics.
//
// For the distinction between NewSampleStat and NewPopulationStat please refer to https://en.wikipedia.org/wiki/Statistical_population
func NewPopulationStat() *OnlineStat {
return &OnlineStat{
Min: math.Inf(1),
@ -45,6 +54,9 @@ func NewPopulationStat() *OnlineStat {
}
}
// MidStreamStat populates an OnlineStat such that it can pick up where
// a previous one left off.
//
// Let's say you have already stored some values and want to start an
// OnlineStat mid-stream; This is the function for you! Just provide it with
// the data in the sinature, and you'll get a properly initialized OnlineStat.
@ -60,9 +72,9 @@ func MidStreamStat(n uint64, mean, stddev, min, max float64, typ uint64) *Online
}
}
// this is how you feed new values into your OnlineStat.
// Push is how you feed new values into an OnlineStat.
func (os *OnlineStat) Push(v float64) {
os.n += 1
os.n++
if v < os.Min {
os.Min = v
}
@ -75,7 +87,7 @@ func (os *OnlineStat) Push(v float64) {
os.m2 = os.m2 + delta*(v-os.mean)
}
// http://en.wikipedia.org/wiki/Expected_value
// Mean as defined by http://en.wikipedia.org/wiki/Expected_value.
func (os *OnlineStat) Mean() float64 {
if os.n == 0 {
return 0.0
@ -83,7 +95,7 @@ func (os *OnlineStat) Mean() float64 {
return os.mean
}
// http://en.wikipedia.org/wiki/Variance
// Variance as defined by http://en.wikipedia.org/wiki/Variance
func (os *OnlineStat) Variance() float64 {
if os.n == 0 {
return 0.0
@ -91,6 +103,7 @@ func (os *OnlineStat) Variance() float64 {
return os.m2 / float64(os.n-os.typ)
}
// StdDev is the standard deviation as defined by
// http://en.wikipedia.org/wiki/Variance
func (os *OnlineStat) StdDev() float64 {
return math.Sqrt(os.Variance())
@ -105,6 +118,7 @@ func (os *OnlineStat) CI() (float64, float64) {
return os.mean - dev*conf, os.mean + dev*conf
}
// N returns how many values have been Pushed into an OnlineStat.
func (os *OnlineStat) N() uint64 {
return os.n
}
@ -130,6 +144,7 @@ func (os *OnlineStat) String() string {
)
}
// MarshalJSON is implemented for convenient encoding to json.
func (os *OnlineStat) MarshalJSON() ([]byte, error) {
s := struct {
N uint64 `json:"n"`