From ceee717e8a3f2306b97b80d348a56e1f4c7c4477 Mon Sep 17 00:00:00 2001 From: nicholas-leonard Date: Thu, 27 Aug 2015 21:56:26 -0400 Subject: readthedocs --- README.md | 402 ++------------------------------------------------- doc/common.md | 99 +++++++++++++ doc/custom.md | 94 ++++++++++++ doc/file.md | 56 +++++++ doc/index.md | 33 +++++ doc/plothistogram.md | 16 ++ doc/plotline.md | 55 +++++++ doc/plotmatrix.md | 20 +++ doc/plotsurface.md | 34 +++++ mkdocs.yml | 14 ++ 10 files changed, 432 insertions(+), 391 deletions(-) create mode 100644 doc/common.md create mode 100644 doc/custom.md create mode 100644 doc/file.md create mode 100644 doc/index.md create mode 100644 doc/plothistogram.md create mode 100644 doc/plotline.md create mode 100644 doc/plotmatrix.md create mode 100644 doc/plotsurface.md create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index 7e63e04..25f4c3c 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,22 @@ - + # Plotting Package Manual with Gnuplot # -A plotting package to visualize [Tensor](..:torch:index#Tensor) objects. +A plotting package to visualize [Tensor](https://github.com/torch/torch7/blob/master/doc/tensor.md#tensor) objects. Functions fall into several types of categories: - * [Line plotting](#gnuplot.line.dok) - * [Plotting 3D surfaces](#gnuplot.surface.dok) - * [Plotting matrices as images](#gnuplot.image.dok) - * [Plotting histogram of data](#gnuplot.histogram.dok) - * [Plotting directly into files](#gnuplot.files.dok) - * [Common operations to decorate plots](#gnuplot.commons.dok) + * [Plotting lines](doc/plotline.md#gnuplot.line.dok) + * [Plotting matrices](doc/plotmatrix.md#gnuplot.image.dok) + * [Plotting surfaces](doc/plotsurface.md#gnuplot.surface.dok) + * [Plotting histograms](doc/plothistogram.md#gnuplot.histogram.dok) + * [Saving to Files](doc/file.md#gnuplot.files.dok) + * [Common operations](doc/decorateplot.md#gnuplot.commons.dok) + The plotting package currently uses [gnuplot](http://gnuplot.info) as a backend to display data. In particular, `Gnuplot` version `4.4` or above is suggested for full support of all functionality. By default, the plot package will search for terminal in following order: + * ` windows ` terminal if operating system is windows * ` wxt `, ` qt `, ` x11 ` terminal if operating system is linux * ` aqua `, `wxt`, ` qt `, ` x11 ` terminal if operating system is mac @@ -27,387 +29,5 @@ rotating... The `Gnuplot` port uses `pipes` to communicate with `gnuplot`, therefore each plotting session is persistent and additional commands -can be sent. For advanced users [gnuplot.raw](#gnuplot.raw) +can be sent. For advanced users [gnuplot.raw](doc/common.md#gnuplot.raw) provides a free form interface to gnuplot. - - -## Customizing Gnuplot Defaults ## - -The default styles of gnuplot can be customized using a personal `.gnuplot` file -located in the users home directory. A sample file is given below as a sample. You can -paste the contents into `$HOME/.gnuplot` file and gnuplot will use the styles -specified in this file. - -``` -##### Modified version of the sample given in -##### http://www.guidolin.net/blog/files/2010/03/gnuplot - - -set macro - -##### Color Palette by Color Scheme Designer -##### Palette URL: http://colorschemedesigner.com/#3K40zsOsOK-K- - - - blue_000 = "#A9BDE6" # = rgb(169,189,230) - blue_025 = "#7297E6" # = rgb(114,151,230) - blue_050 = "#1D4599" # = rgb(29,69,153) - blue_075 = "#2F3F60" # = rgb(47,63,96) - blue_100 = "#031A49" # = rgb(3,26,73) - - green_000 = "#A6EBB5" # = rgb(166,235,181) - green_025 = "#67EB84" # = rgb(103,235,132) - green_050 = "#11AD34" # = rgb(17,173,52) - green_075 = "#2F6C3D" # = rgb(47,108,61) - green_100 = "#025214" # = rgb(2,82,20) - - red_000 = "#F9B7B0" # = rgb(249,183,176) - red_025 = "#F97A6D" # = rgb(249,122,109) - red_050 = "#E62B17" # = rgb(230,43,23) - red_075 = "#8F463F" # = rgb(143,70,63) - red_100 = "#6D0D03" # = rgb(109,13,3) - - brown_000 = "#F9E0B0" # = rgb(249,224,176) - brown_025 = "#F9C96D" # = rgb(249,201,109) - brown_050 = "#E69F17" # = rgb(230,159,23) - brown_075 = "#8F743F" # = rgb(143,116,63) - brown_100 = "#6D4903" # = rgb(109,73,3) - - grid_color = "#d5e0c9" - text_color = "#222222" - - my_font = "SVBasic Manual, 12" - my_export_sz = "1024,768" - - my_line_width = "2" - my_axis_width = "1" - my_ps = "1.5" - my_font_size = "14" - -# must convert font fo svg and ps -# set term svg size @my_export_sz fname my_font fsize my_font_size enhanced dynamic rounded -# set term png size @my_export_sz large font my_font -# set term jpeg size @my_export_sz large font my_font -# set term wxt enhanced font my_font - -set style data linespoints -set style function lines -set pointsize my_ps - -set style line 1 linecolor rgbcolor blue_050 linewidth @my_line_width pt 7 -set style line 2 linecolor rgbcolor green_050 linewidth @my_line_width pt 5 -set style line 3 linecolor rgbcolor red_050 linewidth @my_line_width pt 9 -set style line 4 linecolor rgbcolor brown_050 linewidth @my_line_width pt 13 -set style line 5 linecolor rgbcolor blue_025 linewidth @my_line_width pt 11 -set style line 6 linecolor rgbcolor green_025 linewidth @my_line_width pt 7 -set style line 7 linecolor rgbcolor red_025 linewidth @my_line_width pt 5 -set style line 8 linecolor rgbcolor brown_025 linewidth @my_line_width pt 9 -set style line 9 linecolor rgbcolor blue_075 linewidth @my_line_width pt 13 -set style line 10 linecolor rgbcolor green_075 linewidth @my_line_width pt 11 -set style line 11 linecolor rgbcolor red_075 linewidth @my_line_width pt 7 -set style line 12 linecolor rgbcolor brown_075 linewidth @my_line_width pt 5 -set style line 13 linecolor rgbcolor blue_100 linewidth @my_line_width pt 9 -set style line 14 linecolor rgbcolor green_100 linewidth @my_line_width pt 13 -set style line 15 linecolor rgbcolor red_100 linewidth @my_line_width pt 11 -set style line 16 linecolor rgbcolor brown_100 linewidth @my_line_width pt 7 -set style line 17 linecolor rgbcolor "#224499" linewidth @my_line_width pt 5 - -## plot 1,2,3,4,5,6,7,8,9 -set style increment user -set style arrow 1 filled - -## used for bar chart borders -set style fill solid 0.5 - -set size noratio -set samples 300 - -set border 31 lw @my_axis_width lc rgb text_color -``` - - -## Line Plotting ## - -Line plotting functionality covers many configurations from simplest -case of plotting a single vector to displaying multiple lines at once -with custom line specifictions. - - -### gnuplot.plot(x) ### -Plot vector ` x ` using dots of first default `Gnuplot` type. - -```lua -x=torch.linspace(-2*math.pi,2*math.pi) -gnuplot.plot(torch.sin(x)) -``` -![](doc/plot_x.png) - -In more general form, plot vector `y` vs `x` using the format -specified. The possible entries of format string can be: - * `.` for dots - * `+` for points - * `-` for lines - * `+-` for points and lines - * `~` for using smoothed lines with cubic interpolation - * `|` for using boxes - * `v` for drawing vector fiels. (In this case, `x` and `y` have to be two column vectors `(x, xdelta)`, `(y, ydelta)`) - * custom string, one can also pass custom strings to use full capability of gnuplot. - -```lua -x = torch.linspace(-2*math.pi,2*math.pi) -gnuplot.plot('Sin',x/math.pi,torch.sin(x),'|') -``` -![](doc/plot_xyf.png) - -To plot multiple curves at a time, one can pass each plot struct in a table. - -```lua -x = torch.linspace(-2*math.pi,2*math.pi) -gnuplot.plot({'Cos',x/math.pi,torch.cos(x),'~'},{'Sin',x/math.pi,torch.sin(x),'|'}) -``` -![](doc/plot_sincos.png) - -One can pass data with multiple columns and use custom gnuplot style strings too. When multi-column data -is used, the first column is assumed to be the `x` values and the rest of the columns are separate `y` series. - -```lua -x = torch.linspace(-5,5) -y = torch.sin(x) -yp = y+0.3+torch.rand(x:size())*0.1 -ym = y-(torch.rand(x:size())*0.1+0.3) -yy = torch.cat(x,ym,2) -yy = torch.cat(yy,yp,2) -gnuplot.plot({yy,' filledcurves'},{x,yp,'lines ls 1'},{x,ym,'lines ls 1'},{x,y,'lines ls 1'}) -``` -![](doc/plot_filled.png) - - -## Plotting 3D Surfaces ## - -Surface plotting creates a 3D surface plot of a given matrix `z`. Entries -of `z` are used as height values. It is also possible to specify `x` and -`y` locations corresponding to each point in `z` . If a terminal with -interactive capabilities is being used by `Gnuplot` backend (like `x11` or -`wxt` or `qt`), then rotating, zooming is also possible. - - -### gnuplot.splot(z) ### - -Plot surface ` z ` in 3D. -```lua -x = torch.linspace(-1,1) -xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x) -xx = xx*math.pi*6 -gnuplot.splot(torch.sin(xx)) -``` -![](doc/plot_splot.png) - -It is also possible to specify the `x` and `y` locations of each -point in `z` by `gnuplot.splot(x,y,z)`. In this `x` and `y` has -to be the same shape as `z`. - -One can also display multiple surfaces at a time. - -```lua -x = torch.linspace(-1,1) -xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x) -xx = xx*math.pi*2 -gnuplot.splot({torch.sin(xx)},{torch.sin(xx)+2}) -``` -![](doc/plot_splot2.png) - - -## Plotting Matrices as Images ## - -A given matrix can be plotted using 2D contour plot on a surface. - - -### gnuplot.imagesc(z, ['color' or 'gray']) ### - -Plot surface ` z ` using contour plot. The second argument defines -the color palette for the display. By default, grayscale colors are -used, however, one can also use any color palette available in -`Gnuplot`. - -```lua -x = torch.linspace(-1,1) -xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x) -xx = xx*math.pi*6 -gnuplot.imagesc(torch.sin(xx),'color') -``` -![](doc/plot_imagesc.png) - - -## Histograms ## - -Given a tensor, the distribution of values can be plotted using -`gnuplot.hist` function. - - -### gnuplot.hist(x, [nbins, min, max]) ### - -Plot the histogram of values in `N-D` tensor `x`, optionally using `nbins` -number of bins and only using values between `min` and `max`. - -```lua -gnuplot.hist(torch.randn(100000),100) -``` -![](doc/plot_hist.png) - - -## Plotting Directly into Files ## - -Any of the above plotting utilities can also be used for directly plotting -into `eps` or `png` files, or `pdf` files if your gnuplot installation -allows. A final gnuplot.plotflush() command ensures that all output is -written to the file properly. - -```lua -gnuplot.epsfigure('test.eps') -gnuplot.plot({'Sin Curve',torch.sin(torch.linspace(-5,5))}) -gnuplot.xlabel('X') -gnuplot.ylabel('Y') -gnuplot.plotflush() -``` - - -## Common Operations ## - -It is possible to manage multiple plots at a time, printing plots to -png, eps or pdf files or creating plots directly on png or eps or pdf files. - -There are also several handy operations for decorating plots which are -common to many of the plotting functions. - - - -### gnuplot.setgnuplotexe(exe) ### - -Manually set the location of gnuplot executable. - - -### gnuplot.setterm(teerm) ### - -Manually set the gnuplot terminal. - - -### gnuplot.closeall() ### - -Close all gnuplot active connections. This will not be able to close -open windows, since on the backend gnuplot also can not close windows. - - -### gnuplot.figure([n]) ### - -Select (or create) a new figure with id `n`. Note that until a plot -command is given, the window will not be created. When `n` is -skipped, a new figure is created with the next consecutive id. - - -### gnuplot.epsfigure(fname) ### - -Creates a figure directly on the `eps` file given with -`fname`. This uses `Gnuplot` terminal `postscript eps enhanced color`. - - -### gnuplot.pdffigure(fname) ### - -Only available if your installation of gnuplot has been compiled -with `pdf` support enabled. - -Creates a figure directly on the `pdf` file given with -`fname`. This uses `Gnuplot` terminal `pdf enhanced color`, -or `pdfcairo enhanced color` if available. - - -### gnuplot.pngfigure(fname) ### - -Creates a figure directly on the `png` file given with -`fname`. This uses `Gnuplot` terminal `png`, or `pngcairo` if available. - - -### gnuplot.svgfigure(fname) ### - -Creates a figure directly on the `svg` file given with `fname`. This uses -`Gnuplot` terminal `svg`. - - -### gnuplot.plotflush([n]) ### - -This command sends `unset output` to underlying gnuplot. Usefull for -flushing file based terminals. - - -### gnuplot.figprint(fname) ### - -Prints the current figure to the given file with name `fname`. Only `png` -or `eps` files are supported by default. If your gnuplot installation -allows, `pdf` files are also supported. - - -### gnuplot.xlabel(label) ### - -Sets the label of `x` axis to `label`. Only supported for gnuplot -version 4.4 and above. - - -### gnuplot.ylabel(label) ### - -Sets the label of `y` axis to `label`. Only supported for gnuplot -version 4.4 and above. - - -### gnuplot.zlabel(label) ### - -Sets the label of `z` axis to `label`. Only supported for gnuplot -version 4.4 and above. - - -### gnuplot.title(title) ### - -Sets the title of the plot to `title`. Only supported for gnuplot -version 4.4 and above. - - -### gnuplot.grid(toggle) ### - -If `toggle` is `true` then a grid is displayed, else it is -hidden. Only supported for gnuplot version 4.4 and above. - - -### gnuplot.movelegend(hloc,vloc) ### - -Set the location of legend key. `hloc` can be `left`, `right` or -`center`. `vloc` can be `top`, `bottom` or `middle`. Only -supported for gnuplot version 4.4 and above. - - -### gnuplot.axis(axis) ### - -Sets the properties of axis for the current plot. - - * `auto` : auto scales the axis to fit data and plot canvas - * `image` : scales the axis aspect ratio so that a circle is drawn as circle. - * `equal` : same as `image`. - * `fill` : resets the aspect ratio of the plot to original values so that it fills up the canvas as good as possible. - * `{xmin,xmax,ymin,ymax}` : Sets the limits of x and y axes. Use an empty string (2 apostophes in a row) if you want to keep the current value. - - -### gnuplot.raw(command) ### - -This command is useful for advanced users of gnuplot. `command` is -directly passed to gnuplot without any formatting. - -Let's see an example, by plotting labels for the `xtic` - -```lua -LondonTemp = torch.Tensor{{9, 10, 12, 15, 18, 21, 23, 23, 20, 16, 12, 9}, - {5, 5, 6, 7, 10, 13, 15, 15, 13, 10, 7, 5}} -gnuplot.plot({'High [°C]',LondonTemp[1]},{'Low [°C]',LondonTemp[2]}) -gnuplot.raw('set xtics ("Jan" 1, "Feb" 2, "Mar" 3, "Apr" 4, "May" 5, "Jun" 6, "Jul" 7, "Aug" 8, "Sep" 9, "Oct" 10, "Nov" 11, "Dec" 12)') -gnuplot.plotflush() -gnuplot.axis{0,13,0,''} -gnuplot.grid(true) -gnuplot.title('London average temperature') -``` -![](doc/plot_raw.png) diff --git a/doc/common.md b/doc/common.md new file mode 100644 index 0000000..b63801d --- /dev/null +++ b/doc/common.md @@ -0,0 +1,99 @@ + +## Common Operations ## + +It is possible to manage multiple plots at a time, printing plots to +png, eps or pdf files or creating plots directly on png or eps or pdf files. + +There are also several handy operations for decorating plots which are +common to many of the plotting functions. + + +### gnuplot.setgnuplotexe(exe) ### + +Manually set the location of gnuplot executable. + + +### gnuplot.setterm(teerm) ### + +Manually set the gnuplot terminal. + + +### gnuplot.closeall() ### + +Close all gnuplot active connections. This will not be able to close +open windows, since on the backend gnuplot also can not close windows. + + +### gnuplot.figure([n]) ### + +Select (or create) a new figure with id `n`. Note that until a plot +command is given, the window will not be created. When `n` is +skipped, a new figure is created with the next consecutive id. + + +### gnuplot.xlabel(label) ### + +Sets the label of `x` axis to `label`. Only supported for gnuplot +version 4.4 and above. + + +### gnuplot.ylabel(label) ### + +Sets the label of `y` axis to `label`. Only supported for gnuplot +version 4.4 and above. + + +### gnuplot.zlabel(label) ### + +Sets the label of `z` axis to `label`. Only supported for gnuplot +version 4.4 and above. + + +### gnuplot.title(title) ### + +Sets the title of the plot to `title`. Only supported for gnuplot +version 4.4 and above. + + +### gnuplot.grid(toggle) ### + +If `toggle` is `true` then a grid is displayed, else it is +hidden. Only supported for gnuplot version 4.4 and above. + + +### gnuplot.movelegend(hloc,vloc) ### + +Set the location of legend key. `hloc` can be `left`, `right` or +`center`. `vloc` can be `top`, `bottom` or `middle`. Only +supported for gnuplot version 4.4 and above. + + +### gnuplot.axis(axis) ### + +Sets the properties of axis for the current plot. + + * `auto` : auto scales the axis to fit data and plot canvas + * `image` : scales the axis aspect ratio so that a circle is drawn as circle. + * `equal` : same as `image`. + * `fill` : resets the aspect ratio of the plot to original values so that it fills up the canvas as good as possible. + * `{xmin,xmax,ymin,ymax}` : Sets the limits of x and y axes. Use an empty string (2 apostophes in a row) if you want to keep the current value. + + +### gnuplot.raw(command) ### + +This command is useful for advanced users of gnuplot. `command` is +directly passed to gnuplot without any formatting. + +Let's see an example, by plotting labels for the `xtic` + +```lua +LondonTemp = torch.Tensor{{9, 10, 12, 15, 18, 21, 23, 23, 20, 16, 12, 9}, + {5, 5, 6, 7, 10, 13, 15, 15, 13, 10, 7, 5}} +gnuplot.plot({'High [°C]',LondonTemp[1]},{'Low [°C]',LondonTemp[2]}) +gnuplot.raw('set xtics ("Jan" 1, "Feb" 2, "Mar" 3, "Apr" 4, "May" 5, "Jun" 6, "Jul" 7, "Aug" 8, "Sep" 9, "Oct" 10, "Nov" 11, "Dec" 12)') +gnuplot.plotflush() +gnuplot.axis{0,13,0,''} +gnuplot.grid(true) +gnuplot.title('London average temperature') +``` +![](plot_raw.png) diff --git a/doc/custom.md b/doc/custom.md new file mode 100644 index 0000000..bcbbfbe --- /dev/null +++ b/doc/custom.md @@ -0,0 +1,94 @@ + +## Customizing Gnuplot Defaults ## + +The default styles of gnuplot can be customized using a personal `.gnuplot` file +located in the users home directory. A sample file is given below as a sample. You can +paste the contents into `$HOME/.gnuplot` file and gnuplot will use the styles +specified in this file. + +``` +##### Modified version of the sample given in +##### http://www.guidolin.net/blog/files/2010/03/gnuplot + + +set macro + +##### Color Palette by Color Scheme Designer +##### Palette URL: http://colorschemedesigner.com/#3K40zsOsOK-K- + + + blue_000 = "#A9BDE6" # = rgb(169,189,230) + blue_025 = "#7297E6" # = rgb(114,151,230) + blue_050 = "#1D4599" # = rgb(29,69,153) + blue_075 = "#2F3F60" # = rgb(47,63,96) + blue_100 = "#031A49" # = rgb(3,26,73) + + green_000 = "#A6EBB5" # = rgb(166,235,181) + green_025 = "#67EB84" # = rgb(103,235,132) + green_050 = "#11AD34" # = rgb(17,173,52) + green_075 = "#2F6C3D" # = rgb(47,108,61) + green_100 = "#025214" # = rgb(2,82,20) + + red_000 = "#F9B7B0" # = rgb(249,183,176) + red_025 = "#F97A6D" # = rgb(249,122,109) + red_050 = "#E62B17" # = rgb(230,43,23) + red_075 = "#8F463F" # = rgb(143,70,63) + red_100 = "#6D0D03" # = rgb(109,13,3) + + brown_000 = "#F9E0B0" # = rgb(249,224,176) + brown_025 = "#F9C96D" # = rgb(249,201,109) + brown_050 = "#E69F17" # = rgb(230,159,23) + brown_075 = "#8F743F" # = rgb(143,116,63) + brown_100 = "#6D4903" # = rgb(109,73,3) + + grid_color = "#d5e0c9" + text_color = "#222222" + + my_font = "SVBasic Manual, 12" + my_export_sz = "1024,768" + + my_line_width = "2" + my_axis_width = "1" + my_ps = "1.5" + my_font_size = "14" + +# must convert font fo svg and ps +# set term svg size @my_export_sz fname my_font fsize my_font_size enhanced dynamic rounded +# set term png size @my_export_sz large font my_font +# set term jpeg size @my_export_sz large font my_font +# set term wxt enhanced font my_font + +set style data linespoints +set style function lines +set pointsize my_ps + +set style line 1 linecolor rgbcolor blue_050 linewidth @my_line_width pt 7 +set style line 2 linecolor rgbcolor green_050 linewidth @my_line_width pt 5 +set style line 3 linecolor rgbcolor red_050 linewidth @my_line_width pt 9 +set style line 4 linecolor rgbcolor brown_050 linewidth @my_line_width pt 13 +set style line 5 linecolor rgbcolor blue_025 linewidth @my_line_width pt 11 +set style line 6 linecolor rgbcolor green_025 linewidth @my_line_width pt 7 +set style line 7 linecolor rgbcolor red_025 linewidth @my_line_width pt 5 +set style line 8 linecolor rgbcolor brown_025 linewidth @my_line_width pt 9 +set style line 9 linecolor rgbcolor blue_075 linewidth @my_line_width pt 13 +set style line 10 linecolor rgbcolor green_075 linewidth @my_line_width pt 11 +set style line 11 linecolor rgbcolor red_075 linewidth @my_line_width pt 7 +set style line 12 linecolor rgbcolor brown_075 linewidth @my_line_width pt 5 +set style line 13 linecolor rgbcolor blue_100 linewidth @my_line_width pt 9 +set style line 14 linecolor rgbcolor green_100 linewidth @my_line_width pt 13 +set style line 15 linecolor rgbcolor red_100 linewidth @my_line_width pt 11 +set style line 16 linecolor rgbcolor brown_100 linewidth @my_line_width pt 7 +set style line 17 linecolor rgbcolor "#224499" linewidth @my_line_width pt 5 + +## plot 1,2,3,4,5,6,7,8,9 +set style increment user +set style arrow 1 filled + +## used for bar chart borders +set style fill solid 0.5 + +set size noratio +set samples 300 + +set border 31 lw @my_axis_width lc rgb text_color +``` diff --git a/doc/file.md b/doc/file.md new file mode 100644 index 0000000..3fe6a1d --- /dev/null +++ b/doc/file.md @@ -0,0 +1,56 @@ + +## Saving Plots to Files ## + +Any of the above plotting utilities can also be used for directly plotting +into `eps` or `png` files, or `pdf` files if your gnuplot installation +allows. A final gnuplot.plotflush() command ensures that all output is +written to the file properly. + +```lua +gnuplot.epsfigure('test.eps') +gnuplot.plot({'Sin Curve',torch.sin(torch.linspace(-5,5))}) +gnuplot.xlabel('X') +gnuplot.ylabel('Y') +gnuplot.plotflush() +``` + + +### gnuplot.epsfigure(fname) ### + +Creates a figure directly on the `eps` file given with +`fname`. This uses `Gnuplot` terminal `postscript eps enhanced color`. + + +### gnuplot.pdffigure(fname) ### + +Only available if your installation of gnuplot has been compiled +with `pdf` support enabled. + +Creates a figure directly on the `pdf` file given with +`fname`. This uses `Gnuplot` terminal `pdf enhanced color`, +or `pdfcairo enhanced color` if available. + + +### gnuplot.pngfigure(fname) ### + +Creates a figure directly on the `png` file given with +`fname`. This uses `Gnuplot` terminal `png`, or `pngcairo` if available. + + +### gnuplot.svgfigure(fname) ### + +Creates a figure directly on the `svg` file given with `fname`. This uses +`Gnuplot` terminal `svg`. + + +### gnuplot.figprint(fname) ### + +Prints the current figure to the given file with name `fname`. Only `png` +or `eps` files are supported by default. If your gnuplot installation +allows, `pdf` files are also supported. + + +### gnuplot.plotflush([n]) ### + +This command sends `unset output` to underlying gnuplot. Usefull for +flushing file based terminals. diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..2e68116 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,33 @@ + +# Plotting Package Manual with Gnuplot # + +A plotting package to visualize [Tensor](https://github.com/torch/torch7/blob/master/doc/tensor.md#tensor) objects. +Functions fall into several types of categories: + + * [Plotting lines](plotline.md#gnuplot.line.dok) + * [Plotting matrices](plotmatrix.md#gnuplot.image.dok) + * [Plotting surfaces](plotsurface.md#gnuplot.surface.dok) + * [Plotting histograms](plothistogram.md#gnuplot.histogram.dok) + * [Saving to Files](file.md#gnuplot.files.dok) + * [Common operations](decorateplot.md#gnuplot.commons.dok) + +The plotting package currently uses [gnuplot](http://gnuplot.info) as +a backend to display data. In particular, `Gnuplot` version `4.4` +or above is suggested for full support of all functionality. + +By default, the plot package will search for terminal in following order: + + * ` windows ` terminal if operating system is windows + * ` wxt `, ` qt `, ` x11 ` terminal if operating system is linux + * ` aqua `, `wxt`, ` qt `, ` x11 ` terminal if operating system is mac + +It is also possible to manually set any terminal type using +[gnuplot.setterm](#gnuplot.setterm). Interactivity is +dependent on the terminal being used. By default, `x11` and ''wxt +support'' different interactive operations like, zooming, panning, +rotating... + +The `Gnuplot` port uses `pipes` to communicate with `gnuplot`, +therefore each plotting session is persistent and additional commands +can be sent. For advanced users [gnuplot.raw](common.md#gnuplot.raw) +provides a free form interface to gnuplot. diff --git a/doc/plothistogram.md b/doc/plothistogram.md new file mode 100644 index 0000000..ac1d06a --- /dev/null +++ b/doc/plothistogram.md @@ -0,0 +1,16 @@ + +## Histograms ## + +Given a tensor, the distribution of values can be plotted using +`gnuplot.hist` function. + + +### gnuplot.hist(x, [nbins, min, max]) ### + +Plot the histogram of values in `N-D` tensor `x`, optionally using `nbins` +number of bins and only using values between `min` and `max`. + +```lua +gnuplot.hist(torch.randn(100000),100) +``` +![](plot_hist.png) diff --git a/doc/plotline.md b/doc/plotline.md new file mode 100644 index 0000000..a561981 --- /dev/null +++ b/doc/plotline.md @@ -0,0 +1,55 @@ + +## Plotting Lines ## + +Line plotting functionality covers many configurations from simplest +case of plotting a single vector to displaying multiple lines at once +with custom line specifictions. + + +### gnuplot.plot(x) ### +Plot vector ` x ` using dots of first default `Gnuplot` type. + +```lua +x=torch.linspace(-2*math.pi,2*math.pi) +gnuplot.plot(torch.sin(x)) +``` +![](plot_x.png) + +In more general form, plot vector `y` vs `x` using the format +specified. The possible entries of format string can be: + * `.` for dots + * `+` for points + * `-` for lines + * `+-` for points and lines + * `~` for using smoothed lines with cubic interpolation + * `|` for using boxes + * `v` for drawing vector fiels. (In this case, `x` and `y` have to be two column vectors `(x, xdelta)`, `(y, ydelta)`) + * custom string, one can also pass custom strings to use full capability of gnuplot. + +```lua +x = torch.linspace(-2*math.pi,2*math.pi) +gnuplot.plot('Sin',x/math.pi,torch.sin(x),'|') +``` +![](plot_xyf.png) + +To plot multiple curves at a time, one can pass each plot struct in a table. + +```lua +x = torch.linspace(-2*math.pi,2*math.pi) +gnuplot.plot({'Cos',x/math.pi,torch.cos(x),'~'},{'Sin',x/math.pi,torch.sin(x),'|'}) +``` +![](plot_sincos.png) + +One can pass data with multiple columns and use custom gnuplot style strings too. When multi-column data +is used, the first column is assumed to be the `x` values and the rest of the columns are separate `y` series. + +```lua +x = torch.linspace(-5,5) +y = torch.sin(x) +yp = y+0.3+torch.rand(x:size())*0.1 +ym = y-(torch.rand(x:size())*0.1+0.3) +yy = torch.cat(x,ym,2) +yy = torch.cat(yy,yp,2) +gnuplot.plot({yy,' filledcurves'},{x,yp,'lines ls 1'},{x,ym,'lines ls 1'},{x,y,'lines ls 1'}) +``` +![](plot_filled.png) diff --git a/doc/plotmatrix.md b/doc/plotmatrix.md new file mode 100644 index 0000000..d804ae6 --- /dev/null +++ b/doc/plotmatrix.md @@ -0,0 +1,20 @@ + +## Plotting Matrices ## + +A given matrix can be plotted using 2D contour plot on a surface. + + +### gnuplot.imagesc(z, ['color' or 'gray']) ### + +Plot surface ` z ` using contour plot. The second argument defines +the color palette for the display. By default, grayscale colors are +used, however, one can also use any color palette available in +`Gnuplot`. + +```lua +x = torch.linspace(-1,1) +xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x) +xx = xx*math.pi*6 +gnuplot.imagesc(torch.sin(xx),'color') +``` +![](plot_imagesc.png) diff --git a/doc/plotsurface.md b/doc/plotsurface.md new file mode 100644 index 0000000..5692abe --- /dev/null +++ b/doc/plotsurface.md @@ -0,0 +1,34 @@ + +## Plotting 3D Surfaces ## + +Surface plotting creates a 3D surface plot of a given matrix `z`. Entries +of `z` are used as height values. It is also possible to specify `x` and +`y` locations corresponding to each point in `z` . If a terminal with +interactive capabilities is being used by `Gnuplot` backend (like `x11` or +`wxt` or `qt`), then rotating, zooming is also possible. + + +### gnuplot.splot(z) ### + +Plot surface ` z ` in 3D. +```lua +x = torch.linspace(-1,1) +xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x) +xx = xx*math.pi*6 +gnuplot.splot(torch.sin(xx)) +``` +![](plot_splot.png) + +It is also possible to specify the `x` and `y` locations of each +point in `z` by `gnuplot.splot(x,y,z)`. In this `x` and `y` has +to be the same shape as `z`. + +One can also display multiple surfaces at a time. + +```lua +x = torch.linspace(-1,1) +xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x) +xx = xx*math.pi*2 +gnuplot.splot({torch.sin(xx)},{torch.sin(xx)+2}) +``` +![](plot_splot2.png) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..41e4418 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,14 @@ +site_name: gnuplot +theme : simplex +repo_url : https://github.com/torch/gnuplot +use_directory_urls : false +markdown_extensions: [extra] +docs_dir : doc +pages: +- [index.md, Gnuplot] +- [plotline.md, Plotting Lines] +- [plotmatrix.md, Plotting Matrices] +- [plotsurface.md, Plotting Surfaces] +- [plothistogram.md, Plotting Histograms] +- [file.md, Saving Plots] +- [common.md, Common Operations] -- cgit v1.2.3