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

Set arbitrary options to the legend of the given channel.

The options are deep merged with existing options.

Examples

Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.color_by("species")
|> Tucan.Legend.put_options(:color,
  fill_color: "yellow",
  offset: 5,
  padding: 2,
  label_font_size: 14
)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"},"encoding":{"color":{"field":"species","legend":{"fillColor":"yellow","labelFontSize":14,"offset":5,"padding":2}},"x":{"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":1,"type":"point"}}

@spec set_enabled(vl :: VegaLite.t(), channel :: atom(), enabled :: boolean()) ::
  VegaLite.t()

Enables or disables the legend of the given encoding channel.

@spec set_offset(vl :: VegaLite.t(), channel :: atom(), offset :: integer()) ::
  VegaLite.t()

Sets the offset in pixels by which to displace the legend from the data rectangle and axes.

If not set defaults to 18 pixels.

Examples

Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.color_by("species")
|> Tucan.Legend.set_offset(:color, 5)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"},"encoding":{"color":{"field":"species","legend":{"offset":5}},"x":{"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":1,"type":"point"}}

@spec set_orientation(
  vl :: VegaLite.t(),
  channel :: atom(),
  orientation :: String.t()
) :: VegaLite.t()

Sets the legend orientation with respect to the scene.

You need to define the channel for which the legend will be configured. Orientation can be one of the following: ["left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right", "none"].

Applicable only on plots with a legend.

Examples

Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.color_by("species")
|> Tucan.shape_by("species")
|> Tucan.Legend.set_orientation(:color, "bottom")
|> Tucan.Legend.set_orientation(:shape, "top")

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"},"encoding":{"color":{"field":"species","legend":{"orient":"bottom"}},"shape":{"field":"species","legend":{"orient":"top"}},"x":{"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":1,"type":"point"}}

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

Makes the legend of the given channel selectable.

Clicking on an entry of the legend highlights the data of this entry and fades the rest. Shift-click selects multiple entries and a double click clears the selection.

It is applicable on single view and layered plots, with a legend on a field of the given channel. In layered plots all layers with the same field are highlighted.

See also Tucan.Interactive for more interactive plots.

Options

• :unselected_opacity (number/0) - The opacity of the data that are not selected. The default value is 0.15.

Examples

Click on a symbol of the legend to highlight its stock:

Tucan.lineplot(:stocks, "date", "price", color_by: "symbol", x: [type: :temporal], width: 400)
|> Tucan.Legend.set_selectable(:color)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://vega.github.io/editor/data/stocks.csv"},"encoding":{"color":{"field":"symbol"},"opacity":{"condition":{"param":"_legend","value":1},"value":0.15},"x":{"field":"date","type":"temporal"},"y":{"field":"price","type":"quantitative"}},"mark":{"fillOpacity":1,"type":"line"},"params":[{"bind":"legend","name":"_legend","select":{"fields":["symbol"],"type":"point"}}],"width":400}

Legends of other channels can be selectable as well:

Tucan.scatter(:penguins, "Beak Length (mm)", "Beak Depth (mm)", shape_by: "Island")
|> Tucan.Legend.set_selectable(:shape, unselected_opacity: 0.05)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://raw.githubusercontent.com/vega/vega-datasets/next/data/penguins.json"},"encoding":{"opacity":{"condition":{"param":"_legend","value":1},"value":0.05},"shape":{"field":"Island","type":"nominal"},"x":{"field":"Beak Length (mm)","scale":{"zero":false},"type":"quantitative"},"y":{"field":"Beak Depth (mm)","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":1,"type":"point"},"params":[{"bind":"legend","name":"_legend","select":{"fields":["Island"],"type":"point"}}]}

@spec set_title(
  vl :: VegaLite.t(),
  channel :: atom(),
  title :: String.t() | nil,
  opts :: keyword()
) ::
  VegaLite.t()

Sets the title of the given legend.

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

Applicable only on plots with a legend.

Examples

Tucan.scatter(:iris, "petal_width", "petal_length", color_by: "species")
|> Tucan.Legend.set_title(:color, "Iris Species", title_color: "red", title_font_weight: 300)

{"$schema":"https://vega.github.io/schema/vega-lite/v5.json","data":{"url":"https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"},"encoding":{"color":{"field":"species","legend":{"title":"Iris Species","titleColor":"red","titleFontWeight":300},"type":"nominal"},"x":{"field":"petal_width","scale":{"zero":false},"type":"quantitative"},"y":{"field":"petal_length","scale":{"zero":false},"type":"quantitative"}},"mark":{"fillOpacity":1,"type":"point"}}