package prbnmcn-gnuplot

prbnmcn-gnuplot: a self-contained interface to Gnuplot.

Introduction

We give an introduction to the library by giving some examples. These examples can be run by performing

> dune exec ./test/example.exe

in the root of the library.

Let's assume throughout we've access to some sampler for the standard normal distribution:

val normal : Random.State.t -> float

Data: 1d, 2d, 3d

The library encapsulates 1d, 2d and 3d data points using the types Plot.r1, Plot.r2 and Plot.r3. Similarly named functions allow to inject floating-point values into these types.

As an example, we can write samplers for 2d and 3d normal variates with specified means:

(** [st] is the random state *)
let normal2 (mu_x, mu_y)
  st = Plot.r2 (normal st +. mu_x) (normal st +. mu_y)

Scatter plot example

Let's plot some clouds of points using normal2. For 2d scatter plots, we use Plot.Scatter.points_2d. We need to feed this function with a value of type r2 Plot.Data.t. For instance, the following function specifies a 2d scatter plot with 100 random normally distributed points with mean mu.

let scatter ~mu st =
  Plot.Scatter.points_2d
    ~points:(Plot.Data.of_array (Array.init 100 (fun _ -> normal2 mu st)))
    ()

Let's produce a plot with two clouds around (3, 2) and (10, 8) and display it using the Plot.plot2 function.

let st = Random.State.make_self_init ()

let scatter2d_example =
  Plot.plot2
    ~xaxis:"x"
    ~yaxis:"y"
    ~title:"Clouds"
    [scatter ~mu:(3., 2.) st; scatter ~mu:(10., 8.) st]

Finally, we can produce the plot and save it, say to a .png file.

let () =
  let target = Plot.png ~pixel_size:(1024, 1024) ~png_file:"scatter.png" () in
  Plot.(run ~plot:scatter2d_example ~target exec)

3d plots work similarly, using the Plot.Scatter.points_3d function.

Line plot example

The library also handles line plots, through the functions exposed in Plot.Line. The API works similarly. Functions must be discretized before being plotted: for the sake of the example, let's introduce the following function.

let discretize f =
  Array.init 100 (fun i ->
      let x = float_of_int i *. 0.1 in
      let y = f x in
      Plot.r2 x y)

We prepare a fancy plot for the discretized sine function as follows.

let sine_with_points =
  let open Plot in
  Line.line_2d
    ~points:(Data.of_array (discretize sin))
    ~style:
      Style.(default |> set_color Color.red |> set_point ~ptyp:Pointtype.box)
    ~with_points:true
    ()

We display it similarly as in the scatter plot case.

let line2d_example =
  Plot.plot2 ~xaxis:"x" ~yaxis:"y" ~title:"Lines" [sine_with_points]

let () =
  let target = Plot.png ~pixel_size:(1024, 1024) ~png_file:"lines.png" () in
  Plot.(run ~plot:line2d_example ~target exec)

Histogram example

Finally, the library allows to prepare histograms.

let gaussian =
  let open Plot in
  Histogram.hist
    ~points:(Data.of_array (Array.init 100 (fun _ -> r1 @@ normal st)))
    ()

let histogram_example =
  Plot.plot2 ~xaxis:"x" ~yaxis:"freq" ~title:"Histogram" [gaussian]

let () =
  let target = Plot.png ~pixel_size:(1024, 1024) ~png_file:"histogram.png" () in
  Plot.(run ~plot:histogram_example ~target exec)

The binning is performed automatically by Gnuplot: currently, the API does not provide any functionality for manually specifed box plots.

API

Raw data

Colors, styles, etc

Datasets

Plot specifications

Scatter plots

Line plots

Histograms

Plot rendering

run ~plot ~target:(qt ()) exec