Functions and methods · phiz

Every public function and method, from the source, grouped by reference page. Each function in the Phiz\ namespace is listed with the Plot method it calls, for the pipe operator and apply().

Notation	Meaning
`geom_point()`	a function in the `Phiz\` namespace
`->point()`	a `Plot` instance method
`Plot::of()`, `Data::from()`	a static method
`$data->has()`	an instance method of the named class

Plots and data

Function	Method	Purpose
`ggplot()`	`Plot::of()`	A plot of rows, columns, a phibble Table, a Laravel Collection, or Data::url(…), with optional mappings.
	`->aes()`	Adds plot-wide aesthetic mappings: x, y, color, fill, size, shape, alpha, group, tooltip, label, …
	`->data()`	Replaces the plot’s data with any supported input, keeping the mappings and layers.
	`Data::from()`	Wraps any supported input: rows, columns, a table, a collection, an iterable, or a Data object as given.
	`Data::url()`	Data that Vega-Lite fetches from a URL (CSV, TSV, JSON); types can’t be inferred, so use ‘field:Q’ shorthand.
	`Data::named()`	A named data source the page supplies at runtime (vega-embed’s view.data(name, rows)).
	`$data->isInline()`	Whether the data is embedded, rather than a URL or a named source.
	`$data->isEmpty()`	Whether inline data has no rows.
	`$data->count()`	The number of inline rows, without building them.
	`$data->toSpec()`	The Vega-Lite data definition: values, a url, or a name.
	`$data->fields()`	The field names of inline data, in first-seen order.
	`$data->has()`	Whether inline data has the field.
	`$data->column()`	A field’s values, JSON-safe, read from the table or columns without building rows.
	`$data->type()`	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.
	`$data->isTime()`	Whether a field held phibble times, which are plotted as seconds on a continuous scale, as ggplot2 plots hms.
	`$data->levels()`	Distinct non-null values of a field in first-seen order.
	`$data->withRows()`	New inline data holding the given rows.
	`Data::value()`	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::mpg()`	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()`	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()`	ggplot2’s economics: 574 monthly US rows from 1967 with date, pce ($bn), pop (thousands), psavert (%), uempmed (weeks), and unemploy (thousands).
	`Datasets::faithful()`	R’s faithful: 272 Old Faithful eruptions with their length (eruptions) and the wait before them (waiting), in minutes.
	`Datasets::load()`	A bundled dataset by name, from resources/data/{name}.csv, cached after the first load; an unknown name throws.
	`Bin::histogram()`	Equal-width bins of x: rows with x0, x1, count, and density (count / (n * width)), per group.
	`Bin::grid()`	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.
	`Bin::hex()`	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()`	Downsamples a line to about $threshold points with Largest-Triangle-Three-Buckets, which keeps the visual shape (peaks and troughs).
	`Bin::sample()`	A uniform random sample of n rows (reservoir sampling, one pass), reproducible with a seed.
	`Bin::range()`	The [min, max] of a numeric field, padded when every value is equal.
	`Bin::values()`	The values of the named fields, one list per record.
`aes()`		Aesthetic mappings: aes(x: ‘displ’, y: ‘hwy’, color: ‘class’).
`field()`		A field with an explicit type or other Vega-Lite field-definition properties.
`factor()`		A field treated as discrete categories, like R’s factor(cyl).
`calc()`		A field computed from a Vega expression: calc(‘datum.hwy - datum.cty’, as: ‘gap’).
`expr()`		A Vega expression, such as a slider parameter’s name.

Geoms

Function	Method	Purpose
`geom_point()`	`->point()`	Scatterplot points. jitter: true (or a width, or [width, height]) displaces them randomly. seed: makes the jitter reproducible: phiz draws it in PHP and embeds it in the data, so every render places the points the same way.
`geom_jitter()`	`->jitter()`	Points jittered by up to width/height (fraction of a band on discrete axes, data units otherwise).
`geom_line()`	`->line()`	Lines connecting points in order of x. downsample: n keeps about n points per group (LTTB), in PHP.
`geom_path()`	`->path()`	Lines connecting points in data order.
`geom_step()`	`->step()`	Stairsteps: direction ‘hv’ (horizontal first), ‘vh’, or ‘mid’.
`geom_area()`	`->area()`	Areas from zero, stacked by fill (position: stack, fill, identity).
`geom_ribbon()`	`->ribbon()`	A band between ymin and ymax (or xmin and xmax).
`geom_bar()`	`->bar()`	Bars of counts of x (or y), or of the y values when y is mapped. position: stack, dodge, fill, identity.
`geom_col()`	`->col()`	Bars whose heights are the y values.
`geom_histogram()`	`->histogram()`	Binned counts of x: bins (a maximum; Vega-Lite picks nice boundaries) or binwidth. density: true scales to unit area. compute: ‘server’ bins in PHP (exactly bins equal-width bins), ‘browser’ in Vega-Lite, and ‘auto’ (the default) in PHP above Config::$serverRows rows.
`geom_freqpoly()`	`->freqpoly()`	Frequency polygons: binned counts drawn as lines.
`geom_density()`	`->density()`	Kernel density of x per group (Vega-Lite’s density transform). bw sets the bandwidth; adjust multiplies it (from R’s bw.nrd0 when bw is unset); counts: true scales to counts.
`geom_boxplot()`	`->boxplot()`	Tukey boxplots; coef sets the whisker extent in IQRs.
`geom_violin()`	`->violin()`	Violins: the kernel density of y per level of a discrete x. bw sets the bandwidth, adjust multiplies R’s bw.nrd0, and width is the widest violin’s share of its band.
`geom_errorbar()`	`->errorbar()`	Error bars from ymin to ymax (or xmin to xmax) with end ticks; width is the tick length in pixels.
`geom_linerange()`	`->linerange()`	Vertical (or horizontal) lines from ymin to ymax.
`geom_pointrange()`	`->pointrange()`	A point at y on a line from ymin to ymax: the coefficient-plot geom. position: ‘dodge’ sets groups side by side.
`geom_hline()`	`->hline()`	Horizontal reference lines at fixed values, or at a mapped yintercept field when yintercept is null.
`geom_vline()`	`->vline()`	Vertical reference lines at fixed values, or at a mapped xintercept field.
`geom_abline()`	`->abline()`	Lines y = intercept + slope * x across the x range (lists draw several).
`geom_rule()`	`->rule()`	Rules at mapped positions (x, y, xend, yend).
`geom_segment()`	`->segment()`	Line segments from (x, y) to (xend, yend).
`geom_text()`	`->text()`	Text from the label aesthetic. nudgeX/nudgeY offset it in pixels; angle turns it anticlockwise.
`geom_label()`	`->label()`	Text from the label aesthetic in bold, standing in for geom_label(); Vega-Lite draws no box behind it.
`geom_tile()`	`->tile()`	Heatmap tiles at discrete x and y (numbers are treated as ordered levels), filled by the fill aesthetic.
`geom_raster()`	`->raster()`	Heatmap tiles, as tile() draws them; ggplot2’s geom_raster() name.
`geom_rect()`	`->rect()`	Rectangles from xmin, xmax, ymin, ymax.
`geom_bin2d()`	`->bin2d()`	A 2D histogram: counts in x-by-y bins; compute works as in histogram().
`geom_hex()`	`->hex()`	Hexagonal bins counted in PHP, as ggplot2’s geom_hex: bins hexagons across the x range.
`geom_smooth()`	`->smooth()`	A fitted curve per group. method: loess (span sets the bandwidth), lm, poly (order), quad, log, exp, pow.
`geom_density_2d()`, `stat_density_2d()`	`->density2d()`	Contour lines of a 2D kernel density of x and y, as ggplot2’s geom_density_2d (MASS::kde2d on an n × n grid). h sets the bandwidths ([x, y] or one for both; default MASS::bandwidth.nrd), adjust multiplies them, and bins, binwidth, or breaks set the levels (default pretty(range, 10)). contourVar: density, ndensity (scaled to a maximum of 1 per group), or count. aes(color: ‘level’) colors lines by their level.
`geom_density_2d_filled()`, `stat_density_2d_filled()`	`->density2dFilled()`	Filled bands of a 2D kernel density between consecutive breaks, as ggplot2’s geom_density_2d_filled.
`geom_contour()`, `stat_contour()`	`->contour()`	Contour lines of z over a regular grid of x and y, as ggplot2’s geom_contour; bins, binwidth, or breaks.
`geom_contour_filled()`	`->contourFilled()`	Filled contour bands of z over a regular grid, as ggplot2’s geom_contour_filled.
`geom_polygon()`	`->polygon()`	Filled polygons through the points in data order, one per group (or fill level).
`stat_summary()`	`->summary()`	Summaries of y at each x, drawn with geom (pointrange by default), as ggplot2’s stat_summary. funData: mean_se (the default), mean_cl_normal, mean_sdl, median_hilow, or a callable returning [y, ymin, ymax]. fun, funMin, and funMax: mean, median, min, max, sum, sd, n, or callables of the group’s values. funArgs passes mult or conf. geom: pointrange, errorbar, linerange, crossbar, point, line, col, area, or ribbon.
`geom_crossbar()`	`->crossbar()`	A box from ymin to ymax with a line at y, as ggplot2’s geom_crossbar; width is a share of the band.
`stat_ellipse()`	`->ellipse()`	Confidence ellipses per group, as ggplot2’s stat_ellipse: type ‘t’ (a robust multivariate t fit), ‘norm’, or ‘euclid’ (a circle of radius level), at level. geom: ‘polygon’ fills them.
`geom_count()`	`->count()`	Points sized by how many rows share each x and y, as ggplot2’s geom_count.
`annotate()`	`->annotate()`	A layer of fixed values rather than data, as ggplot2’s annotate(): annotate(‘text’, x: 4, y: 40, label: ‘Note’), annotate(‘rect’, xmin: 2, xmax: 3, ymin: -INF …).
`geom_function()`	`->curve()`	A function of x drawn from `from` to `to`, as ggplot2’s geom_function.
`geom_rug()`	`->rug()`	Marginal ticks: sides ‘b’ (bottom, for x), ‘l’ (left, for y), or ‘bl’; length in pixels.
`stat_ecdf()`	`->ecdf()`	Empirical cumulative distribution of x per group.
`stat_qq()`	`->qq()`	Normal quantile-quantile points of the sample aesthetic.
`stat_qq_line()`	`->qqLine()`	The QQ reference line through the sample’s quartiles.
`geom_arc()`	`->arc()`	Pie (or donut, with innerRadius in pixels) slices sized by theta, or counts of fill.
	`->pie()`	Pie or donut slices, as arc() draws them; innerRadius in pixels makes a donut.
	`->layer()`	A raw Vega-Lite layer, used as given.
	`->geom()`	Adds a geom by name with options: the generic form behind the geom methods.

Scales and guides

Function	Method	Purpose
	`->scale()`	Sets the scale for an aesthetic; see Scale::make() for the options.
`scale_x()`, `scale_x_continuous()`, `scale_x_log10()`, `scale_x_sqrt()`, `scale_x_reverse()`, `scale_x_date()`, `scale_x_discrete()`	`->scaleX()`	x scale: type (linear, log, sqrt, time, …), domain, range, zero, nice, reverse, name, breaks, labels, format.
`scale_y()`, `scale_y_continuous()`, `scale_y_log10()`, `scale_y_sqrt()`, `scale_y_reverse()`, `scale_y_date()`, `scale_y_discrete()`	`->scaleY()`	Scale and guide options for y, as scaleX() takes them.
`scale_color()`, `scale_color_manual()`, `scale_color_scheme()`, `scale_color_viridis()`, `scale_color_brewer()`, `scale_color_gradient()`, `scale_color_gradient2()`, `scale_color_viridis_d()`, `scale_color_viridis_c()`, `scale_color_viridis_b()`, `scale_color_distiller()`, `scale_color_fermenter()`, `scale_color_gradientn()`, `scale_color_grey()`, `scale_color_hue()`, `scale_color_identity()`	`->scaleColor()`	Color scale: scheme (‘viridis’, ‘blues’, ‘category10’, …), range, values (manual palette), domainMid, …
`scale_fill()`, `scale_fill_manual()`, `scale_fill_scheme()`, `scale_fill_viridis()`, `scale_fill_brewer()`, `scale_fill_gradient()`, `scale_fill_gradient2()`, `scale_fill_viridis_d()`, `scale_fill_viridis_c()`, `scale_fill_viridis_b()`, `scale_fill_distiller()`, `scale_fill_fermenter()`, `scale_fill_gradientn()`, `scale_fill_grey()`, `scale_fill_hue()`, `scale_fill_identity()`	`->scaleFill()`	Scale and guide options for fill, as scaleColor() takes them.
`scale_size()`	`->scaleSize()`	Scale and guide options for size: range sets the smallest and largest areas in square pixels.
`scale_shape()`	`->scaleShape()`	Scale and guide options for shape: values sets the shapes, by level or in level order.
`scale_alpha()`	`->scaleOpacity()`	Scale and guide options for opacity (alpha): range sets the lowest and highest opacity.
`scale_linetype()`	`->scaleLinetype()`	Scale and guide options for linetype: values sets the dash patterns, by level or in level order.
`guides()`	`->guides()`	Guides per aesthetic, as ggplot2’s guides(): ‘none’ or false hides one, and an array sets axis or legend properties (see guide_legend(), guide_colorbar(), and guide_axis()).
`xlim()`	`->xlim()`	Fixes the x domain.
`ylim()`	`->ylim()`	Fixes the y domain.
`viridis_scheme()`		viridisLite palettes by option: A magma, B inferno, C plasma, D viridis, E cividis, H turbo (or the names).
`brewer_scheme()`		A ColorBrewer scheme, reversed when direction is -1.
`guide_legend()`		Legend options: title, columns (ncol), direction (horizontal or vertical), and further Vega-Lite legend properties.
`guide_colorbar()`		Color bar options: barwidth and barheight in pixels.
`guide_colourbar()`		An alias of `guide_colorbar()`.
`guide_axis()`		Axis options: angle turns the labels anticlockwise, as ggplot2’s guide_axis(angle =); position is top, bottom, left, or right.
`guide_none()`		Hides a guide, as ggplot2’s guide_none(): guides(color: guide_none()).
`label_number()`		Number labels, as scales::label_number(): accuracy rounds, scale multiplies, prefix and suffix wrap.
`label_comma()`		Thousands separators, as scales::label_comma().
`label_percent()`		Percentages of proportions, as scales::label_percent(): 0.25 becomes 25%.
`label_dollar()`		Currency, as scales::label_dollar().
`label_scientific()`		Scientific notation with digits significant digits, as scales::label_scientific().
`label_date()`		Dates and times with a strftime-style format, as scales::label_date().

Coordinates, facets, and composition

Function	Method	Purpose
`coord_flip()`	`->coordFlip()`	Swaps the x and y channels, so mappings stay as written while the plot turns sideways.
`coord_polar()`	`->coordPolar()`	Polar coordinates for bar() and col() layers, as ggplot2’s coord_polar. theta: ‘y’ turns stacked bars into a pie (map x to a constant, or leave it out; innerRadius in pixels makes a donut), and ‘x’ turns bars over a discrete x into a rose of equal angles with radius y. start rotates the first slice clockwise from twelve o’clock, in radians; direction -1 runs anticlockwise.
`coord_fixed()`, `coord_equal()`	`->coordFixed()`	A fixed aspect ratio, as ggplot2’s coord_fixed: one unit of y takes ratio times the length of one unit of x.
`coord_cartesian()`	`->coordCartesian()`	Zooms to fixed domains, clipping marks outside them.
`facet_wrap()`	`->facetWrap()`	Small multiples wrapped into rows. scales: fixed, free, free_x, free_y.
`facet_grid()`	`->facetGrid()`	A grid of panels by rows and/or cols fields.
	`Compose::beside()`	Charts side by side in one row, as patchwork’s p1 + p2 (a Vega-Lite hconcat).
	`Compose::stack()`	Charts stacked in one column, as patchwork’s p1 / p2 (a Vega-Lite vconcat).
	`Compose::grid()`	A grid filled row by row with the given number of columns.
	`$compose->title()`	A title and subtitle over the whole composition.
	`$compose->theme()`	A theme preset and options for the whole composition, as Plot::theme().
	`$compose->resolve()`	Shares or separates scales, axes, and legends across the plots, e.g. [‘scale’ => [‘color’ => ‘independent’]].
	`$compose->raw()`	Deep-merges raw Vega-Lite into the composition’s top level, as Plot::raw() does.
	`$compose->toArray()`	The composition’s Vega-Lite specification.
	`$compose->toSpec()`	The composition’s specification for nesting in another composition: without $schema or config.

Labels and themes

Function	Method	Purpose
`labs()`, `xlab()`, `ylab()`	`->labs()`	Titles: title, subtitle, caption, and one per aesthetic (x, y, color, fill, size, shape, …).
`ggtitle()`	`->title()`	The title and subtitle, as ggplot2’s ggtitle(); null removes the title.
`theme()`, `theme_gray()`, `theme_grey()`, `theme_bw()`, `theme_minimal()`, `theme_classic()`, `theme_light()`, `theme_dark()`, `theme_void()`, `theme_linedraw()`	`->theme()`	A theme preset (gray, bw, linedraw, minimal, classic, light, dark, void, vega) and/or individual options; config is raw Vega-Lite config merged last.
`size()`	`->size()`	Width and height in pixels (per panel when faceted); ‘container’ fills the parent element’s width.
	`->width()`	The width in pixels (per panel when faceted), or ‘container’ to fill the parent element.
	`->height()`	The height in pixels (per panel when faceted), or ‘container’ to fill the parent element.
	`->description()`	A text description of the chart, which vega-embed uses as its accessible name.

Interaction

Function	Method	Purpose
`tooltip()`	`->tooltip()`	Tooltips on every layer: true shows the encoded fields, a list shows those fields.
`interactive()`	`->interactive()`	Pan and zoom by dragging and scrolling (scales bound to an interval selection).
`brush()`	`->brush()`	A drag-to-select interval named $name.
`highlight()`	`->highlight()`	Click legend entries (or marks, with bind: null) to highlight their group; others fade to $opacity.
	`->slider()`	A slider bound to a parameter; use expr($name) in geoms or a filter to react to it.
	`->dropdown()`	A dropdown bound to a parameter.
	`->param()`	A Vega-Lite parameter: a value, optionally bound to an input, or an expr.
	`->select()`	A raw selection parameter, attached to the first layer.

Output

Function	Method	Purpose
	`->toArray()`	The Vega-Lite specification as a PHP array, with $schema and config.
	`->toSpec()`	The specification for nesting in a composition: without $schema or config.
	`->toJson()`	The specification as JSON; pretty adds indentation.
	`->embed()`	An HTML fragment that renders the chart: a container div plus, unless $assets is false, the script tags.
	`->html()`	A complete HTML page that draws the chart, loading the libraries from the CDN unless assets says otherwise.
	`->svg()`	An SVG image rendered by vl-convert.
	`->png()`	A PNG image rendered by vl-convert; scale multiplies the pixel dimensions.
	`->pdf()`	A PDF document rendered by vl-convert.
	`->save()`	Writes to a file whose extension picks the format: svg, png, jpg, pdf, html, or json.
	`->transform()`	Vega-Lite transforms applied to the data before every layer.
	`->raw()`	Raw Vega-Lite merged into the top-level spec last (nested objects merge; lists and scalars replace).
	`->apply()`	Applies a function to the plot: pipe-friendly composition of reusable plot fragments.
	`Html::container()`	The container element for a chart.
	`Html::deferred()`	A container that loads its spec from a URL when it scrolls into view, for pages with many charts.
	`Html::embed()`	A self-contained fragment: the container plus script tags (null assets means the pinned CDN copies).
	`Html::page()`	A complete HTML page that draws the chart, or holds body when chart is null; assets defaults to the CDN.
	`Html::attributes()`	HTML attributes from a name => value map: true writes a bare attribute, and null or false leaves it out.
	`Assets::cdn()`	The pinned libraries from jsDelivr, with subresource integrity; base replaces the CDN address.
	`Assets::local()`	Copies served from your own URL prefix: {base}/vega.min.js, {base}/vega-lite.min.js, {base}/vega-embed.min.js.
	`Assets::urls()`	Explicit URLs for each library.
	`Assets::inline()`	Embeds the three files from a directory containing vega.min.js, vega-lite.min.js and vega-embed.min.js.
	`Assets::none()`	No library tags: for pages that already load vega-embed (bundled with npm, say).
	`$assets->scripts()`	Script tags for the libraries, followed by the phiz loader.
	`Assets::loader()`	The phiz loader script: renders every [data-phiz] element and re-renders when its spec attribute changes.
	`Export::find()`	The vl-convert binary path, or null when none is found.
	`Export::available()`	Whether the vl-convert binary can be found.
	`$export->svg()`	The chart rendered to SVG.
	`$export->png()`	PNG bytes; scale multiplies the pixel size (2 for high-DPI screens), ppi sets the embedded resolution.
	`$export->jpeg()`	The chart rendered to JPEG; scale multiplies the pixel dimensions, and quality runs from 0 to 100.
	`$export->pdf()`	The chart rendered to PDF.
	`$export->vega()`	The compiled Vega (not Vega-Lite) spec.
	`$export->save()`	Writes the chart to a file whose extension picks the format: svg, png, jpg/jpeg, pdf, html, or json.

Statistics

Function	Method	Purpose
`coefplot()`		Coefficient plot of one fit, or of several keyed by label (dodged side by side).
`residual_plot()`		Residuals against fitted values, with a reference line at zero.
`qq_plot()`		A normal QQ plot of a fit’s residuals, or of a list of values; standardize scales them first.
`fitted_plot()`		Observed against fitted values, with the identity line; observed defaults to fitted plus residuals.
`scale_location_plot()`		The square root of the absolute residuals divided by sigma, against fitted values, as R’s plot(fit, 3).
`diagnostic_plots()`		residual_plot(), qq_plot(), scale_location_plot(), and fitted_plot() in a two-by-two grid.
`effect_plot()`		Predicted values with confidence bands as x varies (by levels of $by), other variables held at typical values.
`predictions()`		The predicted rows behind effect_plot() for a grid of rows, without plotting them: each row with estimate, lower, upper, and std_error.
`interval_plot()`		Posterior intervals from draws columns or a summary, as bayesplot’s mcmc_intervals.
`marginal_means()`		Estimated marginal means of a factor with confidence intervals, as emmeans.
`random_effects_plot()`		A caterpillar plot of a mixed model’s random effects with conditional intervals, as lme4’s dotplot(ranef()).