Module PlotSource

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