VegaLite Elixir Bindings

VegaLite provides Elixir bindings to the Vega-Lite visualization grammar.

Key capabilities include:

• Livebook Integration: Plot graphics directly in notebooks (requires kino_vega_lite).
• File Export: Save graphics to PNG, SVG, or PDF formats in regular Elixir projects.
• Web Rendering: Render graphics using a webviewer.

For a higher-level plotting experience built on top of these bindings, consider using Tucan.

To use VegaLite within a Livebook notebook, use Mix.install/2 to include both :vega_lite and :kino_vega_lite. The :kino_vega_lite dependency is required to ensure that graphics are rendered correctly within the Livebook interface.

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

To use VegaLite in a standard Elixir project, add :vega_lite to your deps function in mix.exs.

def deps do
  [
    {:vega_lite, "~> 0.1.11"}
  ]
end

The VegaLite.Data module uses internal type inference to automatically assign Vega-Lite types to columns based on the content of the data. This reduces the need for manual type declarations in many cases.

Inferred Types Mapping

• :quantitative: Numbers (integers, floats) and Decimal types.
• :temporal: Date, NaiveDateTime, DateTime objects, or ISO8601 formatted strings.
• :nominal: Atoms and strings that do not match date/time formats.

When using Data.chart/3 or Data.chart/4, the module inspects the data provided via the Table.Reader protocol to determine these types for the encoded fields.

The VegaLite.Export module is deprecated and scheduled for removal in v1.0. For all export operations, you should use the VegaLite.Convert module from the :vega_lite_convert package instead.

The VegaLite.Viewer module is deprecated and will be removed in version 1.0. To display Vega-Lite specifications, you should migrate to the :vega_lite_convert package and use its corresponding functions.

• Instead of VegaLite.Viewer.show/1, use VegaLite.Convert.open_viewer/1.
• Instead of VegaLite.Viewer.show_and_wait/1, use VegaLite.Convert.open_viewer_and_wait/1.

To use image export formats (:png, :svg, or :pdf), the VegaLite.Export module requires Node.js and specific npm packages. If the command fails, ensure you have installed the necessary dependencies globally or in your current directory:

npm install -g vega vega-lite canvas
# or in the current directory
npm install vega vega-lite canvas

If VegaLite.WxViewer.start/1 fails, it is likely due to missing Erlang dependencies. The module raises specific RuntimeError messages to help identify the cause:

1. Missing :wx module: If the error states VegaLite.Viewer requires Erlang compilation to include the :wx module, but it's not available, your Erlang installation lacks the :wx library.
2. Missing :wxWebView module: If the error states VegaLite.Viewer requires Erlang compilation to include the :wxWebView module, but it's not available. This module is available as of Erlang/OTP 24, you need to upgrade to Erlang/OTP 24 or higher or ensure :wxWebView is enabled in your build.

If you already have a VegaLite specification (e.g., one with a title or existing configuration), you can use VegaLite.Data.chart/4 to add data, a mark, and encodings to it.

Arguments

• vl: An existing VegaLite specification instance.
• data: Data implementing the Table.Reader protocol.
• mark: An atom or keyword list defining the mark type.
• fields: A keyword list defining the encodings.

Example

# Start with a spec that has a title
VegaLite.new(title: "My Chart")
  |> VegaLite.Data.chart(data, :bar, x: "category", y: "score")

Vl.new(title: "With title")
      |> Data.chart(data, :bar, x: "category", y: "score")

The VegaLite.Export.save!/3 function saves a VegaLite specification to a file path. The output format is determined by the file extension of the path or explicitly via the :format option.

Supported formats:

• :json
• :html
• :png
• :svg
• :pdf

Note: This function is deprecated. Use VegaLite.Convert.save!/3 from the :vega_lite_convert package instead.

# Example: Saving as PNG (uses file extension to infer format)
VegaLite.Export.save!(vl, "chart.png")

# Example: Saving with explicit format option
VegaLite.Export.save!(vl, "chart.output", format: :pdf)

The VegaLite.WxViewer module provides a way to render Vega-Lite specifications in a standalone desktop window using Erlang's :wx and :wxWebView modules. This is useful for viewing graphics outside of a Livebook or web environment.

Requirements

• Erlang/OTP 24 or later: Required for the :wxWebView module.
• :wx module: Must be included in your Erlang compilation.

Usage

Call VegaLite.WxViewer.start(html) with the HTML string containing your Vega-Lite specification. It returns {:ok, pid} on success, where pid is the process managing the window.

# Assuming 'html_content' is a binary containing the Vega-Lite HTML
case VegaLite.WxViewer.start(html_content) do
  {:ok, pid} -> IO.puts("Viewer started with PID: #{inspect(pid)}")
  :error -> IO.puts("Failed to start viewer")
end