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.

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.

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.

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

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

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.

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.

A circular arc.

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

• 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)

Filled area with either vertical or horizontal orientation.

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

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

• 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)

Stroked lines.

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

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

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

Arbitrary filled polygons.

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

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

• 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)

Filled rectangles.

Either

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

• 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)

Stroked line segments.

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

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

Plotting symbols, including circles, squares and other shapes.

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

• 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 labels with configurable fonts, alignment and angle.

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

• 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)

Filled lines with varying width.

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

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

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.

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

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

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

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

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

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

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

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

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.

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.