Module `Hugin`Source

hugin: Functional Plotting and Visualization Library for OCaml

Provides composable artists, axes, figures, and high-level plotting APIs for creating scientific and statistical graphics using Nx.

Sourcemodule Artist : sig ... end

Artist: Visual element constructors and style specifications.

Sourcemodule Axes : sig ... end

Module for axes-level operations (the plotting area).

Sourcemodule Figure : sig ... end

Module for figure-level operations (the top-level canvas).

Sourcemodule Plotting : sig ... end

Module containing functions to add standard plot types to an Axes.

Top-Level API

These functions create a Figure and Axes implicitly, plot the data, apply common optional decorations, and return the Figure.

Sourcetype figure = Figure.t

Type alias for Figure.t

Sourcetype axes = Axes.t

Type alias for Axes.t

Source

val plot : 
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?color:Artist.color ->
  ?linewidth:float ->
  ?linestyle:Artist.line_style ->
  ?marker:Artist.marker_style ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  figure

plot ?title ?xlabel ?ylabel ?color ?linewidth ?linestyle ?marker ?label x y

Create a new figure and plot y versus x.

Parameters

?title: title displayed atop the figure.
?xlabel: label for the x-axis.
?ylabel: label for the y-axis.
?color: line and marker color.
?linewidth: thickness of the line.
?linestyle: dash pattern of the line.
?marker: marker style at data points.
?label: legend entry for the plotted data.
x: 1D float32 nx of x coordinates.
y: 1D float32 nx of y coordinates.

Returns

a figure containing the created plot.

Examples

  let fig = plot x_arr y_arr in
  savefig fig "plot.png"

Source

val plot_y : 
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?color:Artist.color ->
  ?linewidth:float ->
  ?linestyle:Artist.line_style ->
  ?marker:Artist.marker_style ->
  ?label:string ->
  Nx.float32_t ->
  figure

plot_y ?title ?xlabel ?ylabel ?color ?linewidth ?linestyle ?marker ?label y

Create a new figure and plot the data y against indices 0..N-1.

Parameters

?title: figure title.
?xlabel: x-axis label.
?ylabel: y-axis label.
?color: line/marker color.
?linewidth: thickness of the line.
?linestyle: dash pattern of the line.
?marker: marker style at data points.
?label: legend entry for the series.
y: 1D float32 nx of y values.

Returns

a figure containing the plotted series.

Examples

  let fig = plot_y y_arr in
  savefig fig "plot_y.png"

Source

val plot3d : 
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?zlabel:string ->
  ?color:Artist.color ->
  ?linewidth:float ->
  ?linestyle:Artist.line_style ->
  ?marker:Artist.marker_style ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  Nx.float32_t ->
  figure

plot3d ?title ?xlabel ?ylabel ?zlabel ?color ?linewidth ?linestyle ?marker ?label x y z

Create a new figure, add 3D axes, and plot a 3D line through points.

Parameters

?title: figure title.
?xlabel, ?ylabel, ?zlabel: axis labels.
?color: line/marker color.
?linewidth: line width.
?linestyle: dash pattern.
?marker: marker style.
?label: legend entry.
x, y, z: 1D float32 nxs of coordinates.

Returns

a figure with the 3D line plotted.

Examples

  let fig = plot3d x_arr y_arr z_arr in
  savefig fig "plot3d.png"

Source

val scatter : 
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?s:float ->
  ?c:Artist.color ->
  ?marker:Artist.marker_style ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  figure

scatter ?title ?xlabel ?ylabel ?s ?c ?marker ?label x y

Create a new figure and scatter plot points (x,y).

Parameters

?title: figure title.
?xlabel: x-axis label.
?ylabel: y-axis label.
?s: marker size in points.
?c: marker color.
?marker: marker style.
?label: legend entry.
x, y: coordinate arrays.

Returns

a figure containing the scatter plot.

Raises

Invalid_argument if lengths of x and y differ.

Examples

  let fig = scatter x_arr y_arr in
  savefig fig "scatter.png"

Source

val hist : 
  ?bins:[ `Num of int | `Edges of float array ] ->
  ?range:(float * float) ->
  ?density:bool ->
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?color:Artist.color ->
  ?label:string ->
  Nx.float32_t ->
  figure

hist ?bins ?range ?density ?title ?xlabel ?ylabel ?color ?label x

Create a new figure and plot a histogram of the data in x.

Parameters

?bins: number of bins or explicit edges.
?range: (min, max) interval for data inclusion.
?density: if true, plot probability density instead of counts.
?title: figure title.
?xlabel: x-axis label.
?ylabel: y-axis label.
?color: bar fill color.
?label: legend entry.
x: 1D float32 nx of data values.

Returns

a figure containing the histogram plot.

Examples

  let fig = hist ~bins:(`Num 50) ~range:(0., 1.) ~density:true data in
  savefig fig "hist.png"

Source

val bar : 
  ?width:float ->
  ?bottom:float ->
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?color:Artist.color ->
  ?label:string ->
  height:Nx.float32_t ->
  Nx.float32_t ->
  figure

bar ?width ?bottom ?title ?xlabel ?ylabel ?color ?label ~height x

Create a new figure and render a bar chart.

Parameters

?width: width of each bar (default 0.8).
?bottom: baseline for bars (default 0.0).
?title: figure title.
?xlabel: label for x-axis.
?ylabel: label for y-axis.
?color: bar fill color.
?label: legend entry.
~height: 1D float32 nx of bar heights.
x: 1D float32 nx of bar positions.

Returns

a figure containing the bar chart.

Examples

  let fig = bar ~height:h_arr x_arr in
  savefig fig "bar.png"

Source

val imshow : 
  ?cmap:Artist.cmap ->
  ?aspect:string ->
  ?extent:(float * float * float * float) ->
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ('a, 'b) Nx.t ->
  figure

imshow ?cmap ?aspect ?extent ?title ?xlabel ?ylabel data

Create a new figure and display an image from a data array.

Parameters

?cmap: colormap for single-channel (2D) data.
?aspect: aspect ratio mode ("auto" or "equal").
?extent: bounding box (xmin, xmax, ymin, ymax).
?title: figure title.
?xlabel, ?ylabel: axis labels.
data: nx of shape |H;W|, |H;W;3|, or |H;W;4|.

Returns

a figure with the image displayed.

Raises

Invalid_argument if data rank or shape is unsupported.

Examples

  let fig = imshow img_arr in
  savefig fig "image.png"

Source

val step : 
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?color:Artist.color ->
  ?linewidth:float ->
  ?linestyle:Artist.line_style ->
  ?where:Artist.step_where ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  figure

step ?title ?xlabel ?ylabel ?color ?linewidth ?linestyle ?where ?label x y

Create a new figure and draw a step plot for data y vs x.

Parameters

?title: figure title.
?xlabel, ?ylabel: axis labels.
?color: line color.
?linewidth: line width.
?linestyle: dash pattern.
?where: step alignment relative to x.
?label: legend entry.
x, y: coordinate arrays.

Returns

a figure containing the step plot.

Raises

Invalid_argument on length mismatch.

Examples

  let fig = step x_arr y_arr ~where:Mid in
  savefig fig "step.png"

Source

val fill_between : 
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?color:Artist.color ->
  ?where:Nx.float32_t ->
  ?interpolate:bool ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  Nx.float32_t ->
  figure

fill_between ?title ?xlabel ?ylabel ?color ?where ?interpolate ?label x y1 y2

Create a new figure and shade the area between two curves.

Parameters

?title: figure title.
?xlabel, ?ylabel: axis labels.
?color: fill color.
?where: mask array selecting regions to fill.
?interpolate: interpolate across missing regions.
?label: legend entry.
x: x-coordinate array.
y1, y2: arrays defining lower and upper curves.

Returns

a figure containing the shaded region.

Raises

Invalid_argument on length mismatch.

Examples

  let fig = fill_between x_arr y_lo y_hi in
  savefig fig "area.png"

Source

val errorbar : 
  ?title:string ->
  ?xlabel:string ->
  ?ylabel:string ->
  ?yerr:Nx.float32_t ->
  ?xerr:Nx.float32_t ->
  ?ecolor:Artist.color ->
  ?elinewidth:float ->
  ?capsize:float ->
  ?fmt:Artist.plot_style ->
  ?label:string ->
  Nx.float32_t ->
  Nx.float32_t ->
  figure

errorbar ?title ?xlabel ?ylabel ?yerr ?xerr ?ecolor ?elinewidth ?capsize ?fmt ?label x y

Create a new figure and plot data with error bars.

Parameters

?title: figure title.
?xlabel, ?ylabel: axis labels.
?yerr: array of y-error values.
?xerr: array of x-error values.
?ecolor: error bar color.
?elinewidth: error bar line width.
?capsize: cap size in points.
?fmt: plot style for central points/line.
?label: legend entry.
x, y: data coordinate arrays.

Returns

a figure containing the error bar plot.

Raises

Invalid_argument if array lengths mismatch.

Examples

  let fig = errorbar x_arr y_arr ~yerr:y_err in
  savefig fig "errorbar.png"

Source

val matshow : 
  ?cmap:Artist.cmap ->
  ?aspect:string ->
  ?extent:(float * float * float * float) ->
  ?origin:[ `upper | `lower ] ->
  ?title:string ->
  ('a, 'b) Nx.t ->
  figure

matshow ?cmap ?aspect ?extent ?origin ?title data

Create a new figure and display a 2D matrix with cell coloring.

Parameters

?cmap: colormap for mapping values.
?aspect: aspect ratio mode.
?extent: (xmin,xmax,ymin,ymax) plot bounds.
?origin: `upper or `lower y-axis origin placement.
?title: figure title.
data: 2D nx of numeric values.

Returns

a figure containing the matrix image.

Examples

  let fig = matshow matrix in
  savefig fig "matrix.png"

Core Figure/Axes Management

Sourceval figure : ?width:int -> ?height:int -> unit -> figure

figure ?width ?height ()

Create a new figure canvas with optional size.

Parameters

?width: width in pixels (default 800).
?height: height in pixels (default 600).
(): unit argument.

Returns

a new figure.

Examples

  let fig = figure ~width:1024 ~height:768 () in
  ...

Source

val subplot : 
  ?nrows:int ->
  ?ncols:int ->
  ?index:int ->
  ?projection:Axes.projection ->
  figure ->
  axes

subplot ?nrows ?ncols ?index ?projection fig

Add a subplot in a grid layout to the figure.

Parameters

?nrows: number of rows (default 1).
?ncols: number of columns (default 1).
?index: subplot index (1-based, default 1).
?projection: TwoD or ThreeD axes type.
fig: parent figure.

Returns

created axes.

Examples

  let ax = subplot ~nrows:2 ~ncols:2 ~index:3 fig in
  ...

Source

val add_axes : 
  left:float ->
  bottom:float ->
  width:float ->
  height:float ->
  ?projection:Axes.projection ->
  figure ->
  axes

add_axes ~left ~bottom ~width ~height ?projection fig

Add custom-positioned axes to the figure.

Parameters

~left: left margin (fraction of figure width).
~bottom: bottom margin (fraction of figure height).
~width, ~height: size of axes (fractions).
?projection: TwoD or ThreeD.
fig: parent figure.

Returns

created axes.

Examples

  let ax = add_axes ~left:0.1 ~bottom:0.1 ~width:0.8 ~height:0.8 fig in
  ...

Display and Saving

Sourceval show : figure -> unit

show figure

Render and display the figure in an interactive window.

Parameters

figure: the figure to display.

Notes

Blocks execution until the window is closed.

Examples

  let fig = plot x_arr y_arr in
  show fig

Sourceval savefig : ?dpi:int -> ?format:string -> string -> figure -> unit

savefig ?dpi ?format filename fig

Save the figure to a file.

Parameters

?dpi: resolution in dots per inch (default 100).
?format: output format (e.g., "png", "pdf"); inferred from extension by default.
filename: destination file path.
fig: figure to save.

Notes

Only PNG format is supported in the current implementation.

Examples

  let fig = plot x_arr y_arr in
  savefig ~dpi:300 "highres.png" fig

Sourceval render : ?format:string -> figure -> string

render ?format fig

Render to an in-memory buffer and return the image data as a string.

Parameters

?format: output format (default "png").
fig: figure to save.

Returns

A string containing the image data in the specified format.

Notes

Only PNG format is supported in the current implementation.

Examples

  let fig = plot x_arr y_arr in
  let png_data = save_to_buffer fig in
  (* Use png_data, e.g., for network transmission or further processing *)

package hugin

Module HuginSource

Top-Level API

Core Figure/Axes Management

Display and Saving

Module `Hugin`Source