Visualize.Components (Visualize v0.2.35)

Copy Markdown View Source

Phoenix LiveView function components for the common chart types (spec/10 §2).

Each component is a preset design of Visualize.Chart.Presets plus an assign mapping (spec/14 §15, D-64): its assigns become a design and the rows the design's source binds to, Visualize.Chart.Frame realises and draws the design, and the component prints the elements the layer returns — the axes, every path, rectangle, circle and label — in the markup spec/10 declares. Its template is the <svg> shell and the attribute order of each mark, nothing more.

Usage

use Phoenix.Component
import Visualize.Components

<.line_chart data={@data} x={& &1.date} y={& &1.value} width={600} height={400} />

Components

Conventions

  • Empty data renders the frame - the <svg> and, where the chart has them, its axes over a [0, 1] domain - with no marks. A domain whose ends coincide (one datum, or every value zero) stays collapsed and maps to the middle of the axis (D-49, D-60).
  • colors is a scheme atom of Visualize.Scale.Color.schemes/0, whose colours are taken by index and cycled, or an explicit list of colours used as given. An unknown scheme or an empty list raises ArgumentError.
  • animate={true} puts style="transition: all 0.3s ease-in-out;" on every mark, so LiveView's DOM patches animate through CSS.
  • theme is a Visualize.Theme (default Visualize.Theme.default/0); every colour, font and size that is not an explicit assign is a slot of it, rendered as a CSS reference with the literal as fallback so a stylesheet overrides it (D-55). A colour assign left nil takes the slot its documentation names.
  • margin is merged over the component's default, so %{left: 60} moves one side.
  • The defaults below are Visualize.Chart.Presets.defaults/1.

This module compiles only when Phoenix.Component is loaded: phoenix_live_view is an optional dependency, present in a host that has LiveView and never fetched otherwise.

Summary

Functions

area_chart(assigns)

Renders an area chart: the area from the baseline up to the series, then the series line on top of it.

bar_chart(assigns)

Renders a vertical bar chart: a band x scale over the categories in data order and a linear y scale from zero.

horizontal_bar_chart(assigns)

Renders a horizontal bar chart: bar_chart/1 with the roles swapped - y is the category accessor on a band scale down the left, x the numeric accessor on a linear scale from zero along the bottom.

line_chart(assigns)

Renders a line chart: one series with bottom and left axes.

pie_chart(assigns)

Renders a pie or donut chart.

scatter_plot(assigns)

Renders a scatter plot: one circle per datum on two linear scales over the extents of the values.

stacked_bar_chart(assigns)

Renders a stacked bar chart: one bar per category, one segment per key, stacked by the :stack transform of spec/14 §5.4.

Functions

area_chart(assigns)

Renders an area chart: the area from the baseline up to the series, then the series line on top of it.

Assigns

  • data - the data points (required); empty renders the frame alone
  • x - as line_chart/1: time, linear or band by the first datum (required)
  • y - accessor to a non-negative number; the y domain is [0, max] (required)
  • width, height - pixels (default 600 by 400)
  • margin - merged over %{top: 20, right: 20, bottom: 30, left: 40}
  • fill, fill_opacity - the area (default nil, the theme's :series_1, at 0.3)
  • stroke, stroke_width - the line (default nil, the theme's :series_1, 2)
  • curve - applied to both the area and the line (default :linear)
  • animate, class, responsive, theme, title, description - per the module conventions

Attributes

  • data (:any) (required)
  • x (:any) (required)
  • y (:any) (required)
  • width (:integer) - Defaults to 600.
  • height (:integer) - Defaults to 400.
  • margin (:map) - Defaults to %{left: 40, right: 20, top: 20, bottom: 30}.
  • fill (:string) - Defaults to nil.
  • fill_opacity (:float) - Defaults to 0.3.
  • stroke (:string) - Defaults to nil.
  • stroke_width (:integer) - Defaults to 2.
  • curve (:atom) - Defaults to :linear.
  • animate (:boolean) - Defaults to false.
  • class (:string) - Defaults to nil.
  • responsive (:boolean) - Defaults to false.
  • theme (:any) - Defaults to nil.
  • title (:string) - Defaults to nil.
  • description (:string) - Defaults to nil.

bar_chart(assigns)

Renders a vertical bar chart: a band x scale over the categories in data order and a linear y scale from zero.

Assigns

  • data - the data points (required); empty renders the frame alone
  • x - accessor to the category (required)
  • y - accessor to a non-negative number; the y domain is [0, max] (required)
  • width, height - pixels (default 600 by 400)
  • margin - merged over %{top: 20, right: 20, bottom: 30, left: 40}
  • fill - bar colour (default nil: the theme's :series_1)
  • padding - band padding, 0 to 1 (default 0.1)
  • animate, class, responsive, theme, title, description - per the module conventions

Attributes

  • data (:any) (required)
  • x (:any) (required)
  • y (:any) (required)
  • width (:integer) - Defaults to 600.
  • height (:integer) - Defaults to 400.
  • margin (:map) - Defaults to %{left: 40, right: 20, top: 20, bottom: 30}.
  • fill (:string) - Defaults to nil.
  • animate (:boolean) - Defaults to false.
  • class (:string) - Defaults to nil.
  • responsive (:boolean) - Defaults to false.
  • theme (:any) - Defaults to nil.
  • title (:string) - Defaults to nil.
  • description (:string) - Defaults to nil.
  • padding (:float) - Defaults to 0.1.

horizontal_bar_chart(assigns)

Renders a horizontal bar chart: bar_chart/1 with the roles swapped - y is the category accessor on a band scale down the left, x the numeric accessor on a linear scale from zero along the bottom.

Assigns

As bar_chart/1, with margin merged over %{top: 20, right: 20, bottom: 30, left: 100} to leave room for the category labels.

Attributes

  • data (:any) (required)
  • x (:any) (required)
  • y (:any) (required)
  • width (:integer) - Defaults to 600.
  • height (:integer) - Defaults to 400.
  • margin (:map) - Defaults to %{left: 100, right: 20, top: 20, bottom: 30}.
  • fill (:string) - Defaults to nil.
  • animate (:boolean) - Defaults to false.
  • class (:string) - Defaults to nil.
  • responsive (:boolean) - Defaults to false.
  • theme (:any) - Defaults to nil.
  • title (:string) - Defaults to nil.
  • description (:string) - Defaults to nil.
  • padding (:float) - Defaults to 0.1.

line_chart(assigns)

Renders a line chart: one series with bottom and left axes.

Assigns

  • data - the data points (required); empty renders the frame alone
  • x - accessor to the x value: a DateTime, NaiveDateTime or Date gives a time scale, a number a linear scale, anything else a band scale, decided by the first datum (required)
  • y - accessor to a numeric y value; the y domain is the extent of the values (required)
  • width, height - pixels (default 600 by 400)
  • margin - %{top:, right:, bottom:, left:}, merged over %{top: 20, right: 20, bottom: 30, left: 40}
  • curve - any curve type of Visualize.Shape.curve/3 (default :linear)
  • stroke - line colour, also the point fill (default nil: the theme's :series_1)
  • stroke_width - (default 2)
  • show_points - draw an r="4" circle at each datum (default false)
  • x_label, y_label - axis titles as <text class="axis-label">
  • animate, class, responsive, theme, title, description - per the module conventions

Example

<.line_chart data={@sales} x={& &1.date} y={& &1.revenue} curve={:monotone_x} />

Attributes

  • data (:any) (required)
  • x (:any) (required)
  • y (:any) (required)
  • width (:integer) - Defaults to 600.
  • height (:integer) - Defaults to 400.
  • margin (:map) - Defaults to %{left: 40, right: 20, top: 20, bottom: 30}.
  • curve (:atom) - Defaults to :linear.
  • stroke (:string) - Defaults to nil.
  • stroke_width (:integer) - Defaults to 2.
  • animate (:boolean) - Defaults to false.
  • class (:string) - Defaults to nil.
  • responsive (:boolean) - Defaults to false.
  • theme (:any) - Defaults to nil.
  • title (:string) - Defaults to nil.
  • description (:string) - Defaults to nil.
  • x_label (:string) - Defaults to nil.
  • y_label (:string) - Defaults to nil.
  • show_points (:boolean) - Defaults to false.

pie_chart(assigns)

Renders a pie or donut chart.

Assigns

  • data - the slices (required); empty renders an empty <svg>
  • value - accessor to the slice value (required)
  • label - accessor to the label text; drawn only when show_labels is also true
  • width, height - pixels (default 400 by 400)
  • inner_radius - greater than 0 makes a donut (default 0)
  • outer_radius - nil means min(width, height) / 2 - 10
  • pad_angle - radians between slices (default 0.02)
  • colors - scheme atom or colour list; the i-th slice takes the i-th colour (default :category10)
  • show_labels - (default true)
  • animate, class, responsive, theme, title, description - per the module conventions

A label sits at the centroid of the slice's mid-radius, as Visualize.Shape.Arc.centroid/2 computes it, inked the theme's text or background, whichever reads on the slice; a slice too narrow for its whole label draws none.

Attributes

  • data (:any) (required)
  • value (:any) (required)
  • label (:any) - Defaults to nil.
  • width (:integer) - Defaults to 400.
  • height (:integer) - Defaults to 400.
  • inner_radius (:integer) - Defaults to 0.
  • outer_radius (:integer) - Defaults to nil.
  • pad_angle (:float) - Defaults to 0.02.
  • colors (:any) - Defaults to :category10.
  • animate (:boolean) - Defaults to false.
  • class (:string) - Defaults to nil.
  • responsive (:boolean) - Defaults to false.
  • theme (:any) - Defaults to nil.
  • title (:string) - Defaults to nil.
  • description (:string) - Defaults to nil.
  • show_labels (:boolean) - Defaults to true.

scatter_plot(assigns)

Renders a scatter plot: one circle per datum on two linear scales over the extents of the values.

Assigns

  • data - the data points (required); empty renders the frame alone
  • x, y - numeric accessors (required)
  • width, height - pixels (default 600 by 400)
  • margin - merged over %{top: 20, right: 20, bottom: 30, left: 40}
  • fill - point colour (default nil: the theme's :series_1)
  • size - the radius, or a one-argument function of the datum returning it (default 5)
  • animate, class, responsive, theme, title, description - per the module conventions

Attributes

  • data (:any) (required)
  • x (:any) (required)
  • y (:any) (required)
  • width (:integer) - Defaults to 600.
  • height (:integer) - Defaults to 400.
  • margin (:map) - Defaults to %{left: 40, right: 20, top: 20, bottom: 30}.
  • fill (:string) - Defaults to nil.
  • size (:any) - Defaults to 5.
  • animate (:boolean) - Defaults to false.
  • class (:string) - Defaults to nil.
  • responsive (:boolean) - Defaults to false.
  • theme (:any) - Defaults to nil.
  • title (:string) - Defaults to nil.
  • description (:string) - Defaults to nil.

stacked_bar_chart(assigns)

Renders a stacked bar chart: one bar per category, one segment per key, stacked by the :stack transform of spec/14 §5.4.

Assigns

  • data - one map per category (required); empty renders the frame alone
  • x - accessor to the category, applied to each point's data (required)
  • keys - the series keys read from each datum (required)
  • width, height - pixels (default 600 by 400)
  • margin - merged over %{top: 20, right: 20, bottom: 30, left: 40}
  • colors - scheme atom or colour list, one colour per key in order (default :category10)
  • padding - band padding (default 0.1)
  • animate, class, responsive, theme, title, description - per the module conventions

The y domain is [0, max y1] over every point of every series.

Attributes

  • data (:any) (required)
  • x (:any) (required)
  • keys (:list) (required)
  • width (:integer) - Defaults to 600.
  • height (:integer) - Defaults to 400.
  • margin (:map) - Defaults to %{left: 40, right: 20, top: 20, bottom: 30}.
  • colors (:any) - Defaults to :category10.
  • animate (:boolean) - Defaults to false.
  • class (:string) - Defaults to nil.
  • responsive (:boolean) - Defaults to false.
  • theme (:any) - Defaults to nil.
  • title (:string) - Defaults to nil.
  • description (:string) - Defaults to nil.
  • padding (:float) - Defaults to 0.1.