:- module(gnuplot).
:- export plot / 1.
:- export plot / 2.
:- export plot / 3.
:- export plot / 4.
:- comment(categories, ["Interfacing", "Visualisation"]).
:- comment(summary, "Interface to the function and data plotting program - gnuplot").
:- comment(author, "Andrew J Sadler, IC-Parc").
:- comment(date, "$Id: gnuplot.ecl,v 1.4 2009/07/17 15:51:33 kish_shen Exp $").
:- comment(desc, html("<P> This library provides an interface to the function and data\n plotting program - gnuplot.\n\n<P> The gnuplot program is available for most platforms and can be\n downloaded from <a href=\"http://www.gnuplot.info/\">http://www.gnuplot.info/</a>.\n This version of lib(gnuplot) officially supports gnuplot version 3.7\n and higher though it may work with earlier versions as well.\n\n<P> The executable <code>gnuplot</code> on Unices, and\n <code>pgnuplot.exe</code> on Windows must be installed on the default\n path, or be present in the current working directory. \n NOTE: On Windows it is NOT sufficient to simply have the\n <code>gnuplot.exe</code> or <code>wgnuplot.exe</code>, you must have the\n <code>pgnuplot.exe</code> as well.\n\n<P> See the various <code>plot</code> predicates for further example usage.\n\n<P> For a complete description of the avilable options we refer the\n user to the excellent documentation which accompanies gnuplot.  \n Most features have an obvious analogue in this library.\n \n<P> Syntax note: wherever gnuplot expects a string as an option value,\n use a double-quoted ECLiPSe string - unquoted or single-quoted atoms\n will not work!.\n ")).
:- comment(eg, "\n:-lib(gnuplot).\n\nsample:-\n        % x-y pairs with 'points'\n        A=[1-3,5-2,9-2,8-2,5-7], plot(A, [with:points]),\n\n        % y values with large 'smooth' lines and points\n        B=[1,2,3,4,8,9,4,2,4,6], plot(B, [smooth: csplines,\n                                          with:linespoints,\n                                          pointsize:3]),\n\n        % multiple y values in nested lists with lines, boxes and titles\n        C=[[1,2,4,9,18,27,3],[1,4,16,36,25,16,9]],\n        plot(C, [with:[lines, boxes], title:['data 1', 'data 2']]),\n\n        % multiple y values in an array, in a certain range, with impulses of\n        % different widths\n        D=[]([](1,2,4,6,7,8,9),[](1,4,16,36,49,64,81)),\n           plot(D, [ranges:(3:6), with:impulses, linewidth:[8,2]]),\n\n        % multiple t-r pairs, in polar coordinates with a grid and lines\n        E=[[1-3,5-2,9-2,8-2,5-7], [1-2,5-4,8-6,9-1,12-4]],\n           plot(E,[set:[polar, grid=polar], with:lines]),\n\n        \n        % compute sin and cos and tan points\n        (for(I, 0, 314),\n         foreach(R-X,SinPoints),\n         foreach(R-Y,CosPoints),\n         foreach(R-Z,TanPoints)\n        do\n            R is I / 100,\n            X is sin(R),\n            Y is cos(R),\n            Z is tan(R)\n        ),\n        % plot sin and cos on a polar plot\n        plot([SinPoints, CosPoints],\n             [set:[polar, grid=polar], with:linespoints,\n              title:[\"sin\", \"cos\"]]),\n\n        % plot sin, cos and tan on a logarithmic polar plot\n        plot([SinPoints, CosPoints, TanPoints],\n             [set:[polar, grid=polar,logscale=xy], with:linespoints,\n              title:[\"sin\", \"cos\", \"tan\"]]),\n        \n        % a(x,y,error) = x-y data with error values for the y values\n        F=[a(1,1,0.1),a(2,2,0.1),a(5,3,0.5),a(6,2,0.5), a(7,3,0.5)],\n        plot(F, [ranges:[ 0:8, 0:6], with:boxes]),\n        plot(F, [ranges:[ 0:8, 0:6], with:errorbars]),\n        plot(F, [ranges:[ 0:8, 0:6], with:boxerrorbars]),\n        \n        % a(x,y,error) = x-y data with error values for the y values\n        % and a gap between x=2 and x=5\n        G=[a(1,1,0.1),a(2,2,0.1),-,a(5,3,0.5),a(6,2,0.5), a(7,3,0.5)],\n        plot(G, [ranges:[ 0:8, 0:6], with:boxes]),\n        plot(G, [ranges:[ 0:8, 0:6], with:errorbars]),\n        plot(G, [ranges:[ 0:8, 0:6], with:boxerrorbars]).\n        \n").
:- comment(plot / 1, [summary : "Plot the given data using default options", amode : plot(++), args : ["Data" : "The data to be plotted, array or list."], desc : html("<P> Produces an on screen plot of the data given using the default\n settings.\n\n<P> Can either be a list or a nested list of a 1D or 2D array of y\n values or x-y points."), fail_if : "Data is not in a valid format", resat : false, eg : "\n% x-y pairs\n?- A=[1-3,5-2,9-2,8-2,5-7], plot(A).\n\n% y values\n?- A=[1,2,3,4,8,9,4,2,4,6], plot(A).\n\n% multiple y values in nested lists\n?- A=[[1,2,4,6,7,8,9],[1,4,16,36,49,64,81]], plot(A).            \n\n% multiple y values in an array\n?- A=[]([](1,2,4,6,7,8,9),[](1,4,16,36,49,64,81)), plot(A).\n\n% multiple x-y pairs\n?- A=[[1-3,5-2,9-2,8-2,5-7], [1-2,5-4,8-6,9-1,12-4]], plot(A).\n", see_also : [plot / 2, plot / 3, plot / 4]]).
:- comment(plot / 2, [summary : "Plots the given data using the given options", amode : plot(++, +), args : ["Data" : "The data to be plotted, array or list.", "Options" : "Options list"], desc : html("\n<P> Plots the given data to screen using the supplied options.\n\n<P> Can either be a list or a nested list of a 1D or 2D array of y\n values or x-y points.\n\n<P> The options correspond directly to the options of the gnuplot\n 'plot' command.\n\n<P> Syntax note: wherever gnuplot expects a string as an option value,\n use a double-quoted ECLiPSe string - unquoted or single-quoted atoms\n will not work!.\n"), fail_if : "Options are malformed, or data is not in a valid format.", resat : false, eg : "\n% x-y pairs with 'points'\n?- A=[1-3,5-2,9-2,8-2,5-7], plot(A, [with:points]).\n\n% y values with large 'smooth' lines and points\n?- A=[1,2,3,4,8,9,4,2,4,6], plot(A, [smooth: csplines,\n                                     with:linespoints,\n                                     pointsize:3]).\n\n% multiple y values in nested lists with lines, boxes and titles\n?- A=[[1,2,4,9,18,27,3],[1,4,16,36,25,16,9]],\n   plot(A, [with:[lines, boxes], title:['data 1', 'data 2']]).\n\n% multiple y values in an array, in a certain range, with impulses of\n% different widths\n?- A=[]([](1,2,4,6,7,8,9),[](1,4,16,36,49,64,81)),\n   plot(A, [ranges:(3:6), with:impulses, linewidth:[8,2]]).\n\n% multiple t-r pairs, in polar coordinates with a grid and lines\n?- A=[[1-3,5-2,9-2,8-2,5-7], [1-2,5-4,8-6,9-1,12-4]],\n   plot(A,[set:[polar, grid=polar], with:lines]).\n            ", see_also : [plot / 1, plot / 3, plot / 4]]).
:- comment(plot / 3, [summary : "Plots the given data to a file.", amode : plot(++, +, +), args : ["Data" : "The data to be plotted, array or list.", "Options" : "Options list", "OutputFile" : "Name of file to store plot in (atom or string)"], desc : html("\n<P> Plots the data to a file as Postscript (by default).\n\n<P> Can either be a list or a nested list of a 1D or 2D array of y\n values or x-y points.\n\n<P> The output format can be changed either by explicitly setting the\n 'terminal' variable using the 'set' option, or by calling plot/4.\n\n<P> Syntax note: wherever gnuplot expects a string as an option value,\n use a double-quoted ECLiPSe string - unquoted or single-quoted atoms\n will not work!.\n"), fail_if : "Options are malformed, or data is not in a valid format.", resat : false, eg : "\n% multiple t-r pairs, in polar coordinates with a grid and lines, into\n% a postscript file\n?- A=[[1-3,5-2,9-2,8-2,5-7], [1-2,5-4,8-6,9-1,12-4]],\n   plot(A,[set:[polar, grid=polar], with:lines], \"polar.ps\").\n", see_also : [plot / 1, plot / 2, plot / 4]]).
:- comment(plot / 4, [summary : "Plots the given data to a file in the given format.", amode : plot(++, +, +, +), args : ["Data" : "The data to be plotted, array or list.", "Options" : "Options list", "Format" : "Output file format (atom or string)", "OutputFile" : "Name fo file to store plot in (atom or string)"], desc : html("\n<P> Plots the data to a file in the specified format.\n\n<P> The Data can either be a list or a nested list of a 1D or 2D array\n of y values or x-y points.\n\n<P> The output format is defined as being the 'terminal' setting for\n gnuplot.\n\n<P> Syntax note: wherever gnuplot expects a string as an option value,\n use a double-quoted ECLiPSe string - unquoted or single-quoted atoms\n will not work!.\n"), fail_if : "Options are malformed, or data is not in a valid format.", resat : false, eg : "\n% multiple t-r pairs, in polar coordinates with a grid and lines, into\n% a postscript file\n?- A=[[1-3,5-2,9-2,8-2,5-7], [1-2,5-4,8-6,9-1,12-4]],\n   plot(A,[set:[polar, grid=polar], with:lines], postscript, \"polar.ps\").\n\n% multiple t-r pairs, in polar coordinates with a grid and lines, into\n% a postscript file with color\n?- A=[[1-3,5-2,9-2,8-2,5-7], [1-2,5-4,8-6,9-1,12-4]],\n   plot(A,[set:[polar, grid=polar], with:lines], \"postscript color\", \"polar.ps\").\n\n% multiple t-r pairs, in polar coordinates with a grid and lines, into\n% a PNG file\n?- A=[[1-3,5-2,9-2,8-2,5-7], [1-2,5-4,8-6,9-1,12-4]],\n   plot(A,[set:[polar, grid=polar], with:lines], png, \"polar.png\").\n\n% multiple t-r pairs, in polar coordinates with a grid and lines, into\n% a XFIG file\n?- A=[[1-3,5-2,9-2,8-2,5-7], [1-2,5-4,8-6,9-1,12-4]],\n   plot(A,[set:[polar, grid=polar], with:lines], fig, \"polar.fig\").\n", see_also : [plot / 1, plot / 2, plot / 3]]).
