From 0521929449e0137adf08a70beafabfaea90ddec9 Mon Sep 17 00:00:00 2001 From: Vincent Bernat Date: Wed, 14 Dec 2016 14:46:41 +0100 Subject: [PATCH] Document the argument expected for percentile-related functions Some people (notably me) would expect to provide a percentile as the P-th percentile. For example, to get the 75th percentile, I would use m.Percentile(75). However, the correct use is m.Percentile(0.75). This commit just adds an example to each percentile-related function to avoid this error. --- histogram.go | 9 +++++---- sample.go | 19 +++++++++++-------- timer.go | 9 +++++---- 3 files changed, 21 insertions(+), 16 deletions(-) diff --git a/histogram.go b/histogram.go index dbc837f..9df3dc5 100644 --- a/histogram.go +++ b/histogram.go @@ -72,13 +72,13 @@ func (h *HistogramSnapshot) Mean() float64 { return h.sample.Mean() } func (h *HistogramSnapshot) Min() int64 { return h.sample.Min() } // Percentile returns an arbitrary percentile of values in the sample at the -// time the snapshot was taken. +// time the snapshot was taken. To get the 75th percentile, use 0.75. func (h *HistogramSnapshot) Percentile(p float64) float64 { return h.sample.Percentile(p) } // Percentiles returns a slice of arbitrary percentiles of values in the sample -// at the time the snapshot was taken. +// at the time the snapshot was taken. To get the 75th percentile, use 0.75. func (h *HistogramSnapshot) Percentiles(ps []float64) []float64 { return h.sample.Percentiles(ps) } @@ -170,13 +170,14 @@ func (h *StandardHistogram) Mean() float64 { return h.sample.Mean() } // Min returns the minimum value in the sample. func (h *StandardHistogram) Min() int64 { return h.sample.Min() } -// Percentile returns an arbitrary percentile of the values in the sample. +// Percentile returns an arbitrary percentile of the values in the +// sample. To get the 75th percentile, use 0.75. func (h *StandardHistogram) Percentile(p float64) float64 { return h.sample.Percentile(p) } // Percentiles returns a slice of arbitrary percentiles of the values in the -// sample. +// sample. To get the 75th percentile, use 0.75. func (h *StandardHistogram) Percentiles(ps []float64) []float64 { return h.sample.Percentiles(ps) } diff --git a/sample.go b/sample.go index fecee5e..f471206 100644 --- a/sample.go +++ b/sample.go @@ -94,13 +94,14 @@ func (s *ExpDecaySample) Min() int64 { return SampleMin(s.Values()) } -// Percentile returns an arbitrary percentile of values in the sample. +// Percentile returns an arbitrary percentile of values in the +// sample. To get the 75th percentile, use 0.75. func (s *ExpDecaySample) Percentile(p float64) float64 { return SamplePercentile(s.Values(), p) } // Percentiles returns a slice of arbitrary percentiles of values in the -// sample. +// sample. To get the 75th percentile, use 0.75. func (s *ExpDecaySample) Percentiles(ps []float64) []float64 { return SamplePercentiles(s.Values(), ps) } @@ -268,13 +269,14 @@ func SampleMin(values []int64) int64 { return min } -// SamplePercentiles returns an arbitrary percentile of the slice of int64. +// SamplePercentiles returns an arbitrary percentile of the slice of +// int64. To get the 75th percentile, use 0.75. func SamplePercentile(values int64Slice, p float64) float64 { return SamplePercentiles(values, []float64{p})[0] } // SamplePercentiles returns a slice of arbitrary percentiles of the slice of -// int64. +// int64. To get the 75th percentile, use 0.75. func SamplePercentiles(values int64Slice, ps []float64) []float64 { scores := make([]float64, len(ps)) size := len(values) @@ -327,13 +329,13 @@ func (s *SampleSnapshot) Mean() float64 { return SampleMean(s.values) } func (s *SampleSnapshot) Min() int64 { return SampleMin(s.values) } // Percentile returns an arbitrary percentile of values at the time the -// snapshot was taken. +// snapshot was taken. To get the 75th percentile, use 0.75. func (s *SampleSnapshot) Percentile(p float64) float64 { return SamplePercentile(s.values, p) } // Percentiles returns a slice of arbitrary percentiles of values at the time -// the snapshot was taken. +// the snapshot was taken. To get the 75th percentile, use 0.75. func (s *SampleSnapshot) Percentiles(ps []float64) []float64 { return SamplePercentiles(s.values, ps) } @@ -455,7 +457,8 @@ func (s *UniformSample) Min() int64 { return SampleMin(s.values) } -// Percentile returns an arbitrary percentile of values in the sample. +// Percentile returns an arbitrary percentile of values in the +// sample. To get the 75th percentile, use 0.75. func (s *UniformSample) Percentile(p float64) float64 { s.mutex.Lock() defer s.mutex.Unlock() @@ -463,7 +466,7 @@ func (s *UniformSample) Percentile(p float64) float64 { } // Percentiles returns a slice of arbitrary percentiles of values in the -// sample. +// sample. To get the 75th percentile, use 0.75. func (s *UniformSample) Percentiles(ps []float64) []float64 { s.mutex.Lock() defer s.mutex.Unlock() diff --git a/timer.go b/timer.go index 17db8f8..506734c 100644 --- a/timer.go +++ b/timer.go @@ -155,13 +155,14 @@ func (t *StandardTimer) Min() int64 { return t.histogram.Min() } -// Percentile returns an arbitrary percentile of the values in the sample. +// Percentile returns an arbitrary percentile of the values in the +// sample. To get the 75th percentile, use 0.75. func (t *StandardTimer) Percentile(p float64) float64 { return t.histogram.Percentile(p) } // Percentiles returns a slice of arbitrary percentiles of the values in the -// sample. +// sample. To get the 75th percentile, use 0.75. func (t *StandardTimer) Percentiles(ps []float64) []float64 { return t.histogram.Percentiles(ps) } @@ -254,13 +255,13 @@ func (t *TimerSnapshot) Mean() float64 { return t.histogram.Mean() } func (t *TimerSnapshot) Min() int64 { return t.histogram.Min() } // Percentile returns an arbitrary percentile of sampled values at the time the -// snapshot was taken. +// snapshot was taken. To get the 75th percentile, use 0.75. func (t *TimerSnapshot) Percentile(p float64) float64 { return t.histogram.Percentile(p) } // Percentiles returns a slice of arbitrary percentiles of sampled values at -// the time the snapshot was taken. +// the time the snapshot was taken. To get the 75th percentile, use 0.75. func (t *TimerSnapshot) Percentiles(ps []float64) []float64 { return t.histogram.Percentiles(ps) }