Documentation
¶
Overview ¶
Package geom holds the visual marks a chart is made of.
A geom knows what its shape is and never how it is rendered: it reads columns, asks the scales where values go, and emits IR. It has no reference to a backend, no knowledge of SVG or raster, and no opinion about layout beyond the rectangle it is given.
Index ¶
- Variables
- type Frame
- type Geom
- type LegendEntry
- type Missing
- type Option
- func BarWidth(f float64) Option
- func Baseline(v float64) Option
- func Color(col ir.Color) Option
- func ColorBy(col string, s scale.ColorScale) Option
- func Dash(pattern ...float32) Option
- func Fill(col ir.Color) Option
- func Label(s string) Option
- func OnMissing(m Missing) Option
- func Opacity(f float64) Option
- func Outliers(show bool) Option
- func Shape(m ir.Marker) Option
- func Size(s float32) Option
- func Steps(where StepPos) Option
- func Tension(t float64) Option
- func Whisker(k float64) Option
- func Width(w float32) Option
- func X(col string) Option
- func Y(col string) Option
- func Y2(col string) Option
- type StepPos
- type SwatchKind
Constants ¶
This section is empty.
Variables ¶
var ErrCategorical = errors.New("refract/geom: categorical column on a continuous scale")
ErrCategorical reports a text column mapped onto an axis that has no position for a name.
var ErrNoColumn = errors.New("refract/geom: column not found")
ErrNoColumn reports a column named by an option that the source does not have. It is returned rather than panicking because the column name usually comes from user input or a config file.
Functions ¶
This section is empty.
Types ¶
type Frame ¶
type Frame struct {
// Area is the plot rectangle in device space. Scales already map into it.
Area ir.Rect
// X and Y are the trained, ranged scales.
X, Y scale.Scale
// Theme supplies defaults the geom did not override.
Theme theme.Theme
// Index is the geom's position among the chart's layers, used to pick a
// default colour from the palette.
Index int
}
Frame is everything a geom needs to turn data into IR.
type Geom ¶
type Geom interface {
// Train feeds the geom's data into the scales so they can establish their
// domains. It runs before layout, because layout needs tick labels and
// tick labels need a domain.
Train(x, y scale.Scale) error
// Build emits the geom's marks into b.
Build(b ir.Backend, f Frame) error
// Legend returns the entry this geom contributes, or ok == false if it
// should not appear in the legend.
Legend(f Frame) (LegendEntry, bool)
}
Geom is a layer of marks.
func Area ¶ added in v0.2.0
Area fills the region between a series and a baseline, or — given Y2 — the band between two series.
The upper edge is stroked in the layer's full colour and the interior is filled with a faded version of it. A band drawn in one flat colour reads as a solid object; a band with a drawn edge reads as a series with uncertainty around it, which is what an area chart is for. Use Opacity to change the fill, Fill to set it outright.
func Boxplot ¶ added in v0.2.0
Boxplot summarises the distribution of the Y column within each distinct X value: a box spanning the interquartile range, a line at the median, whiskers reaching to the furthest observation within Whisker times the IQR, and a marker for every observation beyond them.
The X column is the grouping key, so a boxplot wants many rows per X value — typically a categorical column against a scale.Ordinal axis, which also gives every box the same width. On a continuous axis the width comes from the closest pair of groups, as it does for a bar.
Whiskers stop at an observation, never at the theoretical fence. A whisker drawn out to 1.5·IQR when the data stops well short of it would be claiming a reading that does not exist.
func Step ¶ added in v0.2.0
Step connects rows with horizontal and vertical segments instead of a straight line.
It is the honest shape for anything that holds a value and then changes it — a configuration, a queue depth, a price, a state machine. A plain line between two such samples draws a gradual transition that never happened. Use Steps to say where the change falls between the two rows.
type LegendEntry ¶
type LegendEntry struct {
Label string
Color ir.Color
Kind SwatchKind
Marker ir.Marker
Dash []float32
Width float32
}
LegendEntry is a geom's contribution to the legend.
type Option ¶
type Option func(*config)
Option configures a geom. Options are shared across geom constructors: an option a given geom has no use for is accepted and ignored, which keeps the API one namespace instead of six.
func BarWidth ¶
BarWidth sets bar width as a fraction of the spacing between adjacent bars, in (0, 1]. The default is 0.8.
func ColorBy ¶ added in v0.2.0
func ColorBy(col string, s scale.ColorScale) Option
ColorBy maps a numeric column through a colour scale, giving every mark its own colour. It applies to Scatter and Bar; geoms whose mark is one connected shape ignore it.
A layer coloured this way contributes no legend entry: the guide such a layer needs is a colourbar, and colourbars are a v0.3 milestone. Naming a colour scale is not a substitute for one, so the legend says nothing rather than saying something misleading.
func Dash ¶
Dash sets a dash pattern in device units. Dashing a series is redundant encoding: it keeps the chart readable in greyscale and for colourblind readers.
func Opacity ¶ added in v0.2.0
Opacity scales the fill alpha, in [0, 1]. The default is 1 for an explicit Fill colour and 0.25 for an area that takes its colour from the palette — a filled band has to sit behind the lines it belongs to.
func Outliers ¶ added in v0.2.0
Outliers turns the individual points beyond the whiskers on or off. They are on by default: a boxplot that hides them is a boxplot that hides exactly the rows a reader opened the chart to find.
func Tension ¶
Tension smooths a line. 0 (the default) is a plain polyline; values in (0, 1] progressively round the corners using a Catmull-Rom spline.
type StepPos ¶ added in v0.2.0
type StepPos uint8
StepPos is where a step geom changes value between two rows.
type SwatchKind ¶
type SwatchKind uint8
SwatchKind is how a legend entry draws its sample.
const ( SwatchLine SwatchKind = iota SwatchMarker SwatchBox )
The swatch kinds.
Source Files