Skip to content

Latest commit

 

History

History
324 lines (215 loc) · 8.83 KB

README.md

File metadata and controls

324 lines (215 loc) · 8.83 KB
Raw

Facet Plot

A plotting library inspired by the Grammar of Graphics and various implementations including ggplot and vega.

The main idea behind the library is that a wide variety of different plots can be created by composing a small set of primitive visual marks and that data can be encoded as some visual attribute of those marks. Some examples created with the library can be found here.

Once a plot is declared, it can be 'compiled' with some appropriate data to generate a Scenegraph.

The Scenegraph can then be rendered with any back-end. At the moment the only available rendering is for SVG but over time I may look to create back-ends for Canvas and WebGL.

Facet also supports theming i.e. creating a set of default styles to be applied to non-data attributes of a plot.

The key abstractions that support this are outlined below.

NOTE

As indicated by the name, this library is very much in development. I have open sourced it now since I want to use it in a work project and would like help and feedback on the API.

Plot

A Plot allows you to combine several layers of Encodings along with the corresponding Legends and Axis.

In addition, you can specify how the plot should be facetted to create small multiples.

Axis

An Axis is a special type of Legend for PositionalChannels which shows the user-defined mapping between data and an on-screen position.

Legend

A visualization of the user-defined mapping between data and some visual aspect of a mark.

Facet

Faceting a plot creates series of similar plots (or 'small multiples') sharing the same scale and axes, allowing them to be easily compared.

A plot can be facetted by one Field to create either a row or column of small multiples.

A plot can also be facetted by two Fields to create a grid of small multiples.

Encoding

An Encoding is a means of encoding data as visual mark by combining several Channels to represent various attributes of that visual mark.

A description of each encoding along with the required and optional Channels is given below.

Arc

A circular arc.

Required channels

  • x position (PositionalChannel)
  • y position (PositionalChannel)
  • start angle in Radians (FloatChannel)
  • end angle in Radians (FloatChannel)
  • outer radius in user-space pixels (FloatChannel)

Optional channels

  • inner radius in user-space pixels (FloatChannel)
  • corner radius in user-space pixels (FloatChannel)
  • fill color (ColorChannel)
  • fill opacity, between 0 and 1 (FloatChannel)
  • stroke color (ColorChannel)
  • stroke opacity, between 0 and 1 (FloatChannel)
  • stroke width in user-space pixels (FloatChannel)
  • stroke dash (StrokeDashChannel)
  • tooltip (TextChannel)

Area

Filled area with either vertical or horizontal orientation.

Required channels

  • x positions (PositionalChannel)
  • y positions (PositionalChannel)

You must also provide an interpolation method and the preferred behaviour when missing values are encountered

Optional channels

  • fill color (ColorChannel)
  • fill opacity, between 0 and 1 (FloatChannel)
  • stroke color (ColorChannel)
  • stroke opacity, between 0 and 1 (FloatChannel)
  • stroke width in user-space pixels (FloatChannel)
  • stroke dash (StrokeDashChannel)
  • tooltip (TextChannel)

Line

Stroked lines.

Required channels

  • x positions (PositionalChannel)
  • y positions (PositionalChannel)

You must also provide an interpolation method and the preferred behaviour when missing values are encountered

Optional channels

  • stroke color (ColorChannel)
  • stroke opacity, between 0 and 1 (FloatChannel)
  • stroke width in user-space pixels (FloatChannel)
  • stroke dash (StrokeDashChannel)
  • tooltip (TextChannel)

Polygon

Arbitrary filled polygons.

Required channels

  • x positions (PositionalChannel)
  • y positions (PositionalChannel)

You must also provide an interpolation method and the preferred behaviour when missing values are encountered

Optional channels

  • fill color (ColorChannel)
  • fill opacity, between 0 and 1 (FloatChannel)
  • stroke color (ColorChannel)
  • stroke opacity, between 0 and 1 (FloatChannel)
  • stroke width in user-space pixels (FloatChannel)
  • stroke dash (StrokeDashChannel)
  • tooltip (TextChannel)

Rect

Filled rectangles.

Required channels

Either

  • primary and secondary x and y positions or
  • primary x and y positions, width and height

Optional channels

  • corner radius in user-space pixels (FloatChannel)
  • fill color (ColorChannel)
  • fill opacity, between 0 and 1 (FloatChannel)
  • stroke color (ColorChannel)
  • stroke opacity, between 0 and 1 (FloatChannel)
  • stroke width in user-space pixels (FloatChannel)
  • stroke dash (StrokeDashChannel)
  • tooltip (TextChannel)

Rule

Stroked line segments.

Required channels

  • primary and secondary x positions (PositionalChannel)
  • primary and secondary y positions (PositionalChannel)

Optional channels

  • stroke color (ColorChannel)
  • stroke opacity, between 0 and 1 (FloatChannel)
  • stroke width in user-space pixels (FloatChannel)
  • stroke dash (StrokeDashChannel)
  • tooltip (TextChannel)

Symbol

Plotting symbols, including circles, squares and other shapes.

Required channels

  • shape (ShapeChannel)
  • x position (PositionalChannel)
  • y position (PositionalChannel)

Optional channels

  • size in user-space pixels squared (FloatChannel)
  • angle in Radians (FloatChannel)
  • fill color (ColorChannel)
  • fill opacity, between 0 and 1 (FloatChannel)
  • stroke color (ColorChannel)
  • stroke opacity, between 0 and 1 (FloatChannel)
  • stroke width in user-space pixels (FloatChannel)
  • stroke dash (StrokeDashChannel)
  • tooltip (TextChannel)

Text

Text labels with configurable fonts, alignment and angle.

Required Channels

  • text (TextChannel)
  • x position (PositionalChannel)
  • y position (PositionalChannel)

Optional channels

  • size in user-space pixels squared (FloatChannel)
  • angle in Radians (FloatChannel)
  • fill color (ColorChannel)
  • fill opacity, between 0 and 1 (FloatChannel)
  • stroke color (ColorChannel)
  • stroke opacity, between 0 and 1 (FloatChannel)
  • stroke width in user-space pixels (FloatChannel)
  • stroke dash (StrokeDashChannel)
  • tooltip (TextChannel)

Trail

Filled lines with varying width.

Required Channels

  • widths (FloatChannel)
  • x positions (PositionalChannel)
  • y positions (PositionalChannel)

Optional channels

  • fill color (ColorChannel)
  • fill opacity, between 0 and 1 (FloatChannel)
  • tooltip (TextChannel)

Channel

A Channel is a means representing data as some attribute of a visual mark by specify a Field to extract data and a Scale to transform it to the type required for that Channel

Available channels are summarized below. Each channel corresponds with the type required by some visual attribute of mark.

Positional Channel

A PositionalChannel is used to associate a data value with a position on either the x- or y-axis.

Angle Channel

An AngleChannel is used to encode data as the rotation of a visual mark.

Color Channel

A ColorChannel is used to encode data as either the fill color or stroke color of a visual mark.

Float Channel

A FloatChannel is used to encode data as some non-positional numeric attribute of a visual mark e.g. stroke width, size, font size.

Int Channel

A IntChannel is used to encode data as some non-positional numeric attribute of a visual mark e.g. stroke width, size, font size.

Shape Channel

A ShapeChannel is used to encode data as the shape used in a Symbol visual mark.

Text Channel

A TextChannel is used to encode data as the text of a Text mark or as the tooltip of any visual mark.

Stroke-dash Channel

A StrokeDashChannel is used to encode data as the stroke dash array and (optional) stroke dash offset of a visual mark.

Scale

A scale provides a means of mapping between values of type domain to values of type range.

Scales allow you to specify how data gets transformed after being extracted by a Field.

Field

A Field is a means of extracting a value from some data type.

There are different Fields allowing you to extract different 'shapes' of data:

  • A scalar Field extracts single item from a single piece of data;
  • A vector Field extracts a list of items from a list of data;
  • An aggregate Field summarizes a list of data as a single item.

In addition, each type of field supports situations where the item you are extracting may be missing.