|
3294
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
4167
|
5 @node Plotting |
|
3294
|
6 @chapter Plotting |
|
|
7 |
|
|
8 All of Octave's plotting functions use @code{gnuplot} to handle the |
|
|
9 actual graphics. There are two low-level functions, @code{gplot} and |
|
|
10 @code{gsplot}, that behave almost exactly like the corresponding |
|
|
11 @code{gnuplot} functions @code{plot} and @code{splot}. A number of |
|
|
12 other higher level plotting functions, patterned after the graphics |
|
|
13 functions found in @sc{Matlab} version 3.5, are also available. |
|
|
14 These higher level functions are all implemented in terms of the two |
|
|
15 low-level plotting functions. |
|
|
16 |
|
|
17 @menu |
|
|
18 * Two-Dimensional Plotting:: |
|
|
19 * Specialized Two-Dimensional Plots:: |
|
|
20 * Three-Dimensional Plotting:: |
|
|
21 * Plot Annotations:: |
|
|
22 * Multiple Plots on One Page:: |
|
3428
|
23 * Multiple Plot Windows:: |
|
3439
|
24 * Interaction with gnuplot:: |
|
3294
|
25 @end menu |
|
|
26 |
|
4167
|
27 @node Two-Dimensional Plotting |
|
3294
|
28 @section Two-Dimensional Plotting |
|
|
29 |
|
|
30 @deffn {Command} gplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} |
|
|
31 Generate a 2-dimensional plot. |
|
|
32 |
|
|
33 The @var{ranges}, @var{using}, @var{title}, and @var{style} arguments |
|
|
34 are optional, and the @var{using}, @var{title} and @var{style} |
|
|
35 qualifiers may appear in any order after the expression. You may plot |
|
|
36 multiple expressions with a single command by separating them with |
|
|
37 commas. Each expression may have its own set of qualifiers. |
|
|
38 |
|
|
39 The optional item @var{ranges} has the syntax |
|
|
40 |
|
|
41 @example |
|
|
42 [ x_lo : x_up ] [ y_lo : y_up ] |
|
|
43 @end example |
|
|
44 |
|
|
45 @noindent |
|
|
46 and may be used to specify the ranges for the axes of the plot, |
|
|
47 independent of the actual range of the data. The range for the y axes |
|
|
48 and any of the individual limits may be omitted. A range @code{[:]} |
|
|
49 indicates that the default limits should be used. This normally means |
|
|
50 that a range just large enough to include all the data points will be |
|
|
51 used. |
|
|
52 |
|
|
53 The expression to be plotted must not contain any literal matrices |
|
|
54 (e.g. @code{[ 1, 2; 3, 4 ]}) since it is nearly impossible to |
|
|
55 distinguish a plot range from a matrix of data. |
|
|
56 |
|
|
57 See the help for @code{gnuplot} for a description of the syntax for the |
|
|
58 optional items. |
|
|
59 |
|
|
60 By default, the @code{gplot} command plots the second column of a matrix |
|
|
61 versus the first. If the matrix only has one column, it is taken as a |
|
|
62 vector of y-coordinates and the x-coordinate is taken as the element |
|
|
63 index, starting with zero. For example, |
|
|
64 |
|
|
65 @example |
|
|
66 gplot rand (100,1) with linespoints |
|
|
67 @end example |
|
|
68 |
|
|
69 @noindent |
|
|
70 will plot 100 random values and connect them with lines. When |
|
|
71 @code{gplot} is used to plot a column vector, the indices of the |
|
|
72 elements are taken as x values. |
|
|
73 |
|
|
74 If there are more than two columns, you can |
|
|
75 choose which columns to plot with the @var{using} qualifier. For |
|
|
76 example, given the data |
|
|
77 |
|
|
78 @example |
|
|
79 x = (-10:0.1:10)'; |
|
|
80 data = [x, sin(x), cos(x)]; |
|
|
81 @end example |
|
|
82 |
|
|
83 @noindent |
|
|
84 the command |
|
|
85 |
|
|
86 @example |
|
|
87 gplot [-11:11] [-1.1:1.1] \ |
|
|
88 data with lines, data using 1:3 with impulses |
|
|
89 @end example |
|
|
90 |
|
|
91 @noindent |
|
|
92 will plot two lines. The first line is generated by the command |
|
|
93 @code{data with lines}, and is a graph of the sine function over the |
|
|
94 range @minus{}10 to 10. The data is taken from the first two columns of |
|
|
95 the matrix because columns to plot were not specified with the |
|
|
96 @var{using} qualifier. |
|
|
97 |
|
|
98 The clause @code{using 1:3} in the second part of this plot command |
|
|
99 specifies that the first and third columns of the matrix @code{data} |
|
|
100 should be taken as the values to plot. |
|
|
101 |
|
|
102 In this example, the ranges have been explicitly specified to be a bit |
|
|
103 larger than the actual range of the data so that the curves do not touch |
|
|
104 the border of the plot. |
|
|
105 @end deffn |
|
|
106 |
|
|
107 @deffn {Command} gset options |
|
|
108 @deffnx {Command} gshow options |
|
|
109 @deffnx {Command} replot options |
|
|
110 In addition to the basic plotting commands, the whole range of |
|
|
111 @code{gset} and @code{gshow} commands from @code{gnuplot} are available, |
|
|
112 as is @code{replot}. |
|
|
113 |
|
|
114 @findex set |
|
|
115 @findex show |
|
|
116 Note that in Octave 2.0, the @code{set} and @code{show} commands were |
|
|
117 renamed to @code{gset} and @code{gshow} in order to allow for |
|
|
118 compatibility with the @sc{Matlab} graphics and GUI commands in a future |
|
|
119 version of Octave. (For now, the old @code{set} and @code{show} |
|
|
120 commands do work, but they print an annoying warning message to try to |
|
|
121 get people to switch to using @code{gset} and @code{gshow}.) |
|
|
122 |
|
|
123 The @code{gset} and @code{gshow} commands allow you to set and show |
|
|
124 @code{gnuplot} parameters. For more information about the @code{gset} |
|
|
125 and @code{gshow} commands, see the documentation for @code{set} and |
|
|
126 @code{show} in the @code{gnuplot} user's guide (also available on line |
|
|
127 if you run @code{gnuplot} directly, instead of running it from Octave). |
|
|
128 |
|
|
129 The @code{replot} command allows you to force the plot to be |
|
|
130 redisplayed. This is useful if you have changed something about the |
|
|
131 plot, such as the title or axis labels. The @code{replot} command also |
|
|
132 accepts the same arguments as @code{gplot} or @code{gsplot} (except for |
|
|
133 data ranges) so you can add additional lines to existing plots. |
|
|
134 |
|
|
135 For example, |
|
|
136 |
|
|
137 @example |
|
|
138 gset term tek40 |
|
|
139 gset output "/dev/plotter" |
|
|
140 gset title "sine with lines and cosine with impulses" |
|
|
141 replot "sin (x) w l" |
|
|
142 @end example |
|
|
143 |
|
|
144 will change the terminal type for plotting, add a title to the current |
|
|
145 plot, add a graph of |
|
|
146 @iftex |
|
|
147 @tex |
|
|
148 $\sin(x)$ |
|
|
149 @end tex |
|
|
150 @end iftex |
|
|
151 @ifinfo |
|
|
152 sin (x) |
|
|
153 @end ifinfo |
|
|
154 to the plot, and force the new plot to be |
|
|
155 sent to the plot device. This last step is normally required in order |
|
|
156 to update the plot. This default is reasonable for slow terminals or |
|
|
157 hardcopy output devices because even when you are adding additional |
|
|
158 lines with a replot command, gnuplot always redraws the entire plot, and |
|
|
159 you probably don't want to have a completely new plot generated every |
|
|
160 time something as minor as an axis label changes. |
|
|
161 |
|
|
162 @findex shg |
|
|
163 The command @code{shg} is equivalent to executing @code{replot} without |
|
|
164 any arguments. |
|
|
165 @end deffn |
|
|
166 |
|
3368
|
167 @DOCSTRING(automatic_replot) |
|
3294
|
168 |
|
|
169 Note that NaN values in the plot data are automatically omitted, and |
|
|
170 Inf values are converted to a very large value before calling gnuplot. |
|
|
171 |
|
|
172 @c XXX FIXME XXX -- add info about what to do to get plots on remote X |
|
|
173 @c terminals. People often forget how to properly set DISPLAY and run |
|
|
174 @c xhost. |
|
|
175 |
|
|
176 @c XXX FIXME XXX -- add info about getting paper copies of plots. |
|
|
177 |
|
|
178 The @sc{Matlab}-style two-dimensional plotting commands are: |
|
|
179 |
|
|
180 @cindex plotting |
|
|
181 @cindex graphics |
|
|
182 |
|
3368
|
183 @DOCSTRING(plot) |
|
3294
|
184 |
|
3368
|
185 @DOCSTRING(hold) |
|
3294
|
186 |
|
3368
|
187 @DOCSTRING(ishold) |
|
3294
|
188 |
|
3368
|
189 @DOCSTRING(clearplot) |
|
3294
|
190 |
|
3428
|
191 @DOCSTRING(shg) |
|
|
192 |
|
3368
|
193 @DOCSTRING(closeplot) |
|
3294
|
194 |
|
3368
|
195 @DOCSTRING(purge_tmp_files) |
|
3294
|
196 |
|
3368
|
197 @DOCSTRING(axis) |
|
3294
|
198 |
|
4167
|
199 @node Specialized Two-Dimensional Plots |
|
3294
|
200 @section Specialized Two-Dimensional Plots |
|
|
201 |
|
3368
|
202 @DOCSTRING(bar) |
|
3294
|
203 |
|
3368
|
204 @DOCSTRING(contour) |
|
3294
|
205 |
|
3368
|
206 @DOCSTRING(hist) |
|
3294
|
207 |
|
3368
|
208 @DOCSTRING(loglog) |
|
3294
|
209 |
|
3368
|
210 @DOCSTRING(polar) |
|
3294
|
211 |
|
3368
|
212 @DOCSTRING(semilogx) |
|
3294
|
213 |
|
3368
|
214 @DOCSTRING(semilogy) |
|
3294
|
215 |
|
3368
|
216 @DOCSTRING(stairs) |
|
3294
|
217 |
|
4169
|
218 @DOCSTRING(errorbar) |
|
|
219 |
|
|
220 @DOCSTRING(loglogerr) |
|
|
221 |
|
|
222 @DOCSTRING(semilogxerr) |
|
|
223 |
|
|
224 @DOCSTRING(semilogyerr) |
|
|
225 |
|
4167
|
226 @node Three-Dimensional Plotting |
|
3294
|
227 @section Three-Dimensional Plotting |
|
|
228 |
|
|
229 @deffn {Command} gsplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} |
|
|
230 Generate a 3-dimensional plot. |
|
|
231 |
|
|
232 The @var{ranges}, @var{using}, @var{title}, and @var{style} arguments |
|
|
233 are optional, and the @var{using}, @var{title} and @var{style} |
|
|
234 qualifiers may appear in any order after the expression. You may plot |
|
|
235 multiple expressions with a single command by separating them with |
|
|
236 commas. Each expression may have its own set of qualifiers. |
|
|
237 |
|
|
238 The optional item @var{ranges} has the syntax |
|
|
239 |
|
|
240 @example |
|
|
241 [ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ] |
|
|
242 @end example |
|
|
243 |
|
|
244 @noindent |
|
|
245 and may be used to specify the ranges for the axes of the plot, |
|
|
246 independent of the actual range of the data. The range for the y and z |
|
|
247 axes and any of the individual limits may be omitted. A range |
|
|
248 @code{[:]} indicates that the default limits should be used. This |
|
|
249 normally means that a range just large enough to include all the data |
|
|
250 points will be used. |
|
|
251 |
|
|
252 The expression to be plotted must not contain any literal matrices (e.g. |
|
|
253 @code{[ 1, 2; 3, 4 ]}) since it is nearly impossible to distinguish a |
|
|
254 plot range from a matrix of data. |
|
|
255 |
|
|
256 See the help for @code{gnuplot} for a description of the syntax for the |
|
|
257 optional items. |
|
|
258 |
|
|
259 By default, the @code{gsplot} command plots each column of the |
|
|
260 expression as the z value, using the row index as the x value, and the |
|
|
261 column index as the y value. The indices are counted from zero, not |
|
|
262 one. For example, |
|
|
263 |
|
|
264 @example |
|
|
265 gsplot rand (5, 2) |
|
|
266 @end example |
|
|
267 |
|
|
268 @noindent |
|
|
269 will plot a random surface, with the x and y values taken from the row |
|
|
270 and column indices of the matrix. |
|
|
271 |
|
|
272 If parametric plotting mode is set (using the command |
|
|
273 @kbd{gset parametric}, then @code{gsplot} takes the columns of the |
|
|
274 matrix three at a time as the x, y and z values that define a line in |
|
|
275 three space. Any extra columns are ignored, and the x and y values are |
|
|
276 expected to be sorted. For example, with @code{parametric} set, it |
|
|
277 makes sense to plot a matrix like |
|
|
278 @iftex |
|
|
279 @tex |
|
|
280 $$ |
|
|
281 \left[\matrix{ |
|
|
282 1 & 1 & 3 & 2 & 1 & 6 & 3 & 1 & 9 \cr |
|
|
283 1 & 2 & 2 & 2 & 2 & 5 & 3 & 2 & 8 \cr |
|
|
284 1 & 3 & 1 & 2 & 3 & 4 & 3 & 3 & 7}\right] |
|
|
285 $$ |
|
|
286 @end tex |
|
|
287 @end iftex |
|
|
288 @ifinfo |
|
|
289 |
|
|
290 @example |
|
|
291 1 1 3 2 1 6 3 1 9 |
|
|
292 1 2 2 2 2 5 3 2 8 |
|
|
293 1 3 1 2 3 4 3 3 7 |
|
|
294 @end example |
|
|
295 @end ifinfo |
|
|
296 |
|
|
297 @noindent |
|
|
298 but not @code{rand (5, 30)}. |
|
|
299 @end deffn |
|
|
300 |
|
|
301 The @sc{Matlab}-style three-dimensional plotting commands are: |
|
|
302 |
|
3368
|
303 @DOCSTRING(mesh) |
|
3294
|
304 |
|
3428
|
305 @DOCSTRING(meshgrid) |
|
3294
|
306 |
|
3428
|
307 @DOCSTRING(meshdom) |
|
3294
|
308 |
|
4167
|
309 @node Plot Annotations |
|
3294
|
310 @section Plot Annotations |
|
|
311 |
|
3368
|
312 @DOCSTRING(grid) |
|
3294
|
313 |
|
3368
|
314 @DOCSTRING(title) |
|
3294
|
315 |
|
3428
|
316 @DOCSTRING(bottom_title) |
|
|
317 |
|
3368
|
318 @DOCSTRING(xlabel) |
|
3294
|
319 |
|
4167
|
320 @node Multiple Plots on One Page |
|
3294
|
321 @section Multiple Plots on One Page |
|
|
322 |
|
|
323 The following functions all require a version of @code{gnuplot} that |
|
|
324 supports the multiplot feature. |
|
|
325 |
|
3368
|
326 @DOCSTRING(mplot) |
|
3294
|
327 |
|
3368
|
328 @DOCSTRING(multiplot) |
|
3294
|
329 |
|
3368
|
330 @DOCSTRING(oneplot) |
|
3294
|
331 |
|
3368
|
332 @DOCSTRING(plot_border) |
|
3294
|
333 |
|
3368
|
334 @DOCSTRING(subplot) |
|
3294
|
335 |
|
3368
|
336 @DOCSTRING(subwindow) |
|
3294
|
337 |
|
3368
|
338 @DOCSTRING(top_title) |
|
3428
|
339 |
|
4167
|
340 @node Multiple Plot Windows |
|
3428
|
341 @section Multiple Plot Windows |
|
|
342 |
|
|
343 @DOCSTRING(figure) |
|
|
344 |
|
4167
|
345 @node Interaction with gnuplot |
|
3428
|
346 @section Interaction with @code{gnuplot} |
|
|
347 |
|
|
348 @DOCSTRING(gnuplot_binary) |
|
|
349 |
|
|
350 @DOCSTRING(gnuplot_has_frames) |
|
|
351 |
|
|
352 @DOCSTRING(graw) |
|
|
353 |
|
|
354 @DOCSTRING(gnuplot_command_plot) |
|
|
355 |
|
|
356 @DOCSTRING(gnuplot_command_replot) |
|
|
357 |
|
|
358 @DOCSTRING(gnuplot_command_splot) |
|
|
359 |
|
|
360 @DOCSTRING(gnuplot_command_using) |
|
|
361 |
|
|
362 @DOCSTRING(gnuplot_command_with) |
|
|
363 |
|
|
364 @DOCSTRING(gnuplot_command_axes) |
|
|
365 |
|
|
366 @DOCSTRING(gnuplot_command_title) |
|
|
367 |
|
|
368 @DOCSTRING(gnuplot_command_end) |
