Create a new live (reactive) Plotly chart widget.

Returns a Kino.JS.Live struct that renders immediately in Livebook. Use push/2 to update the chart data and subscribe/2 to receive browser events.

Examples

fig = Plotly.scatter(data, x: "date", y: "price", title: "Live Feed")
chart = Plotly.Kino.PlotlyLive.new(fig)

# Later, push an update without re-rendering the cell
new_fig = Plotly.scatter(updated_data, x: "date", y: "price")
Plotly.Kino.PlotlyLive.push(chart, new_fig)

Push a new figure to the live widget, updating the chart in place. Returns :ok.

Examples

chart = Plotly.Kino.PlotlyLive.new(initial_figure)

# In a loop or after receiving new data:
Enum.each(1..10, fn i ->
  updated = Plotly.scatter(data_at(i), x: "x", y: "y")
  Plotly.Kino.PlotlyLive.push(chart, updated)
  Process.sleep(500)
end)

Subscribe to Plotly browser events from the live chart.

All four arities send {tag, payload_map} messages when events fire.

Arities

• subscribe(kino, tag) — subscribe self() to all events, tagged tag
• subscribe(kino, tag, filter) — subscribe self() filtered to one event type
• subscribe(kino, pid, tag) — subscribe an explicit pid to all events
• subscribe(kino, pid, tag, filter) — subscribe explicit pid with filter

Filter atoms

• :click — user clicks a data point ("plotly_click")
• :hover — user hovers over a data point ("plotly_hover")
• :unhover — cursor leaves a hovered point or the plot ("plotly_unhover")
• :relayout — user zooms, pans, or resizes ("plotly_relayout")
• :selected — user box/lasso selects points ("plotly_selected")

Payload

Each message is {tag, payload_map} where payload["type"] is the event name and payload["data"] holds event-specific fields. For click/hover, payload["data"]["points"] is a list of maps with x, y, z, curveNumber, pointNumber, pointIndex, text, customdata, name, bbox, xPixel, and yPixel. Point pixels refer to the point centre; top-level data["xPixel"]/data["yPixel"] refer to the cursor. Top-level xvals/yvals contain axis data values (including date/category strings). Every listed field is present, with nil for missing upstream values. Anywhere events have an empty points list. Unhover and selection use the same point contract; relayout retains its original JSON shape.

Examples

chart = Plotly.Kino.PlotlyLive.new(fig)

# All events
Plotly.Kino.PlotlyLive.subscribe(chart, :chart_events)

# Only clicks
Plotly.Kino.PlotlyLive.subscribe(chart, :clicks, :click)

receive do
  {:clicks, %{"type" => "plotly_click", "data" => %{"points" => [pt | _]}}} ->
    IO.inspect(pt, label: "clicked point")
end

# Forward to another process
Plotly.Kino.PlotlyLive.subscribe(chart, handler_pid, :chart_events)