Tucan Elixir Plotting Library

Tucan allows you to enhance visualizations by grouping data by semantic properties or creating facet plots to examine subgroups.

# Semantic grouping by color and shape
Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.color_by("species")
|> Tucan.shape_by("species")

# Creating facet plots using facet_by/4
Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.facet_by(:column, "species")
|> Tucan.color_by("species")

To use Tucan in a Livebook notebook, install both tucan and kino_vega_lite using Mix.install/2. The kino_vega_lite package is required to ensure that the graphics are rendered correctly within the Livebook interface.

Mix.install([
  {:tucan, "~> 0.3.0"},
  {:kino_vega_lite, "~> 0.1.8"}
])

To use Tucan in a standard Elixir Mix project, add :tucan to your deps function in mix.exs.

Note: As this is a 0.x.x version, the API is not considered stable and may undergo breaking changes before v1.0.0.

def deps do
  [
    {:tucan, "~> 0.4.0"}
  ]
end

Tucan provides a high-level API for creating common plot types like scatter plots and bubble charts without needing to know the VegaLite grammar. You can pass Nx tensors directly into plot functions.

Simple Scatter Plot

Tucan.scatter(:iris, "petal_width", "petal_length")

Bubble Chart with Customization

You can use the pipe operator to modify plot dimensions, axis titles, and scales.

Tucan.bubble(:gapminder, "income", "health", "population",
  color_by: "region",
  tooltip: true
)
|> Tucan.set_width(400)
|> Tucan.Axes.set_x_title("Gdp per Capita")
|> Tucan.Axes.set_y_title("Life expectancy")
|> Tucan.Scale.set_x_scale(:log)

# A simple scatter plot
Tucan.scatter(:iris, "petal_width", "petal_length")

A Tucan theme is a keyword list containing a VegaLite configuration object and metadata. Every theme follows this internal structure:

[
  theme: [],          # The actual VegaLite configuration keyword list
  name: :name,        # An atom with a unique name
  doc: "description", # A description of the theme
  source: "url"       # A URL to the source for attribution
]

To use Tucan.Export functions, you must add the vega_lite_convert package to your project's dependencies. Without this, any call to the export module will raise a RuntimeError.

def deps do
  [
    {:vega_lite_convert, "~> 1.0.0"}
  ]
end

You can apply a visual theme to any Tucan plot using the Tucan.set_theme/2 function. This is typically used in a pipeline after creating a plot and applying semantic groupings like color_by or shape_by.

Note for Livebook users: If you are using Tucan within Livebook, the kino_vega_lite package applies a default theme that may override your Tucan settings. To ensure your Tucan theme is applied correctly, disable the default Livebook theme using Kino.VegaLite.configure/1 first.

# 1. Disable default Livebook theme if applicable
Kino.VegaLite.configure(theme: nil)

# 2. Apply your desired Tucan theme
Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.color_by("species")
|> Tucan.shape_by("species")
|> Tucan.set_theme(:dark)

Tucan supports composite plots, such as pairplot, which can be customized with options like width, height, and recursive color grouping.

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

Tucan.pairplot(:iris, fields, width: 130, height: 130)
|> Tucan.color_by("species", recursive: true)

Use Tucan.View.set_background/2 to set the background color of the entire visualization canvas. This affects the outer area of the plot or the overall container for concatenated plots.

Tucan.scatter(:iris, "sepal_width", "sepal_length")
|> Tucan.View.set_background("#fcffde")

Enables or disables the grid for a specific encoding channel (e.g., :x or :y).

Warning: This will raise if the specified channel is not encoded in the plot.

Tucan.scatter(:iris, "petal_width", "petal_length")
|> Tucan.Grid.set_enabled(:y, false)

Tucan provides a collection of built-in datasets for demonstrations and testing. You can retrieve the remote URL for any supported dataset using Tucan.Datasets.dataset/1. This function accepts an atom representing the dataset name and returns its source URL as a string. If you provide an invalid dataset atom, it will raise an ArgumentError listing the valid options.

# Example: Get the URL for the 'iris' dataset
url = Tucan.Datasets.dataset(:iris)
# Returns: "https://gist.githubusercontent.com/curran/a08a1080b88344b0c8a7/raw/0e7a9b0a5d22642a06d3d5b9bcbad9890c8ee534/iris.csv"

Use Tucan.Export.to_png/2 to render the graphic as a PNG image and return its binary content.

Options:

• :scale - The image scale factor. Defaults to 1.0.
• :ppi - The number of pixels per inch. Defaults to 72.