Module Matrix_charts.MarkSource

Chart marks (visual encodings of data).

Marks are the graphical primitives rendered on a chart: lines, scatter points, bars, heatmaps, etc. Each constructor extracts data eagerly via accessor functions (~x, ~y, etc.), so the source data can be garbage collected after mark creation.

Marks without an explicit ~style are auto-coloured from the theme palette in the order they are added to the chart.

Types

Sourcetype id = string

The type for mark identifiers. When set, Hit.t.mark_id carries this value.

Sourcetype t

The type for marks. Construct with the functions below, then pass to Matrix_charts.add or Matrix_charts.make.

Sourcetype direction = [
  1. | `Vertical
  2. | `Horizontal
]

The type for bar chart and rule directions.

  • `Vertical: bars grow upward; rules are horizontal.
  • `Horizontal: bars grow rightward; rules are vertical.
Sourcetype scatter_mode = [
  1. | `Cell
  2. | `Braille
  3. | `Density
]

The type for scatter point rendering modes.

  • `Cell: one glyph per point.
  • `Braille: sub-cell resolution using Braille patterns.
  • `Density: heatmap-style density shading for overlapping points.
Sourcetype heatmap_agg = [
  1. | `Last
  2. | `Avg
  3. | `Max
]

The type for heatmap cell aggregation.

Sourcetype heatmap_mode =
  1. | Cells_fg
    (*

    Foreground colour per cell.

    *)
  2. | Cells_bg
    (*

    Background colour per cell.

    *)
  3. | Halfblock_fg_bg
    (*

    Half-block characters for 2× vertical resolution.

    *)
  4. | Shaded
    (*

    Shade characters from Charset.t.shade_levels.

    *)
  5. | Dense_bilinear
    (*

    Bilinear interpolation for smooth gradients.

    *)

The type for heatmap rendering modes.

Sourcetype bar_mode = [
  1. | `Cell
  2. | `Half_block
]

The type for bar rendering granularity.

  • `Cell: one cell per unit.
  • `Half_block: half-block characters for sub-cell bar heights.
Sourcetype candle_body = [
  1. | `Filled
  2. | `Hollow
]

The type for candlestick body styles.

Sourcetype candle_width = [
  1. | `One
  2. | `Two
]

The type for candlestick widths in cells.

Sourcetype area_baseline = [
  1. | `Zero
  2. | `Value of float
]

The type for area chart baselines. `Zero fills down to y=0; `Value v fills down to y=v.

Sourcetype bin_method =
  1. | Bins of int
    (*

    n equal-width bins.

    *)
  2. | Width of float
    (*

    Bins of width w.

    *)
  3. | Edges of float array
    (*

    Explicit bin edges. At least 2 elements.

    *)

The type for histogram binning methods.

Sourcetype histogram_normalize = [
  1. | `Count
  2. | `Density
  3. | `Probability
]

The type for histogram normalisation.

  • `Count: raw frequency counts.
  • `Density: normalised so the integral equals 1.
  • `Probability: fraction of total observations per bin.
Sourcetype bar_segment = {
  1. value : float;
  2. style : Ansi.Style.t;
  3. label : string option;
}

The type for stacked bar segments.

Sourcetype stacked_bar = {
  1. category : string;
  2. segments : bar_segment list;
}

The type for stacked bar entries.

Sourcetype ohlc = {
  1. time : float;
    (*

    X-axis position (typically a timestamp).

    *)
  2. open_ : float;
  3. high : float;
  4. low : float;
  5. close : float;
}

The type for open-high-low-close data.

Sourcetype y_axis_selector = [
  1. | `Y1
  2. | `Y2
]

The type for y-axis selectors. `Y2 requires a secondary y-axis configured via Matrix_charts.with_y2_scale.

Constructors

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

line ~x ~y data is a line mark connecting consecutive data points in array order. NaN y-values are skipped.

  • resolution defaults to `Cell.
  • pattern defaults to `Solid.
  • glyph, when set, draws this glyph at each point instead of connecting lines.
  • y_axis defaults to `Y1.

See also line_gaps.

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

line_gaps ~x ~y data is like line except the line breaks where y returns None and resumes at the next Some value.

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

scatter ~x ~y data plots individual data points. glyph defaults to the charset's default point. mode defaults to `Cell.

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

bar ~category ~value data is a bar chart. Categories are placed on the band-scale axis; values determine bar length. Implicitly uses a Scale.t.Band on the category axis and includes zero in the value domain. direction defaults to `Vertical. mode defaults to `Half_block.

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

stacked_bar data is stacked bars from pre-segmented data. Segments stack from the baseline upward (or leftward for horizontal).

  • direction defaults to `Vertical.
  • gap is inter-bar spacing in cells. Defaults to 1. Clamped to >= 0.
  • size is explicit bar width in cells. None auto-sizes.
  • mode defaults to `Half_block.
Sourceval rule : ?id:id -> ?style:Ansi.Style.t -> ?direction:direction -> ?pattern:Charset.line_pattern -> ?y_axis:y_axis_selector -> float -> t

rule value is a reference line spanning the full plot area. direction defaults to `Horizontal (line at y=value). pattern defaults to `Solid.

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

heatmap ~x ~y ~value data is a heatmap mapping value to colours. Multiple points in the same cell are combined using agg.

  • color_scale is the colour gradient. Empty uses a default gradient.
  • value_range fixes the (min, max) for colour mapping. None infers from data.
  • auto_value_range defaults to true; computes the range from data when value_range is not set.
  • agg defaults to `Last.
  • mode defaults to Cells_fg.
Sourceval candles : ?id:id -> ?bullish:Ansi.Style.t -> ?bearish:Ansi.Style.t -> ?width:candle_width -> ?body:candle_body -> ?y_axis:y_axis_selector -> ohlc array -> t

candles data is a candlestick chart from OHLC data, sorted by ohlc.time internally. bullish (close >= open) defaults to green; bearish (close < open) defaults to red. width defaults to `One. body defaults to `Filled.

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

circle ~cx ~cy ~r data draws circles. Radius r is in data units.

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

shade ~min ~max () is a vertical shaded region between x=min and x=max. If min > max the values are swapped.

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

column_bg x is a full-height background highlight at data x-coordinate x.

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

area ~x ~y data is a filled area chart between the data line and baseline. baseline defaults to `Zero.

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

fill_between ~x ~y_low ~y_high data fills the region between two y-value curves.

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

histogram ~x data is a histogram from continuous data. Binning is computed eagerly at construction time. bins defaults to Bins 10. normalize defaults to `Count.