Class ui.TimeSeriesGraph

A time-series graph drawn on a Canvas using a CanvasViewport.

Mixes two coordinate layers: - A CanvasViewport (stretch) for the scaled data line. - Direct canvas pixel drawing for fixed-size decorations: Y-axis (x=0), tick marks (x=1), and an X-axis at the position of value 0.

The X-axis position adapts to the data range: - Range straddles zero (e.g. -50..50): axis drawn at the midpoint. - Entire range positive (e.g. 0..100): axis at the bottom. - Entire range negative (e.g. -100..-10): axis at the top.

min and max can be omitted to make the range dynamic: it expands automatically when a pushed value falls outside the current bounds, snapping the new boundary to the nearest nice number.

Methods

ui.timeseriesgraph:clear () Reset the sample history.
ui.timeseriesgraph:draw (canvas) Draw the graph onto an existing Canvas.
ui.timeseriesgraph:get_max () Return the current data-domain maximum.
ui.timeseriesgraph:get_min () Return the current data-domain minimum.
ui.timeseriesgraph:init (opts) Create a new TimeSeriesGraph.
ui.timeseriesgraph:push (value) Add a data sample.
ui.timeseriesgraph:render (opts) Convenience wrapper: create a Canvas, draw, and return the render string.


Methods

ui.timeseriesgraph:clear ()
Reset the sample history. Dynamic min/max bounds are also reset to their initial sentinel values.
ui.timeseriesgraph:draw (canvas)
Draw the graph onto an existing Canvas.

Parameters:

  • canvas Canvas already sized by the caller
ui.timeseriesgraph:get_max ()
Return the current data-domain maximum. For dynamic ranges this reflects the nicely-snapped upper bound after pushes.

Returns:

    number
ui.timeseriesgraph:get_min ()
Return the current data-domain minimum. For dynamic ranges this reflects the nicely-snapped lower bound after pushes.

Returns:

    number
ui.timeseriesgraph:init (opts)
Create a new TimeSeriesGraph. Do not call this method directly, call on the class instead.

Parameters:

  • opts
    • history number sliding window size (number of samples) (default 100)
    • min number data-domain minimum, maps to the bottom of the graph; when omitted the minimum expands dynamically as values are pushed (optional)
    • max number data-domain maximum, maps to the top of the graph; when omitted the maximum expands dynamically as values are pushed (optional)
    • ticks table explicit Y-axis tick values in data units; auto-generated from canvas height when omitted (optional)

Usage:

    local graph = TimeSeriesGraph({
  history = 100,
  min = 0,
  max = 100,
  ticks = { 25, 50, 75, 100 },  -- explicit tick values in data units
})
graph:push(42)
local output = graph:render({ cols = 60, rows = 15 })
ui.timeseriesgraph:push (value)
Add a data sample. Drops the oldest sample when the window is full. For dynamic min/max, expands the range to the next nice boundary when the value falls outside the current bounds.

Parameters:

  • value number
ui.timeseriesgraph:render (opts)
Convenience wrapper: create a Canvas, draw, and return the render string. When opts.fmt is given, min/max labels are drawn to the left of the graph; the canvas is narrowed automatically to keep the total width equal to opts.cols.

Parameters:

  • opts
    • cols number total width in display-columns (labels + graph)
    • rows number total height in display-rows
    • fmt string string.format pattern for the min/max labels (e.g. "%g" or "%d%%"); when given, labels are drawn to the left of the graph (optional)
    • graph_attr table text attributes for the graph area (e.g. { fg = "cyan" }) (optional)
    • label_attr table text attributes for the min/max labels (e.g. { fg = "white" }) (optional)

Returns:

    Sequence terminal escape sequence string ready for output.write

Usage:

    output.write(graph:render({
  cols = 60,
  rows = 15,
  fmt = "%d%%",
  graph_attr = { fg = "cyan" },
  label_attr = { fg = "white" },
}))
generated by LDoc 1.5.0