Documentation
¶
Overview ¶
Package data is refract's data layer: columnar, batch-oriented access to a table of values.
The interface returns whole typed columns, never one value at a time. Scalar access is the single easiest way to make a plotting library slow, and a columnar shape is also what lets a []float64-backed source be borrowed instead of copied.
Index ¶
- func FormatNumber(v float64) string
- func GroupBy(src Source, col string) (keys []string, rows [][]int, ok bool)
- func Labels(src Source, col string) ([]string, bool)
- type Source
- type Table
- func (t *Table) Columns() []string
- func (t *Table) Float64(name string, v []float64) *Table
- func (t *Table) Float64Column(name string) ([]float64, bool)
- func (t *Table) Len() int
- func (t *Table) String(name string, v []string) *Table
- func (t *Table) StringColumn(name string) ([]string, bool)
- func (t *Table) Time(name string, v []time.Time) *Table
- func (t *Table) TimeColumn(name string) ([]time.Time, bool)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatNumber ¶ added in v0.3.0
FormatNumber is how a numeric value is spelled when it is used as a category name. Both faceting and a categorical axis go through it, so a panel key and an axis tick for the same number are the same string.
func GroupBy ¶ added in v0.3.0
GroupBy splits src into groups by the values of a column, returning the distinct values in first-appearance order and the row numbers of each.
The column may be textual, numeric or temporal; whichever it is, the group key is its formatted label, so a facet over a numeric column gets one panel per distinct number rather than a continuous axis. ok is false if src has no such column.
First-appearance order rather than sorted order is deliberate: it is the one ordering that is stable under every column type and lets a caller control panel order by ordering its rows.
Types ¶
type Source ¶
type Source interface {
// Len reports the number of rows. Every column has this length.
Len() int
// Columns lists the available column names. The order is stable across
// calls on the same Source.
Columns() []string
// Float64Column returns a numeric column by name. ok is false if the
// column does not exist or is not numeric.
Float64Column(name string) (data []float64, ok bool)
// TimeColumn returns a time column by name. ok is false if the column does
// not exist or is not temporal.
TimeColumn(name string) (data []time.Time, ok bool)
// StringColumn returns a categorical column by name. ok is false if the
// column does not exist or is not textual.
StringColumn(name string) (data []string, ok bool)
}
Source exposes columnar, batch access to a table.
Implementations return read-only views: the caller must not mutate a returned slice, and refract never does. An implementation that already holds its data as a Go slice should return that slice directly rather than copying.
func Float64Columns ¶
Float64Columns builds a Source over the given numeric columns.
The slices are borrowed, not copied: the returned Source aliases the caller's memory, and mutating it afterwards mutates what refract will plot. All columns must have the same length; Float64Columns panics otherwise, because a ragged table is a programming error rather than a runtime condition.
func Rows ¶ added in v0.3.0
Rows returns a Source over the rows of src named by idx, in the order given.
It is how faceting cuts one table into panels: a facet reads the column it splits on, groups the row numbers, and hands each group to Rows. Out-of-range indices are dropped rather than panicking, because they come from a grouping pass rather than from the caller.
The result materialises the rows it is asked for. That is a copy — the zero-copy promise in Float64Columns is about the whole-column path, and a gathered subset has no contiguous slice to borrow. Columns are gathered lazily, so a table with forty columns and a chart that reads three copies three.
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
Table is a Source that mixes numeric, temporal and categorical columns.
It is the general-purpose implementation: use it when a chart plots time or a category against values, which is the common case for the Time and Ordinal scales.
func (*Table) Float64 ¶
Float64 adds a numeric column, borrowing the slice. It returns t so calls can be chained. It panics if the column length disagrees with columns already added, or if the name is already taken.
func (*Table) Float64Column ¶
Float64Column returns a numeric column by name.
func (*Table) String ¶ added in v0.2.0
String adds a categorical column, borrowing the slice. It returns t so calls can be chained. It panics if the column length disagrees with columns already added, or if the name is already taken.
Plot such a column against a [scale.Ordinal] axis; a continuous scale has no position for a category name and a geom says so rather than guessing one.
func (*Table) StringColumn ¶ added in v0.2.0
StringColumn returns a categorical column by name.
Source Files