Refactor comma lists to plots and splots

Author: devstopfix

README.md

@@ -52,17 +52,17 @@ The command string sent (`_cmd` above) can be manually inspected should the char
 Write two datasets to a PNG file:
 
 ```elixir
-alias Gnuplot, as: G
+import Gnuplot
 
-{:ok, _cmd} = G.plot([
-  [:set, :term, :png],
+{:ok, _cmd} = plot([
+  [:set, :term, :pngcairo],
   [:set, :output, "/tmp/rand.png"]
   [:set, :title, "rand uniform vs normal"],
   [:set, :key, :left, :top],
-  [:plot,
-    G.list(
+  plots([
       ["-", :title, "uniform", :with, :points],
-      ["-", :title, "normal", :with, :points])]
+      ["-", :title, "normal", :with, :points]
+      ])
   ],
   [
         for(n <- 0..100, do: [n, n * :rand.uniform()]),
@@ -72,7 +72,9 @@ alias Gnuplot, as: G
 
 ![uniform-vs-rand](docs/rand.PNG)
 
-NB When we are plotting multiple datasets in the same plot we need a comma separated list for the `plot` command which is made here with `G.list([ [...], [...], ... ])`
+When we are plotting multiple datasets in the same chart we need a comma separated list for the `plot` command which is made with the `plots`, `splots` or `list` function.
+
+NB the `:png` terminal can also be used but it produces [rougher output](http://www.gnuplotting.org/output-terminals/).
 
 
 ### Plot functions without datasets
@@ -95,6 +97,18 @@ NB [ranges](https://hexdocs.pm/elixir/Range.html) can be used
 
 ![rand](docs/atan_sin.PNG)
 
+### Multiplot
+
+The `multiplot` mode places serveral plots on the same page:
+
+```elixir
+Gnuplot.plot([
+  [:set, :multiplot, :layout, '2,1'], 
+  [:plot, 'sin(x)/x'], 
+  [:plot, 'cos(x)']
+  ])
+```
+
 ## Installation
 
 This library is [available in Hex](https://hex.pm/packages/gnuplot), the package can be installed
@@ -103,7 +117,7 @@ by adding `gnuplot` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:gnuplot, "~> 1.19.88"}
+    {:gnuplot, "~> 1.19.95"}
   ]
 end
 ```
@@ -140,8 +154,9 @@ clojure_gui = [1.487, 1.397, 1.400, 1.381, 1.440, 5.784, 49.275]
 elixir_gui  = [0.005, 0.010, 0.004, 0.059, 0.939, 5.801, 43.464]
 elixir_png  = [0.002, 0.010, 0.049, 0.040, 0.349, 4.091, 41.521]
 ubuntu_t2m  = [0.004, 0.002, 0.001, 0.008, 0.211, 1.873, 19.916]
-ubuntu_stream = [0.002, 0.001, 0.001, 0.009, 0.204, 1.279, 12.858]
-datasets = for ds <- [clojure_gui, elixir_gui, elixir_png, ubuntu_t2m, ubuntu_stream], do: Enum.zip (points, ds)
+ubuntu_strm = [0.002, 0.001, 0.001, 0.009, 0.204, 1.279, 12.858]
+datasets = for ds <- [clojure_gui, elixir_gui, elixir_png, ubuntu_t2m, ubuntu_strm], do: 
+  Enum.zip(points, ds)
 
 Gnuplot.plot([
   [:set, :title, "Time to render scatter plots"],
@@ -155,14 +170,15 @@ Gnuplot.plot([
   ~w(set style line 3 lw 2 lc '#5E2750')a,
   ~w(set style line 4 lw 2 lc '#E95420')a,
   ~w(set style line 5 lw 4 lc '#77216F')a,
-  [:plot, Gnuplot.list(
+  Gnuplot.plots([
     ["-", :title, "Clojure GUI", :with, :lines, :ls, 1],
     ["-", :title, "Elixir GUI", :with, :lines, :ls, 2],
     ["-", :title, "Elixir PNG", :with, :lines, :ls, 3],
     ["-", :title, "Elixir t2.m", :with, :lines, :ls, 4],
     ["-", :title, "Elixir Stream", :with, :lines, :ls, 5]
-  )]], datasets
-])
+  ])], 
+  datasets
+)
 ```
 
 ## Credits and licence

examples/perf.exs

@@ -1,5 +1,5 @@
 defmodule Perf do
-  alias Gnuplot, as: G
+  import Gnuplot
 
   @moduledoc false
 
@@ -24,16 +24,13 @@ defmodule Perf do
       ~w(set style line 3 lw 2 lc '#5E2750')a,
       ~w(set style line 4 lw 2 lc '#E95420')a,
       ~w(set style line 5 lw 4 lc '#77216F')a,
-      [
-        :plot,
-        G.list(
-          ["-", :title, "Clojure GUI", :with, :lines, :ls, 1],
-          ["-", :title, "Elixir GUI", :with, :lines, :ls, 2],
-          ["-", :title, "Elixir PNG", :with, :lines, :ls, 3],
-          ["-", :title, "Elixir t2.m", :with, :lines, :ls, 4],
-          ["-", :title, "Elixir Stream", :with, :lines, :ls, 5]
-        )
-      ]
+      plots([
+        ["-", :title, "Clojure GUI", :with, :lines, :ls, 1],
+        ["-", :title, "Elixir GUI", :with, :lines, :ls, 2],
+        ["-", :title, "Elixir PNG", :with, :lines, :ls, 3],
+        ["-", :title, "Elixir t2.m", :with, :lines, :ls, 4],
+        ["-", :title, "Elixir Stream", :with, :lines, :ls, 5]
+      ])
     ]
 
   def data do
@@ -48,8 +45,8 @@ defmodule Perf do
         do: Enum.zip(points, ds)
   end
 
-  def plot, do: G.plot(target() ++ commands(), data())
+  def draw, do: plot(target() ++ commands(), data())
 end
 
 # mix run examples/perf.exs
-Perf.plot()
+{:ok, _} = Perf.draw()

examples/rand.exs

@@ -1,5 +1,5 @@
 defmodule Rand do
-  alias Gnuplot, as: G
+  import Gnuplot
 
   @moduledoc false
 
@@ -16,13 +16,10 @@ defmodule Rand do
       ~w(set key left top)a,
       ~w(set style line 1 lc rgb '#77216F' pt 13)a,
       ~w(set style line 2 lc rgb '#599B2B' pt 2)a,
-      [
-        :plot,
-        G.list(
-          ["-", :title, "uniform", :with, :points, :ls, 1],
-          ["-", :title, "normal", :with, :points, :ls, 2]
-        )
-      ]
+      plots([
+        ["-", :title, "uniform", :with, :points, :ls, 1],
+        ["-", :title, "normal", :with, :points, :ls, 2]
+      ])
     ]
 
   def data,
@@ -31,8 +28,8 @@ defmodule Rand do
       for(n <- 0..99, do: [n, n * :rand.normal()])
     ]
 
-  def plot, do: G.plot(target() ++ commands(), data())
+  def draw, do: plot(target() ++ commands(), data())
 end
 
 # mix run examples/rand.exs
-Rand.plot()
+{:ok, _} = Rand.draw()

lib/gnuplot.ex

@@ -66,6 +66,53 @@ defmodule Gnuplot do
       |> Stream.run()
   end
 
+  @doc """
+  Builds a comma separated list of plot commands that are overlayed in a single plot.
+
+  Only useful inside `plot/1`:
+
+      import Gnuplot
+
+      plot([
+        [:set, :title, "Sine vs Cosine"],
+        plots([
+          ['sin(x)'],
+          ['cos(x)']
+        ])
+      ])
+
+  is equivalent to:
+
+      set title "Sine vs Cosine"
+      plot sin(x),cos(x)
+
+  """
+  @spec plots(list(command())) :: list()
+  def plots(commands) do
+    [:plot, list(commands)]
+  end
+
+  @doc """
+  Build a comma separated list of two or more overlayed 3D plots (as 2D projections).
+
+  Only useful inside `plot/1`:
+
+      import Gnuplot
+
+      plot([
+        [:set, :grid],
+        splots([
+          ['x**2+y**2'],
+          ['x**2-y**2']
+        ])
+      ])
+
+  """
+  @spec splots(list(command())) :: list()
+  def splots(commands) do
+    [:splot, list(commands)]
+  end
+
   @doc "Build a comma separated list from a list of terms."
   def list(xs) when is_list(xs), do: %Commands.List{xs: xs}
 

lib/gnuplot/dataset.ex

@@ -1,7 +1,7 @@
 defmodule Gnuplot.Dataset do
   @moduledoc false
 
-  @type point :: list(number()) | tuple()
+  @type point :: list(number() | String.t()) | tuple()
   @type t :: list(point())
 
   @gnuplot_end_row "\n"
@@ -37,6 +37,7 @@ defmodule Gnuplot.Dataset do
 
   defp to_str(f) when is_float(f), do: Float.to_string(f)
   defp to_str(i) when is_integer(i), do: Integer.to_string(i)
+
   defp to_str(s) when is_binary(s) do
     if contains_space?(s) do
       "\"" <> s <> "\""

mix.exs

@@ -4,7 +4,7 @@ defmodule Gnuplot.MixProject do
   def project do
     [
       app: :gnuplot,
-      version: "1.19.88",
+      version: "1.19.95",
       elixir: "~> 1.6",
       start_permanent: Mix.env() == :prod,
       description: "Interface between Elixir and Gnuplot graphing library",

test/gnuplot_test.exs

@@ -77,17 +77,45 @@ defmodule GnuplotTest do
     plot = [
       [:set, :xrange, -3..3],
       [:set, :yrange, -3..3],
-      [:splot, 'sin(x) * cos(y)']
+      G.splots([['x**2+y**2'], ['x**2-y**2']])
     ]
 
-    expected = "set xrange [-3:3];\nset yrange [-3:3];\nsplot sin(x) * cos(y)"
+    expected = "set xrange [-3:3];\nset yrange [-3:3];\nsplot x**2+y**2,x**2-y**2"
     assert {:ok, expected} == G.plot(plot)
   end
 
   test "Strings with spaces in datasets" do
     input = [[0, "label", 100], [1, "label2", 450], [2, "bar label", 75]]
     expected = ["0 label 100", "\n", "1 label2 450", "\n", "2 \"bar label\" 75", "\ne\n"]
+
     assert expected ==
              [input] |> D.format_datasets() |> Enum.to_list()
   end
+
+  test "Multiplot with two plot(s)" do
+    input = [[:set, :multiplot, :layout, '2,1'], [:plot, 'sin(x)'], [:plot, 'cos(x)']]
+    expected = "set multiplot layout 2,1;\nplot sin(x);\nplot cos(x)"
+
+    assert expected == C.format(input)
+  end
+
+  test "Multiplot with plots" do
+    input = [[:set, :multiplot, :layout, '2,1'], G.plots([['sin(x)'], ['cos(x)']])]
+    expected = "set multiplot layout 2,1;\nplot sin(x),cos(x)"
+
+    assert expected == C.format(input)
+  end
+
+  test "Multiplot with list" do
+    input = [[:set, :multiplot, :layout, '2,1'], [:plot, G.list([['sin(x)'], ['cos(x)']])]]
+    expected = "set multiplot layout 2,1;\nplot sin(x),cos(x)"
+
+    assert expected == C.format(input)
+  end
+
+  test "Splots" do
+    input = G.splots([['x**2+y**2'], ['x**2-y**2']])
+    expected = "splot x**2+y**2,x**2-y**2"
+    assert expected == C.format([input])
+  end
 end