Skip to content

Commit bc42a5b

Browse files
soumithsoumith
committed
Merge pull request #8 from nicholas-leonard/readthedocs
Readthedocs
2 parents c0cf2c0 + ceee717 commit bc42a5b

File tree

10 files changed

+432
-391
lines changed

10 files changed

+432
-391
lines changed

‎README.md‎

Lines changed: 11 additions & 391 deletions
Large diffs are not rendered by default.

‎doc/common.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
<a name="gnuplot.commons.dok"></a>
2+
## Common Operations ##
3+
4+
It is possible to manage multiple plots at a time, printing plots to
5+
png, eps or pdf files or creating plots directly on png or eps or pdf files.
6+
7+
There are also several handy operations for decorating plots which are
8+
common to many of the plotting functions.
9+
10+
<a name="gnuplot.setgnuplotexe"></a>
11+
### gnuplot.setgnuplotexe(exe) ###
12+
13+
Manually set the location of gnuplot executable.
14+
15+
<a name="gnuplot.setterm"></a>
16+
### gnuplot.setterm(teerm) ###
17+
18+
Manually set the gnuplot terminal.
19+
20+
<a name="gnuplot.closeall"></a>
21+
### gnuplot.closeall() ###
22+
23+
Close all gnuplot active connections. This will not be able to close
24+
open windows, since on the backend gnuplot also can not close windows.
25+
26+
<a name="gnuplot.figure"></a>
27+
### gnuplot.figure([n]) ###
28+
29+
Select (or create) a new figure with id `n`. Note that until a plot
30+
command is given, the window will not be created. When `n` is
31+
skipped, a new figure is created with the next consecutive id.
32+
33+
<a name="gnuplot.xlabel"></a>
34+
### gnuplot.xlabel(label) ###
35+
36+
Sets the label of `x` axis to `label`. Only supported for gnuplot
37+
version 4.4 and above.
38+
39+
<a name="gnuplot.ylabel"></a>
40+
### gnuplot.ylabel(label) ###
41+
42+
Sets the label of `y` axis to `label`. Only supported for gnuplot
43+
version 4.4 and above.
44+
45+
<a name="gnuplot.zlabel"></a>
46+
### gnuplot.zlabel(label) ###
47+
48+
Sets the label of `z` axis to `label`. Only supported for gnuplot
49+
version 4.4 and above.
50+
51+
<a name="gnuplot.title"></a>
52+
### gnuplot.title(title) ###
53+
54+
Sets the title of the plot to `title`. Only supported for gnuplot
55+
version 4.4 and above.
56+
57+
<a name="gnuplot.grid"></a>
58+
### gnuplot.grid(toggle) ###
59+
60+
If `toggle` is `true` then a grid is displayed, else it is
61+
hidden. Only supported for gnuplot version 4.4 and above.
62+
63+
<a name="gnuplot.movelegend"></a>
64+
### gnuplot.movelegend(hloc,vloc) ###
65+
66+
Set the location of legend key. `hloc` can be `left`, `right` or
67+
`center`. `vloc` can be `top`, `bottom` or `middle`. Only
68+
supported for gnuplot version 4.4 and above.
69+
70+
<a name="gnuplot.axis"></a>
71+
### gnuplot.axis(axis) ###
72+
73+
Sets the properties of axis for the current plot.
74+
75+
* `auto` : auto scales the axis to fit data and plot canvas
76+
* `image` : scales the axis aspect ratio so that a circle is drawn as circle.
77+
* `equal` : same as `image`.
78+
* `fill` : resets the aspect ratio of the plot to original values so that it fills up the canvas as good as possible.
79+
* `{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.
80+
81+
<a name="gnuplot.raw"></a>
82+
### gnuplot.raw(command) ###
83+
84+
This command is useful for advanced users of gnuplot. `command` is
85+
directly passed to gnuplot without any formatting.
86+
87+
Let's see an example, by plotting labels for the `xtic`
88+
89+
```lua
90+
LondonTemp = torch.Tensor{{9, 10, 12, 15, 18, 21, 23, 23, 20, 16, 12, 9},
91+
{5, 5, 6, 7, 10, 13, 15, 15, 13, 10, 7, 5}}
92+
gnuplot.plot({'High [°C]',LondonTemp[1]},{'Low [°C]',LondonTemp[2]})
93+
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)')
94+
gnuplot.plotflush()
95+
gnuplot.axis{0,13,0,''}
96+
gnuplot.grid(true)
97+
gnuplot.title('London average temperature')
98+
```
99+
![](plot_raw.png)

‎doc/custom.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
<a name="gnuplot.custom.dok"></a>
2+
## Customizing Gnuplot Defaults ##
3+
4+
The default styles of gnuplot can be customized using a personal `.gnuplot` file
5+
located in the users home directory. A sample file is given below as a sample. You can
6+
paste the contents into `$HOME/.gnuplot` file and gnuplot will use the styles
7+
specified in this file.
8+
9+
```
10+
##### Modified version of the sample given in
11+
##### http://www.guidolin.net/blog/files/2010/03/gnuplot
12+
13+
14+
set macro
15+
16+
##### Color Palette by Color Scheme Designer
17+
##### Palette URL: http://colorschemedesigner.com/#3K40zsOsOK-K-
18+
19+
20+
blue_000 = "#A9BDE6" # = rgb(169,189,230)
21+
blue_025 = "#7297E6" # = rgb(114,151,230)
22+
blue_050 = "#1D4599" # = rgb(29,69,153)
23+
blue_075 = "#2F3F60" # = rgb(47,63,96)
24+
blue_100 = "#031A49" # = rgb(3,26,73)
25+
26+
green_000 = "#A6EBB5" # = rgb(166,235,181)
27+
green_025 = "#67EB84" # = rgb(103,235,132)
28+
green_050 = "#11AD34" # = rgb(17,173,52)
29+
green_075 = "#2F6C3D" # = rgb(47,108,61)
30+
green_100 = "#025214" # = rgb(2,82,20)
31+
32+
red_000 = "#F9B7B0" # = rgb(249,183,176)
33+
red_025 = "#F97A6D" # = rgb(249,122,109)
34+
red_050 = "#E62B17" # = rgb(230,43,23)
35+
red_075 = "#8F463F" # = rgb(143,70,63)
36+
red_100 = "#6D0D03" # = rgb(109,13,3)
37+
38+
brown_000 = "#F9E0B0" # = rgb(249,224,176)
39+
brown_025 = "#F9C96D" # = rgb(249,201,109)
40+
brown_050 = "#E69F17" # = rgb(230,159,23)
41+
brown_075 = "#8F743F" # = rgb(143,116,63)
42+
brown_100 = "#6D4903" # = rgb(109,73,3)
43+
44+
grid_color = "#d5e0c9"
45+
text_color = "#222222"
46+
47+
my_font = "SVBasic Manual, 12"
48+
my_export_sz = "1024,768"
49+
50+
my_line_width = "2"
51+
my_axis_width = "1"
52+
my_ps = "1.5"
53+
my_font_size = "14"
54+
55+
# must convert font fo svg and ps
56+
# set term svg size @my_export_sz fname my_font fsize my_font_size enhanced dynamic rounded
57+
# set term png size @my_export_sz large font my_font
58+
# set term jpeg size @my_export_sz large font my_font
59+
# set term wxt enhanced font my_font
60+
61+
set style data linespoints
62+
set style function lines
63+
set pointsize my_ps
64+
65+
set style line 1 linecolor rgbcolor blue_050 linewidth @my_line_width pt 7
66+
set style line 2 linecolor rgbcolor green_050 linewidth @my_line_width pt 5
67+
set style line 3 linecolor rgbcolor red_050 linewidth @my_line_width pt 9
68+
set style line 4 linecolor rgbcolor brown_050 linewidth @my_line_width pt 13
69+
set style line 5 linecolor rgbcolor blue_025 linewidth @my_line_width pt 11
70+
set style line 6 linecolor rgbcolor green_025 linewidth @my_line_width pt 7
71+
set style line 7 linecolor rgbcolor red_025 linewidth @my_line_width pt 5
72+
set style line 8 linecolor rgbcolor brown_025 linewidth @my_line_width pt 9
73+
set style line 9 linecolor rgbcolor blue_075 linewidth @my_line_width pt 13
74+
set style line 10 linecolor rgbcolor green_075 linewidth @my_line_width pt 11
75+
set style line 11 linecolor rgbcolor red_075 linewidth @my_line_width pt 7
76+
set style line 12 linecolor rgbcolor brown_075 linewidth @my_line_width pt 5
77+
set style line 13 linecolor rgbcolor blue_100 linewidth @my_line_width pt 9
78+
set style line 14 linecolor rgbcolor green_100 linewidth @my_line_width pt 13
79+
set style line 15 linecolor rgbcolor red_100 linewidth @my_line_width pt 11
80+
set style line 16 linecolor rgbcolor brown_100 linewidth @my_line_width pt 7
81+
set style line 17 linecolor rgbcolor "#224499" linewidth @my_line_width pt 5
82+
83+
## plot 1,2,3,4,5,6,7,8,9
84+
set style increment user
85+
set style arrow 1 filled
86+
87+
## used for bar chart borders
88+
set style fill solid 0.5
89+
90+
set size noratio
91+
set samples 300
92+
93+
set border 31 lw @my_axis_width lc rgb text_color
94+
```

‎doc/file.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
<a name="gnuplot.files.dok"></a>
2+
## Saving Plots to Files ##
3+
4+
Any of the above plotting utilities can also be used for directly plotting
5+
into `eps` or `png` files, or `pdf` files if your gnuplot installation
6+
allows. A final gnuplot.plotflush() command ensures that all output is
7+
written to the file properly.
8+
9+
```lua
10+
gnuplot.epsfigure('test.eps')
11+
gnuplot.plot({'Sin Curve',torch.sin(torch.linspace(-5,5))})
12+
gnuplot.xlabel('X')
13+
gnuplot.ylabel('Y')
14+
gnuplot.plotflush()
15+
```
16+
17+
<a name="gnuplot.epsfigure"></a>
18+
### gnuplot.epsfigure(fname) ###
19+
20+
Creates a figure directly on the `eps` file given with
21+
`fname`. This uses `Gnuplot` terminal `postscript eps enhanced color`.
22+
23+
<a name="gnuplot.pdffigure"></a>
24+
### gnuplot.pdffigure(fname) ###
25+
26+
Only available if your installation of gnuplot has been compiled
27+
with `pdf` support enabled.
28+
29+
Creates a figure directly on the `pdf` file given with
30+
`fname`. This uses `Gnuplot` terminal `pdf enhanced color`,
31+
or `pdfcairo enhanced color` if available.
32+
33+
<a name="gnuplot.pngfigure"></a>
34+
### gnuplot.pngfigure(fname) ###
35+
36+
Creates a figure directly on the `png` file given with
37+
`fname`. This uses `Gnuplot` terminal `png`, or `pngcairo` if available.
38+
39+
<a name="gnuplot.svgfigure"></a>
40+
### gnuplot.svgfigure(fname) ###
41+
42+
Creates a figure directly on the `svg` file given with `fname`. This uses
43+
`Gnuplot` terminal `svg`.
44+
45+
<a name="gnuplot.figprint"></a>
46+
### gnuplot.figprint(fname) ###
47+
48+
Prints the current figure to the given file with name `fname`. Only `png`
49+
or `eps` files are supported by default. If your gnuplot installation
50+
allows, `pdf` files are also supported.
51+
52+
<a name="gnuplot.plotflush"></a>
53+
### gnuplot.plotflush([n]) ###
54+
55+
This command sends `unset output` to underlying gnuplot. Usefull for
56+
flushing file based terminals.

‎doc/index.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<a name="gnuplot.dok"></a>
2+
# Plotting Package Manual with Gnuplot #
3+
4+
A plotting package to visualize [Tensor](https://github.com/torch/torch7/blob/master/doc/tensor.md#tensor) objects.
5+
Functions fall into several types of categories:
6+
7+
* [Plotting lines](plotline.md#gnuplot.line.dok)
8+
* [Plotting matrices](plotmatrix.md#gnuplot.image.dok)
9+
* [Plotting surfaces](plotsurface.md#gnuplot.surface.dok)
10+
* [Plotting histograms](plothistogram.md#gnuplot.histogram.dok)
11+
* [Saving to Files](file.md#gnuplot.files.dok)
12+
* [Common operations](decorateplot.md#gnuplot.commons.dok)
13+
14+
The plotting package currently uses [gnuplot](http://gnuplot.info) as
15+
a backend to display data. In particular, `Gnuplot` version `4.4`
16+
or above is suggested for full support of all functionality.
17+
18+
By default, the plot package will search for terminal in following order:
19+
20+
* ` windows ` terminal if operating system is windows
21+
* ` wxt `, ` qt `, ` x11 ` terminal if operating system is linux
22+
* ` aqua `, `wxt`, ` qt `, ` x11 ` terminal if operating system is mac
23+
24+
It is also possible to manually set any terminal type using
25+
[gnuplot.setterm](#gnuplot.setterm). Interactivity is
26+
dependent on the terminal being used. By default, `x11` and ''wxt
27+
support'' different interactive operations like, zooming, panning,
28+
rotating...
29+
30+
The `Gnuplot` port uses `pipes` to communicate with `gnuplot`,
31+
therefore each plotting session is persistent and additional commands
32+
can be sent. For advanced users [gnuplot.raw](common.md#gnuplot.raw)
33+
provides a free form interface to gnuplot.

‎doc/plothistogram.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<a name="gnuplot.histogram.dok"></a>
2+
## Histograms ##
3+
4+
Given a tensor, the distribution of values can be plotted using
5+
`gnuplot.hist` function.
6+
7+
<a name="gnuplot.hist"></a>
8+
### gnuplot.hist(x, [nbins, min, max]) ###
9+
10+
Plot the histogram of values in `N-D` tensor `x`, optionally using `nbins`
11+
number of bins and only using values between `min` and `max`.
12+
13+
```lua
14+
gnuplot.hist(torch.randn(100000),100)
15+
```
16+
![](plot_hist.png)

‎doc/plotline.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<a name="gnuplot.line.dok"></a>
2+
## Plotting Lines ##
3+
4+
Line plotting functionality covers many configurations from simplest
5+
case of plotting a single vector to displaying multiple lines at once
6+
with custom line specifictions.
7+
8+
<a name="gnuplot.plot"></a>
9+
### gnuplot.plot(x) ###
10+
Plot vector ` x ` using dots of first default `Gnuplot` type.
11+
12+
```lua
13+
x=torch.linspace(-2*math.pi,2*math.pi)
14+
gnuplot.plot(torch.sin(x))
15+
```
16+
![](plot_x.png)
17+
18+
In more general form, plot vector `y` vs `x` using the format
19+
specified. The possible entries of format string can be:
20+
* `.` for dots
21+
* `+` for points
22+
* `-` for lines
23+
* `+-` for points and lines
24+
* `~` for using smoothed lines with cubic interpolation
25+
* `|` for using boxes
26+
* `v` for drawing vector fiels. (In this case, `x` and `y` have to be two column vectors `(x, xdelta)`, `(y, ydelta)`)
27+
* custom string, one can also pass custom strings to use full capability of gnuplot.
28+
29+
```lua
30+
x = torch.linspace(-2*math.pi,2*math.pi)
31+
gnuplot.plot('Sin',x/math.pi,torch.sin(x),'|')
32+
```
33+
![](plot_xyf.png)
34+
35+
To plot multiple curves at a time, one can pass each plot struct in a table.
36+
37+
```lua
38+
x = torch.linspace(-2*math.pi,2*math.pi)
39+
gnuplot.plot({'Cos',x/math.pi,torch.cos(x),'~'},{'Sin',x/math.pi,torch.sin(x),'|'})
40+
```
41+
![](plot_sincos.png)
42+
43+
One can pass data with multiple columns and use custom gnuplot style strings too. When multi-column data
44+
is used, the first column is assumed to be the `x` values and the rest of the columns are separate `y` series.
45+
46+
```lua
47+
x = torch.linspace(-5,5)
48+
y = torch.sin(x)
49+
yp = y+0.3+torch.rand(x:size())*0.1
50+
ym = y-(torch.rand(x:size())*0.1+0.3)
51+
yy = torch.cat(x,ym,2)
52+
yy = torch.cat(yy,yp,2)
53+
gnuplot.plot({yy,' filledcurves'},{x,yp,'lines ls 1'},{x,ym,'lines ls 1'},{x,y,'lines ls 1'})
54+
```
55+
![](plot_filled.png)

‎doc/plotmatrix.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<a name="gnuplot.image.dok"></a>
2+
## Plotting Matrices ##
3+
4+
A given matrix can be plotted using 2D contour plot on a surface.
5+
6+
<a name="gnuplot.imagesc"></a>
7+
### gnuplot.imagesc(z, ['color' or 'gray']) ###
8+
9+
Plot surface ` z ` using contour plot. The second argument defines
10+
the color palette for the display. By default, grayscale colors are
11+
used, however, one can also use any color palette available in
12+
`Gnuplot`.
13+
14+
```lua
15+
x = torch.linspace(-1,1)
16+
xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x)
17+
xx = xx*math.pi*6
18+
gnuplot.imagesc(torch.sin(xx),'color')
19+
```
20+
![](plot_imagesc.png)

0 commit comments

Comments
 (0)