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

Returns the specification of an area plot.

Options

• :interpolate (binary/0) - The line interpolation method to use for line and area marks. One of the following:
  • "linear" - piecewise linear segments, as in a poly-line.
  • "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.
• :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.
• :points (boolean/0) - Whether points will be included in the chart. The default value is false.
• :tension (number/0) - Depending on the interpolation type, sets the tension parameter

Data Grouping Options

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

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :fill_color (String.t/0) - The fill color of the marks. This will override the color encoding if set.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :line_color (String.t/0) - The color of the line
• :point_color (String.t/0) - The color of the points
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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
• :zoomable (boolean/0) - Whether the plot will be zoomable or not. If set to true you will be able to pan and zoom the plot with your mouse. You can reset to the original view with a double click. The default value is false.

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":1,"line":false,"type":"area"},"transform":[{"filter":"datum.symbol==='GOOG'"}]}

You can overlay the points and/or the line, you can change the colors of the points, the line and the area if needed:

Tucan.area(:stocks, "date", "price",
  x: [type: :temporal],
  points: true,
  line: true,
  fill_color: "#fa3456",
  point_color: "orange",
  line_color: "green",
  width: 400
)
|> 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":{"color":"#fa3456","fillOpacity":1,"line":{"color":"green"},"point":{"color":"orange"},"type":"area"},"transform":[{"filter":"datum.symbol==='GOOG'"}],"width":400}

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
)

{"$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,"line":false,"type":"area"},"width":300}

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

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

Tucan.hconcat([left, right])

{"$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":1,"line":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":1,"line":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,
  fill_opacity: 0.4
)
|> Tucan.Scale.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.4,"line":false,"type":"area"},"width":400}

@spec bar(
  plotdata :: plotdata(),
  field :: String.t(),
  value :: String.t(),
  opts :: keyword()
) ::
  VegaLite.t()

Draws 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.

See also lollipop/4.

Options

• :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.

Data Grouping Options

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

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :corner_radius (non_neg_integer/0) - The radius in pixels of rounded rectangles. The end radius is affected:
  • For vertical bars, top-left and top-right corner radius.
  • For horizontal bars, top-right and bottom-right corner radius.
• :fill_color (String.t/0) - The fill color of the marks. This will override the color encoding if set.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :orient (atom/0) - The plot's orientation, can be either :horizontal or :vertical. The default value is :vertical.
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :x_offset (keyword/0) - Extra vega lite options for the :x_offset encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].
• :y_offset (keyword/0) - Extra vega lite options for the :y_offset encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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

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", fill_color: "#33245A", corner_radius: 5)

{"$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":{"axis":{"labelAngle":0},"field":"a","type":"nominal"},"y":{"field":"b","type":"quantitative"}},"mark":{"color":"#33245A","cornerRadiusEnd":5,"fillOpacity":1,"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":{"axis":{"labelAngle":0},"field":"date","timeUnit":"month","type":"ordinal"},"y":{"aggregate":"count","field":"date","type":"quantitative"}},"mark":{"fillOpacity":1,"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: :horizontal
  )

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

Tucan.hconcat([grouped, normalized])

{"$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":{"axis":{"labelAngle":0},"field":"category","type":"nominal"},"yOffset":{"field":"group"}},"mark":{"fillOpacity":1,"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":{"axis":{"labelAngle":0},"field":"category","type":"nominal"},"y":{"field":"value","stack":"normalize","type":"quantitative"}},"mark":{"fillOpacity":1,"type":"bar"}}]}

@spec boxplot(plotdata :: plotdata(), field :: String.t(), 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_by 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

• :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.
• :mode - The type of the box plot. Either a Tukey box plot (:tukey) or a min-max plot (:min_max) will be created. The default value is :tukey.

Data Grouping Options

• :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 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.

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :orient (atom/0) - The plot's orientation, can be either :horizontal or :vertical. The default value is :horizontal.
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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

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":1,"type":"boxplot"}}

You can set :group_by 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":1,"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":1,"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":1,"type":"boxplot"}}

@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

Data Grouping Options

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

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :size (keyword/0) - Extra vega lite options for the :size encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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
• :zoomable (boolean/0) - Whether the plot will be zoomable or not. If set to true you will be able to pan and zoom the plot with your mouse. You can reset to the original view with a double click. The default value is false.

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.Scale.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}

@spec countplot(plotdata :: plotdata(), field :: String.t(), 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":{"axis":{"labelAngle":0},"field":"Pclass","type":"nominal"},"y":{"aggregate":"count","field":"Pclass","type":"quantitative"}},"mark":{"fillOpacity":1,"type":"bar"}}

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

Tucan.countplot(:titanic, "Pclass", orient: :horizontal)

{"$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":{"axis":{"labelAngle":0},"field":"Pclass","type":"nominal"}},"mark":{"fillOpacity":1,"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":{"axis":{"labelAngle":0},"field":"Pclass","type":"nominal"},"y":{"aggregate":"count","field":"Pclass","type":"quantitative"}},"mark":{"fillOpacity":1,"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":{"axis":{"labelAngle":0},"field":"Pclass","type":"nominal"},"xOffset":{"field":"Survived"},"y":{"aggregate":"count","field":"Pclass","type":"quantitative"}},"mark":{"fillOpacity":1,"type":"bar"}}

@spec density(plotdata :: plotdata(), field :: String.t(), 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":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":1,"orient":"vertical","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":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":0.2,"orient":"vertical","type":"area"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]}

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

Tucan.density(:penguins, "Body Mass (g)", group_by: ["Species"], fill_opacity: 0.2)
|> Tucan.color_by("Species")

See also histogram/3.

Options

• :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.

• :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.

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

• :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.

• :group_by (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 :group_by 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 :group_by and :color_by are set then only :group_by is used for grouping the density transform and color_by is used for encoding the color.

• :interpolate (binary/0) - The line interpolation method to use for line and area marks. One of the following:

  • "linear" - piecewise linear segments, as in a poly-line.
  • "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.

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

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

• :stacked (boolean/0) - Whether the density plots will be stacked or not. The default value is false.

• :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.

Data Grouping Options

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

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :fill_color (String.t/0) - The fill color of the marks. This will override the color encoding if set.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :filled (boolean/0) - Whether the density plot will be filled or not, default to true if not set
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :orient (atom/0) - The plot's orientation, can be either :horizontal or :vertical. The default value is :horizontal.
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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
• :zoomable (boolean/0) - Whether the plot will be zoomable or not. If set to true you will be able to pan and zoom the plot with your mouse. You can reset to the original view with a double click. The default value is false.

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":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":1,"orient":"vertical","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. You can stack overlapping densities by setting the :stacked property.

unstacked =
  Tucan.density(:penguins, "Body Mass (g)", color_by: "Species", fill_opacity: 0.2)
  |> Tucan.set_title("Unstacked")

stacked =
  Tucan.density(:penguins, "Body Mass (g)",
    color_by: "Species",
    fill_opacity: 0.8,
    stacked: true
  )
  |> Tucan.set_title("Stacked")

Tucan.hconcat([unstacked, stacked])

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","hconcat":[{"data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":0.2,"orient":"vertical","type":"area"},"title":{"text":"Unstacked"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]},{"data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"color":{"field":"Species"},"x":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":"zero","type":"quantitative"}},"mark":{"fillOpacity":0.8,"orient":"vertical","type":"area"},"title":{"text":"Stacked"},"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 :group_by variable in order to correctly calculate the density plot per field's value.

Tucan.density(:penguins, "Body Mass (g)", group_by: ["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":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":1,"orient":"vertical","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: 50.0,
  fill_opacity: 0.5
)

{"$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":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":0.5,"orient":"vertical","type":"area"},"transform":[{"bandwidth":50.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":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":1,"orient":"vertical","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":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":1,"orient":"vertical","type":"area"},"transform":[{"counts":false,"cumulative":true,"density":"Body Mass (g)","groupby":["Species"],"maxsteps":200,"minsteps":25}]}

You can change the color of the plot by setting the :fill_color option and/or specify if it will be filled or not:

Tucan.hconcat([
  Tucan.density(:penguins, "Body Mass (g)", fill_color: "red"),
  Tucan.density(:penguins, "Body Mass (g)", filled: false)
])
|> Tucan.set_theme(:ggplot2)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","config":{"arc":{"fill":"#000"},"area":{"fill":"#000"},"axis":{"domain":false,"grid":true,"gridColor":"#FFFFFF","gridOpacity":1,"labelColor":"#7F7F7F","labelPadding":4,"tickColor":"#7F7F7F","tickSize":5.67,"titleFontSize":16,"titleFontWeight":"normal"},"group":{"fill":"#e5e5e5"},"legend":{"labelBaseline":"middle","labelFontSize":11,"symbolSize":40},"line":{"stroke":"#000"},"path":{"stroke":"#000"},"range":{"category":["#000000","#7F7F7F","#1A1A1A","#999999","#333333","#B0B0B0","#4D4D4D","#C9C9C9","#666666","#DCDCDC"]},"rect":{"fill":"#000"},"shape":{"stroke":"#000"},"symbol":{"fill":"#000","size":40}},"hconcat":[{"data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"x":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"color":"red","fillOpacity":1,"orient":"vertical","type":"area"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","maxsteps":200,"minsteps":25}]},{"data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"x":{"axis":{"title":"Body Mass (g)"},"field":"value","scale":{"zero":false},"type":"quantitative"},"y":{"field":"density","stack":null,"type":"quantitative"}},"mark":{"fillOpacity":0,"filled":false,"orient":"vertical","type":"line"},"transform":[{"counts":false,"cumulative":false,"density":"Body Mass (g)","maxsteps":200,"minsteps":25}]}]}

@spec density_heatmap(
  plotdata :: plotdata(),
  x :: String.t(),
  y :: String.t(),
  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

• :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.
• :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.

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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
• :zoomable (boolean/0) - Whether the plot will be zoomable or not. If set to true you will be able to pan and zoom the plot with your mouse. You can reset to the original view with a double click. The default value is false.

Examples

Let's start with a default density 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":1,"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":1,"type":"rect"}}

@spec donut(
  plotdata :: plotdata(),
  field :: String.t(),
  category :: String.t(),
  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":1,"innerRadius":50,"tooltip":true,"type":"arc"}}

@spec errorband(
  plotdata :: plotdata(),
  x :: String.t(),
  y :: String.t(),
  opts :: keyword()
) ::
  VegaLite.t()

Draws an error band (confidence interval).

An error band summarizes an error range of quantitative values using a set of summary statistics, represented by area. Both x and y should be quantitative variables.

Options

• :borders (boolean/0) - If set to true the error band's border will be added. The default value is false.

• :extent - The extent of the rule. Can be one of the following:

  • :ci - Extend the rule to the confidence interval of the mean.
  • :stderr - The size of rule are set to the value of standard error, extending from the mean.
  • :stdev - The size of rule are set to the value of standard deviation, extending from the mean.
  • :iqr - Extend the rule to the q1 and q3.

  The default value is :stderr.

• :interpolate (binary/0) - The line interpolation method to use for line and area marks. One of the following:

  • "linear" - piecewise linear segments, as in a poly-line.
  • "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.

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :fill_color (String.t/0) - The fill color of the marks. This will override the color encoding if set.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :line_color (String.t/0) - The color of the line
• :stroke_dash (list of pos_integer/0) - An array of alternating stroke, space lengths in pixels for creating dashed or dotted lines.
• :stroke_width (pos_integer/0) - The stroke width in pixels
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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

Examples

Tucan.errorband(:cars, "Year", "Miles_per_Gallon", x: [time_unit: "year", type: :temporal])

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"field":"Year","scale":{"zero":false},"timeUnit":"year","type":"temporal"},"y":{"field":"Miles_per_Gallon","scale":{"zero":false},"type":"quantitative"}},"mark":{"borders":false,"extent":"stderr","fillOpacity":1,"type":"errorband"}}

You can modify the look of the error band, change the :extent and include the borders if needed.

Tucan.errorband(:cars, "Year", "Miles_per_Gallon",
  extent: :ci,
  fill_color: "red",
  borders: true,
  x: [time_unit: "year", type: :temporal]
)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"field":"Year","scale":{"zero":false},"timeUnit":"year","type":"temporal"},"y":{"field":"Miles_per_Gallon","scale":{"zero":false},"type":"quantitative"}},"mark":{"borders":[],"color":"red","extent":"ci","fillOpacity":1,"type":"errorband"}}

You can also change the look of the borders:

Tucan.errorband(:cars, "Year", "Miles_per_Gallon",
  extent: :ci,
  fill_color: "black",
  borders: true,
  line_color: "red",
  stroke_width: 3,
  stroke_dash: [7, 5],
  x: [time_unit: "year", type: :temporal]
)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"field":"Year","scale":{"zero":false},"timeUnit":"year","type":"temporal"},"y":{"field":"Miles_per_Gallon","scale":{"zero":false},"type":"quantitative"}},"mark":{"borders":{"color":"red","strokeDash":[7,5],"strokeWidth":3},"color":"black","extent":"ci","fillOpacity":1,"type":"errorband"}}

Usually you want to combine the errorband with the mean trend line. You can use Tucan.layers/2 to combine it with a lineplot.

errorband =
  Tucan.errorband(:cars, "Year", "Miles_per_Gallon",
    extent: :ci,
    fill_color: "green",
    x: [time_unit: "year", type: :temporal]
  )

trendline =
  Tucan.lineplot(:cars, "Year", "Miles_per_Gallon",
    x: [time_unit: "year", type: :temporal],
    y: [aggregate: :mean]
  )

Tucan.layers([errorband, trendline])

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","layer":[{"data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"field":"Year","scale":{"zero":false},"timeUnit":"year","type":"temporal"},"y":{"field":"Miles_per_Gallon","scale":{"zero":false},"type":"quantitative"}},"mark":{"borders":false,"color":"green","extent":"ci","fillOpacity":1,"type":"errorband"}},{"data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"field":"Year","timeUnit":"year","type":"temporal"},"y":{"aggregate":"mean","field":"Miles_per_Gallon","type":"quantitative"}},"mark":{"fillOpacity":1,"type":"line"}}]}

Similar to other Tucan plots you can apply semantic grouping:

errorband =
  Tucan.errorband(:cars, "Year", "Miles_per_Gallon",
    extent: :ci,
    x: [time_unit: "year", type: :temporal]
  )

trendline =
  Tucan.lineplot(:cars, "Year", "Miles_per_Gallon",
    x: [time_unit: "year", type: :temporal],
    y: [aggregate: :mean]
  )

Tucan.layers([errorband, trendline])
|> Tucan.color_by("Origin")
|> Tucan.set_width(400)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","encoding":{"color":{"field":"Origin"}},"layer":[{"data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"field":"Year","scale":{"zero":false},"timeUnit":"year","type":"temporal"},"y":{"field":"Miles_per_Gallon","scale":{"zero":false},"type":"quantitative"}},"mark":{"borders":false,"extent":"ci","fillOpacity":1,"type":"errorband"}},{"data":{"url":"https://vega.github.io/editor/data/cars.json"},"encoding":{"x":{"field":"Year","timeUnit":"year","type":"temporal"},"y":{"aggregate":"mean","field":"Miles_per_Gallon","type":"quantitative"}},"mark":{"fillOpacity":1,"type":"line"}}],"width":400}

@spec errorbar(plotdata :: plotdata(), field :: String.t(), opts :: keyword()) ::
  VegaLite.t()

Plots the errorbar for the given numerical variable field.

Error bars sho by default the standard error. It can also be explicitly specified by setting :extent to :stderr. The length of lower and upper rules represent standard error. By default, the rule marks expand from the mean.

Options

• :extent - The extent of the rule. Can be one of the following:

  • :ci - Extend the rule to the confidence interval of the mean.
  • :stderr - The size of rule are set to the value of standard error, extending from the mean.
  • :stdev - The size of rule are set to the value of standard deviation, extending from the mean.
  • :iqr - Extend the rule to the q1 and q3.

  The default value is :stderr.

• :group_by (String.t/0) - A field to be used for grouping the error bars by a category. If not set the plot will be one dimensional.

• :points (boolean/0) - If set the means of the error bar are also included.

• :ticks (boolean/0) - If set ticks will be included to the error bars ends

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :line_color (String.t/0) - The color of the line
• :orient (atom/0) - The plot's orientation, can be either :horizontal or :vertical. The default value is :horizontal.
• :point_color (String.t/0) - The color of the points if enabled. If not set defaults to the error bars color
• :stroke_width (pos_integer/0) - The stroke width in pixels
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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

Examples

A 1-d error bar:

Tucan.errorbar(:barley, "yield")

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"}},"mark":{"extent":"stderr","fillOpacity":1,"type":"errorbar"}}]}

By setting the :group_by option you can show the error range of a continuous field broken down by categories.

Tucan.errorbar(:barley, "yield", group_by: "variety")

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"},"y":{"field":"variety","type":"nominal"}},"mark":{"extent":"stderr","fillOpacity":1,"type":"errorbar"}}]}

You can change the orientation by setting the :orient option:

Tucan.errorbar(:barley, "yield", group_by: "variety", orient: :vertical)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"layer":[{"encoding":{"x":{"field":"variety","type":"nominal"},"y":{"field":"yield","scale":{"zero":false},"type":"quantitative"}},"mark":{"extent":"stderr","fillOpacity":1,"type":"errorbar"}}]}

By setting :ticks to true you can enable errorbar end ticks. Also you can overlay the means by setting :points to true.

Tucan.errorbar(:barley, "yield", group_by: "variety", ticks: true, points: true)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"},"y":{"field":"variety","type":"nominal"}},"mark":{"extent":"stderr","fillOpacity":1,"ticks":true,"type":"errorbar"}},{"encoding":{"x":{"aggregate":"mean","field":"yield","type":"quantitative"},"y":{"field":"variety","type":"nominal"}},"mark":{"filled":true,"type":"point"}}]}

You can change the :extent value in order to configure how the error bars are extended. Below you can see all supported options:

valid_extent_values = [:ci, :stderr, :stdev, :iqr]

plots =
  for extent <- valid_extent_values do
    Tucan.errorbar(:barley, "yield", group_by: "variety", extent: extent)
    |> Tucan.set_title(inspect(extent) <> " extent")
    |> Tucan.Axes.set_enabled(:y, extent == :ci)
    |> Tucan.set_size(160, 160)
  end

Tucan.hconcat(plots)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","hconcat":[{"__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"height":160,"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"},"y":{"axis":[],"field":"variety","type":"nominal"}},"mark":{"extent":"ci","fillOpacity":1,"type":"errorbar"}}],"title":{"text":":ci extent"},"width":160},{"__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"height":160,"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"},"y":{"axis":null,"field":"variety","type":"nominal"}},"mark":{"extent":"stderr","fillOpacity":1,"type":"errorbar"}}],"title":{"text":":stderr extent"},"width":160},{"__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"height":160,"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"},"y":{"axis":null,"field":"variety","type":"nominal"}},"mark":{"extent":"stdev","fillOpacity":1,"type":"errorbar"}}],"title":{"text":":stdev extent"},"width":160},{"__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"height":160,"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"},"y":{"axis":null,"field":"variety","type":"nominal"}},"mark":{"extent":"iqr","fillOpacity":1,"type":"errorbar"}}],"title":{"text":":iqr extent"},"width":160}]}

You can use :line_color and :stroke_width to modify the look of the error bars:

Tucan.errorbar(:barley, "yield",
  group_by: "variety",
  line_color: "red",
  stroke_width: 3,
  ticks: true,
  points: true
)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"},"y":{"field":"variety","type":"nominal"}},"mark":{"color":"red","extent":"stderr","fillOpacity":1,"rule":{"strokeWidth":3},"ticks":true,"type":"errorbar"}},{"encoding":{"x":{"aggregate":"mean","field":"yield","type":"quantitative"},"y":{"field":"variety","type":"nominal"}},"mark":{"color":"red","filled":true,"type":"point"}}]}

You can color categories by combining it with Tucan.color_by/3.

Tucan.errorbar(:barley, "yield", group_by: "variety", points: true)
|> Tucan.color_by("variety")

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/barley.json"},"encoding":{"color":{"field":"variety"}},"layer":[{"encoding":{"x":{"field":"yield","scale":{"zero":false},"type":"quantitative"},"y":{"field":"variety","type":"nominal"}},"mark":{"extent":"stderr","fillOpacity":1,"type":"errorbar"}},{"encoding":{"x":{"aggregate":"mean","field":"yield","type":"quantitative"},"y":{"field":"variety","type":"nominal"}},"mark":{"filled":true,"type":"point"}}]}

@spec heatmap(
  plotdata :: plotdata(),
  x :: String.t(),
  y :: String.t(),
  color :: nil | String.t(),
  opts :: keyword()
) :: VegaLite.t()

Returns the specification of a heatmap.

A heatmap is a graphical representation of data where the individual values contained in a matrix are represented as colors.

It expects two categorical fields x, y which will be used for the axes and a numerical field color. If color is nil then the color represents the count of the observations for each x, y.

If an :aggregate is set this statistic will be used for encoding the color. If no :aggregate is set the color encodes by default the :mean of the data.

Options

• :aggregate (atom/0) - The statistic that will be used for aggregating the observations within a heatmap tile. Defaults to :mean which in case of single data will encode the value of the color data field.

  Ignored if :color is set to nil.

• :annotate (boolean/0) - If set to true then the values of each cell will be included in the plot. The default value is false.

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :color_scheme (atom/0) - The color scheme to use, for supported color schemes check Tucan.Scale. Notice that this is just a helper option for easily setting color schemes. If you need to set specific colors or customize the scheme, use Tucan.Scale.set_color_scheme/3.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :text_color - The color to be used for the textual annotations. Valid only if :annotate is set to true. Can be one of the following:
  • a string with the color to be used, e.g. "white"
  • a list of tuples of the form {low_threshold, upper_threshold, color} for conditionally setting the color based on the value of the annotated variable. low_threshold and upper_threshold can either be a number or nil. For example [{nil, 0, "green"}, {0, 5, "red"}, {5, nil, "white"}] will apply the following colors:
    • green for all items with value < 0
    • red for all items with value >= 0 && value < 5
    • white for all items with value >= 5 Notice that the low_threshold, upper_threshold correspond to the [low_threshold, upper_threshold) range.
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :text (keyword/0) - Extra vega lite options for the :text encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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

Examples

A simple heatmap of two categorical variables, using a third one for the color values.

data = [
  %{"x" => "A", "y" => "K", "value" => 0.5},
  %{"x" => "A", "y" => "L", "value" => 1.5},
  %{"x" => "A", "y" => "M", "value" => 4.5},
  %{"x" => "B", "y" => "K", "value" => 1.5},
  %{"x" => "B", "y" => "L", "value" => 2.5},
  %{"x" => "B", "y" => "M", "value" => 0.5},
  %{"x" => "C", "y" => "K", "value" => -1.5},
  %{"x" => "C", "y" => "L", "value" => 5.5},
  %{"x" => "C", "y" => "M", "value" => 1.5}
]

Tucan.heatmap(data, "x", "y", "value", width: 200, height: 200)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"values":[{"value":0.5,"x":"A","y":"K"},{"value":1.5,"x":"A","y":"L"},{"value":4.5,"x":"A","y":"M"},{"value":1.5,"x":"B","y":"K"},{"value":2.5,"x":"B","y":"L"},{"value":0.5,"x":"B","y":"M"},{"value":-1.5,"x":"C","y":"K"},{"value":5.5,"x":"C","y":"L"},{"value":1.5,"x":"C","y":"M"}]},"height":200,"layer":[{"encoding":{"color":{"aggregate":"mean","field":"value","type":"quantitative"},"x":{"field":"x","type":"nominal"},"y":{"field":"y","type":"nominal"}},"mark":{"fillOpacity":1,"type":"rect"}}],"width":200}

You can change the color scheme:

Tucan.heatmap(:glue, "Task", "Model", "Score", color_scheme: :redyellowgreen, tooltip: true)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://raw.githubusercontent.com/mwaskom/seaborn-data/master/glue.csv"},"layer":[{"encoding":{"color":{"aggregate":"mean","field":"Score","scale":{"scheme":"redyellowgreen"},"type":"quantitative"},"x":{"field":"Task","type":"nominal"},"y":{"field":"Model","type":"nominal"}},"mark":{"fillOpacity":1,"tooltip":true,"type":"rect"}}]}

Heatmaps are also useful for visualizing temporal data. Let's use a heatmap to examine how Seattle's max temperature changes over the year. On the x-axis we will encode the days of the month along the x-axis, and the months on the y-axis. We will aggregate over the max temperature for the color field. (example borrowed from here)

Tucan.heatmap(:weather, "date", "date", "temp_max",
  x: [type: :ordinal, time_unit: :date],
  y: [type: :ordinal, time_unit: :month],
  tooltip: true
)
|> Tucan.Scale.set_color_scheme(:redyellowblue, reverse: true)
|> Tucan.Axes.set_x_title("Day")
|> Tucan.Axes.set_y_title("Month")
|> Tucan.Legend.set_title(:color, "Avg Max Temp")
|> Tucan.set_title("Heatmap of Avg Max Temperatures in Seattle (2012-2015)")

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/weather.csv"},"layer":[{"encoding":{"color":{"aggregate":"mean","field":"temp_max","legend":{"title":"Avg Max Temp"},"scale":{"reverse":true,"scheme":"redyellowblue"},"type":"quantitative"},"x":{"axis":{"title":"Day"},"field":"date","timeUnit":"date","type":"ordinal"},"y":{"axis":{"title":"Month"},"field":"date","timeUnit":"month","type":"ordinal"}},"mark":{"fillOpacity":1,"tooltip":true,"type":"rect"}}],"title":{"text":"Heatmap of Avg Max Temperatures in Seattle (2012-2015)"}}

You can enable annotations by setting the :annotate flag. Notice that you can conditionally color the annotation text by setting the :text_color option. It expects a list of tuples corresponding to {lower_threshold, upper_threshold, color}. Below we color white everything below 0 and black everything with a value >=0.

Tucan.heatmap(:weather, "date", "date", "temp_max",
  annotate: true,
  text_color: [{nil, 5, "white"}, {5, 25, "black"}, {25, nil, "white"}],
  x: [type: :ordinal, time_unit: :date],
  y: [type: :ordinal, time_unit: :month],
  text: [format: ".1f"],
  tooltip: true,
  width: 800
)
|> Tucan.Scale.set_color_scheme(:redyellowblue, reverse: true)
|> Tucan.Axes.set_x_title("Day")
|> Tucan.Axes.set_y_title("Month")
|> Tucan.Legend.set_title(:color, "Avg Max Temp")
|> Tucan.set_title("Heatmap of Avg Max Temperatures in Seattle (2012-2015)")

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"url":"https://vega.github.io/editor/data/weather.csv"},"layer":[{"encoding":{"color":{"aggregate":"mean","field":"temp_max","legend":{"title":"Avg Max Temp"},"scale":{"reverse":true,"scheme":"redyellowblue"},"type":"quantitative"},"x":{"axis":{"title":"Day"},"field":"date","timeUnit":"date","type":"ordinal"},"y":{"axis":{"title":"Month"},"field":"date","timeUnit":"month","type":"ordinal"}},"mark":{"fillOpacity":1,"tooltip":true,"type":"rect"}},{"encoding":{"color":{"aggregate":"mean","condition":[{"test":"datum['mean_temp_max'] < 5","value":"white"},{"test":"datum['mean_temp_max'] >= 5 && datum['mean_temp_max'] < 25","value":"black"},{"test":"datum['mean_temp_max'] >= 25","value":"white"},{"test":"true","value":"black"}],"field":"temp_max","legend":{"title":"Avg Max Temp"},"scale":{"reverse":true,"scheme":"redyellowblue"},"type":"quantitative"},"text":{"aggregate":"mean","field":"temp_max","format":".1f","type":"quantitative"},"x":{"axis":{"title":"Day"},"field":"date","timeUnit":"date","type":"ordinal"},"y":{"axis":{"title":"Month"},"field":"date","timeUnit":"month","type":"ordinal"}},"mark":"text"}],"title":{"text":"Heatmap of Avg Max Temperatures in Seattle (2012-2015)"},"width":800}

@spec histogram(plotdata :: plotdata(), field :: String.t(), opts :: keyword()) ::
  VegaLite.t()

Plots a histogram.

See also density/3

Options

• :extent - A two-element ([min, max]) array indicating the range of desired bin values.
• :maxbins (integer/0) - Maximum number of bins.
• :orient - Histogram's orientation. It specifies the axis along which the field values are plotted. The default value is :horizontal.
• :relative (boolean/0) - If set a relative frequency histogram is generated. The default value is false.
• :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.
• :step - An exact step size to use between bins. If provided, options such as maxbins will be ignored.

Data Grouping Options

• :color_by (String.t/0) - The field to group observations by. This will used for coloring the histogram if set.

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :corner_radius (non_neg_integer/0) - The radius in pixels of rounded rectangles. The end radius is affected:
  • For vertical bars, top-left and top-right corner radius.
  • For horizontal bars, top-right and bottom-right corner radius.
• :fill_color (String.t/0) - The fill color of the marks. This will override the color encoding if set.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :x2 (keyword/0) - Extra vega lite options for the :x2 encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].
• :y2 (keyword/0) - Extra vega lite options for the :y2 encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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
• :zoomable (boolean/0) - Whether the plot will be zoomable or not. If set to true you will be able to pan and zoom the plot with your mouse. You can reset to the original view with a double click. The default value is false.

Examples

Histogram of Horsepower

Tucan.histogram(:cars, "Horsepower")

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"plot":"histogram"},"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":1,"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","__tucan__":{"plot":"histogram"},"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":1,"type":"bar"},"transform":[{"as":"bin_Horsepower","bin":true,"field":"Horsepower"},{"aggregate":[{"as":"count_Horsepower","op":"count"}],"groupby":["bin_Horsepower","bin_Horsepower_end"]}]}

You can also modify the default color and add a radius to the histogram bars:

Tucan.histogram(:cars, "Horsepower", orient: :vertical, fill_color: "red", corner_radius: 5)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"plot":"histogram"},"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":{"color":"red","cornerRadiusEnd":5,"fillOpacity":1,"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","__tucan__":{"plot":"histogram"},"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":1,"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","__tucan__":{"plot":"histogram"},"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":1,"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","__tucan__":{"plot":"histogram"},"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","__tucan__":{"plot":"histogram"},"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", tooltip: true)
  |> Tucan.facet_by(:column, "Origin")

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

Tucan.vconcat([histograms, relative_histograms])

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","vconcat":[{"__tucan__":{"plot":"histogram"},"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":1,"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"]}]},{"__tucan__":{"plot":"histogram"},"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":1,"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"}]}]}

@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

• :interpolate (binary/0) - The line interpolation method to use for line and area marks. One of the following:
  • "linear" - piecewise linear segments, as in a poly-line.
  • "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 (number/0) - Depending on the interpolation type, sets the tension parameter

Data Grouping Options

• :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.

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :clip (boolean/0) - Whether a mark will be clipped to the enclosing group’s width and height.
• :fill_opacity (number/0) - The fill opacity of the plotted elements. The default value is 1.
• :filled (boolean/0) - Whether the points will be filled or not. Valid only if :points is set. The default value is true.
• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :line_color (String.t/0) - The color of the line
• :point_color (String.t/0) - The color of the points, if :points is set to true.
• :points (boolean/0) - Whether points will be included in the chart. The default value is false.
• :stroke_dash (list of pos_integer/0) - An array of alternating stroke, space lengths in pixels for creating dashed or dotted lines.
• :stroke_width (pos_integer/0) - The stroke width in pixels
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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
• :zoomable (boolean/0) - Whether the plot will be zoomable or not. If set to true you will be able to pan and zoom the plot with your mouse. You can reset to the original view with a double click. The default value is false.

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":1,"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")

Tucan.hconcat([left, right])

{"$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":1,"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":1,"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
  )

Tucan.hconcat([filled_points, stroked_points])

{"$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":1,"point":[],"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":1,"point":{"fill":"white","filled":false},"tooltip":true,"type":"line"},"width":300}]}

You can configure the style of the lines using :stroke_dash, :stroke_width and :line_color options.

data =
  for i <- 0..100, x = 0.1 * i do
    %{x: x, cos: :math.cos(x), sin: :math.sin(x)}
  end

Tucan.layers([
  Tucan.lineplot(data, "x", "cos", stroke_width: 3, stroke_dash: [5, 2], line_color: "red"),
  Tucan.lineplot(data, "x", "sin", stroke_width: 2, stroke_dash: [5, 3, 2], line_color: "green")
])
|> Tucan.set_width(300)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","layer":[{"data":{"values":[{"cos":1.0,"sin":0.0,"x":0.0},{"cos":0.9950041652780258,"sin":0.09983341664682815,"x":0.1},{"cos":0.9800665778412416,"sin":0.19866933079506122,"x":0.2},{"cos":0.955336489125606,"sin":0.2955202066613396,"x":0.30000000000000004},{"cos":0.9210609940028851,"sin":0.3894183423086505,"x":0.4},{"cos":0.8775825618903728,"sin":0.479425538604203,"x":0.5},{"cos":0.8253356149096782,"sin":0.5646424733950355,"x":0.6000000000000001},{"cos":0.7648421872844884,"sin":0.6442176872376911,"x":0.7000000000000001},{"cos":0.6967067093471654,"sin":0.7173560908995228,"x":0.8},{"cos":0.6216099682706644,"sin":0.7833269096274834,"x":0.9},{"cos":0.5403023058681398,"sin":0.8414709848078965,"x":1.0},{"cos":0.4535961214255773,"sin":0.8912073600614354,"x":1.1},{"cos":0.3623577544766734,"sin":0.9320390859672264,"x":1.2000000000000002},{"cos":0.26749882862458735,"sin":0.963558185417193,"x":1.3},{"cos":0.16996714290024081,"sin":0.9854497299884603,"x":1.4000000000000001},{"cos":0.0707372016677029,"sin":0.9974949866040544,"x":1.5},{"cos":-0.029199522301288815,"sin":0.9995736030415051,"x":1.6},{"cos":-0.12884449429552486,"sin":0.9916648104524686,"x":1.7000000000000002},{"cos":-0.2272020946930871,"sin":0.9738476308781951,"x":1.8},{"cos":-0.3232895668635035,"sin":0.9463000876874145,"x":1.9000000000000001},{"cos":-0.4161468365471424,"sin":0.9092974268256817,"x":2.0},{"cos":-0.5048461045998576,"sin":0.8632093666488737,"x":2.1},{"cos":-0.5885011172553458,"sin":0.8084964038195901,"x":2.2},{"cos":-0.6662760212798244,"sin":0.74570521217672,"x":2.3000000000000003},{"cos":-0.7373937155412458,"sin":0.6754631805511506,"x":2.4000000000000004},{"cos":-0.8011436155469337,"sin":0.5984721441039564,"x":2.5},{"cos":-0.8568887533689473,"sin":0.5155013718214642,"x":2.6},{"cos":-0.9040721420170612,"sin":0.4273798802338298,"x":2.7},{"cos":-0.9422223406686583,"sin":0.33498815015590466,"x":2.8000000000000003},{"cos":-0.9709581651495907,"sin":0.23924932921398198,"x":2.9000000000000004},{"cos":-0.9899924966004454,"sin":0.1411200080598672,"x":3.0},{"cos":-0.9991351502732795,"sin":0.04158066243329049,"x":3.1},{"cos":-0.9982947757947531,"sin":-0.058374143427580086,"x":3.2},{"cos":-0.9874797699088649,"sin":-0.15774569414324865,"x":3.3000000000000003},{"cos":-0.9667981925794609,"sin":-0.25554110202683167,"x":3.4000000000000004},{"cos":-0.9364566872907963,"sin":-0.35078322768961984,"x":3.5},{"cos":-0.896758416334147,"sin":-0.44252044329485246,"x":3.6},{"cos":-0.848100031710408,"sin":-0.5298361409084934,"x":3.7},{"cos":-0.7909677119144165,"sin":-0.6118578909427193,"x":3.8000000000000003},{"cos":-0.7259323042001399,"sin":-0.6877661591839741,"x":3.9000000000000004},{"cos":-0.6536436208636119,"sin":-0.7568024953079283,"x":4.0},{"cos":-0.5748239465332685,"sin":-0.8182771110644108,"x":4.1000000000000005},{"cos":-0.4902608213406994,"sin":-0.8715757724135882,"x":4.2},{"cos":-0.40079917207997545,"sin":-0.9161659367494549,"x":4.3},{"cos":-0.30733286997841935,"sin":-0.9516020738895161,"x":4.4},{"cos":-0.2107957994307797,"sin":-0.977530117665097,"x":4.5},{"cos":-0.112152526935054,"sin":-0.9936910036334645,"x":4.6000000000000005},{"cos":-0.01238866346289056,"sin":-0.9999232575641008,"x":4.7},{"cos":0.08749898343944727,"sin":-0.9961646088358406,"x":4.800000000000001},{"cos":0.18651236942257576,"sin":-0.9824526126243325,"x":4.9},{"cos":0.28366218546322625,"sin":-0.9589242746631385,"x":5.0},{"cos":0.37797774271298107,"sin":-0.9258146823277321,"x":5.1000000000000005},{"cos":0.4685166713003771,"sin":-0.8834546557201531,"x":5.2},{"cos":0.5543743361791615,"sin":-0.8322674422239008,"x":5.300000000000001},{"cos":0.6346928759426347,"sin":-0.7727644875559871,"x":5.4},{"cos":0.70866977429126,"sin":-0.7055403255703919,"x":5.5},{"cos":0.7755658785102502,"sin":-0.631266637872321,"x":5.6000000000000005},{"cos":0.8347127848391598,"sin":-0.5506855425976376,"x":5.7},{"cos":0.8855195169413194,"sin":-0.4646021794137566,"x":5.800000000000001},{"cos":0.9274784307440359,"sin":-0.373876664830236,"x":5.9},{"cos":0.960170286650366,"sin":-0.27941549819892586,"x":6.0},{"cos":0.9832684384425847,"sin":-0.18216250427209502,"x":6.1000000000000005},{"cos":0.9965420970232175,"sin":-0.0830894028174964,"x":6.2},{"cos":0.9998586363834151,"sin":0.0168139004843506,"x":6.300000000000001},{"cos":0.9931849187581926,"sin":0.11654920485049364,"x":6.4},{"cos":0.9765876257280235,"sin":0.21511998808781552,"x":6.5},{"cos":0.9502325919585293,"sin":0.3115413635133787,"x":6.6000000000000005},{"cos":0.9143831482353194,"sin":0.4048499206165983,"x":6.7},{"cos":0.8693974903498248,"sin":0.49411335113860894,"x":6.800000000000001},{"cos":0.8157251001253569,"sin":0.5784397643882002,"x":6.9},{"cos":0.7539022543433046,"sin":0.6569865987187891,"x":7.0},{"cos":0.6845466664428059,"sin":0.7289690401258765,"x":7.1000000000000005},{"cos":0.6083513145322546,"sin":0.7936678638491531,"x":7.2},{"cos":0.5260775173811045,"sin":0.850436620628565,"x":7.300000000000001},{"cos":0.43854732757439036,"sin":0.8987080958116269,"x":7.4},{"cos":0.3466353178350258,"sin":0.9379999767747389,"x":7.5},{"cos":0.25125984258225487,"sin":0.9679196720314865,"x":7.6000000000000005},{"cos":0.15337386203786435,"sin":0.9881682338770004,"x":7.7},{"cos":0.05395542056264886,"sin":0.998543345374605,"x":7.800000000000001},{"cos":-0.04600212563953695,"sin":0.998941341839772,"x":7.9},{"cos":-0.14550003380861354,"sin":0.9893582466233818,"x":8.0},{"cos":-0.2435441537357911,"sin":0.9698898108450863,"x":8.1},{"cos":-0.33915486098383624,"sin":0.9407305566797726,"x":8.200000000000001},{"cos":-0.43137684497062084,"sin":0.9021718337562934,"x":8.3},{"cos":-0.5192886541166856,"sin":0.8545989080882804,"x":8.4},{"cos":-0.6020119026848236,"sin":0.7984871126234903,"x":8.5},{"cos":-0.6787200473200125,"sin":0.7343970978741134,"x":8.6},{"cos":-0.7486466455973999,"sin":0.662969230082182,"x":8.700000000000001},{"cos":-0.811093014061656,"sin":0.5849171928917617,"x":8.8},{"cos":-0.8654352092411123,"sin":0.5010208564578846,"x":8.9},{"cos":-0.9111302618846769,"sin":0.4121184852417566,"x":9.0},{"cos":-0.9477216021311119,"sin":0.3190983623493521,"x":9.1},{"cos":-0.974843621404164,"sin":0.22288991410024592,"x":9.200000000000001},{"cos":-0.9922253254526034,"sin":0.1244544235070617,"x":9.3},{"cos":-0.9996930420352065,"sin":0.024775425453357765,"x":9.4},{"cos":-0.9971721561963784,"sin":-0.0751511204618093,"x":9.5},{"cos":-0.9846878557941267,"sin":-0.1743267812229814,"x":9.600000000000001},{"cos":-0.9623648798313097,"sin":-0.2717606264109442,"x":9.700000000000001},{"cos":-0.9304262721047533,"sin":-0.36647912925192844,"x":9.8},{"cos":-0.8891911526253609,"sin":-0.4575358937753214,"x":9.9},{"cos":-0.8390715290764524,"sin":-0.5440211108893698,"x":10.0}]},"encoding":{"x":{"field":"x","type":"quantitative"},"y":{"field":"cos","type":"quantitative"}},"mark":{"color":"red","fillOpacity":1,"strokeDash":[5,2],"strokeWidth":3,"type":"line"}},{"data":{"values":[{"cos":1.0,"sin":0.0,"x":0.0},{"cos":0.9950041652780258,"sin":0.09983341664682815,"x":0.1},{"cos":0.9800665778412416,"sin":0.19866933079506122,"x":0.2},{"cos":0.955336489125606,"sin":0.2955202066613396,"x":0.30000000000000004},{"cos":0.9210609940028851,"sin":0.3894183423086505,"x":0.4},{"cos":0.8775825618903728,"sin":0.479425538604203,"x":0.5},{"cos":0.8253356149096782,"sin":0.5646424733950355,"x":0.6000000000000001},{"cos":0.7648421872844884,"sin":0.6442176872376911,"x":0.7000000000000001},{"cos":0.6967067093471654,"sin":0.7173560908995228,"x":0.8},{"cos":0.6216099682706644,"sin":0.7833269096274834,"x":0.9},{"cos":0.5403023058681398,"sin":0.8414709848078965,"x":1.0},{"cos":0.4535961214255773,"sin":0.8912073600614354,"x":1.1},{"cos":0.3623577544766734,"sin":0.9320390859672264,"x":1.2000000000000002},{"cos":0.26749882862458735,"sin":0.963558185417193,"x":1.3},{"cos":0.16996714290024081,"sin":0.9854497299884603,"x":1.4000000000000001},{"cos":0.0707372016677029,"sin":0.9974949866040544,"x":1.5},{"cos":-0.029199522301288815,"sin":0.9995736030415051,"x":1.6},{"cos":-0.12884449429552486,"sin":0.9916648104524686,"x":1.7000000000000002},{"cos":-0.2272020946930871,"sin":0.9738476308781951,"x":1.8},{"cos":-0.3232895668635035,"sin":0.9463000876874145,"x":1.9000000000000001},{"cos":-0.4161468365471424,"sin":0.9092974268256817,"x":2.0},{"cos":-0.5048461045998576,"sin":0.8632093666488737,"x":2.1},{"cos":-0.5885011172553458,"sin":0.8084964038195901,"x":2.2},{"cos":-0.6662760212798244,"sin":0.74570521217672,"x":2.3000000000000003},{"cos":-0.7373937155412458,"sin":0.6754631805511506,"x":2.4000000000000004},{"cos":-0.8011436155469337,"sin":0.5984721441039564,"x":2.5},{"cos":-0.8568887533689473,"sin":0.5155013718214642,"x":2.6},{"cos":-0.9040721420170612,"sin":0.4273798802338298,"x":2.7},{"cos":-0.9422223406686583,"sin":0.33498815015590466,"x":2.8000000000000003},{"cos":-0.9709581651495907,"sin":0.23924932921398198,"x":2.9000000000000004},{"cos":-0.9899924966004454,"sin":0.1411200080598672,"x":3.0},{"cos":-0.9991351502732795,"sin":0.04158066243329049,"x":3.1},{"cos":-0.9982947757947531,"sin":-0.058374143427580086,"x":3.2},{"cos":-0.9874797699088649,"sin":-0.15774569414324865,"x":3.3000000000000003},{"cos":-0.9667981925794609,"sin":-0.25554110202683167,"x":3.4000000000000004},{"cos":-0.9364566872907963,"sin":-0.35078322768961984,"x":3.5},{"cos":-0.896758416334147,"sin":-0.44252044329485246,"x":3.6},{"cos":-0.848100031710408,"sin":-0.5298361409084934,"x":3.7},{"cos":-0.7909677119144165,"sin":-0.6118578909427193,"x":3.8000000000000003},{"cos":-0.7259323042001399,"sin":-0.6877661591839741,"x":3.9000000000000004},{"cos":-0.6536436208636119,"sin":-0.7568024953079283,"x":4.0},{"cos":-0.5748239465332685,"sin":-0.8182771110644108,"x":4.1000000000000005},{"cos":-0.4902608213406994,"sin":-0.8715757724135882,"x":4.2},{"cos":-0.40079917207997545,"sin":-0.9161659367494549,"x":4.3},{"cos":-0.30733286997841935,"sin":-0.9516020738895161,"x":4.4},{"cos":-0.2107957994307797,"sin":-0.977530117665097,"x":4.5},{"cos":-0.112152526935054,"sin":-0.9936910036334645,"x":4.6000000000000005},{"cos":-0.01238866346289056,"sin":-0.9999232575641008,"x":4.7},{"cos":0.08749898343944727,"sin":-0.9961646088358406,"x":4.800000000000001},{"cos":0.18651236942257576,"sin":-0.9824526126243325,"x":4.9},{"cos":0.28366218546322625,"sin":-0.9589242746631385,"x":5.0},{"cos":0.37797774271298107,"sin":-0.9258146823277321,"x":5.1000000000000005},{"cos":0.4685166713003771,"sin":-0.8834546557201531,"x":5.2},{"cos":0.5543743361791615,"sin":-0.8322674422239008,"x":5.300000000000001},{"cos":0.6346928759426347,"sin":-0.7727644875559871,"x":5.4},{"cos":0.70866977429126,"sin":-0.7055403255703919,"x":5.5},{"cos":0.7755658785102502,"sin":-0.631266637872321,"x":5.6000000000000005},{"cos":0.8347127848391598,"sin":-0.5506855425976376,"x":5.7},{"cos":0.8855195169413194,"sin":-0.4646021794137566,"x":5.800000000000001},{"cos":0.9274784307440359,"sin":-0.373876664830236,"x":5.9},{"cos":0.960170286650366,"sin":-0.27941549819892586,"x":6.0},{"cos":0.9832684384425847,"sin":-0.18216250427209502,"x":6.1000000000000005},{"cos":0.9965420970232175,"sin":-0.0830894028174964,"x":6.2},{"cos":0.9998586363834151,"sin":0.0168139004843506,"x":6.300000000000001},{"cos":0.9931849187581926,"sin":0.11654920485049364,"x":6.4},{"cos":0.9765876257280235,"sin":0.21511998808781552,"x":6.5},{"cos":0.9502325919585293,"sin":0.3115413635133787,"x":6.6000000000000005},{"cos":0.9143831482353194,"sin":0.4048499206165983,"x":6.7},{"cos":0.8693974903498248,"sin":0.49411335113860894,"x":6.800000000000001},{"cos":0.8157251001253569,"sin":0.5784397643882002,"x":6.9},{"cos":0.7539022543433046,"sin":0.6569865987187891,"x":7.0},{"cos":0.6845466664428059,"sin":0.7289690401258765,"x":7.1000000000000005},{"cos":0.6083513145322546,"sin":0.7936678638491531,"x":7.2},{"cos":0.5260775173811045,"sin":0.850436620628565,"x":7.300000000000001},{"cos":0.43854732757439036,"sin":0.8987080958116269,"x":7.4},{"cos":0.3466353178350258,"sin":0.9379999767747389,"x":7.5},{"cos":0.25125984258225487,"sin":0.9679196720314865,"x":7.6000000000000005},{"cos":0.15337386203786435,"sin":0.9881682338770004,"x":7.7},{"cos":0.05395542056264886,"sin":0.998543345374605,"x":7.800000000000001},{"cos":-0.04600212563953695,"sin":0.998941341839772,"x":7.9},{"cos":-0.14550003380861354,"sin":0.9893582466233818,"x":8.0},{"cos":-0.2435441537357911,"sin":0.9698898108450863,"x":8.1},{"cos":-0.33915486098383624,"sin":0.9407305566797726,"x":8.200000000000001},{"cos":-0.43137684497062084,"sin":0.9021718337562934,"x":8.3},{"cos":-0.5192886541166856,"sin":0.8545989080882804,"x":8.4},{"cos":-0.6020119026848236,"sin":0.7984871126234903,"x":8.5},{"cos":-0.6787200473200125,"sin":0.7343970978741134,"x":8.6},{"cos":-0.7486466455973999,"sin":0.662969230082182,"x":8.700000000000001},{"cos":-0.811093014061656,"sin":0.5849171928917617,"x":8.8},{"cos":-0.8654352092411123,"sin":0.5010208564578846,"x":8.9},{"cos":-0.9111302618846769,"sin":0.4121184852417566,"x":9.0},{"cos":-0.9477216021311119,"sin":0.3190983623493521,"x":9.1},{"cos":-0.974843621404164,"sin":0.22288991410024592,"x":9.200000000000001},{"cos":-0.9922253254526034,"sin":0.1244544235070617,"x":9.3},{"cos":-0.9996930420352065,"sin":0.024775425453357765,"x":9.4},{"cos":-0.9971721561963784,"sin":-0.0751511204618093,"x":9.5},{"cos":-0.9846878557941267,"sin":-0.1743267812229814,"x":9.600000000000001},{"cos":-0.9623648798313097,"sin":-0.2717606264109442,"x":9.700000000000001},{"cos":-0.9304262721047533,"sin":-0.36647912925192844,"x":9.8},{"cos":-0.8891911526253609,"sin":-0.4575358937753214,"x":9.9},{"cos":-0.8390715290764524,"sin":-0.5440211108893698,"x":10.0}]},"encoding":{"x":{"field":"x","type":"quantitative"},"y":{"field":"sin","type":"quantitative"}},"mark":{"color":"green","fillOpacity":1,"strokeDash":[5,3,2],"strokeWidth":2,"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

Tucan.concat(plots, columns: 2)

{"$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":1,"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":1,"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":1,"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":1,"interpolate":"monotone","type":"line"},"title":{"text":"monotone"}}]}

@spec lollipop(
  plotdata :: plotdata(),
  field :: String.t(),
  value :: String.t(),
  opts :: keyword()
) :: VegaLite.t()

Draws a lollipop plot.

A lollipop plot is nothing more than a bar plot, where the bar is transformed in a line and a dot. It shows the relationship between a numeric and a categoric variable.

Comparison to bar/4

The lollipop plot is used exactly in the same situation as a bar plot. However it is somewhat more appealing and convey as well the information. It is especially useful when you have several bars of the same height.

data = [
  category: ["A", "B", "C", "D", "E"],
  value: [99, 97, 94, 90, 88]
]

bar = Tucan.bar(data, "category", "value", orient: :horizontal)
lollipop = Tucan.lollipop(data, "category", "value", orient: :horizontal)

Tucan.hconcat([bar, lollipop])

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","hconcat":[{"data":{"values":[{"category":"A","value":99},{"category":"B","value":97},{"category":"C","value":94},{"category":"D","value":90},{"category":"E","value":88}]},"encoding":{"x":{"field":"value","type":"quantitative"},"y":{"axis":{"labelAngle":0},"field":"category","type":"nominal"}},"mark":{"fillOpacity":1,"type":"bar"}},{"__tucan__":{"multilayer":true},"data":{"values":[{"category":"A","value":99},{"category":"B","value":97},{"category":"C","value":94},{"category":"D","value":90},{"category":"E","value":88}]},"layer":[{"encoding":{"x":{"field":"value","type":"quantitative"},"y":{"axis":{"labelAngle":0},"field":"category","type":"nominal"}},"mark":{"color":"black","type":"rule"}},{"encoding":{"x":{"field":"value","type":"quantitative"},"y":{"axis":{"labelAngle":0},"field":"category","type":"nominal"}},"mark":{"color":"black","filled":true,"opacity":1,"size":60,"type":"point"}}]}]}

See also bar/4.

Options

Data Grouping Options

• :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 categorical field to group the lollipops by. It is used for adding a second dimension to the plot. When set, the groups are also color coded by the same categorical variable.

Data Options

• :only - A subset of fields to pick from the data. Applicable only if tabular data are provided.

Styling Options

• :height (pos_integer/0 or :container) - Height of the plot. Can either be the height in pixels or :container to indicate that the height of the plot should be the same as its surrounding container.
• :line_color (String.t/0) - The color of the line The default value is "black".
• :orient (atom/0) - The plot's orientation, can be either :horizontal or :vertical. The default value is :vertical.
• :point_color (String.t/0) - The color of the points The default value is "black".
• :point_shape - Shape of the point marks. Circle by default.
• :point_size (pos_integer/0) - The pixel area of the marks. Note that this value sets the area of the symbol; the side lengths will increase with the square root of this value. The default value is 60.
• :title (String.t/0) - The title of the graph
• :width (pos_integer/0 or :container) - Width of the plot. Can either be the width in pixels or :container to indicate that the width of the plot should be the same as its surrounding container.

Encodings Custom Options

All Tucan plots are building a VegaLite specification based on some sane default parameters. Through these encodings options you are free to set any vega-lite supported option to any encoding channel of the plot.

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.

You can set an arbitrary keyword list. Notice that the contents are not validated.

• :color (keyword/0) - Extra vega lite options for the :color encoding. The default value is [].
• :x (keyword/0) - Extra vega lite options for the :x encoding. The default value is [].
• :x_offset (keyword/0) - Extra vega lite options for the :x_offset encoding. The default value is [].
• :y (keyword/0) - Extra vega lite options for the :y encoding. The default value is [].
• :y_offset (keyword/0) - Extra vega lite options for the :y_offset encoding. The default value is [].

Interactivity Options

• :tooltip (boolean() | :data | :encoding) - 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

Examples

A lollipop chart for some synthetic data:

data =
  for category <- ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"] do
    %{category: category, value: 9 + :rand.uniform(90)}
  end

Tucan.lollipop(data, "category", "value", width: 400)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"values":[{"category":"A","value":37},{"category":"B","value":31},{"category":"C","value":42},{"category":"D","value":23},{"category":"E","value":65},{"category":"F","value":41},{"category":"G","value":16},{"category":"H","value":44},{"category":"I","value":50},{"category":"J","value":74}]},"layer":[{"encoding":{"x":{"axis":{"labelAngle":0},"field":"category","type":"nominal"},"y":{"field":"value","type":"quantitative"}},"mark":{"color":"black","type":"rule"}},{"encoding":{"x":{"axis":{"labelAngle":0},"field":"category","type":"nominal"},"y":{"field":"value","type":"quantitative"}},"mark":{"color":"black","filled":true,"opacity":1,"size":60,"type":"point"}}],"width":400}

You can make the lollipops horizontal by setting the :orient flag:

data =
  for category <- ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"] do
    %{category: category, value: 9 + :rand.uniform(90)}
  end

Tucan.lollipop(data, "category", "value", width: 400, orient: :horizontal)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","__tucan__":{"multilayer":true},"data":{"values":[{"category":"A","value":91},{"category":"B","value":79},{"category":"C","value":83},{"category":"D","value":90},{"category":"E","value":27},{"category":"F","value":47},{"category":"G","value":69},{"category":"H","value":27},{"category":"I","value":12},{"category":"J","value":13}]},"layer":[{"encoding":{"x":{"field":"value","type":"quantitative"},"y":{"axis":{"labelAngle":0},"field":"category","type":"nominal"}},"mark":{"color":"black","type":"rule"}},{"encoding":{"x":{"field":"value","type":"quantitative"},"y":{"axis":{"labelAngle":0},"field":"category","type":"nominal"}},"mark":{"color":"black","filled":true,"opacity":1,"size":60,"type":"point"}}],"width":400}

You can change the points shape and the default colors if needed:

data =
  for category <- ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"] do
    %{category: category, value: 9 + :rand.uniform(90)}
  end

Tucan.lollipop(data, "category", "value",
  point_color: "red",
  point_shape: "square",
  point_size: 80,
  line_color: "blue",
  width: 400
)