|
2670
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
2333
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
2653
|
5 @node Plotting, Matrix Manipulation, Input and Output, Top |
|
2333
|
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 |
|
2670
|
11 @code{gnuplot} functions @code{plot} and @code{splot}. A number of |
|
2333
|
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:: |
|
2689
|
19 * Specialized Two-Dimensional Plots:: |
|
2333
|
20 * Three-Dimensional Plotting:: |
|
2689
|
21 * Plot Annotations:: |
|
2570
|
22 * Multiple Plots on One Page:: |
|
2333
|
23 @end menu |
|
|
24 |
|
2689
|
25 @node Two-Dimensional Plotting, Specialized Two-Dimensional Plots, Plotting, Plotting |
|
2333
|
26 @section Two-Dimensional Plotting |
|
|
27 |
|
2449
|
28 @deffn {Command} gplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} |
|
|
29 Generate a 2-dimensional plot. |
|
2333
|
30 |
|
2449
|
31 The @var{ranges}, @var{using}, @var{title}, and @var{style} arguments |
|
|
32 are optional, and the @var{using}, @var{title} and @var{style} |
|
2333
|
33 qualifiers may appear in any order after the expression. You may plot |
|
|
34 multiple expressions with a single command by separating them with |
|
|
35 commas. Each expression may have its own set of qualifiers. |
|
|
36 |
|
|
37 The optional item @var{ranges} has the syntax |
|
|
38 |
|
|
39 @example |
|
|
40 [ x_lo : x_up ] [ y_lo : y_up ] |
|
|
41 @end example |
|
|
42 |
|
|
43 @noindent |
|
|
44 and may be used to specify the ranges for the axes of the plot, |
|
|
45 independent of the actual range of the data. The range for the y axes |
|
|
46 and any of the individual limits may be omitted. A range @code{[:]} |
|
|
47 indicates that the default limits should be used. This normally means |
|
|
48 that a range just large enough to include all the data points will be |
|
|
49 used. |
|
|
50 |
|
|
51 The expression to be plotted must not contain any literal matrices |
|
|
52 (e.g. @code{[ 1, 2; 3, 4 ]}) since it is nearly impossible to |
|
|
53 distinguish a plot range from a matrix of data. |
|
|
54 |
|
|
55 See the help for @code{gnuplot} for a description of the syntax for the |
|
|
56 optional items. |
|
|
57 |
|
|
58 By default, the @code{gplot} command plots the second column of a matrix |
|
|
59 versus the first. If the matrix only has one column, it is taken as a |
|
|
60 vector of y-coordinates and the x-coordinate is taken as the element |
|
|
61 index, starting with zero. For example, |
|
|
62 |
|
|
63 @example |
|
|
64 gplot rand (100,1) with linespoints |
|
|
65 @end example |
|
|
66 |
|
|
67 @noindent |
|
|
68 will plot 100 random values and connect them with lines. When |
|
|
69 @code{gplot} is used to plot a column vector, the indices of the |
|
|
70 elements are taken as x values. |
|
|
71 |
|
|
72 If there are more than two columns, you can |
|
|
73 choose which columns to plot with the @var{using} qualifier. For |
|
|
74 example, given the data |
|
|
75 |
|
|
76 @example |
|
|
77 x = (-10:0.1:10)'; |
|
|
78 data = [x, sin(x), cos(x)]; |
|
|
79 @end example |
|
|
80 |
|
|
81 @noindent |
|
|
82 the command |
|
|
83 |
|
|
84 @example |
|
2535
|
85 gplot [-11:11] [-1.1:1.1] \ |
|
|
86 data with lines, data using 1:3 with impulses |
|
2333
|
87 @end example |
|
|
88 |
|
|
89 @noindent |
|
|
90 will plot two lines. The first line is generated by the command |
|
|
91 @code{data with lines}, and is a graph of the sine function over the |
|
2689
|
92 range @minus{}10 to 10. The data is taken from the first two columns of |
|
|
93 the matrix because columns to plot were not specified with the |
|
|
94 @var{using} qualifier. |
|
2333
|
95 |
|
|
96 The clause @code{using 1:3} in the second part of this plot command |
|
|
97 specifies that the first and third columns of the matrix @code{data} |
|
|
98 should be taken as the values to plot. |
|
|
99 |
|
|
100 In this example, the ranges have been explicitly specified to be a bit |
|
|
101 larger than the actual range of the data so that the curves do not touch |
|
|
102 the border of the plot. |
|
2449
|
103 @end deffn |
|
2333
|
104 |
|
2670
|
105 @deffn {Command} gset options |
|
|
106 @deffnx {Command} gshow options |
|
2449
|
107 @deffnx {Command} replot options |
|
2333
|
108 In addition to the basic plotting commands, the whole range of |
|
2670
|
109 @code{gset} and @code{gshow} commands from @code{gnuplot} are available, |
|
2333
|
110 as is @code{replot}. |
|
|
111 |
|
2670
|
112 @findex set |
|
|
113 @findex show |
|
|
114 Note that in Octave 2.0, the @code{set} and @code{show} commands were |
|
|
115 renamed to @code{gset} and @code{gshow} in order to allow for |
|
|
116 compatibility with the @sc{Matlab} graphics and GUI commands in a future |
|
|
117 version of Octave. (For now, the old @code{set} and @code{show} |
|
|
118 commands do work, but they print an annoying warning message to try to |
|
|
119 get people to switch to using @code{gset} and @code{gshow}.) |
|
|
120 |
|
|
121 The @code{gset} and @code{gshow} commands allow you to set and show |
|
|
122 @code{gnuplot} parameters. For more information about the @code{gset} |
|
|
123 and @code{gshow} commands, see the documentation for @code{set} and |
|
|
124 @code{show} in the @code{gnuplot} user's guide (also available on line |
|
|
125 if you run @code{gnuplot} directly, instead of running it from Octave). |
|
2333
|
126 |
|
|
127 The @code{replot} command allows you to force the plot to be |
|
|
128 redisplayed. This is useful if you have changed something about the |
|
|
129 plot, such as the title or axis labels. The @code{replot} command also |
|
|
130 accepts the same arguments as @code{gplot} or @code{gsplot} (except for |
|
|
131 data ranges) so you can add additional lines to existing plots. |
|
|
132 |
|
|
133 For example, |
|
|
134 |
|
|
135 @example |
|
2670
|
136 gset term tek40 |
|
|
137 gset output "/dev/plotter" |
|
|
138 gset title "sine with lines and cosine with impulses" |
|
2333
|
139 replot "sin (x) w l" |
|
|
140 @end example |
|
|
141 |
|
|
142 will change the terminal type for plotting, add a title to the current |
|
2689
|
143 plot, add a graph of |
|
|
144 @iftex |
|
|
145 @tex |
|
|
146 $\sin(x)$ |
|
|
147 @end tex |
|
|
148 @end iftex |
|
|
149 @ifinfo |
|
|
150 sin (x) |
|
|
151 @end ifinfo |
|
|
152 to the plot, and force the new plot to be |
|
2333
|
153 sent to the plot device. This last step is normally required in order |
|
|
154 to update the plot. This default is reasonable for slow terminals or |
|
|
155 hardcopy output devices because even when you are adding additional |
|
|
156 lines with a replot command, gnuplot always redraws the entire plot, and |
|
|
157 you probably don't want to have a completely new plot generated every |
|
|
158 time something as minor as an axis label changes. |
|
2670
|
159 |
|
|
160 @findex shg |
|
|
161 The command @code{shg} is equivalent to executing @code{replot} without |
|
|
162 any arguments. |
|
2449
|
163 @end deffn |
|
2333
|
164 |
|
2449
|
165 @defvr {Built-in Variable} automatic_replot |
|
|
166 You can tell Octave to redisplay the plot each time anything about it |
|
|
167 changes by setting the value of the builtin variable |
|
|
168 @code{automatic_replot} to a nonzero value. Since this is fairly |
|
|
169 inefficient, the default value is 0. |
|
|
170 @end defvr |
|
2333
|
171 |
|
|
172 Note that NaN values in the plot data are automatically omitted, and |
|
|
173 Inf values are converted to a very large value before calling gnuplot. |
|
|
174 |
|
|
175 @c XXX FIXME XXX -- add info about what to do to get plots on remote X |
|
|
176 @c terminals. People often forget how to properly set DISPLAY and run |
|
|
177 @c xhost. |
|
|
178 |
|
|
179 @c XXX FIXME XXX -- add info about getting paper copies of plots. |
|
|
180 |
|
|
181 The @sc{Matlab}-style two-dimensional plotting commands are: |
|
|
182 |
|
|
183 @cindex plotting |
|
|
184 @cindex graphics |
|
|
185 |
|
2449
|
186 @deftypefn {Function File} {} plot (@var{args}) |
|
2333
|
187 This function produces two-dimensional plots. Many different |
|
|
188 combinations of arguments are possible. The simplest form is |
|
|
189 |
|
|
190 @example |
|
2689
|
191 plot (@var{y}) |
|
2333
|
192 @end example |
|
|
193 |
|
|
194 @noindent |
|
|
195 where the argument is taken as the set of @var{y} coordinates and the |
|
|
196 @var{x} coordinates are taken to be the indices of the elements, |
|
|
197 starting with 1. |
|
|
198 |
|
|
199 If more than one argument is given, they are interpreted as |
|
|
200 |
|
|
201 @example |
|
2689
|
202 plot (@var{x}, @var{y}, @var{fmt} ...) |
|
2333
|
203 @end example |
|
|
204 |
|
|
205 @noindent |
|
|
206 where @var{y} and @var{fmt} are optional, and any number of argument |
|
|
207 sets may appear. The @var{x} and @var{y} values are |
|
|
208 interpreted as follows: |
|
|
209 |
|
|
210 @itemize @bullet |
|
|
211 @item |
|
|
212 If a single data argument is supplied, it is taken as the set of @var{y} |
|
|
213 coordinates and the @var{x} coordinates are taken to be the indices of |
|
|
214 the elements, starting with 1. |
|
|
215 |
|
|
216 @item |
|
|
217 If the first argument is a vector and the second is a matrix, the |
|
|
218 the vector is plotted versus the columns (or rows) of the matrix. |
|
|
219 (using whichever combination matches, with columns tried first.) |
|
|
220 |
|
|
221 @item |
|
|
222 If the first argument is a matrix and the second is a vector, the |
|
|
223 the columns (or rows) of the matrix are plotted versus the vector. |
|
|
224 (using whichever combination matches, with columns tried first.) |
|
|
225 |
|
|
226 @item |
|
|
227 If both arguments are vectors, the elements of @var{y} are plotted versus |
|
|
228 the elements of @var{x}. |
|
|
229 |
|
|
230 @item |
|
|
231 If both arguments are matrices, the columns of @var{y} are plotted |
|
|
232 versus the columns of @var{x}. In this case, both matrices must have |
|
|
233 the same number of rows and columns and no attempt is made to transpose |
|
|
234 the arguments to make the number of rows match. |
|
|
235 |
|
|
236 If both arguments are scalars, a single point is plotted. |
|
|
237 @end itemize |
|
|
238 |
|
|
239 The @var{fmt} argument, if present is interpreted as follows. If |
|
|
240 @var{fmt} is missing, the default gnuplot line style is assumed. |
|
|
241 |
|
2670
|
242 @table @samp |
|
|
243 @item - |
|
2333
|
244 Set lines plot style (default). |
|
|
245 |
|
2670
|
246 @item . |
|
2333
|
247 Set dots plot style. |
|
|
248 |
|
2670
|
249 @item @@ |
|
2333
|
250 Set points plot style. |
|
|
251 |
|
2670
|
252 @item -@@ |
|
2333
|
253 Set linespoints plot style. |
|
|
254 |
|
2670
|
255 @item ^ |
|
2333
|
256 Set impulses plot style. |
|
|
257 |
|
2670
|
258 @item L |
|
2333
|
259 Set steps plot style. |
|
|
260 |
|
2670
|
261 @item # |
|
2333
|
262 Set boxes plot style. |
|
|
263 |
|
2670
|
264 @item ~ |
|
2333
|
265 Set errorbars plot style. |
|
|
266 |
|
2670
|
267 @item #~ |
|
2333
|
268 Set boxerrorbars plot style. |
|
|
269 |
|
2689
|
270 @item @var{n} |
|
2333
|
271 Interpreted as the plot color if @var{n} is an integer in the range 1 to |
|
|
272 6. |
|
|
273 |
|
2689
|
274 @item @var{nm} |
|
2333
|
275 If @var{nm} is a two digit integer and @var{m} is an integer in the |
|
|
276 range 1 to 6, @var{m} is interpreted as the point style. This is only |
|
|
277 valid in combination with the @code{@@} or @code{-@@} specifiers. |
|
|
278 |
|
2689
|
279 @item @var{c} |
|
|
280 If @var{c} is one of @code{"r"}, @code{"g"}, @code{"b"}, @code{"m"}, |
|
|
281 @code{"c"}, or @code{"w"}, it is interpreted as the plot color (red, |
|
2333
|
282 green, blue, magenta, cyan, or white). |
|
|
283 |
|
2670
|
284 @item + |
|
|
285 @itemx * |
|
|
286 @itemx o |
|
|
287 @itemx x |
|
2333
|
288 Used in combination with the points or linespoints styles, set the point |
|
|
289 style. |
|
|
290 @end table |
|
|
291 |
|
|
292 The color line styles have the following meanings on terminals that |
|
|
293 support color. |
|
|
294 |
|
|
295 @example |
|
|
296 Number Gnuplot colors (lines)points style |
|
|
297 1 red * |
|
|
298 2 green + |
|
|
299 3 blue o |
|
|
300 4 magenta x |
|
|
301 5 cyan house |
|
|
302 6 brown there exists |
|
|
303 @end example |
|
|
304 |
|
|
305 Here are some plot examples: |
|
|
306 |
|
|
307 @example |
|
|
308 plot (x, y, "@@12", x, y2, x, y3, "4", x, y4, "+") |
|
|
309 @end example |
|
|
310 |
|
2689
|
311 This command will plot @code{y} with points of type 2 (displayed as |
|
|
312 @samp{+}) and color 1 (red), @code{y2} with lines, @code{y3} with lines of |
|
|
313 color 4 (magenta) and @code{y4} with points displayed as @samp{+}. |
|
2333
|
314 |
|
|
315 @example |
|
|
316 plot (b, "*") |
|
|
317 @end example |
|
|
318 |
|
2689
|
319 This command will plot the data in the variable @code{b} will be plotted |
|
|
320 with points displayed as @samp{*}. |
|
2449
|
321 @end deftypefn |
|
2333
|
322 |
|
2449
|
323 @deftypefn {Function File} {} hold @var{args} |
|
2333
|
324 Tell Octave to `hold' the current data on the plot when executing |
|
|
325 subsequent plotting commands. This allows you to execute a series of |
|
|
326 plot commands and have all the lines end up on the same figure. The |
|
|
327 default is for each new plot command to clear the plot device first. |
|
|
328 For example, the command |
|
|
329 |
|
|
330 @example |
|
|
331 hold on |
|
|
332 @end example |
|
|
333 |
|
|
334 @noindent |
|
|
335 turns the hold state on. An argument of @code{off} turns the hold state |
|
|
336 off, and @code{hold} with no arguments toggles the current hold state. |
|
2449
|
337 @end deftypefn |
|
2333
|
338 |
|
2449
|
339 @deftypefn {Function File} {} ishold |
|
2689
|
340 Return 1 if the next line will be added to the current plot, or 0 if |
|
2333
|
341 the plot device will be cleared before drawing the next line. |
|
2449
|
342 @end deftypefn |
|
2333
|
343 |
|
2689
|
344 @deftypefn {Function File} {} clearplot |
|
|
345 @deftypefnx {Function File} {} clg |
|
|
346 Clear the plot window and any titles or axis labels. The name |
|
|
347 @code{clg} is aliased to @code{clearplot} for compatibility with @sc{Matlab}. |
|
|
348 |
|
|
349 The commands @kbd{gplot clear}, @kbd{gsplot clear}, and @kbd{replot |
|
|
350 clear} are equivalent to @code{clearplot}. (Previously, commands like |
|
|
351 @kbd{gplot clear} would evaluate @code{clear} as an ordinary expression |
|
|
352 and clear all the visible variables.) |
|
|
353 @end deftypefn |
|
|
354 |
|
|
355 @deftypefn {Function File} {} closeplot |
|
|
356 Close stream to the @code{gnuplot} subprocess. If you are using X11, |
|
|
357 this will close the plot window. |
|
|
358 @end deftypefn |
|
|
359 |
|
|
360 @deftypefn {Function File} {} purge_tmp_files |
|
|
361 Delete the temporary files created by the plotting commands. |
|
|
362 |
|
|
363 Octave creates temporary data files for @code{gnuplot} and then sends |
|
|
364 commands to @code{gnuplot} through a pipe. Octave will delete the |
|
|
365 temporary files on exit, but if you are doing a lot of plotting you may |
|
|
366 want to clean up in the middle of a session. |
|
|
367 |
|
|
368 A future version of Octave will eliminate the need to use temporary |
|
|
369 files to hold the plot data. |
|
|
370 @end deftypefn |
|
|
371 |
|
|
372 @deftypefn {Function File} {} axis (@var{limits}) |
|
|
373 Sets the axis limits for plots. |
|
|
374 |
|
|
375 The argument @var{limits} should be a 2, 4, or 6 element vector. The |
|
|
376 first and second elements specify the lower and upper limits for the x |
|
|
377 axis. The third and fourth specify the limits for the y axis, and the |
|
|
378 fifth and sixth specify the limits for the z axis. |
|
|
379 |
|
|
380 With no arguments, @code{axis} turns autoscaling on. |
|
|
381 |
|
|
382 If your plot is already drawn, then you need to use @code{replot} before |
|
|
383 the new axis limits will take effect. You can get this to happen |
|
|
384 automatically by setting the built-in variable @code{automatic_replot} |
|
|
385 to a nonzero value. |
|
|
386 @end deftypefn |
|
|
387 |
|
|
388 @node Specialized Two-Dimensional Plots, Three-Dimensional Plotting, Two-Dimensional Plotting, Plotting |
|
|
389 @section Specialized Two-Dimensional Plots |
|
|
390 |
|
|
391 @deftypefn {Function File} {} bar (@var{x}, @var{y}) |
|
|
392 Given two vectors of x-y data, @code{bar} produces a bar graph. |
|
|
393 |
|
|
394 If only one argument is given, it is taken as a vector of y-values |
|
|
395 and the x coordinates are taken to be the indices of the elements. |
|
|
396 |
|
|
397 If two output arguments are specified, the data are generated but |
|
|
398 not plotted. For example, |
|
|
399 |
|
|
400 @example |
|
|
401 bar (x, y); |
|
|
402 @end example |
|
|
403 |
|
|
404 @noindent |
|
|
405 and |
|
|
406 |
|
|
407 @example |
|
|
408 [xb, yb] = bar (x, y); |
|
|
409 plot (xb, yb); |
|
|
410 @end example |
|
|
411 |
|
|
412 @noindent |
|
|
413 are equivalent. |
|
|
414 @end deftypefn |
|
|
415 |
|
|
416 @deftypefn {Function File} {} contour (@var{z}, @var{n}, @var{x}, @var{y}) |
|
|
417 Make a contour plot of the three-dimensional surface described by |
|
|
418 @var{z}. Someone needs to improve @code{gnuplot}'s contour routines |
|
|
419 before this will be very useful. |
|
|
420 @end deftypefn |
|
|
421 |
|
|
422 @deftypefn {Function File} {} hist (@var{y}, @var{x}) |
|
|
423 Produce histogram counts or plots. |
|
|
424 |
|
|
425 With one vector input argument, plot a histogram of the values with |
|
|
426 10 bins. The range of the histogram bins is determined by the range |
|
|
427 of the data. |
|
|
428 |
|
|
429 Given a second scalar argument, use that as the number of bins. |
|
|
430 |
|
|
431 Given a second vector argument, use that as the centers of the bins, |
|
|
432 with the width of the bins determined from the adjacent values in |
|
|
433 the vector. |
|
|
434 |
|
|
435 Extreme values are lumped in the first and last bins. |
|
|
436 |
|
|
437 With two output arguments, produce the values @var{nn} and @var{xx} such |
|
|
438 that @code{bar (@var{xx}, @var{nn})} will plot the histogram. |
|
|
439 @end deftypefn |
|
|
440 |
|
2449
|
441 @deftypefn {Function File} {} loglog (@var{args}) |
|
2333
|
442 Make a two-dimensional plot using log scales for both axes. See the |
|
|
443 description of @code{plot} above for a description of the arguments that |
|
|
444 @code{loglog} will accept. |
|
2449
|
445 @end deftypefn |
|
2333
|
446 |
|
2689
|
447 @deftypefn {Function File} {} polar (@var{theta}, @var{rho}) |
|
|
448 Make a two-dimensional plot given polar the coordinates @var{theta} and |
|
|
449 @var{rho}. |
|
|
450 @end deftypefn |
|
|
451 |
|
2449
|
452 @deftypefn {Function File} {} semilogx (@var{args}) |
|
2333
|
453 Make a two-dimensional plot using a log scale for the @var{x} axis. See |
|
|
454 the description of @code{plot} above for a description of the arguments |
|
|
455 that @code{semilogx} will accept. |
|
2449
|
456 @end deftypefn |
|
2333
|
457 |
|
2449
|
458 @deftypefn {Function File} {} semilogy (@var{args}) |
|
2333
|
459 Make a two-dimensional plot using a log scale for the @var{y} axis. See |
|
|
460 the description of @code{plot} above for a description of the arguments |
|
|
461 that @code{semilogy} will accept. |
|
2449
|
462 @end deftypefn |
|
2333
|
463 |
|
2689
|
464 @deftypefn {Function File} {} stairs (@var{x}, @var{y}) |
|
|
465 Given two vectors of x-y data, bar produces a `stairstep' plot. |
|
|
466 |
|
|
467 If only one argument is given, it is taken as a vector of y-values |
|
|
468 and the x coordinates are taken to be the indices of the elements. |
|
|
469 |
|
|
470 If two output arguments are specified, the data are generated but |
|
|
471 not plotted. For example, |
|
|
472 |
|
|
473 @example |
|
|
474 stairs (x, y); |
|
|
475 @end example |
|
|
476 |
|
|
477 @noindent |
|
|
478 and |
|
|
479 |
|
|
480 @example |
|
|
481 [xs, ys] = stairs (x, y); |
|
|
482 plot (xs, ys); |
|
|
483 @end example |
|
|
484 |
|
|
485 @noindent |
|
|
486 are equivalent. |
|
2449
|
487 @end deftypefn |
|
2333
|
488 |
|
2689
|
489 @node Three-Dimensional Plotting, Plot Annotations, Specialized Two-Dimensional Plots, Plotting |
|
2333
|
490 @section Three-Dimensional Plotting |
|
|
491 |
|
2449
|
492 @deffn {Command} gsplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} |
|
|
493 Generate a 3-dimensional plot. |
|
2333
|
494 |
|
2449
|
495 The @var{ranges}, @var{using}, @var{title}, and @var{style} arguments |
|
|
496 are optional, and the @var{using}, @var{title} and @var{style} |
|
2333
|
497 qualifiers may appear in any order after the expression. You may plot |
|
|
498 multiple expressions with a single command by separating them with |
|
|
499 commas. Each expression may have its own set of qualifiers. |
|
|
500 |
|
|
501 The optional item @var{ranges} has the syntax |
|
|
502 |
|
|
503 @example |
|
|
504 [ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ] |
|
|
505 @end example |
|
|
506 |
|
|
507 @noindent |
|
|
508 and may be used to specify the ranges for the axes of the plot, |
|
|
509 independent of the actual range of the data. The range for the y and z |
|
|
510 axes and any of the individual limits may be omitted. A range |
|
|
511 @code{[:]} indicates that the default limits should be used. This |
|
|
512 normally means that a range just large enough to include all the data |
|
|
513 points will be used. |
|
|
514 |
|
|
515 The expression to be plotted must not contain any literal matrices (e.g. |
|
|
516 @code{[ 1, 2; 3, 4 ]}) since it is nearly impossible to distinguish a |
|
|
517 plot range from a matrix of data. |
|
|
518 |
|
|
519 See the help for @code{gnuplot} for a description of the syntax for the |
|
|
520 optional items. |
|
|
521 |
|
|
522 By default, the @code{gsplot} command plots each column of the |
|
|
523 expression as the z value, using the row index as the x value, and the |
|
|
524 column index as the y value. The indices are counted from zero, not |
|
|
525 one. For example, |
|
|
526 |
|
|
527 @example |
|
|
528 gsplot rand (5, 2) |
|
|
529 @end example |
|
|
530 |
|
|
531 @noindent |
|
|
532 will plot a random surface, with the x and y values taken from the row |
|
|
533 and column indices of the matrix. |
|
|
534 |
|
|
535 If parametric plotting mode is set (using the command |
|
2670
|
536 @kbd{gset parametric}, then @code{gsplot} takes the columns of the |
|
2333
|
537 matrix three at a time as the x, y and z values that define a line in |
|
|
538 three space. Any extra columns are ignored, and the x and y values are |
|
2689
|
539 expected to be sorted. For example, with @code{parametric} set, it |
|
2333
|
540 makes sense to plot a matrix like |
|
|
541 @iftex |
|
|
542 @tex |
|
|
543 $$ |
|
|
544 \left[\matrix{ |
|
|
545 1 & 1 & 3 & 2 & 1 & 6 & 3 & 1 & 9 \cr |
|
|
546 1 & 2 & 2 & 2 & 2 & 5 & 3 & 2 & 8 \cr |
|
|
547 1 & 3 & 1 & 2 & 3 & 4 & 3 & 3 & 7}\right] |
|
|
548 $$ |
|
|
549 @end tex |
|
|
550 @end iftex |
|
|
551 @ifinfo |
|
|
552 |
|
|
553 @example |
|
|
554 1 1 3 2 1 6 3 1 9 |
|
|
555 1 2 2 2 2 5 3 2 8 |
|
|
556 1 3 1 2 3 4 3 3 7 |
|
|
557 @end example |
|
|
558 @end ifinfo |
|
|
559 |
|
|
560 @noindent |
|
|
561 but not @code{rand (5, 30)}. |
|
2449
|
562 @end deffn |
|
2333
|
563 |
|
|
564 The @sc{Matlab}-style three-dimensional plotting commands are: |
|
|
565 |
|
2449
|
566 @deftypefn {Function File} {} mesh (@var{x}, @var{y}, @var{z}) |
|
2333
|
567 Plot a mesh given matrices @code{x}, and @var{y} from @code{meshdom} and |
|
|
568 a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of |
|
|
569 the mesh. |
|
2449
|
570 @end deftypefn |
|
2333
|
571 |
|
2449
|
572 @deftypefn {Function File} {} meshdom (@var{x}, @var{y}) |
|
2333
|
573 Given vectors of @var{x} and @var{y} coordinates, return two matrices |
|
|
574 corresponding to the @var{x} and @var{y} coordinates of the mesh. |
|
|
575 |
|
|
576 See the file @file{sombrero.m} for an example of using @code{mesh} and |
|
|
577 @code{meshdom}. |
|
2449
|
578 @end deftypefn |
|
|
579 |
|
|
580 @defvr {Built-in Variable} gnuplot_binary |
|
|
581 The name of the program invoked by the plot command. The default value |
|
|
582 is @code{"gnuplot"}. @xref{Installation}. |
|
|
583 @end defvr |
|
|
584 |
|
|
585 @defvr {Built-in Variable} gnuplot_has_frames |
|
|
586 If the value of this variable is nonzero, Octave assumes that your copy |
|
|
587 of gnuplot has support for multiple frames that is included in recent |
|
|
588 3.6beta releases. It's initial value is determined by configure, but it |
|
|
589 can be changed in your startup script or at the command line in case |
|
|
590 configure got it wrong, or if you upgrade your gnuplot installation. |
|
|
591 @end defvr |
|
|
592 |
|
2670
|
593 @deftypefn {Function File} {} figure (@var{n}) |
|
|
594 Set the current plot window to plot window @var{n}. This function |
|
|
595 currently requires X11 and a version of gnuplot that supports multiple |
|
|
596 frames. |
|
|
597 @end deftypefn |
|
|
598 |
|
2449
|
599 @defvr {Built-in Variable} gnuplot_has_multiplot |
|
|
600 If the value of this variable is nonzero, Octave assumes that your copy |
|
|
601 of gnuplot has the multiplot support that is included in recent |
|
|
602 3.6beta releases. It's initial value is determined by configure, but it |
|
|
603 can be changed in your startup script or at the command line in case |
|
|
604 configure got it wrong, or if you upgrade your gnuplot installation. |
|
|
605 @end defvr |
|
2333
|
606 |
|
2689
|
607 @node Plot Annotations, Multiple Plots on One Page, Three-Dimensional Plotting, Plotting |
|
|
608 @section Plot Annotations |
|
|
609 |
|
|
610 @deftypefn {Function File} {} grid |
|
|
611 For two-dimensional plotting, force the display of a grid on the plot. |
|
|
612 @end deftypefn |
|
|
613 |
|
|
614 @deftypefn {Function File} {} title (@var{string}) |
|
|
615 Specify a title for the plot. If you already have a plot displayed, use |
|
|
616 the command @code{replot} to redisplay it with the new title. |
|
|
617 @end deftypefn |
|
|
618 |
|
|
619 @deftypefn {Function File} {} xlabel (@var{string}) |
|
|
620 @deftypefnx {Function File} {} ylabel (@var{string}) |
|
|
621 @deftypefnx {Function File} {} zlabel (@var{string}) |
|
|
622 Specify x, y, and z axis labels for the plot. If you already have a plot |
|
|
623 displayed, use the command @code{replot} to redisplay it with the new |
|
|
624 labels. |
|
|
625 @end deftypefn |
|
|
626 |
|
|
627 @node Multiple Plots on One Page, , Plot Annotations, Plotting |
|
2570
|
628 @section Multiple Plots on One Page |
|
|
629 |
|
|
630 The following functions all require a version of @code{gnuplot} that |
|
|
631 supports the multiplot feature. |
|
|
632 |
|
|
633 @deftypefn {Function File} {} mplot (@var{x}, @var{y}) |
|
|
634 @deftypefnx {Function File} {} mplot (@var{x}, @var{y}, @var{fmt}) |
|
|
635 @deftypefnx {Function File} {} mplot (@var{x1}, @var{y1}, @var{x2}, @var{y2}) |
|
2670
|
636 This is a modified version of the @code{plot} function that works with |
|
|
637 the multiplot version of @code{gnuplot} to plot multiple plots per page. |
|
2570
|
638 This plot version automatically advances to the next subplot position |
|
|
639 after each set of arguments are processed. |
|
|
640 |
|
2670
|
641 See the description of the @var{plot} function for the various options. |
|
2570
|
642 @end deftypefn |
|
|
643 |
|
|
644 @deftypefn {Function File} {} multiplot (@var{xn}, @var{yn}) |
|
|
645 Sets and resets multiplot mode. |
|
|
646 |
|
|
647 If the arguments are non-zero, @code{multiplot} will set up multiplot |
|
|
648 mode with @var{xn}, @var{yn} subplots along the @var{x} and @var{y} |
|
|
649 axes. If both arguments are zero, @code{multiplot} closes multiplot |
|
|
650 mode. |
|
|
651 @end deftypefn |
|
|
652 |
|
|
653 @deftypefn {Function File} {} oneplot () |
|
|
654 If in multiplot mode, switches to single plot mode. |
|
|
655 @end deftypefn |
|
|
656 |
|
2670
|
657 @deftypefn {Function File} {} plot_border (...) |
|
|
658 Multiple arguments allowed to specify the sides on which the border |
|
|
659 is shown. Allowed arguments include: |
|
|
660 |
|
|
661 @table @code |
|
|
662 @item "blank" |
|
|
663 No borders displayed. |
|
|
664 |
|
|
665 @item "all" |
|
|
666 All borders displayed |
|
|
667 |
|
|
668 @item "north" |
|
|
669 North Border |
|
|
670 |
|
|
671 @item "south" |
|
|
672 South Border |
|
|
673 |
|
|
674 @item "east" |
|
|
675 East Border |
|
|
676 |
|
|
677 @item "west" |
|
|
678 West Border |
|
|
679 @end table |
|
|
680 |
|
|
681 @noindent |
|
|
682 The arguments may be abbreviated to single characters. Without any |
|
|
683 arguments, @code{plot_border} turns borders off. |
|
|
684 @end deftypefn |
|
|
685 |
|
2570
|
686 @deftypefn {Function File} {} subplot (@var{rows}, @var{cols}, @var{index}) |
|
|
687 @deftypefnx {Function File} {} subplot (@var{rcn}) |
|
|
688 Sets @code{gnuplot} in multiplot mode and plots in location |
|
|
689 given by index (there are @var{cols} by @var{rows} subwindows). |
|
|
690 |
|
|
691 Input: |
|
|
692 |
|
|
693 @table @var |
|
|
694 @item rows |
|
|
695 Number of rows in subplot grid. |
|
|
696 |
|
|
697 @item columns |
|
|
698 Number of columns in subplot grid. |
|
|
699 |
|
|
700 @item index |
|
|
701 Index of subplot where to make the next plot. |
|
|
702 @end table |
|
|
703 |
|
|
704 If only one argument is supplied, then it must be a three digit value |
|
|
705 specifying the location in digits 1 (rows) and 2 (columns) and the plot |
|
|
706 index in digit 3. |
|
|
707 |
|
|
708 The plot index runs row-wise. First all the columns in a row are filled |
|
|
709 and then the next row is filled. |
|
|
710 |
|
|
711 For example, a plot with 4 by 2 grid will have plot indices running as |
|
|
712 follows: |
|
2670
|
713 @iftex |
|
|
714 @tex |
|
|
715 \vskip 10pt |
|
|
716 \hfil\vbox{\offinterlineskip\hrule |
|
|
717 \halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr |
|
|
718 height13pt&1&2&3&4\cr height12pt&&&&\cr\noalign{\hrule} |
|
|
719 height13pt&5&6&7&8\cr height12pt&&&&\cr\noalign{\hrule}}} |
|
|
720 \hfil |
|
|
721 \vskip 10pt |
|
|
722 @end tex |
|
|
723 @end iftex |
|
|
724 @ifinfo |
|
|
725 @display |
|
2570
|
726 @group |
|
2670
|
727 +-----+-----+-----+-----+ |
|
|
728 | 1 | 2 | 3 | 4 | |
|
|
729 +-----+-----+-----+-----+ |
|
|
730 | 5 | 6 | 7 | 8 | |
|
|
731 +-----+-----+-----+-----+ |
|
2570
|
732 @end group |
|
2670
|
733 @end display |
|
|
734 @end ifinfo |
|
2570
|
735 @end deftypefn |
|
|
736 |
|
|
737 @deftypefn {Function File} {} subwindow (@var{xn}, @var{yn}) |
|
|
738 Sets the subwindow position in multiplot mode for the next plot. The |
|
|
739 multiplot mode has to be previously initialized using the |
|
2670
|
740 @code{multiplot} function, otherwise this command just becomes an alias |
|
2689
|
741 to @code{multiplot} |
|
2570
|
742 @end deftypefn |
|
|
743 |
|
|
744 @deftypefn {Function File} {} top_title (@var{string}) |
|
|
745 @deftypefnx {Function File} {} bottom_title (@var{string}) |
|
|
746 Makes a title with text @var{string} at the top (bottom) of the plot. |
|
|
747 @end deftypefn |
