View Source Tucan (tucan v0.1.0)

Documentation for Tucan.

Summary

Plots

Returns the specification of an area plot.

Returns the specification of a bar chart.

Returns the specification of a box plot.

Returns the specification of a bubble plot.

Plot the counts of observations for a categorical variable.

Plot the distribution of a numeric variable.

Draw a line plot between x and y

Returns the specification of a scatter plot with possibility of several semantic groupings.

Returns the specification of a step chart.

Returns the specification of a streamgraph.

Draws a strip plot (categorical scatterplot).

Composite Plots

Plot pairwise relationships in a dataset.

Grouping

Adds a color encoding for the given field.

Apply facetting on the input plot vl by the given field.

Adds a fill encoding for the given field.

Adds a shape encoding for the given field.

Adds a size encoding for the given field.

Adds a stroke_dash encoding for the given field.

Utilities

Flips the axes of the provided chart.

Sets the width of the plot (in pixels).

Sets the title of the plot.

Sets the width of the plot (in pixels).

Functions

Creates if needed a VegaLite plot and adds data to it.

Sets the plot's theme.

Types

Plots

Link to this function

area(plotdata, x, y, opts \\ [])

View Source
@spec area(plotdata :: plotdata(), x :: field(), y :: field(), opts :: keyword()) ::
  VegaLite.t()

Returns the specification of an area plot.

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :interpolate - The line interpolation method to use for line and area marks. One of the following:
    • "linear" - piecewise linear segments, as in a polyline.
    • "linear-closed" - close the linear segments to form a polygon.
    • "step" - alternate between horizontal and vertical segments, as in a step function.
    • "step-before" - alternate between vertical and horizontal segments, as in a step function.
    • "step-after" - alternate between horizontal and vertical segments, as in a step function.
    • "basis" - a B-spline, with control point duplication on the ends.
    • "basis-open" - an open B-spline; may not intersect the start or end.
    • "basis-closed" - a closed B-spline, as in a loop.
    • "cardinal" - a Cardinal spline, with control point duplication on the ends.
    • "cardinal-open" - an open Cardinal spline; may not intersect the start or end, but will intersect other control points.
    • "cardinal-closed" - a closed Cardinal spline, as in a loop.
    • "bundle" - equivalent to basis, except the tension parameter is used to straighten the spline.
    • "monotone" - cubic interpolation that preserves monotonicity in y.
  • :tension (float/0) - Depending on the interpolation type, sets the tension parameter
  • :color_by (String.t/0) - If set a data field that will be used for coloring the data. It is considered :nominal by default.
  • :points (boolean/0) - Whether points will be included in the chart. The default value is false.
  • :line (boolean/0) - Whether the line will be included in the chart The default value is false.
  • :mode - The stacking mode, applied only if :color_by is set. Can be one of the following:
    • :stacked - the default one, areas are stacked
    • :normalize - the stacked charts are normalized
    • :streamgraph - the chart is displaced around a central axis
    • :no_stack - no stacking is applied The default value is :stacked.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

A simple area chart of Google stock price over time. Notice how we change the x axis type from the default (:quantitative) to :temporal using the generic :x channel configuration option:

Tucan.area(:stocks, "date", "price", x: [type: :temporal])
|> VegaLite.transform(filter: "datum.symbol==='GOOG'")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"x":{"field":"date","type":"temporal"},"y":{"field":"price","stack":true,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"line":false,"point":false,"type":"area"},"transform":[{"filter":"datum.symbol==='GOOG'"}]}

You can overlay the points and/or the line:

Tucan.area(:stocks, "date", "price", x: [type: :temporal], points: true, line: true)
|> VegaLite.transform(filter: "datum.symbol==='GOOG'")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"x":{"field":"date","type":"temporal"},"y":{"field":"price","stack":true,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"line":true,"point":true,"type":"area"},"transform":[{"filter":"datum.symbol==='GOOG'"}]}

If you add the :color_by property then the area charts are stacked by default. Below you can see how the generic encoding options can be used in order to modify any part of the underlying VegaLite specification:

Tucan.area(:unemployment, "date", "count",
  color_by: "series",
  x: [type: :temporal, time_unit: :yearmonth, axis: [format: "%Y"]],
  y: [aggregate: :sum],
  color: [scale: [scheme: "category20b"]],
  width: 300,
  height: 200,
  fill_opacity: 1.0
)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/unemployment-across-industries.json"},"encoding":{"color":{"field":"series","scale":{"scheme":"category20b"}},"x":{"axis":{"format":"%Y"},"field":"date","timeUnit":"yearmonth","type":"temporal"},"y":{"aggregate":"sum","field":"count","stack":true,"type":"quantitative"}},"height":200,"mark":{"fillOpacity":1.0,"line":false,"point":false,"type":"area"},"width":300}

You could change the mode to :normalize or :stramgraph:

left =
  Tucan.area(:unemployment, "date", "count",
    color_by: "series",
    mode: :normalize,
    x: [type: :temporal, time_unit: :yearmonth, axis: [format: "%Y"]],
    y: [aggregate: :sum]
  )
  |> Tucan.set_title("normalize")

right =
  Tucan.area(:unemployment, "date", "count",
    color_by: "series",
    mode: :streamgraph,
    x: [type: :temporal, time_unit: :yearmonth, axis: [format: "%Y"]],
    y: [aggregate: :sum]
  )
  |> Tucan.set_title("streamgraph")

VegaLite.concat(VegaLite.new(), [left, right], :horizontal)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","hconcat":[{"data":{"url":"https://vega.github.io/editor/data/unemployment-across-industries.json"},"encoding":{"color":{"field":"series"},"x":{"axis":{"format":"%Y"},"field":"date","timeUnit":"yearmonth","type":"temporal"},"y":{"aggregate":"sum","field":"count","stack":"normalize","type":"quantitative"}},"mark":{"fillOpacity":0.5,"line":false,"point":false,"type":"area"},"title":{"text":"normalize"}},{"data":{"url":"https://vega.github.io/editor/data/unemployment-across-industries.json"},"encoding":{"color":{"field":"series"},"x":{"axis":{"format":"%Y"},"field":"date","timeUnit":"yearmonth","type":"temporal"},"y":{"aggregate":"sum","field":"count","stack":"center","type":"quantitative"}},"mark":{"fillOpacity":0.5,"line":false,"point":false,"type":"area"},"title":{"text":"streamgraph"}}]}

Or you could disable the stacking at all:

Tucan.area(:stocks, "date", "price",
  color_by: "symbol",
  mode: :no_stack,
  x: [type: :temporal],
  width: 400
)
|> Tucan.Axes.set_y_scale(:log)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","type":"temporal"},"y":{"field":"price","scale":{"type":"log"},"stack":false,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"line":false,"point":false,"type":"area"},"width":400}
Link to this function

bar(plotdata, field, value, opts \\ [])

View Source
@spec bar(
  plotdata :: plotdata(),
  field :: binary(),
  value :: binary(),
  opts :: keyword()
) ::
  VegaLite.t()

Returns the specification of a bar chart.

A bar chart is consisted by a categorical field and a numerical value field that defines the height of the bars. You can create a grouped bar chart by setting the :color_by option.

Additionally you should specify the aggregate for the y values, if your dataset contains more than one values per category.

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :color_by (String.t/0) - If set a data field that will be used for coloring the data. It is considered :nominal by default.
  • :orient - The plot's orientation, can be either :horizontal or :vertical. The default value is :horizontal.
  • :mode - The stacking mode, applied only if :color_by is set. Can be one of the following:
    • :stacked - the default one, bars are stacked
    • :normalize - the bars are stacked are normalized
    • :grouped - no stacking is applied, a separate bar for each category The default value is :stacked.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :x_offset (keyword/0) - Extra vega lite options for the :x_offset encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

A simple bar chart:

data = [
  %{"a" => "A", "b" => 28},
  %{"a" => "B", "b" => 55},
  %{"a" => "C", "b" => 43},
  %{"a" => "D", "b" => 91},
  %{"a" => "E", "b" => 81},
  %{"a" => "F", "b" => 53},
  %{"a" => "G", "b" => 19},
  %{"a" => "H", "b" => 87},
  %{"a" => "I", "b" => 52}
]

Tucan.bar(data, "a", "b")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"values":[{"a":"A","b":28},{"a":"B","b":55},{"a":"C","b":43},{"a":"D","b":91},{"a":"E","b":81},{"a":"F","b":53},{"a":"G","b":19},{"a":"H","b":87},{"a":"I","b":52}]},"encoding":{"x":{"field":"a","type":"nominal"},"y":{"field":"b","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"}}

You can set a color_by option that will create a stacked bar chart:

Tucan.bar(:weather, "date", "date",
  color_by: "weather",
  tooltip: true,
  x: [type: :ordinal, time_unit: :month],
  y: [aggregate: :count]
)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/weather.csv"},"encoding":{"color":{"field":"weather"},"x":{"field":"date","timeUnit":"month","type":"ordinal"},"y":{"aggregate":"count","field":"date","type":"quantitative"}},"mark":{"fillOpacity":0.5,"tooltip":true,"type":"bar"}}

If you set the mode option to :grouped you will instead have a different bar per group, you can also change the orientation by setting the :orient flag. Similarly you can set the mode to :normalize in order to have normalized stacked bars.

data = [
  %{"category" => "A", "group" => "x", "value" => 0.1},
  %{"category" => "A", "group" => "y", "value" => 0.6},
  %{"category" => "A", "group" => "z", "value" => 0.9},
  %{"category" => "B", "group" => "x", "value" => 0.7},
  %{"category" => "B", "group" => "y", "value" => 0.2},
  %{"category" => "B", "group" => "z", "value" => 1.1},
  %{"category" => "C", "group" => "x", "value" => 0.6},
  %{"category" => "C", "group" => "y", "value" => 0.1},
  %{"category" => "C", "group" => "z", "value" => 0.2}
]

grouped =
  Tucan.bar(
    data,
    "category",
    "value",
    color_by: "group",
    mode: :grouped,
    orient: :vertical
  )

normalized =
  Tucan.bar(
    data,
    "category",
    "value",
    color_by: "group",
    mode: :normalize
  )

VegaLite.concat(VegaLite.new(), [grouped, normalized], :horizontal)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","hconcat":[{"data":{"values":[{"category":"A","group":"x","value":0.1},{"category":"A","group":"y","value":0.6},{"category":"A","group":"z","value":0.9},{"category":"B","group":"x","value":0.7},{"category":"B","group":"y","value":0.2},{"category":"B","group":"z","value":1.1},{"category":"C","group":"x","value":0.6},{"category":"C","group":"y","value":0.1},{"category":"C","group":"z","value":0.2}]},"encoding":{"color":{"field":"group"},"x":{"field":"value","type":"quantitative"},"y":{"field":"category","type":"nominal"},"yOffset":{"field":"group"}},"mark":{"fillOpacity":0.5,"type":"bar"}},{"data":{"values":[{"category":"A","group":"x","value":0.1},{"category":"A","group":"y","value":0.6},{"category":"A","group":"z","value":0.9},{"category":"B","group":"x","value":0.7},{"category":"B","group":"y","value":0.2},{"category":"B","group":"z","value":1.1},{"category":"C","group":"x","value":0.6},{"category":"C","group":"y","value":0.1},{"category":"C","group":"z","value":0.2}]},"encoding":{"color":{"field":"group"},"x":{"field":"category","type":"nominal"},"y":{"field":"value","stack":"normalize","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"}}]}
Link to this function

boxplot(plotdata, field, opts \\ [])

View Source
@spec boxplot(plotdata :: plotdata(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Returns the specification of a box plot.

By default a one dimensional box plot of the :field - which must be a numerical variable - is generated. You can add a second dimension across a categorical variable by either setting the :group or :color_by options.

By default a Tukey box plot will be generated. In the Tukey box plot the whisker spans from the smallest data to the largest data within the range [Q1 - k * IQR, Q3 + k * IQR] where Q1and Q3 are the first and third quartiles while IQR is the interquartile range (Q3-Q1). You can specify if needed the constant k which defaults to 1.5.

Additionally you can set the mode to :min_max where the lower and upper whiskers are defined as the min and max respectively. No points will be considered as outliers for this type of box plots. In this case the k value is ignored.

What is a box plot

A box plot (box and whisker plot) displays the five-number summary of a set of data. The five-number summary is the minimum, first quartile, median, third quartile, and maximum. In a box plot, we draw a box from the first quartile to the third quartile. A vertical line goes through the box at the median.

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :orient - The plot's orientation, can be either :horizontal or :vertical. The default value is :horizontal.
  • :color_by (String.t/0) - If set a data field that will be used for coloring the data. It is considered :nominal by default.
  • :group (String.t/0) - A field to be used for grouping the boxplot. It is used for adding a second dimension to the plot. If not set the plot will be one dimensional. Notice that a grouping is automatically applied if the :color_by option is set.
  • :mode - The type of the box plot. Either a Tukey box plot will be created or a min-max plot. The default value is :tukey.
  • :k (float/0) - The constant used for calculating the extent of the whiskers in a Tukey boxplot. Applicable only if :mode is set to :tukey. The default value is 1.5.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

A one dimensional Tukey boxplot:

Tucan.boxplot(:penguins, "Body Mass (g)")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"x":{"field":"Body Mass (g)","scale":{"zero":false},"type":"quantitative"}},"mark":{"extent":1.5,"fillOpacity":0.5,"type":"boxplot"}}

You can set :group or :color_by in order to set a second dimension:

Tucan.boxplot(:penguins, "Body Mass (g)", color_by: "Species")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"field":"Body Mass (g)","scale":{"zero":false},"type":"quantitative"},"y":{"field":"Species","type":"nominal"}},"mark":{"extent":1.5,"fillOpacity":0.5,"type":"boxplot"}}

You can set the mode to :min_max in order to extend the whiskers to the min and max values:

Tucan.boxplot(:penguins, "Body Mass (g)", color_by: "Species", mode: :min_max)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"field":"Body Mass (g)","scale":{"zero":false},"type":"quantitative"},"y":{"field":"Species","type":"nominal"}},"mark":{"extent":"min-max","fillOpacity":0.5,"type":"boxplot"}}

By setting the :orient to :vertical you can change the default horizontal orientation:

Tucan.boxplot(:penguins, "Body Mass (g)", color_by: "Species", orient: :vertical)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"field":"Species","type":"nominal"},"y":{"field":"Body Mass (g)","scale":{"zero":false},"type":"quantitative"}},"mark":{"extent":1.5,"fillOpacity":0.5,"type":"boxplot"}}
Link to this function

bubble(plotdata, x, y, size, opts \\ [])

View Source
@spec bubble(
  plotdata :: plotdata(),
  x :: field(),
  y :: field(),
  size :: field(),
  opts :: keyword()
) :: VegaLite.t()

Returns the specification of a bubble plot.

A bubble plot is a scatter plot with a third parameter defining the size of the dots.

All x, y and size must be numerical data fields.

See also scatter/4.

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :color_by (String.t/0) - If set a data field that will be used for coloring the data. It is considered :nominal by default.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :size (keyword/0) - Extra vega lite options for the :size encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

Tucan.bubble(:gapminder, "income", "health", "population", width: 400)
|> Tucan.Axes.set_x_title("Gdp per Capita")
|> Tucan.Axes.set_y_title("Life expectancy")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/vega-datasets/data/gapminder-health-income.csv"},"encoding":{"size":{"field":"population","type":"quantitative"},"x":{"axis":{"title":"Gdp per Capita"},"field":"income","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"Life expectancy"},"field":"health","scale":{"zero":false},"type":"quantitative"}},"mark":"circle","width":400}

You could use a fourth variable to color the graph. As always you can set the tooltip in order to make the plot interactive:

Tucan.bubble(:gapminder, "income", "health", "population",
  color_by: "region",
  width: 400,
  tooltip: :data
)
|> Tucan.Axes.set_x_title("Gdp per Capita")
|> Tucan.Axes.set_y_title("Life expectancy")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/vega-datasets/data/gapminder-health-income.csv"},"encoding":{"color":{"field":"region","type":"nominal"},"size":{"field":"population","type":"quantitative"},"x":{"axis":{"title":"Gdp per Capita"},"field":"income","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"Life expectancy"},"field":"health","scale":{"zero":false},"type":"quantitative"}},"mark":{"tooltip":{"content":"data"},"type":"circle"},"width":400}

It makes more sense to use a log scale for the x axis:

Tucan.bubble(:gapminder, "income", "health", "population",
  color_by: "region",
  width: 400,
  tooltip: :data
)
|> Tucan.Axes.set_x_title("Gdp per Capita")
|> Tucan.Axes.set_y_title("Life expectancy")
|> Tucan.Axes.set_x_scale(:log)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/vega-datasets/data/gapminder-health-income.csv"},"encoding":{"color":{"field":"region","type":"nominal"},"size":{"field":"population","type":"quantitative"},"x":{"axis":{"title":"Gdp per Capita"},"field":"income","scale":{"type":"log","zero":false},"type":"quantitative"},"y":{"axis":{"title":"Life expectancy"},"field":"health","scale":{"zero":false},"type":"quantitative"}},"mark":{"tooltip":{"content":"data"},"type":"circle"},"width":400}
Link to this function

countplot(plotdata, field, opts \\ [])

View Source
@spec countplot(plotdata :: plotdata(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Plot the counts of observations for a categorical variable.

Takes a categorical field as input and generates a count plot visualization. By default the counts are plotted on the y-axis and the categorical field across the x-axis.

This is similar to histogram/3 but specifically for a categorical variable.

This is a simple wrapper around bar/4 where by default the count of observations is mapped to the y variable.

What is a countplot?

A countplot is a type of bar chart used in data visualization to display the frequency of occurrences of categorical data. It is particularly useful for visualizing the distribution and frequency of different categories within a dataset.

In a countplot, each unique category is represented by a bar, and the height of the bar corresponds to the number of occurrences of that category in the data.

Options

See bar/4

Examples

We will use the :titanic dataset on the following examples. We can plot the number of passengers by ticket class:

Tucan.countplot(:titanic, "Pclass")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv"},"encoding":{"x":{"field":"Pclass","type":"nominal"},"y":{"aggregate":"count","field":"Pclass","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"}}

You can make the bars horizontal by setting the :orient option:

Tucan.countplot(:titanic, "Pclass", orient: :vertical)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv"},"encoding":{"x":{"aggregate":"count","field":"Pclass","type":"quantitative"},"y":{"field":"Pclass","type":"nominal"}},"mark":{"fillOpacity":0.5,"type":"bar"}}

You can set :color_by to group it by a second variable:

Tucan.countplot(:titanic, "Pclass", color_by: "Survived")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv"},"encoding":{"color":{"field":"Survived"},"x":{"field":"Pclass","type":"nominal"},"y":{"aggregate":"count","field":"Pclass","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"}}

By default the bars are stacked. You can unstack them by setting the :mode to :grouped

Tucan.countplot(:titanic, "Pclass", color_by: "Survived", mode: :grouped)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv"},"encoding":{"color":{"field":"Survived"},"x":{"field":"Pclass","type":"nominal"},"xOffset":{"field":"Survived"},"y":{"aggregate":"count","field":"Pclass","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"}}
Link to this function

density(plotdata, field, opts \\ [])

View Source
@spec density(plotdata :: plotdata(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Plot the distribution of a numeric variable.

Density plots allow you to visualize the distribution of a numeric variable for one or several groups. If you want to draw the density for several groups you need to specify the :color_by option which is assumed to be a categorical variable.

Avoid calling color_by/3 with a density plot

Since the grouping variable must also be used for properly calculating the density transformation you should avoid calling the color_by/3 grouping function after a density/3 call. Instead use the :color_by option, which will ensure that the proper settings are applied to the underlying transformation.

Calling color_by/3 would produce this graph:

Tucan.density(:penguins, "Body Mass (g)")
|> Tucan.color_by("Species")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"area"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","maxsteps":200,"minsteps":25}]}

In the above case the density function has been calculated on the complete dataset and you cannot color by the Species. Instead you should use the :color_by option which would calculate the density function per group:

Tucan.density(:penguins, "Body Mass (g)", color_by: "Species", fill_opacity: 0.2)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.2,"type":"area"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]}

Alternatively you should use the :groupby option in order to group the density tranform by the Species field and then apply the color_by/3 function:

Tucan.density(:penguins, "Body Mass (g)", groupby: ["Species"])
|> Tucan.color_by("Species")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"area"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]}

See also histogram/3.

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.

  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.

  • :color_by (String.t/0) - If set a data field that will be used for coloring the data. It is considered :nominal by default.

  • :groupby (list of String.t/0) - The data fields to group by. If not specified, a single group containing all data objects will be used. This is applied only on the density transform.

    In most cases you only need to set color_by which will automatically handle the density transform grouping. Use groupby only if you want to manually post-process the generated specification, or if you want to apply grouping by more than one variable.

    If both groupby and color_by are set then only groupby is used for grouping the density transform and color_by is used for encoding the color.

  • :cumulative (boolean/0) - A boolean flag indicating whether to produce density estimates (false) or cumulative density estimates (true). The default value is false.

  • :counts (boolean/0) - A boolean flag indicating if the output values should be probability estimates (false) or smoothed counts (true). The default value is false.

  • :bandwidth (float/0) - The bandwidth (standard deviation) of the Gaussian kernel. If unspecified or set to zero, the bandwidth value is automatically estimated from the input data using Scott’s rule.

  • :extent - A [min, max] domain from which to sample the distribution. If unspecified, the extent will be determined by the observed minimum and maximum values of the density value field.

  • :minsteps (integer/0) - The minimum number of samples to take along the extent domain for plotting the density. The default value is 25.

  • :maxsteps (integer/0) - The maximum number of samples to take along the extent domain for plotting the density. The default value is 200.

  • :steps (integer/0) - The exact number of samples to take along the extent domain for plotting the density. If specified, overrides both minsteps and maxsteps to set an exact number of uniform samples. Potentially useful in conjunction with a fixed extent to ensure consistent sample points for stacked densities.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

Tucan.density(:penguins, "Body Mass (g)")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"area"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","maxsteps":200,"minsteps":25}]}

It is a common use case to compare the density of several groups in a dataset. Several options exist to do so. You can plot all items on the same chart, using transparency and annotation to make the comparison possible.

Tucan.density(:penguins, "Body Mass (g)", color_by: "Species")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"area"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]}

You can also combine it with facet_by/4 in order to draw a different plot for each value of the grouping variable. Notice that we need to set the :groupby variable in order to correctly calculate the density plot per field's value.

Tucan.density(:penguins, "Body Mass (g)", groupby: ["Species"])
|> Tucan.color_by("Species")
|> Tucan.facet_by(:column, "Species")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"column":{"field":"Species"},"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"area"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]}

You can control the smoothing by setting a specific bandwidth value (if not set it is automatically calculated by vega lite):

Tucan.density(:penguins, "Body Mass (g)", color_by: "Species", bandwidth: 20.0)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"area"},"transform":[{"bandwidth":20.0,"counts":false,"cumulative":false,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]}

You can plot a cumulative density distribution by setting the :cumulative option to true:

Tucan.density(:penguins, "Body Mass (g)", cumulative: true)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"area"},"transform":[{"counts":false,"cumulative":true,"density":"Body Mass (g)","maxsteps":200,"minsteps":25}]}

or calculate a separate cumulative distribution for each group:

Tucan.density(:penguins, "Body Mass (g)", cumulative: true, color_by: "Species")
|> Tucan.facet_by(:column, "Species")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"column":{"field":"Species"},"x":{"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"area"},"transform":[{"counts":false,"cumulative":true,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]}
Link to this function

density_heatmap(plotdata, x, y, opts \\ [])

View Source
@spec density_heatmap(
  plotdata :: plotdata(),
  x :: binary(),
  y :: binary(),
  opts :: keyword()
) ::
  VegaLite.t()

Draws a density heatmap.

A density heatmap is a bivariate histogram, e.g. the x, y data are binned within rectangles that tile the plot and then the count of observations within each rectangle is shown with the fill color.

By default the count of observations within each rectangle is encoded, but you can calculate the statistic of any field and use it instead.

Density heatmaps are a powerful visualization tool that find their best use cases in situations where you need to explore and understand the distribution and concentration of data points in a two-dimensional space. They are particularly effective when dealing with large datasets, allowing you to uncover patterns, clusters, and trends that might be difficult to discern in raw data.

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :z (String.t/0) - If set corresponds to the field that will be used for calculating the color fo the bin using the provided aggregate. If not set (the default behaviour) the count of observations are used for coloring the bin.
  • :aggregate (atom/0) - The statistic that will be used for aggregating the observations within a bin. The z field must be set if aggregate is set.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

Let's start with a default denisty heatmap on the penguins dataset:

Tucan.density_heatmap(:penguins, "Beak Length (mm)", "Beak Depth (mm)")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"aggregate":"count","type":"quantitative"},"x":{"bin":true,"field":"Beak Length (mm)","type":"quantitative"},"y":{"bin":true,"field":"Beak Depth (mm)","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"rect"}}

You can summarize over another field:

Tucan.density_heatmap(:penguins, "Beak Length (mm)", "Beak Depth (mm)",
  z: "Body Mass (g)",
  aggregate: :mean
)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"aggregate":"mean","field":"Body Mass (g)","type":"quantitative"},"x":{"bin":true,"field":"Beak Length (mm)","type":"quantitative"},"y":{"bin":true,"field":"Beak Depth (mm)","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"rect"}}
Link to this function

donut(plotdata, field, category, opts \\ [])

View Source
@spec donut(
  plotdata :: plotdata(),
  field :: binary(),
  category :: binary(),
  opts :: keyword()
) ::
  VegaLite.t()

Draw a donut chart.

A donut chart is a circular visualization that resembles a pie chart but features a hole at its center. This central hole creates a donut shape, distinguishing it from traditional pie charts.

This is a wrapper around pie/4 that sets by default the :inner_radius.

Options

See pie/4

Examples

Tucan.donut(:barley, "yield", "site", aggregate: :sum, tooltip: true)
|> Tucan.facet_by(:column, "year", type: :nominal)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/barley.json"},"encoding":{"color":{"field":"site"},"column":{"field":"year","type":"nominal"},"theta":{"aggregate":"sum","field":"yield","type":"quantitative"}},"mark":{"fillOpacity":0.5,"innerRadius":50,"tooltip":true,"type":"arc"}}
Link to this function

histogram(plotdata, field, opts \\ [])

View Source
@spec histogram(plotdata :: plotdata(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Plots a histogram.

See also density/3

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :relative (boolean/0) - If set a relative frequency histogram is generated. The default value is false.
  • :orient - Histogram's orientation. It specifies the axis along which the field values are plotted. The default value is :horizontal.
  • :color_by (String.t/0) - The field to group observations by. This will used for coloring the histogram if set.
  • :maxbins (integer/0) - Maximum number of bins.
  • :step - An exact step size to use between bins. If provided, options such as maxbins will be ignored.
  • :extent - A two-element ([min, max]) array indicating the range of desired bin values.
  • :stacked (boolean/0) - If set it will stack the group histograms instead of layering one over another. Valid only if a semantic grouping has been applied.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :x2 (keyword/0) - Extra vega lite options for the :x2 encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

Histogram of Horsepower

Tucan.histogram(:cars, "Horsepower")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"bin":{"binned":true},"field":"bin_Horsepower","title":"Horsepower"},"x2":{"field":"bin_Horsepower_end"},"y":{"field":"count_Horsepower","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":true,"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end"]}]}

You can flip the plot by setting the :orient option to :vertical:

Tucan.histogram(:cars, "Horsepower", orient: :vertical)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"field":"count_Horsepower","stack":null,"type":"quantitative"},"y":{"bin":{"binned":true},"field":"bin_Horsepower","title":"Horsepower"},"y2":{"field":"bin_Horsepower_end"}},"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":true,"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end"]}]}

By setting the :relative flag you can get a relative frequency histogram:

Tucan.histogram(:cars, "Horsepower", relative: true)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"bin":{"binned":true},"field":"bin_Horsepower","title":"Horsepower"},"x2":{"field":"bin_Horsepower_end"},"y":{"axis":{"format":".1~%"},"field":"percent_Horsepower","stack":null,"title":"Relative Frequency","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":true,"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end"]},{"groupby":[],"joinaggregate":[{"as":"total_count_Horsepower","field":"count_Horsepower","op":"sum"}]},{"as":"percent_Horsepower","calculate":"datum.count_Horsepower/datum.total_count_Horsepower"}]}

You can increase the number of bins by settings the maxbins or the step options:

Tucan.histogram(:cars, "Horsepower", step: 5)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"bin":{"binned":true},"field":"bin_Horsepower","title":"Horsepower"},"x2":{"field":"bin_Horsepower_end"},"y":{"field":"count_Horsepower","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":{"step":5},"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end"]}]}

You can draw multiple histograms by grouping the observations by a second categorical variable:

Tucan.histogram(:cars, "Horsepower", color_by: "Origin", fill_opacity: 0.5)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"color":{"field":"Origin"},"x":{"bin":{"binned":true},"field":"bin_Horsepower","title":"Horsepower"},"x2":{"field":"bin_Horsepower_end"},"y":{"field":"count_Horsepower","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":true,"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end","Origin"]}]}

By default the histograms are plotted layered, but you can also stack them:

Tucan.histogram(:cars, "Horsepower", color_by: "Origin", fill_opacity: 0.5, stacked: true)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"color":{"field":"Origin"},"x":{"bin":{"binned":true},"field":"bin_Horsepower","title":"Horsepower"},"x2":{"field":"bin_Horsepower_end"},"y":{"field":"count_Horsepower","stack":true,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":true,"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end","Origin"]}]}

or you can facet it, in order to make the histograms more clear:

histograms =
  Tucan.histogram(:cars, "Horsepower", color_by: "Origin")
  |> Tucan.facet_by(:column, "Origin")

relative_histograms =
  Tucan.histogram(:cars, "Horsepower",
    relative: true,
    color_by: "Origin",
    fill_opacity: 0.5,
    tooltip: true
  )
  |> Tucan.facet_by(:column, "Origin")

VegaLite.concat(VegaLite.new(), [histograms, relative_histograms], :vertical)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","vconcat":[{"data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"color":{"field":"Origin"},"column":{"field":"Origin"},"x":{"bin":{"binned":true},"field":"bin_Horsepower","title":"Horsepower"},"x2":{"field":"bin_Horsepower_end"},"y":{"field":"count_Horsepower","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":true,"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end","Origin"]}]},{"data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"color":{"field":"Origin"},"column":{"field":"Origin"},"x":{"bin":{"binned":true},"field":"bin_Horsepower","title":"Horsepower"},"x2":{"field":"bin_Horsepower_end"},"y":{"axis":{"format":".1~%"},"field":"percent_Horsepower","stack":null,"title":"Relative Frequency","type":"quantitative"}},"mark":{"fillOpacity":0.5,"tooltip":true,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":true,"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end","Origin"]},{"groupby":["Origin"],"joinaggregate":[{"as":"total_count_Horsepower","field":"count_Horsepower","op":"sum"}]},{"as":"percent_Horsepower","calculate":"datum.count_Horsepower/datum.total_count_Horsepower"}]}]}
Link to this function

lineplot(plotdata, x, y, opts \\ [])

View Source
@spec lineplot(plotdata :: plotdata(), x :: field(), y :: field(), opts :: keyword()) ::
  VegaLite.t()

Draw a line plot between x and y

Both x and y are considered numerical variables.

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :interpolate - The line interpolation method to use for line and area marks. One of the following:
    • "linear" - piecewise linear segments, as in a polyline.
    • "linear-closed" - close the linear segments to form a polygon.
    • "step" - alternate between horizontal and vertical segments, as in a step function.
    • "step-before" - alternate between vertical and horizontal segments, as in a step function.
    • "step-after" - alternate between horizontal and vertical segments, as in a step function.
    • "basis" - a B-spline, with control point duplication on the ends.
    • "basis-open" - an open B-spline; may not intersect the start or end.
    • "basis-closed" - a closed B-spline, as in a loop.
    • "cardinal" - a Cardinal spline, with control point duplication on the ends.
    • "cardinal-open" - an open Cardinal spline; may not intersect the start or end, but will intersect other control points.
    • "cardinal-closed" - a closed Cardinal spline, as in a loop.
    • "bundle" - equivalent to basis, except the tension parameter is used to straighten the spline.
    • "monotone" - cubic interpolation that preserves monotonicity in y.
  • :tension (float/0) - Depending on the interpolation type, sets the tension parameter
  • :color_by (String.t/0) - If set a data field that will be used for coloring the data. It is considered :nominal by default.
  • :group_by (String.t/0) - A field to group by the lines without affecting the style of it.
  • :points (boolean/0) - Whether points will be included in the chart. The default value is false.
  • :filled (boolean/0) - Whether the points will be filled or not. Valid only if :points is set. The default value is true.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

Plotting a simple line chart of Google stock price over time. Notice how we change the x axis type from the default (:quantitative) to :temporal using the generic :x channel configuration option:

Tucan.lineplot(:stocks, "date", "price", x: [type: :temporal])
|> VegaLite.transform(filter: "datum.symbol==='GOOG'")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"x":{"field":"date","type":"temporal"},"y":{"field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"line"},"transform":[{"filter":"datum.symbol==='GOOG'"}]}

You could plot all stocks of the dataset with different colors by setting the :color_by option. If you do not want to color lines differently, you can pass the :group_by option instead of :color_by:

left = Tucan.lineplot(:stocks, "date", "price", x: [type: :temporal], color_by: "symbol")
right = Tucan.lineplot(:stocks, "date", "price", x: [type: :temporal], group_by: "symbol")

VegaLite.concat(VegaLite.new(), [left, right], :horizontal)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","hconcat":[{"data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","type":"temporal"},"y":{"field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"line"}},{"data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"detail":{"field":"symbol","type":"nominal"},"x":{"field":"date","type":"temporal"},"y":{"field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"line"}}]}

You can also overlay the points by setting the :points and :filled opts. Notice that below we plot by year and aggregating the y values:

filled_points =
  Tucan.lineplot(:stocks, "date", "price",
    x: [type: :temporal, time_unit: :year],
    y: [aggregate: :mean],
    color_by: "symbol",
    points: true,
    tooltip: true,
    width: 300
  )

stroked_points =
  Tucan.lineplot(:stocks, "date", "price",
    x: [type: :temporal, time_unit: :year],
    y: [aggregate: :mean],
    color_by: "symbol",
    points: true,
    filled: false,
    tooltip: true,
    width: 300
  )

VegaLite.concat(VegaLite.new(), [filled_points, stroked_points], :horizontal)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","hconcat":[{"data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","timeUnit":"year","type":"temporal"},"y":{"aggregate":"mean","field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"point":true,"tooltip":true,"type":"line"},"width":300},{"data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","timeUnit":"year","type":"temporal"},"y":{"aggregate":"mean","field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"point":{"fill":"white","filled":false},"tooltip":true,"type":"line"},"width":300}]}

You can use various interpolation methods. Some examples follow:

plots =
  for interpolation <- ["linear", "step", "cardinal", "monotone"] do
    Tucan.lineplot(:stocks, "date", "price",
      x: [type: :temporal, time_unit: :year],
      y: [aggregate: :mean],
      color_by: "symbol",
      interpolate: interpolation
    )
    |> Tucan.set_title(interpolation)
  end

VegaLite.concat(VegaLite.new(columns: 2), plots, :wrappable)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","columns":2,"concat":[{"data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","timeUnit":"year","type":"temporal"},"y":{"aggregate":"mean","field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"interpolate":"linear","type":"line"},"title":{"text":"linear"}},{"data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","timeUnit":"year","type":"temporal"},"y":{"aggregate":"mean","field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"interpolate":"step","type":"line"},"title":{"text":"step"}},{"data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","timeUnit":"year","type":"temporal"},"y":{"aggregate":"mean","field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"interpolate":"cardinal","type":"line"},"title":{"text":"cardinal"}},{"data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","timeUnit":"year","type":"temporal"},"y":{"aggregate":"mean","field":"price","type":"quantitative"}},"mark":{"fillOpacity":0.5,"interpolate":"monotone","type":"line"},"title":{"text":"monotone"}}]}
Link to this function

pie(plotdata, field, category, opts \\ [])

View Source
@spec pie(
  plotdata :: plotdata(),
  field :: binary(),
  category :: binary(),
  opts :: keyword()
) ::
  VegaLite.t()

Draws a pie chart.

A pie chart is a circle divided into sectors that each represents a proportion of the whole. The field specifies the data column that contains the proportions of each category. The chart will be colored by the caregory field.

Avoid using pie charts

Despite it's popularity pie charts should rarely be used. Pie charts are best suited for displaying a small number of categories and can make it challenging to accurately compare data. They rely on angle perception, which can lead to misinterpretation, and lack the precision offered by other charts like bar charts or line charts.

Instead, opt for alternatives such as bar charts for straightforward comparisons, stacked area charts for cumulative effects.

The following example showcases the limitations of a pie chart, compared to a bar chart:

alias VegaLite, as: Vl

data = [
  %{value: 30, category: "A"},
  %{value: 33, category: "B"},
  %{value: 38, category: "C"}
]

pie = Tucan.pie(Vl.new(), "value", "category")

# TODO: replace with the bar call once implemented
bar =
  Vl.new()
  |> Tucan.new()
  |> Vl.mark(:bar)
  |> Vl.encode_field(:y, "category")
  |> Vl.encode_field(:x, "value", type: :quantitative)

Vl.new()
|> Vl.data_from_values(data)
|> Vl.concat([pie, bar], :horizontal)
|> Tucan.set_title("Pie vs Bar chart", anchor: :middle, offset: 15)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"values":[{"category":"A","value":30},{"category":"B","value":33},{"category":"C","value":38}]},"hconcat":[{"encoding":{"color":{"field":"category"},"theta":{"field":"value","type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"arc"}},{"encoding":{"x":{"field":"value","type":"quantitative"},"y":{"field":"category"}},"mark":"bar"}],"title":{"anchor":"middle","offset":15,"text":"Pie vs Bar chart"}}

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :inner_radius (integer/0) - The inner radius in pixels. 0 for a pie chart, > 0 for a donut chart. If not set it defaults to 0
  • :aggregate (atom/0) - The statistic to use (if any) for aggregating values per pie slice (e.g. :mean).

Encodings Custom Options

  • :theta (keyword/0) - Extra vega lite options for the :thetar encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

Tucan.pie(:barley, "yield", "site", aggregate: :sum, tooltip: true)
|> Tucan.facet_by(:column, "year", type: :nominal)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/barley.json"},"encoding":{"color":{"field":"site"},"column":{"field":"year","type":"nominal"},"theta":{"aggregate":"sum","field":"yield","type":"quantitative"}},"mark":{"fillOpacity":0.5,"tooltip":true,"type":"arc"}}
Link to this function

scatter(plotdata, x, y, opts \\ [])

View Source
@spec scatter(plotdata :: plotdata(), x :: binary(), y :: binary(), opts :: keyword()) ::
  VegaLite.t()

Returns the specification of a scatter plot with possibility of several semantic groupings.

Both x and y must be :quantitative.

Semantic groupings

The relationship between x and y can be shown for different subsets of the data using the color_by, size_by and shape_by parameters. This is equivalent to calling the corresponding functions after a scatter/4 call.

These parameters control what visual semantics are used to identify the different subsets. It is possible to show up to three dimensions independently by using all three semantic types, but this style of plot can be hard to interpret and is often ineffective.

Tucan.scatter(:tips, "total_bill", "tip",
  color_by: "day",
  shape_by: "sex",
  size_by: "size"
)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"day","type":"nominal"},"shape":{"field":"sex","type":"nominal"},"size":{"field":"size","type":"quantitative"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"}}

The above is equivalent to calling:

Tucan.scatter(:tips, "total_bill", "tip")
|> Tucan.color_by("day", type: :nominal)
|> Tucan.shape_by("sex", type: :nominal)
|> Tucan.size_by("size", type: :quantitative)

Using redundant semantics (i.e. both color and shape for the same variable) can be helpful for making graphics more accessible.

Tucan.scatter(:tips, "total_bill", "tip",
  color_by: "day",
  shape_by: "day"
)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"day","type":"nominal"},"shape":{"field":"day","type":"nominal"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"}}

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.
  • :color_by (String.t/0) - If set a data field that will be used for coloring the data. It is considered :nominal by default.
  • :shape_by (String.t/0) - If set a data field that will be used for setting the shape of the data points. It is considered :nominal by default.
  • :size_by (String.t/0) - If set a data field that will be used for controlling the size of the data points. It is considered :quantitative by default.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :color (keyword/0) - Extra vega lite options for the :color encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :shape (keyword/0) - Extra vega lite options for the :shape encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :size (keyword/0) - Extra vega lite options for the :size encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Examples

We will use the :tips dataset thoughout the following examples.

Drawing a scatter plot betwen two variables:

Tucan.scatter(:tips, "total_bill", "tip")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"}}

You can combine it with color_by/3 to color code the points:

Tucan.scatter(:tips, "total_bill", "tip")
|> Tucan.color_by("time")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"time"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"}}

Assigning the same variable to shape_by/3 will also vary the markers and create a more accessible plot:

Tucan.scatter(:tips, "total_bill", "tip", width: 400)
|> Tucan.color_by("time")
|> Tucan.shape_by("time")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"time"},"shape":{"field":"time"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"},"width":400}

Assigning color_by/3 and shape_by/3 to different variables will vary colors and markers independently:

Tucan.scatter(:tips, "total_bill", "tip", width: 400)
|> Tucan.color_by("day")
|> Tucan.shape_by("time")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"day"},"shape":{"field":"time"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"},"width":400}

You can also color the points by a numeric variable, the semantic mapping will be quantitative and will use a different default palette:

Tucan.scatter(:tips, "total_bill", "tip", width: 400)
|> Tucan.color_by("size", type: :quantitative)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"size","type":"quantitative"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"},"width":400}

A numeric variable can also be assigned to size to apply a semantic mapping to the areas of the points:

Tucan.scatter(:tips, "total_bill", "tip", width: 400, tooltip: :data)
|> Tucan.color_by("size", type: :quantitative)
|> Tucan.size_by("size", type: :quantitative)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"size","type":"quantitative"},"size":{"field":"size","type":"quantitative"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"tooltip":{"content":"data"},"type":"point"},"width":400}

You can also combine it with facet_by/3 in order to group within additional categorical variables, and plot them across multiple subplots.

Tucan.scatter(:tips, "total_bill", "tip", width: 300)
|> Tucan.color_by("day")
|> Tucan.shape_by("day")
|> Tucan.facet_by(:column, "time")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"day"},"column":{"field":"time"},"shape":{"field":"day"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"},"width":300}

You can also apply faceting on more than one variables, both horizontally and vertically:

Tucan.scatter(:tips, "total_bill", "tip", width: 300)
|> Tucan.color_by("day")
|> Tucan.shape_by("day")
|> Tucan.size_by("size")
|> Tucan.facet_by(:column, "time")
|> Tucan.facet_by(:row, "sex")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"day"},"column":{"field":"time"},"row":{"field":"sex"},"shape":{"field":"day"},"size":{"field":"size"},"x":{"field":"total_bill","scale":{"zero":false},"type":"quantitative"},"y":{"field":"tip","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"},"width":300}
Link to this function

step(plotdata, x, y, opts \\ [])

View Source
@spec step(plotdata :: plotdata(), x :: field(), y :: field(), opts :: keyword()) ::
  VegaLite.t()

Returns the specification of a step chart.

This is a simple wrapper around lineplot/4 with :interpolate set by default to "step". If :interpolate is set to any of step, step-before, step-after it will be used. In any other case defaults to step.

Options

Check lineplot/4

Examples

Tucan.step(:stocks, "date", "price", color_by: "symbol", width: 300, x: [type: :temporal])
|> Tucan.Axes.set_y_scale(:log)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","type":"temporal"},"y":{"field":"price","scale":{"type":"log"},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"interpolate":"step","type":"line"},"width":300}
Link to this function

streamgraph(plotdata, x, y, group, opts \\ [])

View Source
@spec streamgraph(
  plotdata :: plotdata(),
  x :: field(),
  y :: field(),
  group :: field(),
  opts :: keyword()
) :: VegaLite.t()

Returns the specification of a streamgraph.

This is a simple wrapper around area/4 with :mode set by default to :streamgraph. Any value set to the :mode option will be ignored.

A grouping field must also be provided which will be set as :color_by to the area chart.

Options

Check area/4

Examples

Tucan.streamgraph(:stocks, "date", "price", "symbol",
  width: 300,
  x: [type: :temporal],
  tooltip: true
)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"x":{"field":"date","type":"temporal"},"y":{"field":"price","stack":"center","type":"quantitative"}},"mark":{"fillOpacity":0.5,"line":false,"point":false,"tooltip":true,"type":"area"},"width":300}
Link to this function

stripplot(plotdata, field, opts \\ [])

View Source
@spec stripplot(plotdata :: plotdata(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Draws a strip plot (categorical scatterplot).

A strip plot is a single-axis scatter plot used to visualize the distribution of a numerical field. The values are plotted as dots or ticks along one axis, so the dots with the same value may overlap.

You can use the :jitter mode for a better view of overlapping points. In this case points are randomnly shifted along with other axis, which has no meaning in itself data-wise.

Typically several strip plots are placed side by side to compare the distribution of a numerical value among several categories.

Options

  • :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.

  • :fill_opacity (float/0) - The fill opacity of the plotted elemets. The default value is 0.5.

  • :orient - The plot's orientation, can be either :horizontal or :vertical. The default value is :horizontal.

  • :group (String.t/0) - A field to be used for grouping the strip plot. If not set the plot will be one dimensional.

  • :style - The style of the plot. Can be one of the following:

    • :tick - use ticks for each data point
    • :point - use points for each data point
    • :jitter - use points but also apply some jittering across the other axis

    Use :jitter in case of many data points in order to avoid overlaps.

    The default value is :tick.

Encodings Custom Options

  • :x (keyword/0) - Extra vega lite options for the :x encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y (keyword/0) - Extra vega lite options for the :y encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].
  • :y_offset (keyword/0) - Extra vega lite options for the :y_offset encoding. It can be an arbitrary keyword list. Notice that if set they will be merged with any option set by the plot. Since they have a higher precedence they may override the default settings and affect the generated plot. The contents are not validated. The default value is [].

Interactivity Options

  • :tooltip - The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from. Can be one of the following:
    • :encoding - all fields from encoding are used
    • :data - all fields of the highlighted data point are used
    • true - same as :encoding
    • false, nil - no tooltip is used

Global Options

Internal VegaLite representation

If style is set to :tick the following VegaLite represenation is generated:

Vl.new()
|> Vl.mark(:tick)
|> Vl.encode_field(:x, field, type: :quantitative)
|> Vl.encode_field(:y, opts[:group], type: :nominal)

If style is set to :jitter then a transform is added to generate Gaussian jitter using the Box-Muller transform, and the y_offset is also encoded based on this:

Vl.new()
|> Vl.mark(:point)
|> Vl.transform(calculate: "sqrt(-2*log(random()))*cos(2*PI*random())", as: "jitter")
|> Vl.encode_field(:x, field, type: :quantitative)
|> Vl.encode_field(:y, opts[:group], type: :nominal)
|> Vl.encode_field(:y_offset, "jitter", type: :quantitative)

Examples

Assigning a single numeric variable shows the univariate distribution. The default style is the :tick:

Tucan.stripplot(:tips, "total_bill")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"x":{"field":"total_bill","type":"quantitative"}},"mark":"tick"}

For very dense distribution it makes more sense to use the :jitter style in order to reduce overlapping points:

Tucan.stripplot(:tips, "total_bill", style: :jitter, height: 30, width: 300)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"x":{"field":"total_bill","type":"quantitative"},"yOffset":{"axis":null,"field":"jitter","type":"quantitative"}},"height":30,"mark":{"size":16,"type":"point"},"transform":[{"as":"jitter","calculate":"sqrt(-2*log(random()))*cos(2*PI*random())"}],"width":300}

You can set the :group option in order to add a second dimension. Notice that the field must be categorical.

Tucan.stripplot(:tips, "total_bill", group: "day", style: :jitter)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"x":{"field":"total_bill","type":"quantitative"},"y":{"field":"day","type":"nominal"},"yOffset":{"axis":null,"field":"jitter","type":"quantitative"}},"mark":{"size":16,"type":"point"},"transform":[{"as":"jitter","calculate":"sqrt(-2*log(random()))*cos(2*PI*random())"}]}

The plot would be more clear if you also colored the points with the same field:

Tucan.stripplot(:tips, "total_bill", group: "day", style: :jitter)
|> Tucan.color_by("day")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"day"},"x":{"field":"total_bill","type":"quantitative"},"y":{"field":"day","type":"nominal"},"yOffset":{"axis":null,"field":"jitter","type":"quantitative"}},"mark":{"size":16,"type":"point"},"transform":[{"as":"jitter","calculate":"sqrt(-2*log(random()))*cos(2*PI*random())"}]}

Or you can color by a distinct variable to show a multi-dimensional relationship:

Tucan.stripplot(:tips, "total_bill", group: "day", style: :jitter)
|> Tucan.color_by("sex")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"sex"},"x":{"field":"total_bill","type":"quantitative"},"y":{"field":"day","type":"nominal"},"yOffset":{"axis":null,"field":"jitter","type":"quantitative"}},"mark":{"size":16,"type":"point"},"transform":[{"as":"jitter","calculate":"sqrt(-2*log(random()))*cos(2*PI*random())"}]}

or you can color by a numerical variable:

Tucan.stripplot(:tips, "total_bill", group: "day", style: :jitter)
|> Tucan.color_by("size", type: :ordinal)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"size","type":"ordinal"},"x":{"field":"total_bill","type":"quantitative"},"y":{"field":"day","type":"nominal"},"yOffset":{"axis":null,"field":"jitter","type":"quantitative"}},"mark":{"size":16,"type":"point"},"transform":[{"as":"jitter","calculate":"sqrt(-2*log(random()))*cos(2*PI*random())"}]}

You could draw the same with points but without jittering:

Tucan.stripplot(:tips, "total_bill", group: "day", style: :point)
|> Tucan.color_by("sex")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"sex"},"x":{"field":"total_bill","type":"quantitative"},"y":{"field":"day","type":"nominal"}},"mark":{"size":16,"type":"point"}}

or with ticks which is the default one:

Tucan.stripplot(:tips, "total_bill", group: "day", style: :tick)
|> Tucan.color_by("sex")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"sex"},"x":{"field":"total_bill","type":"quantitative"},"y":{"field":"day","type":"nominal"}},"mark":"tick"}

You can set the :orient flag to :vertical to change the orientation:

Tucan.stripplot(:tips, "total_bill", group: "day", style: :jitter, orient: :vertical)
|> Tucan.color_by("sex")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"},"encoding":{"color":{"field":"sex"},"x":{"field":"day","type":"nominal"},"xOffset":{"axis":null,"field":"jitter","type":"quantitative"},"y":{"field":"total_bill","type":"quantitative"}},"mark":{"size":16,"type":"point"},"transform":[{"as":"jitter","calculate":"sqrt(-2*log(random()))*cos(2*PI*random())"}]}

Composite Plots

Link to this function

pairplot(plotdata, fields, opts \\ [])

View Source
@spec pairplot(plotdata :: plotdata(), fields :: [binary()], opts :: keyword()) ::
  VegaLite.t()

Plot pairwise relationships in a dataset.

This function expects an array of fields to be provided. A grid will be created where each numeric variable in fields will be shared acrosss the y-axes across a single row and the x-axes across a single column.

Numerical field types

Notice that currently pairplot/3 works only with numerical (:quantitative) variables. If you need to create a pair plot containing other variable types you need to manually build the grid using the VegaLite concatenation operations.

Options

  • :diagonal - The plot type to be used for the diagonal subplots. Can be one on :scatter, :density and :histogram. The default value is :scatter.

  • :plot_fn (function of arity 3) - An optional function for customizing the look any subplot. It expects a function with the following signature:

    (vl :: VegaLite.t(), row :: {binary(), integer()}, column :: {binary(), integer()})
      :: VegaLite.t() 

    where both row and column are tuples containing the index and field of the current and row and column respectively.

    You are free to specify any function for every cell of the grid.

Global Options

Notice that if set width and height will be applied to individual sub plots. On the other hand title is applied to the composite plot.

Examples

By default a scatter plot will be drawn for all pairwise plots:

fields = ["petal_width", "petal_length", "sepal_width", "sepal_length"]

Tucan.pairplot(:iris, fields, width: 130, height: 130)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","columns":4,"concat":[{"encoding":{"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"petal_width"},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"petal_length"},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"sepal_width"},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":"petal_width"},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"sepal_length"},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":"petal_length"},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":"sepal_width"},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"x":{"axis":{"title":"sepal_length"},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130}],"data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"}}

You can color the points by another field in to add some semantic mapping. Notice that you need the recursive option to true for the grouping to be applied on all internal subplots.

fields = ["petal_width", "petal_length", "sepal_width", "sepal_length"]

Tucan.pairplot(:iris, fields, width: 130, height: 130)
|> Tucan.color_by("species", recursive: true)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","columns":4,"concat":[{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"petal_width"},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"petal_length"},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"sepal_width"},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"petal_width"},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"sepal_length"},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"petal_length"},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"sepal_width"},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"sepal_length"},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130}],"data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"}}

By specifying the :diagonal option you can change the default plot for the diagonal elements to a histogram:

fields = ["petal_width", "petal_length", "sepal_width", "sepal_length"]

Tucan.pairplot(:iris, fields, width: 130, height: 130, diagonal: :histogram)
|> Tucan.color_by("species", recursive: true)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","columns":4,"concat":[{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"bin":{"binned":true},"field":"bin_petal_width","title":"petal_width"},"x2":{"field":"bin_petal_width_end"},"y":{"axis":{"title":"petal_width"},"field":"count_petal_width","stack":null,"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_petal_width","bin":true,"field":"petal_width"},{"aggregate":[{"as":"count_petal_width","op":"count"}],"groupby":["bin_petal_width","bin_petal_width_end"]}],"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"petal_length"},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"bin":{"binned":true},"field":"bin_petal_length","title":"petal_length"},"x2":{"field":"bin_petal_length_end"},"y":{"axis":{"title":null},"field":"count_petal_length","stack":null,"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_petal_length","bin":true,"field":"petal_length"},{"aggregate":[{"as":"count_petal_length","op":"count"}],"groupby":["bin_petal_length","bin_petal_length_end"]}],"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"sepal_width"},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"bin":{"binned":true},"field":"bin_sepal_width","title":"sepal_width"},"x2":{"field":"bin_sepal_width_end"},"y":{"axis":{"title":null},"field":"count_sepal_width","stack":null,"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_sepal_width","bin":true,"field":"sepal_width"},{"aggregate":[{"as":"count_sepal_width","op":"count"}],"groupby":["bin_sepal_width","bin_sepal_width_end"]}],"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"petal_width"},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"sepal_length"},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"petal_length"},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"sepal_width"},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"point"},"width":130},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"sepal_length"},"bin":{"binned":true},"field":"bin_sepal_length","title":"sepal_length"},"x2":{"field":"bin_sepal_length_end"},"y":{"axis":{"title":null},"field":"count_sepal_length","stack":null,"type":"quantitative"}},"height":130,"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_sepal_length","bin":true,"field":"sepal_length"},{"aggregate":[{"as":"count_sepal_length","op":"count"}],"groupby":["bin_sepal_length","bin_sepal_length_end"]}],"width":130}],"data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"}}

Additionally you have the option to configure a plot_fn with which we can go crazy and modify any part of the grid based on our needs. plot_fn should accept as input a VegaLite struct and two tuples containing the row and column fields and indexes. In the following example we draw differently the diagonal, the lower and the upper grid. Notice that we don't call color_by/3 since we color differently the plots based on their index positions.

Tucan.pairplot(:iris, ["petal_width", "petal_length", "sepal_width", "sepal_length"],
  width: 150,
  height: 150,
  plot_fn: fn vl, {row_field, row_index}, {col_field, col_index} ->
    cond do
      # For the first two diagonal elements we plot a histogram, no 
      row_index == col_index and row_index < 2 ->
        Tucan.histogram(vl, row_field)

      row_index == 2 and col_index == 2 ->
        Tucan.stripplot(vl, row_field, group: "species", style: :tick)
        |> Tucan.color_by("species")
        |> Tucan.Axes.put_axis_options(:y, labels: false)

      # For the other diagonal plots we plot a histogram colored_by the species
      row_index == col_index ->
        Tucan.histogram(vl, row_field, color_by: "species")

      # For the upper part of the diagram we apply a scatter plot
      row_index < col_index ->
        Tucan.scatter(vl, col_field, row_field)
        |> Tucan.color_by("species")

      # for anything else scatter plot with a quantitative color scale
      # and size
      true ->
        Tucan.scatter(vl, col_field, row_field)
        |> Tucan.size_by("petal_width", type: :quantitative)
    end
  end
)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","columns":4,"concat":[{"encoding":{"x":{"axis":{"title":null},"bin":{"binned":true},"field":"bin_petal_width","title":"petal_width"},"x2":{"field":"bin_petal_width_end"},"y":{"axis":{"title":"petal_width"},"field":"count_petal_width","stack":null,"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_petal_width","bin":true,"field":"petal_width"},{"aggregate":[{"as":"count_petal_width","op":"count"}],"groupby":["bin_petal_width","bin_petal_width_end"]}],"width":150},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"size":{"field":"petal_width","type":"quantitative"},"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"petal_length"},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"x":{"axis":{"title":null},"bin":{"binned":true},"field":"bin_petal_length","title":"petal_length"},"x2":{"field":"bin_petal_length_end"},"y":{"axis":{"title":null},"field":"count_petal_length","stack":null,"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_petal_length","bin":true,"field":"petal_length"},{"aggregate":[{"as":"count_petal_length","op":"count"}],"groupby":["bin_petal_length","bin_petal_length_end"]}],"width":150},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"size":{"field":"petal_width","type":"quantitative"},"x":{"axis":{"title":null},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"sepal_width"},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"size":{"field":"petal_width","type":"quantitative"},"x":{"axis":{"title":null},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_width","type":"quantitative"},"y":{"axis":{"labels":false,"title":null},"field":"species","type":"nominal"}},"height":150,"mark":"tick","width":150},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"size":{"field":"petal_width","type":"quantitative"},"x":{"axis":{"title":"petal_width"},"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":"sepal_length"},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"size":{"field":"petal_width","type":"quantitative"},"x":{"axis":{"title":"petal_length"},"field":"petal_length","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"size":{"field":"petal_width","type":"quantitative"},"x":{"axis":{"title":"sepal_width"},"field":"sepal_width","scale":{"zero":false},"type":"quantitative"},"y":{"axis":{"title":null},"field":"sepal_length","scale":{"zero":false},"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"point"},"width":150},{"encoding":{"color":{"field":"species"},"x":{"axis":{"title":"sepal_length"},"bin":{"binned":true},"field":"bin_sepal_length","title":"sepal_length"},"x2":{"field":"bin_sepal_length_end"},"y":{"axis":{"title":null},"field":"count_sepal_length","stack":null,"type":"quantitative"}},"height":150,"mark":{"fillOpacity":0.5,"type":"bar"},"transform":[{"as":"bin_sepal_length","bin":true,"field":"sepal_length"},{"aggregate":[{"as":"count_sepal_length","op":"count"}],"groupby":["bin_sepal_length","bin_sepal_length_end","species"]}],"width":150}],"data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"}}

Grouping

Link to this function

color_by(vl, field, opts \\ [])

View Source
@spec color_by(vl :: VegaLite.t(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Adds a color encoding for the given field.

opts can be an arbitrary keyword list with vega-lite supported options.

If :recursive is set the encoding is applied in all subplots of the given plot.

Link to this function

facet_by(vl, faceting_mode, field, opts \\ [])

View Source
@spec facet_by(
  vl :: VegaLite.t(),
  faceting_mode :: :row | :column,
  field :: binary(),
  opts :: keyword()
) :: VegaLite.t()

Apply facetting on the input plot vl by the given field.

This will create multiple plots either horizontally (:column faceting mode) or vertically (:row faceting mode), one for each distinct value of the given field, which must be a categorical variable.

opts is an arbitraty keyword list that will be passed to the :row or :column encoding.

Facet plots

Facet plots, also known as trellis plots or small multiples, are figures made up of multiple subplots which have the same set of axes, where each subplot shows a subset of the data.

Examples

Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.facet_by(:column, "species")
|> Tucan.color_by("species")
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"},"encoding":{"color":{"field":"species"},"column":{"field":"species"},"x":{"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"}}
Link to this function

fill_by(vl, field, opts \\ [])

View Source
@spec fill_by(vl :: VegaLite.t(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Adds a fill encoding for the given field.

opts can be an arbitrary keyword list with vega-lite supported options.

If :recursive is set the encoding is applied in all subplots of the given plot.

Link to this function

shape_by(vl, field, opts \\ [])

View Source
@spec shape_by(vl :: VegaLite.t(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Adds a shape encoding for the given field.

opts can be an arbitrary keyword list with vega-lite supported options.

If :recursive is set the encoding is applied in all subplots of the given plot.

Link to this function

size_by(vl, field, opts \\ [])

View Source
@spec size_by(vl :: VegaLite.t(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Adds a size encoding for the given field.

opts can be an arbitrary keyword list with vega-lite supported options.

If :recursive is set the encoding is applied in all subplots of the given plot.

Link to this function

stroke_dash_by(vl, field, opts \\ [])

View Source
@spec stroke_dash_by(vl :: VegaLite.t(), field :: binary(), opts :: keyword()) ::
  VegaLite.t()

Adds a stroke_dash encoding for the given field.

opts can be an arbitrary keyword list with vega-lite supported options.

If :recursive is set the encoding is applied in all subplots of the given plot.

Utilities

@spec flip_axes(vl :: VegaLite.t()) :: VegaLite.t()

Flips the axes of the provided chart.

This works for both one dimensional and two dimensional charts. All positional channels that are defined will be flipped.

This is used internally by plots that support setting orientation.

@spec set_height(vl :: VegaLite.t(), height :: pos_integer()) :: VegaLite.t()

Sets the width of the plot (in pixels).

Link to this function

set_title(vl, title, opts \\ [])

View Source
@spec set_title(vl :: VegaLite.t(), title :: binary(), opts :: keyword()) ::
  VegaLite.t()

Sets the title of the plot.

You can optionally pass any title option supported by vega-lite to customize the style of it.

Examples

Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.set_title("My awesome plot",
  color: "red",
  subtitle: "with a subtitle",
  subtitle_color: "green",
  anchor: "start"
)
{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"},"encoding":{"x":{"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":0.5,"type":"point"},"title":{"anchor":"start","color":"red","subtitle":"with a subtitle","subtitleColor":"green","text":"My awesome plot"}}
@spec set_width(vl :: VegaLite.t(), width :: pos_integer()) :: VegaLite.t()

Sets the width of the plot (in pixels).

Functions

Link to this function

new(plotdata, opts \\ [])

View Source
@spec new(plotdata :: plotdata(), opts :: keyword()) :: VegaLite.t()

Creates if needed a VegaLite plot and adds data to it.

The behaviour of this function depends on the type of plotdata:

  • if a VegaLite.t() struct is passed then it is returned unchanged.
  • If it is a binary it is considered a url and the VegaLite.data_from_url/2 is called on a newly created VegaLite struct.
  • if it is an atom then it is considered a Tucan.Dataset and it is translated to the dataset's url. If the dataset name is invalid an exception is raised.
  • in any other case it is considered a set of data values and the values are set as data to a newly created VegaLite struct.
@spec set_theme(vl :: VegaLite.t(), theme :: atom()) :: VegaLite.t()

Sets the plot's theme.

Check Tucan.Themes for more details on theming.