scale

func Classed ¶

func Classed(s ColorScale) (ClassedColorScale, bool)

Classed reports whether a colour scale paints a finite set of classes, which is what decides whether its colourbar is a gradient or a ladder of steps.

func Quantile ¶

func Quantile(ramp palette.Ramp, classes int, opts ...ColorOption) ClassedColorScale

Quantile returns a colour scale that cuts the domain so that each class holds as near as possible the same number of observations.

It is the scale for a quantity whose distribution is the thing worth seeing: a count, an income, a latency. Equal-width classes over such data put nearly every observation in one class and leave the rest to name a handful of outliers, which is Quantize's honest failure and this scale's whole purpose. What it gives up in exchange is that a class no longer stands for a fixed span — two charts drawn from different rows cut at different values, so a quantile ramp is read against its own bar and never against another's.

Cost ¶

Quantiles cannot be computed from a running minimum and maximum, so this is the one colour scale that keeps what it is trained on: every finite value, held until the scale is discarded. That is a fixed cost per row rather than per scale, and it is the reason the boundaries are recomputed at the end of each ColorScale.Train rather than lazily — training is serial and drawing is not, so a scale that sorted itself the first time a mark asked for a colour would be sorting itself from several panels at once.

A chart redrawn from a github.com/timzifer/figure/data.Stream should therefore hand each frame a scale of its own, or compute the boundaries once and pin them with Threshold. A scale trained on every frame of a live chart has kept every frame of it.

A nil ramp uses palette.DefaultRamp.

func Quantize ¶

func Quantize(ramp palette.Ramp, classes int, opts ...ColorOption) ClassedColorScale

Quantize returns a colour scale that cuts the domain into equal classes.

Equal in the space the ramp runs in: under ColorLog the classes are decades rather than equal spans, which is the point of asking for both. A count of zero or less means one class.

It is the scale for a quantity a reader should read in bands without the bands claiming to say anything about the distribution. When the bands should say something about it — equally many observations in each — the scale is Quantile.

A nil ramp uses palette.DefaultRamp.

func Threshold ¶

func Threshold(ramp palette.Ramp, breaks []float64, opts ...ColorOption) ClassedColorScale

Threshold returns a colour scale that cuts the domain at boundaries given explicitly. A value lands in the class above a boundary it is equal to, so breaks of 10 and 100 make three classes: below 10, 10 up to 100, and 100 and over.

It is the scale for boundaries that come from outside the data — a legal limit, a service level, a clinical range. Boundaries derived *from* the data are Quantize's and Quantile's business.

The breaks are sorted and de-duplicated, so the caller need not. Passing none makes a scale of one class, which is a solid colour: that is what "cut this nowhere" means, and it is more useful than a panic in a chart whose breaks came from a configuration file.

A nil ramp uses palette.DefaultRamp.

func DescribeColor ¶

func DescribeColor(s ColorScale) (ColorDesc, bool)

DescribeColor reports s's configuration, or ok == false if s cannot describe itself.

func ColorCenter ¶

func ColorCenter(v float64) ColorOption

ColorCenter pins the value that lands on the middle of a diverging ramp. The default is 0.

It has no effect on a sequential scale, where there is no middle to pin.

func ColorDomain ¶

func ColorDomain(min, max float64) ColorOption

ColorDomain pins the domain explicitly, disabling training.

func ColorFallback ¶

func ColorFallback(p palette.Qualitative) ColorOption

ColorFallback sets the palette a Named scale colours a label it was not given a colour for from. The default is palette.Default.

It is a separate option from ColorUndefined because the two answer different questions. Undefined is for a value that is not a category at all — a null, a NaN — and drawing nothing is the honest answer to it. A label the caller did not enumerate *is* a category, and it is one the chart should show: it is how a reader learns that the machine reported a state nobody wrote down. It has no effect on any other kind of scale.

func ColorLog ¶

func ColorLog(base float64) ColorOption

ColorLog runs the ramp logarithmically across the domain, so that each decade of the data gets an equal share of the ramp. A base at or below 1 means the default, 10.

The domain is strictly positive, exactly as Log's is. Training ignores zero and negative values, and ColorScale.Color returns the undefined colour for one rather than clamping it to the low end of the ramp — a heatmap that painted an empty cell the colour of its rarest observation would be inventing a count. With the default transparent undefined colour that is what a reader expects anyway: the empty cells of a binned heatmap are the background.

On a Diverging scale the transform runs on the signed deviation from the centre rather than on the value, so a logarithm there is a symmetric one — see ColorSymLog. A plain logarithm has nothing to say about a negative deviation, and nothing to say about zero, which is the centre itself.

func ColorReverse ¶

func ColorReverse() ColorOption

ColorReverse runs the ramp the other way.

func ColorSymLog ¶

func ColorSymLog(base, threshold float64) ColorOption

ColorSymLog runs the ramp across a symmetric logarithm of the domain: linear within threshold of zero, logarithmic outside it, and defined for every finite value including negative ones. A base at or below 1 means the default, 10; a threshold at or below 0 means the default, 1.

This is the transform for a quantity that spans orders of magnitude *and* crosses zero — a signed residual, a change, a log-fold ratio — which is also the quantity a Diverging ramp is for. Choose the threshold to match the smallest magnitude that carries meaning.

func ColorUndefined ¶

func ColorUndefined(col ir.Color) ColorOption

ColorUndefined sets the colour for a value the scale cannot place — NaN, an infinity, or a category outside a fixed set. The default is fully transparent, which draws nothing.

func ColorFromDesc ¶

func ColorFromDesc(d ColorDesc) (ColorScale, error)

ColorFromDesc builds the colour scale d describes. A kind this package does not define is built by whoever registered it — see RegisterColor.

func Diverging ¶

func Diverging(ramp palette.Ramp, opts ...ColorOption) ColorScale

Diverging returns a colour scale that puts the middle of a ramp on a centre value and stretches both halves to the further end of the domain, so that equal deviations in either direction get equally strong colours.

It is the scale for a quantity read against a reference: a residual, a change, an anomaly. Use ColorCenter to move the centre off zero.

A nil ramp uses palette.BlueOrange.

func Sequential ¶

func Sequential(ramp palette.Ramp, opts ...ColorOption) ColorScale

Sequential returns a colour scale that runs a ramp across the domain from end to end. It is the scale for a quantity with a natural low and high — a count, a duration, a temperature.

A nil ramp uses palette.DefaultRamp.

func ColorTransformOf ¶

func ColorTransformOf(cs ColorScale) ColorTransform

ColorTransformOf names cs's transform, reporting TransformLinear for a scale that is not a ColorTransformer.

func Describe ¶

func Describe(s Scale) (Desc, bool)

Describe reports s's configuration, or ok == false if s cannot describe itself.

func Discrete ¶

func Discrete(s ColorScale) (DiscreteColorScale, bool)

Discrete reports whether a colour scale paints categories, which is what decides whether a layer using it contributes legend entries or a colourbar.

func Named ¶

func Named(colors map[string]ir.Color, opts ...ColorOption) DiscreteColorScale

Named returns a discrete colour scale whose categories are coloured by name rather than by the order they turn up in.

It is Qualitative's sibling and it exists because first appearance is the wrong rule for some categories. A machine state, a severity, a pass/fail — these carry a colour before any data does: a reader knows that a fault is red without consulting the legend, and a chart that painted it green on a window where no fault came first would be worse than one with no colour at all. Qualitative hands out palette entries in the order the rows arrive, so the colour of a state there depends on which slice of the stream is on screen. That is right for series nobody has an opinion about and wrong for these.

The named categories are listed first and in sorted order, which is also the order the legend lists them in. Sorted rather than as-written because a Go map has no order to preserve, and ADR 0012 does not allow one that depends on map iteration: a parallel render must be byte-identical to a serial one.

scale.Named(map[string]ir.Color{
    "RUN":   palette.Green,
    "FAULT": palette.Red,
})

A label the map does not mention is still drawn. It takes the next colour from the fallback palette, in order of first appearance, and is appended to DiscreteColorScale.Labels after the named ones — see ColorFallback. It is not left undefined because a status code nobody enumerated would then be a hole in the mark, and a hole in a line reads as a gap in the measurements rather than as a category the chart was not told about.

A nil or empty map is legal and makes this a Qualitative scale with extra steps, which is what a configuration file that named no colours should draw. Of the colour options ColorUndefined, ColorReverse and ColorFallback mean something here; the rest are accepted and ignored, exactly as they are on a qualitative scale.

func Qualitative ¶

func Qualitative(p palette.Qualitative, opts ...ColorOption) DiscreteColorScale

Qualitative returns a colour scale that gives each distinct label a colour from p, in order of first appearance in the data.

First appearance rather than sorted order is the same convention faceting and the ordinal axis already use, and ADR 0012 is why it is not negotiable: a parallel render must be byte-identical to a serial one, and an order that depends on map iteration is an order that depends on scheduling.

A domain larger than the palette wraps rather than fails — palette.Qualitative.At does — which is the behaviour a layer index already gets. A chart with more series than the palette has colours needs a second encoding channel, not a longer palette; see github.com/timzifer/figure/theme.Redundant.

A nil palette uses palette.Default. Of the colour options only ColorUndefined and ColorReverse mean anything here: there is no domain to pin and no middle to centre, so ColorDomain and ColorCenter are accepted and ignored, exactly as an option a geom has no use for is.

func Domain ¶

func Domain(min, max float64) LinearOption

Domain pins the data domain explicitly, disabling training.

func Format ¶

func Format(fn func(v float64) string) LinearOption

Format overrides tick label formatting.

func Nice ¶

func Nice() LinearOption

Nice expands the domain outwards to the tick sequence's own bounds, so the axis starts and ends on a labelled tick rather than on the extreme data value. This is what most charts want and what CONCEPT.md §13 shows.

func NumberFormat ¶

func NumberFormat(spec string) LinearOption

A tick label is described rather than computed.

Format, LogFormat and SymLogFormat take a Go function, which is the most direct thing an axis can be given and the one thing a document cannot hold: Desc says so through Formatted, and a chart written down as JSON and read back labelled its ticks the standard way. That made the one field a dashboard most wants to set — thousands separated, two decimals, a currency, a percentage — reachable only from Go, which is to say not reachable at all from the configuration file the chart actually lives in.

NumberFormat is the same choice written down. It is a string because a string is what survives the round trip and what a person editing a configuration can type; it is a *small* string because an axis asks few questions.

The grammar ¶

spec   := prefix "#" [","] ["." digits] [style] suffix
style  := "%" | "k" | "e"

The "#" is the number, and it is what tells the prefix from the suffix: everything before it is written before the number and everything left after the body is written after it.

• "," groups the whole part with the locale's group separator.
• "." followed by digits fixes the number of decimal places. Without it the axis chooses, as it always has — enough decimals to tell adjacent ticks apart, which is a property of the tick step rather than of any one value and is what keeps a column of labels aligned.
• "%" multiplies by 100 and appends the locale's percent sign, spacing and all: "12.5%" in English and "12,5 %" in German, from one spec.
• "k" is SI: 12500 becomes "12.5k", 0.0012 becomes "1.2m". Three significant digits unless "." says otherwise.
• "e" is scientific, two decimals unless "." says otherwise.

So:

"#,"        1,234,567
"#,.2"      1,234,567.00
"€ #,.2"    € 1,234,567.00
"#.1%"      12.5%
"#k"        1.23M
"# kg"      1234567 kg

The last two are worth reading together. A style letter counts as one only where the body ends — directly after the "#", the grouping comma and the decimals — so "#k" is SI and "# kg" is a number with a unit after it. A suffix that begins with one of the three letters wants a space, or a spec that does not need one.

What it does not do ¶

It has no currency table, no accounting negatives, no significant-digit mode and no per-value conditionals. Those are a formatting library, and the seam for one is still Format: a Go function outranks a spec, so a caller who has a formatter keeps it. What the spec is for is the chart that is configured rather than compiled.

An invalid spec ¶

A spec written in Go source is a literal, so a malformed one panics — the same line github.com/timzifer/figure/data.Table draws about a ragged table. A spec read out of a document is input, so FromDesc returns an error for it rather than panicking. The two paths are the same parser.

func TickValues ¶

func TickValues(vs ...float64) LinearOption

TickValues pins the tick positions, replacing the chosen sequence with the one given. It is for an axis whose readable positions are a convention rather than a search result: the 0.2 / 0.5 / 1 / 2 / 5 grid of a Smith chart, the five points of a Likert item, the octaves of a frequency axis.

It says nothing about the domain. A tick outside the domain is dropped rather than stretching the axis to reach it — Domain is how an axis is widened — and an empty or all-infinite list leaves the automatic sequence in place, so TickValues() is not a way to ask for an axis with no ticks at all.

Labels are formatted as they always are: by Format when one was given, and otherwise from the closest spacing in the list, so that a sequence which is not evenly spaced still labels every tick to the same precision.

func Zero ¶

func Zero() LinearOption

Zero forces the domain to include zero. Bar charts need this: a bar chart whose baseline is off-screen misleads.

func LookupLocale ¶

func LookupLocale(name string) (*Locale, bool)

LookupLocale returns the locale registered under a name.

A name with a region — "de-AT", "pt-BR" — falls back to its language when the region itself is not registered, because a chart asking for Austrian German is better served by German than by English. Matching is on the tag as written, and the tags figure ships are lower-case language codes.

func LogBase ¶

func LogBase(b float64) LogOption

LogBase sets the base. The default is 10. Bases at or below 1 are ignored, because a logarithm to such a base is not a scale.

func LogDomain ¶

func LogDomain(min, max float64) LogOption

LogDomain pins the data domain explicitly, disabling training. Both bounds must be positive; a non-positive bound is ignored, since a log scale has no position for it.

func LogFormat ¶

func LogFormat(fn func(v float64) string) LogOption

LogFormat overrides tick label formatting.

func LogMinorTicks ¶

func LogMinorTicks(show bool) LogOption

LogMinorTicks turns the unlabelled subdivisions inside each decade on or off. They are on by default: without them a reader has no way to judge where 3 sits between 1 and 10, which is the one thing a log axis is bad at.

func LogNice ¶

func LogNice() LogOption

LogNice expands the domain outwards to whole powers of the base, so the axis starts and ends on a labelled decade.

func LogNumberFormat ¶

func LogNumberFormat(spec string) LogOption

LogNumberFormat is NumberFormat for a log scale.

func Categories ¶

func Categories(labels ...string) OrdinalOption

Categories fixes the category set and its axis order.

Without it the scale discovers categories as it encodes them, in the order the data presents them — which is right for data that is already in the order you want to read it, and wrong for anything else. A chart whose bars reorder themselves because yesterday's export sorted differently is a chart nobody trusts.

A label outside a fixed set has no position: it encodes to NaN and the geom treats the row as missing under its own policy.

func OrdinalPadding ¶

func OrdinalPadding(f float64) OrdinalOption

OrdinalPadding sets the fraction of each slot left blank, in [0, 1). The default is 0.2, which separates adjacent bars without making them look unrelated.

func ColorAxisOf ¶

func ColorAxisOf(cs ColorScale) Scale

ColorAxisOf returns the axis a colourbar over cs is labelled by. It is never nil: a scale that is not a ColorTransformer gets a linear axis over its domain, which is what a colourbar has always drawn.

func FromDesc ¶

func FromDesc(d Desc) (Scale, error)

FromDesc builds the scale d describes. A kind this package does not define is built by whoever registered it — see Register — and one nobody did is ErrUnknownKind.

func Linear ¶

func Linear(opts ...LinearOption) Scale

Linear returns a linear scale.

func Log ¶

func Log(opts ...LogOption) Scale

Log returns a logarithmic scale.

The domain is strictly positive. Training ignores zero and negative values the same way it ignores NaN, and Scale.Map returns NaN for them, which geoms treat as missing data under the layer's own policy — a log chart that silently clamped a negative reading to the axis minimum would be inventing a measurement. Use SymLog for data that genuinely crosses zero.

func Ordinal ¶

func Ordinal(opts ...OrdinalOption) Scale

Ordinal returns a categorical band scale: each category gets an equal slot, and a value sits at the centre of its slot.

It satisfies the same Scale interface as every continuous scale by carrying the category *index* as its numeric domain — see Categorical. A geom mapping a string column onto an ordinal axis encodes the labels through the scale; a geom mapping a numeric or time column onto one treats each distinct formatted value as a category, so a bar chart over the values 10, 20 and 30 gets three equally spaced bars rather than a numeric axis with gaps.

It also satisfies Band, so bars and boxplots take their width from the scale rather than inferring it from the spacing of the data.

func SymLog ¶

func SymLog(opts ...SymLogOption) Scale

SymLog returns a symmetric log scale: linear within a threshold of zero, logarithmic outside it, and defined for every finite value including negative ones.

This is the scale for data that spans orders of magnitude *and* crosses zero — a signed residual, a profit and loss, a delta that is sometimes tiny. A plain Log cannot show such data at all and a Linear one buries everything small.

The transform is sign(v)·log_base(1 + |v|/threshold), which is smooth at the origin rather than merely continuous: there is no visible kink where the linear region hands over to the logarithmic one.

func Time ¶

func Time(opts ...TimeOption) Scale

Time returns a time scale.

Its domain is carried as float64 Unix nanoseconds, so it satisfies the same Scale interface as every other scale and geoms need no special case. Use Nanos and FromNanos to convert.

func DescribeSize ¶

func DescribeSize(s SizeScale) (SizeDesc, bool)

DescribeSize reports s's configuration, or ok == false if s cannot describe itself.

func SizeDomain ¶

func SizeDomain(min, max float64) SizeOption

SizeDomain pins the domain explicitly, disabling training.

func SizeRange ¶

func SizeRange(min, max float32) SizeOption

SizeRange sets the diameters, in device units, that the ends of the domain map to. It is what SizeScale.SetRange sets, given at construction so that a caller can override what the theme would have chosen.

The minimum is 0 by default, and that is the choice that makes the channel honest: a floor is a constant added to every area, so a value of zero draws a mark of some size and the ratio between two marks stops being the ratio between their values. Raise it when the smallest bubbles would otherwise vanish, knowing that is the trade being made.

A range given here is *pinned*: SizeScale.SetRange no longer moves it. That is the same line Zoomer.SetDomain draws between a domain the data decides and one the caller did — a geom sets the range from its theme on every frame, and a caller who named the sizes has not asked for the theme's.

func SizeZero ¶

func SizeZero(v float64) SizeOption

SizeZero anchors the area scale at a value other than zero: the value whose mark has the minimum size.

Zero is the default and is what makes a bubble's ink proportional to its value. Anchoring at the smallest observation instead spreads the sizes over the data's own range, which shows small differences between large values — and stops the drawing being a proportion at all, so it is asked for rather than assumed.

func Size ¶

func Size(opts ...SizeOption) SizeScale

Size returns a scale that maps values onto mark diameters by area.

The domain runs from zero to the largest value trained into it, and the range from a diameter of zero to whatever SizeRange or SizeScale.SetRange names. With those defaults the mapping is exactly d(v) = D·√(v/vmax): the area is proportional to the value, so twice the value is twice the ink and √2 times the diameter.

Negative values have no area and no mark. A quantity that runs both ways is not a size channel — it is a colour channel over a diverging ramp, where a deviation of -3 and one of +3 are equally strong and visibly opposite.

func SizeFromDesc ¶

func SizeFromDesc(d SizeDesc) (SizeScale, error)

SizeFromDesc builds the size scale d describes.

func SymLogBase ¶

func SymLogBase(b float64) SymLogOption

SymLogBase sets the base. The default is 10.

func SymLogDomain ¶

func SymLogDomain(min, max float64) SymLogOption

SymLogDomain pins the data domain explicitly, disabling training.

func SymLogFormat ¶

func SymLogFormat(fn func(v float64) string) SymLogOption

SymLogFormat overrides tick label formatting.

func SymLogMinorTicks ¶

func SymLogMinorTicks(show bool) SymLogOption

SymLogMinorTicks turns the unlabelled subdivisions inside each decade on or off. They are on by default.

func SymLogNumberFormat ¶

func SymLogNumberFormat(spec string) SymLogOption

SymLogNumberFormat is NumberFormat for a symlog scale.

func SymLogThreshold ¶

func SymLogThreshold(t float64) SymLogOption

SymLogThreshold sets the half-width of the linear region around zero. The default is 1.

Choose it to match the smallest magnitude that carries meaning: below the threshold the scale is linear, above it logarithmic, and the join is smooth.

func In ¶

func In(loc *time.Location) TimeOption

In sets the location used to compute calendar ticks and format labels. The default is time.UTC, so that a chart renders identically wherever it is built — a server rendering in the client's local zone is a bug, not a feature.

func Origin ¶

func Origin(t time.Time) TimeOption

Origin sets the instant the scale measures its domain from, so that a domain value is nanoseconds since t rather than nanoseconds since 1970.

It is what makes a deep zoom exact. A float64 holds 53 bits of mantissa, and a Unix nanosecond count in this century needs 61 — so two instants a nanosecond apart become the *same* float64, and an axis zoomed to a microsecond window has nothing left to separate them with. Measured from an origin near the data, the same two instants are 1.0 apart, and stay whole numbers of nanoseconds for the hundred days either side of it that a float64 counts exactly.

The origin is part of the scale's domain space: every value handed to Scale.Map or Scale.Train on this scale, and every value it returns from Scale.Invert or Scale.Domain, is measured from it. Use Temporal — or the package helpers ValueOf and InstantOf — to convert, rather than Nanos and FromNanos, which are the origin-free pair and stay so. A geom reading a time column does this for you.

The default origin is the Unix epoch, which is exactly Nanos.

func TimeFormat ¶

func TimeFormat(fn func(t time.Time, unit time.Duration) string) TimeOption

TimeFormat overrides tick label formatting. The unit the tick sequence settled on is passed so a caller can vary detail with zoom level.

func TimeLayout ¶

func TimeLayout(layout string) TimeOption

TimeLayout fixes the layout every tick label on this axis is written in, instead of letting the scale choose one per tick spacing.

It is TimeFormat written down: a Go reference layout is a string, so it survives a round trip through the JSON spec, and a chart configured rather than compiled can say that its axis reads "2006-01-02" — which TimeFormat's function could say only from Go. A Go function still outranks it, for the reason it outranks NumberFormat: a caller who wrote one has answered the question.

The scale's own choice is what it always was — a ladder of layouts, one per tick spacing, so that an axis over three hours says "Jan 2 15:04" and one over three years says "Jan 2006". Naming a layout gives that up in exchange for knowing exactly what every label says, which is what a caller who names one is asking for.

The month and weekday names come from the axis's locale rather than from Go's own tables, so "January 2006" is "Januar 2006" on a German axis. See Locale.