stat

type Bucket ¶

type Bucket struct {
	Lo, Hi float64
	Count  int
}

Bucket is one bin of a histogram: the interval it covers and how many observations fell in it.

The interval is half open, [Lo, Hi), except for the last bucket of a run, which includes its upper bound — otherwise the largest observation in a column would fall in no bucket at all, which is the one value a reader is certain to look for.

func AppendBin(dst []Bucket, vs []float64, lo, hi float64, n int) []Bucket

func Bin(vs []float64, lo, hi float64, n int) []Bucket

func (b Bucket) Mid() float64

type Cell ¶

type Cell struct {
	Col, Row int
	X, Y     float64
	Count    uint32
}

Cell is one populated hexagon: where it is and how many rows landed in it.

type Chord ¶

type Chord struct {
	// Arcs has one span per node, in node order. A node no edge touches gets an
	// empty span rather than being dropped, so a caller can index Arcs by node.
	Arcs []Span
	// Ribbons has one entry per edge, in the order the edges were given.
	Ribbons []Ribbon
	// contains filtered or unexported fields
}

Chord lays an edge list out around the unit interval: one arc per node, sized by the traffic through it, and one ribbon per edge joining a slice of one arc to a slice of another.

Wrapped round a circle by a polar coord this is a chord diagram; left straight under a Cartesian one it is an arc diagram, whose edges rise off a rail instead of crossing a disc. The layout does not know which — it works in the unit interval and the coordinate system decides what that looks like.

It is a struct with a Chord.Reset rather than a pair of functions for the reason Sankey and Hex are: the layout keeps a cursor per node, and a chart redrawn every frame should reuse it rather than allocate it again.

Order ¶

Arcs go round in node order and ribbons leave them in edge order, both of which are the order the caller's rows appeared in. Nothing here sorts, and nothing here reads a map: the picture is a pure function of the table (docs/adr/0012-parallel-panels.md). A caller that wants the busiest node first sorts its own rows.

The zero Chord is unusable; call Chord.Reset first.

func (c *Chord) Reset(from, to []int, value []float64, nodes int, pad float64)

type Contour ¶ added in v0.10.0

type Contour struct {
	// Lines has one run per connected piece of an isoline: grouped by level in
	// ascending order, and within a level in the order the runs were found,
	// which is lattice order. Nothing here depends on a map's iteration order —
	// see the package documentation on determinism.
	Lines []Isoline
	// Points is the vertex arena every run indexes, in the coordinates the
	// lattice was given. A geom maps them through its scales exactly as it maps
	// a row.
	Points []Point
	// Levels is the list the runs were traced at, ascending and with any
	// repeats removed.
	Levels []float64
	// contains filtered or unexported fields
}

Contour traces the isolines of a value sampled on a regular lattice, by marching squares.

It is one tracing serving two charts. A flat contour plot strokes what it returns through the panel's scales; a projected scene strokes the same runs on the floor of its cube. Handed one level list they are the same lines, and that is the point: a reading taken off the plan and a reading taken off the floor of the surface have to agree, and two implementations of marching squares would agree until the first saddle.

It is a struct with a Contour.Reset rather than a pair of functions because its working state is the size of the data, which is Hex's reason and Sankey's. It is not generic over float32, and that is a decision rather than an omission: a reduction is generic so that a geom can run it on projected device coordinates, and a contour runs in Train, in data space, where there is no float32 caller.

The zero Contour is unusable; call Contour.Reset first. Reset keeps the arena and the working tables.

func (c *Contour) Line(l Isoline) []Point

func (c *Contour) Reset(xs, ys, z []float64, levels []float64)

type Extent ¶ added in v0.10.0

type Extent struct {
	X0, X1, Y0, Y1 float64
	Steps          int
}

Extent is the region of data space a curve is drawn over, and how finely.

The bounds are the panel's own domains, ascending. They are what a repeating family needs in order to know how many times to repeat, and what an unbounded one needs in order to know where to stop; a family whose curves are bounded — a VSWR circle is a circle whatever the axes say — ignores them. Steps is how many samples the panel is wide enough to be worth, which is a question about the screen and is therefore answered when the chart is drawn rather than when its axes are trained.

An empty extent is legitimate: it is what a family is handed before the domains exist, and every family answers it with a curve rather than with nothing.

type Family ¶ added in v0.10.0

type Family interface {
	Locus(xs, ys []float64, level float64, ext Extent) ([]float64, []float64)
}

Family is one indexed set of curves in data space.

Given a level and the panel's extent, Locus appends the data-space points of that level's curve to xs and ys and returns the extended slices. Both are appended to in lockstep and come back the same length; the caller owns them and truncates them, which is what keeps a chart redrawn every frame from allocating a curve every frame.

A curve that leaves the extent and comes back, or that repeats — a Nichols family repeats every 360° of phase — appends NaN between its runs, which is the gap every mark in figure already understands.

Stability ¶

Family is implemented outside this module, so it never gains a method, and the extent it is handed is a struct for the same reason — ADR 0060. The four families below are values rather than functions so that each has a name that can be written down: FamilyName reports it, FamilyNamed reads it back, and a family a caller wrote in Go has neither and does not serialise.

var (
	// NicholsM is the locus of constant closed-loop magnitude |T|, and its
	// level is that magnitude in decibels. It is what the resonance peak M_r is
	// read off. The 0 dB member is the perpendicular bisector of the origin and
	// the critical point rather than a circle, which is the one degenerate case
	// in either Nichols family.
	NicholsM Family = nameNicholsM

	// NicholsN is the locus of constant closed-loop phase ∠T, and its level is
	// that phase in degrees. Every member passes through L = 0 and through
	// L = −1, which is why the contours all converge on the critical point and
	// why each one plunges to −∞ dB where it passes through the origin — a
	// place no scale can put, and the missing-value policy has covered that
	// since v0.1. The 0° and 180° members are the real axis itself and are not
	// drawn.
	NicholsN Family = nameNicholsN

	// SmithVSWR is the locus of constant reflection magnitude, and its level is
	// the standing-wave ratio the chart is read in: 1.5, 2, 3. A level of 1 is a
	// matched load, which is the middle of the chart and a point rather than a
	// curve, so it draws nothing.
	SmithVSWR Family = nameSmithVSWR

	// SmithQ is the locus of constant reactance-to-resistance ratio |x| = Q·r,
	// and its level is Q. It is two straight rays in impedance, so it is two
	// arcs on the disc, by the coord's own map and with no second
	// implementation. They run to an infinite impedance, which is the rim.
	SmithQ Family = nameSmithQ
)

func FamilyNamed(name string) (Family, bool)

type Float ¶

type Float interface{ ~float32 | ~float64 }

Float is the coordinate type these functions accept.

Both widths are here because both are real: a geom decimates in device space, where coordinates are float32 and a pixel is the unit that matters, while a caller aggregating before it ever reaches a chart has float64 data. Converting one to the other to cross this boundary would cost a copy of the whole column.

type Grid ¶

type Grid struct {
	// Cols and Rows are the grid's shape.
	Cols, Rows int
	// X0, Y0, X1, Y1 are the region the grid covers. X0 may exceed X1, and Y0
	// may exceed Y1: a device-space Y axis runs downwards, and a grid over it
	// has to bin the same way round as the axis it covers.
	X0, Y0, X1, Y1 float64

	// Counts holds Cols*Rows cells in row-major order.
	Counts []uint32
	// Max is the busiest cell's count, and N the number of rows binned.
	Max uint32
	N   int
}

Grid is a two-dimensional histogram: how many rows fall in each cell of a regular grid over a rectangle.

It is the aggregate behind the density raster. A scatter of ten million points has no honest drawing as ten million markers — they overplot, the last one drawn wins, and the picture says more about row order than about the data. Counting per cell and painting the counts says how many rows are there, which is the thing the marks were standing in for.

The zero Grid is unusable; call Grid.Reset first. Reset keeps the count buffer, so a chart redrawn every frame bins into the same memory.

func BinGrid[F Float](g *Grid, xs, ys []F) *Grid

func (g *Grid) Add(x, y float64) bool

func (g *Grid) At(col, row int) uint32

func (g *Grid) Cell(x, y float64) (col, row int, ok bool)

func (g *Grid) Fraction(count uint32, s Scaling) float64

func (g *Grid) Raster(dst *image.NRGBA, s Scaling, paint func(t float64) color.NRGBA) *image.NRGBA

func (g *Grid) Reset(cols, rows int, x0, y0, x1, y1 float64)

type Hex ¶

type Hex struct {
	// Radius is a cell's circumradius: the distance from its centre to a
	// vertex, and half its height.
	Radius float64
	// Cols and Rows are the lattice's shape.
	Cols, Rows int
	// X0 and Y0 are the centre of cell (0, 0).
	X0, Y0 float64

	// MinX, MinY, MaxX and MaxY are the rectangle the lattice covers,
	// normalised so that the minimum is the lower corner on both axes. A
	// device-space Y axis runs downwards and a caller may hand the two corners
	// over in either order; a hexagonal lattice is symmetric about both, so
	// which way round it was given changes nothing but which points are inside.
	MinX, MinY, MaxX, MaxY float64

	// Counts holds Cols*Rows cells in row-major order.
	Counts []uint32
	// Max is the busiest cell's count, and N the number of rows binned.
	Max uint32
	N   int
}

Hex is a hexagonal lattice over a rectangle: how many rows fall in each hexagonal cell.

It is Grid with a better tiling. A square grid has four neighbours at one distance and four at another, so a cloud binned into it grows faint crosses and diagonal seams that are artefacts of the bins rather than features of the data; a hexagon has six neighbours all the same distance away, which is why this is the aggregate a hexbin chart is made of. The other difference is what is drawn: a density raster paints one pixel per cell, and a hexbin draws a mark per cell, so the cells are counted in the hundreds rather than in the hundreds of thousands.

The lattice is pointy-topped: a cell is 2·Radius tall and √3·Radius wide, rows are 1.5·Radius apart, and odd rows are offset half a cell to the right.

The zero Hex is unusable; call Hex.Reset first. Reset keeps the count buffer, so a chart redrawn every frame bins into the same memory.

func BinHex[F Float](h *Hex, xs, ys []F) *Hex

func (h *Hex) Add(x, y float64) bool

func (h *Hex) At(col, row int) uint32

func (h *Hex) Cell(x, y float64) (col, row int, ok bool)

func (h *Hex) Cells(dst []Cell) []Cell

func (h *Hex) Center(col, row int) (x, y float64)

func (h *Hex) Fraction(count uint32, s Scaling) float64

func (h *Hex) Reset(radius, x0, y0, x1, y1 float64)

type Isoline ¶ added in v0.10.0

type Isoline struct {
	// Level is the value the run traces, and Index its position in
	// [Contour.Levels] — so a caller colouring by level does not have to search
	// for it.
	Level float64
	Index int
	// Lo and Hi bound the run in [Contour.Points]. Reach for [Contour.Line].
	Lo, Hi int
	// Closed reports a ring: the run's last point is exactly its first. An open
	// run begins and ends on the edge of the lattice or at a hole, so this is a
	// statement about the points rather than about where the run stopped.
	Closed bool
}

Isoline is one connected run of one contour level.

It is a range into the Contour's point arena rather than a slice of its own, so a chart redrawn every frame refills one buffer instead of allocating a slice per line. Sankey.Flows has the same shape for the same reason.

type Lattice ¶ added in v0.10.0

type Lattice struct {
	// Xs and Ys are the sorted distinct values of the two axes.
	Xs, Ys []float64
	// V holds len(Ys) rows of len(Xs) values, row-major in y: the value at
	// (Xs[i], Ys[j]) is V[j*len(Xs)+i], which is [Lattice.Index].
	V []float64
	// Row is the source row behind each cell, in the same order, or -1 for a
	// cell no row reached — which happens only when Fault is not [LatticeOK].
	Row []int32

	// Fault says whether the table was a lattice, and At and With name the rows
	// a [LatticeOffGrid] or [LatticeDuplicate] is about so that a caller can
	// point its message at the data.
	Fault    LatticeFault
	At, With int
	// contains filtered or unexported fields
}

Lattice turns a long table of (x, y, v) rows into a regular grid.

It is the shape a surface, a contour and a raster of a measured field all need, and it is one implementation rather than one each because two resolvers that agree today disagree at the first duplicated position — and the symptom of that is a surface and its own contours that do not line up.

The grid is required rather than guessed. The rows must be the full product of the distinct x and y values with each cell present exactly once, and anything else is a LatticeFault rather than a picture with holes in it: a field drawn over a scattered sample is a field over a triangulation nobody asked for. A cell whose value is NaN is a different matter and is allowed — that is a hole in the data, and a mark decides for itself what to do with one.

The zero Lattice is unusable; call Lattice.Reset first. Reset keeps the buffers and clears the index maps rather than replacing them, so their buckets survive too — which is what keeps a chart redrawn every frame from allocating per frame.

func (l *Lattice) Index(i, j int) int

func (l *Lattice) Reset(xs, ys, vs []float64) LatticeFault

func (l *Lattice) Value(i, j int) float64

type LatticeFault ¶ added in v0.10.0

type LatticeFault uint8

LatticeFault says why a table is not a product lattice.

It is a code rather than an error because a useful message names a column and a mark, and this package knows about numbers and nothing else. The caller spells the sentence; this says which one. Sankey.Cyclic is the same trade.

const (
	// LatticeOK is a table that is a lattice.
	LatticeOK LatticeFault = iota
	// LatticeRagged is three columns of different lengths.
	LatticeRagged
	// LatticeTooSmall is fewer than two distinct values on one of the axes.
	// One value is a line rather than a grid, and no surface, contour or image
	// can be drawn over it.
	LatticeTooSmall
	// LatticeWrongCount is a table with a number of rows that is not the
	// product of the two axes' distinct values, which means cells are missing
	// or repeated whatever the positions say.
	LatticeWrongCount
	// LatticeBadPosition is a row whose x or y is not a finite number.
	// [Lattice.At] is the row.
	//
	// It is checked rather than discovered, because the axes are the distinct
	// values of the columns themselves — so every row is at a node of the
	// lattice by construction, and the only position that is not one is a
	// position that is not a number.
	LatticeBadPosition
	// LatticeDuplicate is two rows at one node. [Lattice.At] and [Lattice.With]
	// are the two.
	LatticeDuplicate
)

type Point ¶

type Point struct{ X, Y float64 }

Point is a position a distribution stat computed: a bin's centre and its count, a density's argument and its value, a fit's abscissa and its estimate.

It is float64 and not ir.Point because none of it is a device coordinate — stat knows about numbers and nothing else, and a density evaluated in float32 would lose the tail of a narrow kernel.

func AppendECDF(dst []Point, sorted []float64) []Point

func AppendKDE(dst []Point, vs []float64, bw, lo, hi float64, n int) []Point

func AppendLoess(dst []Point, xs, ys []float64, span float64, n int) []Point

func AppendQQ(dst []Point, sorted []float64, quantile func(float64) float64) []Point

func ECDF(sorted []float64) []Point

func KDE(vs []float64, bw, lo, hi float64, n int) []Point

func Loess(xs, ys []float64, span float64, n int) []Point

func QQ(sorted []float64, quantile func(float64) float64) []Point

func Vertices(dst []Point, cx, cy, radius float64) []Point

type Ribbon ¶

type Ribbon struct {
	Src, Dst Span
}

Ribbon is one edge's two ends: the span it takes on its source's arc and the span it takes on its target's. The two are the same width, because they are the same quantity read twice — which is exactly what a chord diagram asserts and what tells it apart from two bar charts side by side.

type Sankey ¶

type Sankey struct {
	// Nodes has one entry per node, indexed as the caller's edge list indexes
	// them.
	Nodes []SankeyNode
	// Flows has one entry per link, in the order the links were given.
	Flows []SankeyFlow

	// Layers is how many columns the diagram has, and Cyclic reports an edge
	// list that is not a DAG — in which case Nodes and Flows are empty, because
	// a flow that returns to where it came from has no column to stand in.
	Layers int
	Cyclic bool
	// contains filtered or unexported fields
}

Sankey lays an edge list out as a flow diagram: nodes in columns, links as bands whose thickness is their value.

It is a struct with a Sankey.Reset rather than a pair of functions because the layout has working state the size of the data — a value per node, a cursor per node — and a chart redrawn every frame should reuse it rather than allocate it again. That is the shape Hex has, for the same reason.

What it decides, and what it does not ¶

It decides two things: which column each node stands in, and how far down each node and each band sits. It does **not** decide the order of the nodes within a column — that is the order they were given in, which is the order their rows appeared in the source table. Reordering nodes to reduce crossings would mean a sort per sweep, and a sort is where a layout stops being a pure function of its input and starts depending on how a tie was broken. A caller that wants a different order sorts its own rows and hands them over that way.

The zero Sankey is unusable; call Sankey.Reset first.

func (s *Sankey) Reset(from, to []int, value []float64, nodes int, pad float64)

type SankeyFlow ¶

type SankeyFlow struct {
	SrcLo, SrcHi float64
	DstLo, DstHi float64
}

SankeyFlow is one link's band, given as the span it occupies where it leaves its source and the span it occupies where it enters its target. The two differ, which is what makes the band a ribbon rather than a rectangle.

type SankeyNode ¶

type SankeyNode struct {
	// Layer is the node's column, counting from zero at the sources.
	Layer int
	// Lo and Hi are the node's near and far edge, in [0, 1].
	Lo, Hi float64
	// Value is the flow through the node: the greater of what enters it and
	// what leaves it.
	Value float64
}

SankeyNode is one node's place in a flow diagram: which column it stands in, and the span of the unit interval it fills.

type Scaling ¶

type Scaling uint8

Scaling is how a cell's count becomes a fraction of the busiest cell.

const (
	Log Scaling = iota
	Sqrt
	Linear
)

type Span ¶

type Span struct {
	Lo, Hi float64
}

Span is a half-open interval [Lo, Hi) of the unit interval.

func (s Span) Width() float64

type StackMode ¶

type StackMode uint8

StackMode is where the bottom of a stack sits.

Stacking itself is a running sum and needs no help. What differs between a stacked bar chart, a 100 % chart and a streamgraph is only the *baseline* each column of the stack is measured from, which is what this package computes: numbers in, numbers out, no scales and no geometry.

const (
	// StackZero puts the bottom of every stack on zero. It is the ordinary
	// stacked bar or area.
	StackZero StackMode = iota

	// StackFill normalises each column to sum to one, so the stack fills the
	// axis and the chart reads as proportions. The baseline is still zero;
	// the caller scales the values.
	StackFill

	// StackSilhouette centres each column on zero, which is the symmetric
	// baseline a ThemeRiver is drawn about.
	StackSilhouette

	// StackWiggle minimises the total slope of the interior boundaries, which
	// is what makes a streamgraph readable: the eye follows a band by its
	// thickness, and a band that is also climbing steeply is hard to follow.
	// Byron & Wattenberg, "Stacked Graphs — Geometry & Aesthetics" (2008).
	StackWiggle
)

type Tile ¶

type Tile struct {
	X0, Y0, X1, Y1 float64
}

Tile is one rectangle of a treemap: the box a value was given.

It is four float64s rather than an ir.Rect because stat does not import ir, and it is a value rather than a pointer because a treemap of a hundred thousand nodes is a slice of these and nothing else.

func AppendSquarify(dst []Tile, values []float64, x0, y0, x1, y1 float64) []Tile

func Squarify(values []float64, x0, y0, x1, y1 float64) []Tile