ExeQute.EChart (exe_qute v0.1.1)

Copy Markdown

Live Apache ECharts widget for Livebook.

Work in progress

This module is functional but not yet fully polished. The API and behaviour may change in future releases.

Wraps Apache ECharts via Kino.JS.Live. ECharts options are passed as Elixir maps and serialised to JSON; the JavaScript side calls setOption on every update. The goal is a lower-overhead alternative to VegaLite for high-frequency streaming data — ECharts handles incremental series updates without rebuilding the entire chart.

Static usage

options = %{
  "xAxis" => %{"type" => "category", "data" => ["EUR/USD", "USD/JPY"]},
  "yAxis" => %{"type" => "value"},
  "series" => [%{"name" => "lp1", "type" => "bar", "data" => [1.05, 1.08]}]
}

chart = ExeQute.EChart.new(options: options)

Live usage

chart = ExeQute.EChart.new()
ExeQute.EChart.render(chart, initial_options)
ExeQute.EChart.push(chart, updated_options)

Chart cell helpers

update_buffer/3, options_from_buffer/2, and buffer_to_rows/2 are used by the generated code of ExeQute.ChartCell but are public so they can be called directly when building custom subscription callbacks.

Summary

Functions

buffer_to_rows(arg, cfg)

Converts a buffer to a flat list of row maps for Kino.DataTable.

new(opts \\ [])

Creates a new EChart widget.

options_from_buffer(cfg, arg)

Builds a full ECharts option map from the current buffer and config.

push(widget, options)

Pushes an incremental update.

render(widget, options)

Replaces the chart entirely with options.

update_buffer(arg, new_rows, cfg)

Updates the internal row buffer with newly arrived rows.

Functions

buffer_to_rows(arg, cfg)

@spec buffer_to_rows(
  {list(), map()},
  map()
) :: [map()]

Converts a buffer to a flat list of row maps for Kino.DataTable.

new(opts \\ [])

@spec new(keyword()) :: Kino.JS.Live.t()

Creates a new EChart widget.

Options

  • :options - initial ECharts option map (default: %{})
  • :height - chart height in pixels (default: 400)

options_from_buffer(cfg, arg)

@spec options_from_buffer(
  map(),
  {list(), map()}
) :: map()

Builds a full ECharts option map from the current buffer and config.

push(widget, options)

@spec push(Kino.JS.Live.t(), map()) :: :ok

Pushes an incremental update.

Calls setOption(options, { replaceMerge: ['series'] }) — series are replaced by the new list while axes, legend, and tooltip are preserved. Suitable for streaming data updates.

render(widget, options)

@spec render(Kino.JS.Live.t(), map()) :: :ok

Replaces the chart entirely with options.

Calls setOption(options, { notMerge: true }) — all existing components are discarded. Use this for structural changes (switching chart type, etc.).

update_buffer(arg, new_rows, cfg)

@spec update_buffer({list(), map()}, [map()], map()) :: {list(), map()}

Updates the internal row buffer with newly arrived rows.

cfg is the config map read from ETS (atom keys). Returns the updated buffer. The buffer format is {list, map}:

  • list — newest-first list of rows, used for temporal/quantitative x axes
  • map — keyed by x_value or {x_value, color_value}, used for nominal axes