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