Plots and data API · phiz

A plot starts with Plot::of() or ggplot(), which take the data and optional mappings. The data can be rows, columns, a phibble table, a Laravel collection, or a Data source. Data and fields explains the forms data can take, and Large data explains when to bin in PHP with Bin.

Construction: Plot::of()

Mappings and data: aes() · data()

Data: Data::from() · Data::url() · Data::named() · $data->isInline() · $data->isEmpty() · $data->count() · $data->toSpec() · $data->fields() · $data->has() · $data->column() · $data->type() · $data->isTime() · $data->levels() · $data->withRows() · Data::value()

Datasets: Datasets::mpg() · Datasets::mtcars() · Datasets::economics() · Datasets::faithful() · Datasets::load()

Bin: Bin::histogram() · Bin::grid() · Bin::hex() · Bin::lttb() · Bin::sample() · Bin::range() · Bin::values()

Functions: aes() · ggplot() · field() · factor() · calc() · expr()

Construction

`Plot::of()`

Plot::of(mixed $data = null, Aes|array|null $aes = null): Plot

A plot of rows, columns, a phibble Table, a Laravel Collection, or Data::url(…), with optional mappings.

Mappings and data

`aes()`

->aes(mixed ...$mappings): Plot

Adds plot-wide aesthetic mappings: x, y, color, fill, size, shape, alpha, group, tooltip, label, …

`data()`

->data(mixed $data): Plot

Replaces the plot’s data with any supported input, keeping the mappings and layers.

Data

`Data::from()`

Data::from(mixed $data): Data

Wraps any supported input: rows, columns, a table, a collection, an iterable, or a Data object as given.

`Data::url()`

Data::url(string $url, ?string $type = null, ?array $parse = null): Data

Data that Vega-Lite fetches from a URL (CSV, TSV, JSON); types can’t be inferred, so use ‘field:Q’ shorthand.

`Data::named()`

Data::named(string $name): Data

A named data source the page supplies at runtime (vega-embed’s view.data(name, rows)).

`$data->isInline()`

->isInline(): bool

Whether the data is embedded, rather than a URL or a named source.

`$data->isEmpty()`

->isEmpty(): bool

Whether inline data has no rows. URL and named data count as empty.

`$data->count()`

->count(): int

The number of inline rows, without building them.

`$data->toSpec()`

->toSpec(): array

The Vega-Lite data definition: values, a url, or a name.

`$data->fields()`

->fields(): array

The field names of inline data, in first-seen order.

`$data->has()`

->has(string $field): bool

Whether inline data has the field.

`$data->column()`

->column(string $field): array

A field’s values, JSON-safe, read from the table or columns without building rows.

`$data->type()`

->type(string $field): ?string

The Vega-Lite measurement type of a field: quantitative when every non-null value is a number, temporal when every value is an ISO date string, nominal otherwise. Null for non-inline data or an all-null column.

`$data->isTime()`

->isTime(string $field): bool

Whether a field held phibble times, which are plotted as seconds on a continuous scale, as ggplot2 plots hms.

`$data->levels()`

->levels(string $field): array

Distinct non-null values of a field in first-seen order.

`$data->withRows()`

->withRows(array $rows): Data

New inline data holding the given rows.

`Data::value()`

Data::value(mixed $value): mixed

One value made JSON-safe: non-finite floats become null, dates ISO 8601 strings, phibble times seconds, enums their values or case names, and Stringable objects strings.

Datasets

`Datasets::mpg()`

Datasets::mpg(): array

ggplot2’s mpg: 234 cars from 1999 and 2008 with displacement (displ, liters), city and highway mpg (cty, hwy), drive (drv), and class.

`Datasets::mtcars()`

Datasets::mtcars(): array

R’s mtcars: 32 cars with mpg, cylinders (cyl), weight (wt, 1,000 lb), horsepower (hp), transmission (am, 1 manual), and the model name.

`Datasets::economics()`

Datasets::economics(): array

ggplot2’s economics: 574 monthly US rows from 1967 with date, pce ($bn), pop (thousands), psavert (%), uempmed (weeks), and unemploy (thousands).

`Datasets::faithful()`

Datasets::faithful(): array

R’s faithful: 272 Old Faithful eruptions with their length (eruptions) and the wait before them (waiting), in minutes.

`Datasets::load()`

Datasets::load(string $name): array

A bundled dataset by name, from resources/data/{name}.csv, cached after the first load; an unknown name throws.

Bin

`Bin::histogram()`

Bin::histogram(    mixed $source,    string $x,    int $bins = 30,    int|float|null $binwidth = null,    int|float|null $boundary = null,    ?array $limits = null,    array $groups = [],): array

Equal-width bins of x: rows with x0, x1, count, and density (count / (n * width)), per group.

`Bin::grid()`

Bin::grid(    mixed $source,    string $x,    string $y,    array|int $bins = 30,    ?array $xlim = null,    ?array $ylim = null,    array $groups = [],): array

Counts in a grid of x-by-y rectangles: rows with x_start, x_end, y_start, y_end (named after the fields) and count. Empty cells are omitted.

`Bin::hex()`

Bin::hex(    mixed $source,    string $x,    string $y,    int $bins = 30,    ?array $xlim = null,    ?array $ylim = null,    float $aspect = 1.0,    array $groups = [],): array

Counts in a hexagonal grid, as ggplot2’s geom_hex: rows with the hexagon centers (under the x and y names) and count. bins hexagons span the x range; aspect (height / width of the panel in pixels) keeps them regular on screen.

`Bin::lttb()`

Bin::lttb(    array $rows,    string $x,    string $y,    int $threshold = 1000,    array $groups = [],): array

Downsamples a line to about $threshold points with Largest-Triangle-Three-Buckets, which keeps the visual shape (peaks and troughs). Rows are sorted by x; groups are downsampled separately.

`Bin::sample()`

Bin::sample(mixed $source, int $n, int $seed = 1): array

A uniform random sample of n rows (reservoir sampling, one pass), reproducible with a seed.

`Bin::range()`

Bin::range(mixed $source, string $field): array

The [min, max] of a numeric field, padded when every value is equal.

`Bin::values()`

Bin::values(mixed $source, array $fields): Generator

The values of the named fields, one list per record.

Functions

`aes()`

aes(mixed ...$mappings): Aes

Aesthetic mappings: aes(x: ‘displ’, y: ‘hwy’, color: ‘class’).

`ggplot()`

ggplot(mixed $data = null, Aes|array|null $mapping = null): Plot

A plot of data with optional mappings.

`field()`

field(string $name, ?string $type = null, mixed ...$properties): Field

A field with an explicit type or other Vega-Lite field-definition properties.

`factor()`

factor(string $name, ?array $levels = null): Field

A field treated as discrete categories, like R’s factor(cyl). Levels set the order.

`calc()`

calc(string $expression, string $as, ?string $type = null): Field

A field computed from a Vega expression: calc(‘datum.hwy - datum.cty’, as: ‘gap’).

`expr()`

expr(string $expression): Expr

A Vega expression, such as a slider parameter’s name.