histogram

README

histogram

Makes histograms.

Usage

Pass []float64 values to Hist, along with the number of bins you want:

bins := 9
data := []float64{
    0.1,
    0.2, 0.21, 0.22, 0.22,
    0.3,
    0.4,
    0.5, 0.51, 0.52, 0.53, 0.54, 0.55, 0.56, 0.57, 0.58,
    0.6,
    // 0.7 is empty
    0.8,
    0.9,
    1.0,
}

hist := Hist(bins, data)

Then use hist:

hist.Count // total values in buckets
hist.Min   // size of smallest bucket
hist.Max   // size of biggest bucket
for _, bkt := range hist.Buckets {
    // bkt.Min, bin.Max, bkt.Count
}

You can use the Fprint utility to create this Unicode graph (the graph looks better with fonts that draw unicode blocks properly):

0.1-0.2  5%   ▋1
0.2-0.3  25%  ██▊5
0.3-0.4  0%   ▏
0.4-0.5  5%   ▋1
0.5-0.6  45%  █████▏9
0.6-0.7  5%   ▋1
0.7-0.8  0%   ▏
0.8-0.9  5%   ▋1
0.9-1    10%  █▏2

Like this:

data := []float64{
    0.1,
    0.2, 0.21, 0.22, 0.22,
    0.3,
    0.4,
    0.5, 0.51, 0.52, 0.53, 0.54, 0.55, 0.56, 0.57, 0.58,
    0.6,
    // 0.7 is empty
    0.8,
    0.9,
    1.0,
}

bins := 9
hist := Hist(bins, data)

maxWidth := 5
err := Fprint(os.Stdout, hist, Linear(maxWidth))

You can pass your own Scale func if you want a Log scale instead of Linear.

Docs?

Godocs!

License

MIT license.

Documentation

Overview

Package histogram is a helper to quickly create histograms from slices of float64.

You can use it with any numeric value, given that you convert it back and forth to []float64.

Index

• func Fprint(w io.Writer, h Histogram, s ScaleFunc) error
• func Fprintf(w io.Writer, h Histogram, s ScaleFunc, f FormatFunc) error
• type Bucket
• type FormatFunc
• type Histogram
  • func Hist(bins int, input []float64) Histogram
  • func PowerHist(power float64, input []float64) Histogram
  • func (h Histogram) Scale(s ScaleFunc, idx int) float64
• type ScaleFunc
  • func Linear(width int) ScaleFunc

Examples

• Hist
• Hist (Duration)

Functions

func Fprint

func Fprint(w io.Writer, h Histogram, s ScaleFunc) error

Fprint prints a unicode histogram on the io.Writer, using scale s. This code:

hist := Hist(9, data)
err := Fprint(os.Stdout, hist, Linear(5))

... yields the graph:

0.1-0.2  5%   ▋1
0.2-0.3  25%  ██▋5
0.3-0.4  0%   ▏
0.4-0.5  5%   ▋1
0.5-0.6  50%  █████▏10
0.6-0.7  0%   ▏
0.7-0.8  0%   ▏
0.8-0.9  5%   ▋1
0.9-1    10%  █▏2

func Fprintf

func Fprintf(w io.Writer, h Histogram, s ScaleFunc, f FormatFunc) error

Fprintf is the same as Fprint, but applies f to the axis labels.

Types

type Bucket

type Bucket struct {
	// Count is the number of values represented in the bucket.
	Count int
	// Min is the low, inclusive bound of the bucket.
	Min float64
	// Max is the high, exclusive bound of the bucket. If
	// this bucket is the last bucket, the bound is inclusive
	// and contains the max value of the histogram.
	Max float64
}

Bucket counts a partion of values.

type FormatFunc

type FormatFunc func(v float64) string

FormatFunc formats a float into the proper string form. Used to print meaningful axe labels.

type Histogram

type Histogram struct {
	// Min is the size of the smallest bucket.
	Min int
	// Max is the size of the biggest bucket.
	Max int
	// Count is the total size of all buckets.
	Count int
	// Buckets over which values are partionned.
	Buckets []Bucket
}

Histogram holds a count of values partionned over buckets.

func Hist

func Hist(bins int, input []float64) Histogram

Hist creates an histogram partionning input over `bins` buckets.

Example

data := []float64{
	0.1,
	0.2, 0.21, 0.22, 0.22,
	0.3,
	0.4,
	0.5, 0.51, 0.52, 0.53, 0.54, 0.55, 0.56, 0.57, 0.58,
	0.6,
	// 0.7 is empty
	0.8,
	0.9,
	1.0,
}

hist := Hist(9, data)

if err := Fprint(os.Stdout, hist, Linear(5)); err != nil {
	panic(err)
}
// 0.1-0.2  5%   ▋       1
// 0.2-0.3  25%  ██▊     5
// 0.3-0.4  0%   ▏
// 0.4-0.5  5%   ▋       1
// 0.5-0.6  45%  █████▏  9
// 0.6-0.7  5%   ▋       1
// 0.7-0.8  0%   ▏
// 0.8-0.9  5%   ▋       1
// 0.9-1    10%  █▏      2

Example (Duration)

data := []float64{
	float64(time.Millisecond * 100),
	float64(time.Millisecond * 200),
	float64(time.Millisecond * 210),
	float64(time.Millisecond * 220),
	float64(time.Millisecond * 221),
	float64(time.Millisecond * 222),
	float64(time.Millisecond * 223),
	float64(time.Millisecond * 300),
	float64(time.Millisecond * 400),
	float64(time.Millisecond * 500),
	float64(time.Millisecond * 510),
	float64(time.Millisecond * 520),
	float64(time.Millisecond * 530),
	float64(time.Millisecond * 540),
	float64(time.Millisecond * 550),
	float64(time.Millisecond * 560),
	float64(time.Millisecond * 570),
	float64(time.Millisecond * 580),
	float64(time.Millisecond * 600),
	// no 0.7s
	float64(time.Millisecond * 800),
	float64(time.Millisecond * 900),
	float64(time.Millisecond * 1000),
}

hist := Hist(9, data)

err := Fprintf(os.Stdout, hist, Linear(5), func(v float64) string {
	return time.Duration(v).String()
})
if err != nil {
	panic(err)
}
// 100ms-200ms  4.55%  ▋       1
// 200ms-300ms  27.3%  ███▍    6
// 300ms-400ms  4.55%  ▋       1
// 400ms-500ms  4.55%  ▋       1
// 500ms-600ms  40.9%  █████▏  9
// 600ms-700ms  4.55%  ▋       1
// 700ms-800ms  0%     ▏
// 800ms-900ms  4.55%  ▋       1
// 900ms-1s     9.09%  █▏      2

func PowerHist

func PowerHist(power float64, input []float64) Histogram

PowerHist creates an histogram partionning input over buckets of power `pow`.

func (Histogram) Scale

func (h Histogram) Scale(s ScaleFunc, idx int) float64

Scale gives the scaled count of the bucket at idx, using the provided scale func.

type ScaleFunc

type ScaleFunc func(min, max, value int) float64

ScaleFunc is the type to implement to scale an histogram.

func Linear

func Linear(width int) ScaleFunc

Linear builds a ScaleFunc that will linearly scale the values of an histogram so that they do not exceed width.