@spec put_options(vl :: VegaLite.t(), encoding :: atom(), options :: keyword()) ::
  VegaLite.t()

Sets an arbitrary set of options to the given encoding's scale object.

Notice that no validation is performed, any option set will be merged with the existing scale options of the given encoding.

An ArgumentError is raised if the given encoding channel is not defined.

@spec set_clamp(vl :: VegaLite.t(), channel :: atom(), clamp :: boolean()) ::
  VegaLite.t()

Enables or disables clamping for the given axis.

If true, values that exceed the data domain are clamped to either the minimum or maximum range value.

This is applicable only on continuous scales.

Examples

Clamp set to false (left) vs true (right)

left =
  Tucan.scatter(:iris, "petal_width", "petal_length")
  |> Tucan.Scale.set_x_domain(0.5, 2.0)
  |> Tucan.Scale.set_clamp(:x, false)

right =
  Tucan.scatter(:iris, "petal_width", "petal_length")
  |> Tucan.Scale.set_x_domain(0.5, 2.0)
  |> Tucan.Scale.set_clamp(:x, true)

Tucan.hconcat([left, right])copy

clamp vs clip

Notice that clamp does not remove the items that exceed the domain. :clip on the other side drops these items.

clamp =
  Tucan.scatter(:iris, "petal_width", "petal_length")
  |> Tucan.Scale.set_x_domain(0.5, 2.0)
  |> Tucan.Scale.set_clamp(:x, true)

clip =
  Tucan.scatter(:iris, "petal_width", "petal_length", clip: true)
  |> Tucan.Scale.set_x_domain(0.5, 2.0)

Tucan.hconcat([clamp, clip])copy

@spec set_color_scheme(
  vl :: VegaLite.t(),
  scheme :: color_scheme(),
  opts :: keyword()
) :: VegaLite.t()

Sets the color scheme.

You can either set one of the predefined schemes, or an array of colors which will be used as the color range.

The input plot must be a single view with a color encoding defined.

Options

• :reverse (boolean/0) - If set to true the selected scheme is reversed. Ignored if a range is set. The default value is false.

Supported color schemes

All vega supported schemes are supported by Tucan.

Categorical Schemes

Categorical color schemes can be used to encode discrete data values, each representing a distinct category.

Sequential Single-Hue Schemes

Sequential color schemes can be used to encode quantitative values. These color ramps are designed to encode increasing numeric values.

Sequential Multi-Hue Schemes

Sequential color schemes can be used to encode quantitative values. These color ramps are designed to encode increasing numeric values, but use additional hues for more color discrimination, which may be useful for visualizations such as heatmaps.

Schemes for Dark Backgrounds

Schemes for Light Backgrounds

Diverging Schemes

Diverging color schemes can be used to encode quantitative values with a meaningful mid-point, such as zero or the average value. Color ramps with different hues diverge with increasing saturation to highlight the values below and above the mid-point.

Cyclical Schemes

Cyclical color schemes may be used to highlight periodic patterns in continuous data. However, these schemes are not well suited to accurately convey value differences.

Examples

Setting a specific color range

Tucan.scatter(:iris, "petal_width", "petal_length", color_by: "species")
|> Tucan.Scale.set_color_scheme(["yellow", "black", "#f234c1"])copy

You can set any of the predefined color schemes to any plot with a color encoding.

Tucan.scatter(:weather, "date", "temp_max",
  x: [time_unit: :monthdate],
  y: [aggregate: :mean],
  color_by: "temp_max",
  color: [aggregate: :mean, type: :quantitative],
  width: 400
)
|> Tucan.Scale.set_color_scheme(:redyellowblue)copy

You can reverse it by setting the :reverse option:

Tucan.scatter(:weather, "date", "temp_max",
  x: [time_unit: :monthdate],
  y: [aggregate: :mean],
  color_by: "temp_max",
  color: [aggregate: :mean, type: :quantitative],
  width: 400
)
|> Tucan.Scale.set_color_scheme(:redyellowblue, reverse: true)copy

@spec set_domain(vl :: VegaLite.t(), channel :: atom(), domain :: term()) ::
  VegaLite.t()

Sets the domain for the given encoding channel.

domain can be anything Vega-Lite supports and the validity of it depends on the type of the encoding's data.

Notice that no validation is performed.

@spec set_scale(
  vl :: VegaLite.t(),
  channel :: atom(),
  scale :: atom(),
  opts :: keyword()
) ::
  VegaLite.t()

Sets the scale for the given encoding channel.

Notice that only continuous scales are supported.

See also set_x_scale/3 and set_y_scale/3 wrappers for setting the scale directly on x and y axes.

Continuous Scales

Continuous scales map a continuous domain (numbers or dates) to a continuous output range (pixel locations, sizes, colors). Supported continuous scale types for quantitative fields are :linear, :log, :pow, :sqrt, and :symlog.

Meanwhile, supported continuous scale types for temporal fields are :time, :utc, and :symlog.

By default, :linear scales are used for quantitative fields and :time scales are used for temporal fields for all encoding channels.

Options

The supported options depend on the selected scale.

:pow scale

• :exponent (number/0) - The exponent to be used, applicable only for :pow scale.

:log scale

• :base (number/0) - The logarithm base of the :log scale. If not set defaults to 10.

:symlog scale

• :constant (number/0) - A constant determining the slope of the symlog function around zero. If not set defaults to 1.

Examples

Applying log scale on x-axis.

Tucan.scatter(:gapminder, "income", "health", width: 400)
|> Tucan.Scale.set_scale(:x, :log)copy

Applying pow scale on x-axis with arbitrary exponent.

Tucan.scatter(:gapminder, "income", "health", width: 400)
|> Tucan.Scale.set_scale(:x, :pow, exponent: 0.2)copy

@spec set_x_domain(vl :: VegaLite.t(), min :: number(), max :: number()) ::
  VegaLite.t()

Sets the x-axis domain.

This is a helper wrapper around set_domain/3 for setting the domain of continuous scales.

@spec set_x_scale(vl :: VegaLite.t(), scale :: atom(), opts :: keyword()) ::
  VegaLite.t()

Sets the x axis scale.

Options

See set_scale/4.

@spec set_xy_domain(vl :: VegaLite.t(), min :: number(), max :: number()) ::
  VegaLite.t()

Sets the same [x, y] domain for x-axis and y-axis at once.

@spec set_y_domain(vl :: VegaLite.t(), min :: number(), max :: number()) ::
  VegaLite.t()

Sets the y-axis domain.

This is a helper wrapper around set_domain/3 for setting the domain of continuous scales.

@spec set_y_scale(vl :: VegaLite.t(), scale :: atom(), opts :: keyword()) ::
  VegaLite.t()

Sets the y axis scale.

Options

See set_scale/4.