Module Matrix_chartsSource

Terminal charts rendered to a Grid.t.

Matrix_charts renders line, scatter, bar, heatmap, candlestick, and other chart types into a terminal grid. Charts are immutable specifications built from composable Mark.t values, then compiled into a Layout.t for drawing and interaction.

The typical workflow is:

  1. Build an immutable t by layering marks (lines, bars, scatter, etc.).
  2. Keep viewport state in a separate View.t (zoom and pan belong in your model, not the chart).
  3. Call draw which compiles a Layout.t and renders to a Grid.t.
  4. Use Layout + Hit + Overlay for hover tooltips, crosshairs, snapping, and zoom-to-cursor.

Coordinate systems

Cell coordinates (px, py) are integer terminal-cell positions. (0, 0) is the top-left corner of the grid.

Data coordinates (x, y) are floating-point values in the data domain. Convert between systems with Layout.data_of_px and Layout.px_of_data.

Some marks support sub-cell resolution (e.g. `Braille2x4 renders 2×4 dots per cell). Sub-cell rendering is purely visual; all coordinates in the API remain in cell units.

Charset

Sourcemodule Charset : sig ... end

Character sets for chart rendering.

Theme

Sourcemodule Theme : sig ... end

Colour and style themes for charts.

Label formatting

Sourcemodule Label_format : sig ... end

Axis label formatters.

Transform

Sourcemodule Transform : sig ... end

Data smoothing and transformation.

Scale

Sourcemodule Scale : sig ... end

Axis scaling strategies.

Axis

Sourcemodule Axis : sig ... end

Axis rendering configuration.

Gridlines

Sourcemodule Gridlines : sig ... end

Background gridline configuration.

View

Sourcemodule View : sig ... end

Viewport windowing for zoom and pan.

Raster

Sourcemodule Raster : sig ... end

Sub-cell resolution modes.

Mark

Sourcemodule Mark : sig ... end

Chart marks (visual encodings of data).

Hit testing

Sourcemodule Hit : sig ... end

Hit-testing results for interactive charts.

Layout

Sourcemodule Layout : sig ... end

Compiled chart layout for coordinate mapping, hit-testing, and interaction.

Overlay

Sourcemodule Overlay : sig ... end

Interactive overlays drawn on top of the chart.

Legend

Sourcemodule Legend : sig ... end

Chart legend rendering.

Sparkline

Sourcemodule Sparkline : sig ... end

Compact sparkline charts. See Sparkline.

Chart specification

Sourcetype t

The type for immutable chart specifications. Build with empty or make, configure with with_* functions, add marks with add, then render with draw.

Sourcetype frame_config = {
  1. margins : int * int * int * int;
  2. inner_padding : int;
}

The type for manual frame configurations. margins is (top, right, bottom, left) in cells.

Sourcetype frame =
  1. | Auto
    (*

    Compute margins from axis/label sizes.

    *)
  2. | Manual of frame_config
    (*

    Explicit margins and padding.

    *)

The type for frame modes.

Sourcetype title = {
  1. text : string;
  2. style : Ansi.Style.t option;
}

The type for chart titles.

Sourceval default_frame : frame

default_frame is Auto.

Sourceval manual_frame : ?margins:(int * int * int * int) -> ?inner_padding:int -> unit -> frame

manual_frame () is a Manual frame. margins defaults to (0, 0, 0, 0). inner_padding defaults to 0, clamped to >= 0.

Constructors

Sourceval empty : ?theme:Theme.t -> unit -> t

empty () is an empty chart with no marks. Gridlines are hidden by default; use with_grid to enable them. theme defaults to Theme.default.

Sourceval make : ?theme:Theme.t -> ?title:string -> Mark.t list -> t

make marks is a chart from marks. Marks render in list order (first mark is drawn first, last is on top). theme defaults to Theme.default.

Configuration

Sourceval with_theme : Theme.t -> t -> t

with_theme theme t is t with the given theme. Axis and gridline styles are updated to inherit from the new theme.

Sourceval with_frame : frame -> t -> t

with_frame frame t is t with the given frame mode.

Sourceval with_title : ?style:Ansi.Style.t -> string -> t -> t

with_title text t is t with chart title text.

Sourceval with_x_scale : Scale.t -> t -> t

with_x_scale scale t is t with x-axis scale scale.

Sourceval with_y_scale : Scale.t -> t -> t

with_y_scale scale t is t with primary y-axis scale scale.

Sourceval with_y2_scale : Scale.t -> t -> t

with_y2_scale scale t enables and sets the secondary y-axis scale.

Sourceval with_axes : ?x:Axis.t -> ?y:Axis.t -> t -> t

with_axes t configures the primary axes. Only provided axes are replaced; omitted axes keep their current configuration.

Sourceval with_y2_axis : Axis.t -> t -> t

with_y2_axis axis t enables and configures the secondary y-axis.

Sourceval with_grid : Gridlines.t -> t -> t

with_grid g t is t with background gridlines g.

Sourceval add : Mark.t -> t -> t

add mark t appends mark to the chart. Marks render in add order (later marks draw on top).

Mark convenience wrappers

Shorthand for add (Mark.xxx ...) t, enabling pipeline-style chart construction.

Sourceval line : ?id:Mark.id -> ?label:string -> ?style:Ansi.Style.t -> ?resolution:Raster.resolution -> ?pattern:Charset.line_pattern -> ?glyph:string -> ?y_axis:Mark.y_axis_selector -> x:('a -> float) -> y:('a -> float) -> 'a array -> t -> t

line ~x ~y data t is add (Mark.line ~x ~y data) t. See Mark.line.

Sourceval line_gaps : ?id:Mark.id -> ?label:string -> ?style:Ansi.Style.t -> ?resolution:Raster.resolution -> ?pattern:Charset.line_pattern -> ?glyph:string -> ?y_axis:Mark.y_axis_selector -> x:('a -> float) -> y:('a -> float option) -> 'a array -> t -> t

line_gaps ~x ~y data t is add (Mark.line_gaps ~x ~y data) t. See Mark.line_gaps.

Sourceval scatter : ?id:Mark.id -> ?label:string -> ?style:Ansi.Style.t -> ?glyph:string -> ?mode:Mark.scatter_mode -> ?y_axis:Mark.y_axis_selector -> x:('a -> float) -> y:('a -> float) -> 'a array -> t -> t

scatter ~x ~y data t is add (Mark.scatter ~x ~y data) t. See Mark.scatter.

Sourceval bar : ?id:Mark.id -> ?label:string -> ?style:Ansi.Style.t -> ?direction:Mark.direction -> ?mode:Mark.bar_mode -> category:('a -> string) -> value:('a -> float) -> 'a array -> t -> t

bar ~category ~value data t is add (Mark.bar ~category ~value data) t. See Mark.bar.

Sourceval stacked_bar : ?id:Mark.id -> ?direction:Mark.direction -> ?gap:int -> ?size:int -> ?mode:Mark.bar_mode -> Mark.stacked_bar array -> t -> t

stacked_bar data t is add (Mark.stacked_bar data) t. See Mark.stacked_bar.

Sourceval rule : ?id:Mark.id -> ?style:Ansi.Style.t -> ?direction:Mark.direction -> ?pattern:Charset.line_pattern -> ?y_axis:Mark.y_axis_selector -> float -> t -> t

rule value t is add (Mark.rule value) t. See Mark.rule.

Sourceval heatmap : ?id:Mark.id -> ?color_scale:Ansi.Color.t array -> ?value_range:(float * float) -> ?auto_value_range:bool -> ?agg:Mark.heatmap_agg -> ?mode:Mark.heatmap_mode -> x:('a -> float) -> y:('a -> float) -> value:('a -> float) -> 'a array -> t -> t

heatmap ~x ~y ~value data t is add (Mark.heatmap ~x ~y ~value data) t. See Mark.heatmap.

Sourceval candles : ?id:Mark.id -> ?bullish:Ansi.Style.t -> ?bearish:Ansi.Style.t -> ?width:Mark.candle_width -> ?body:Mark.candle_body -> ?y_axis:Mark.y_axis_selector -> Mark.ohlc array -> t -> t

candles data t is add (Mark.candles data) t. See Mark.candles.

Sourceval circle : ?id:Mark.id -> ?style:Ansi.Style.t -> ?resolution:Raster.resolution -> ?y_axis:Mark.y_axis_selector -> cx:('a -> float) -> cy:('a -> float) -> r:('a -> float) -> 'a array -> t -> t

circle ~cx ~cy ~r data t is add (Mark.circle ~cx ~cy ~r data) t. See Mark.circle.

Sourceval shade : ?id:Mark.id -> ?style:Ansi.Style.t -> min:float -> max:float -> t -> t

shade ~min ~max t is add (Mark.shade ~min ~max ()) t. See Mark.shade.

Sourceval column_bg : ?id:Mark.id -> ?style:Ansi.Style.t -> float -> t -> t

column_bg x t is add (Mark.column_bg x) t. See Mark.column_bg.

Sourceval area : ?id:Mark.id -> ?label:string -> ?style:Ansi.Style.t -> ?baseline:Mark.area_baseline -> ?resolution:Raster.resolution -> ?y_axis:Mark.y_axis_selector -> x:('a -> float) -> y:('a -> float) -> 'a array -> t -> t

area ~x ~y data t is add (Mark.area ~x ~y data) t. See Mark.area.

Sourceval fill_between : ?id:Mark.id -> ?label:string -> ?style:Ansi.Style.t -> ?resolution:Raster.resolution -> ?y_axis:Mark.y_axis_selector -> x:('a -> float) -> y_low:('a -> float) -> y_high:('a -> float) -> 'a array -> t -> t

fill_between ~x ~y_low ~y_high data t is add (Mark.fill_between ~x ~y_low ~y_high data) t. See Mark.fill_between.

Sourceval histogram : ?id:Mark.id -> ?label:string -> ?style:Ansi.Style.t -> ?bins:Mark.bin_method -> ?normalize:Mark.histogram_normalize -> x:('a -> float) -> 'a array -> t -> t

histogram ~x data t is add (Mark.histogram ~x data) t. See Mark.histogram.

Rendering

Sourceval layout : ?view:View.t -> ?x:int -> ?y:int -> t -> width:int -> height:int -> Layout.t

layout t ~width ~height compiles t into a Layout.t without rendering. Use this when you need layout information (coordinate mapping, hit-testing) without drawing.

  • view defaults to View.empty.
  • x and y are horizontal and vertical offsets. Default 0.
  • width and height are clamped to >= 1.
Sourceval draw : ?view:View.t -> ?x:int -> ?y:int -> t -> Grid.t -> width:int -> height:int -> Layout.t

draw t grid ~width ~height renders t to grid and returns the compiled layout.

Fills the chart region with the theme background, then draws gridlines, marks (in add order), axes, and title. The returned Layout.t can be used for hit-testing and overlay drawing.

  • view defaults to View.empty.
  • x and y are horizontal and vertical offsets. Default 0.
  • width and height are clamped to >= 1.