1
## Copyright (C) 1993-2013 John W. Eaton
3
## This file is part of Octave.
5
## Octave is free software; you can redistribute it and/or modify it
6
## under the terms of the GNU General Public License as published by
7
## the Free Software Foundation; either version 3 of the License, or (at
8
## your option) any later version.
10
## Octave is distributed in the hope that it will be useful, but
11
## WITHOUT ANY WARRANTY; without even the implied warranty of
12
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13
## General Public License for more details.
15
## You should have received a copy of the GNU General Public License
16
## along with Octave; see the file COPYING. If not, see
17
## <http://www.gnu.org/licenses/>.
20
## @deftypefn {Function File} {} plot (@var{y})
21
## @deftypefnx {Function File} {} plot (@var{x}, @var{y})
22
## @deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{fmt})
23
## @deftypefnx {Function File} {} plot (@dots{}, @var{property}, @var{value}, @dots{})
24
## @deftypefnx {Function File} {} plot (@var{x1}, @var{y1}, @dots{}, @var{xn}, @var{yn})
25
## @deftypefnx {Function File} {} plot (@var{hax}, @dots{})
26
## @deftypefnx {Function File} {@var{h} =} plot (@dots{})
29
## Many different combinations of arguments are possible. The simplest
37
## where the argument is taken as the set of @var{y} coordinates and the
38
## @var{x} coordinates are taken to be the range @code{1:numel (@var{y})}.
40
## If more than one argument is given, they are interpreted as
43
## plot (@var{y}, @var{property}, @var{value}, @dots{})
50
## plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
57
## plot (@var{x}, @var{y}, @var{fmt}, @dots{})
61
## and so on. Any number of argument sets may appear. The @var{x} and
62
## @var{y} values are interpreted as follows:
66
## If a single data argument is supplied, it is taken as the set of @var{y}
67
## coordinates and the @var{x} coordinates are taken to be the indices of
68
## the elements, starting with 1.
71
## If @var{x} and @var{y} are scalars, a single point is plotted.
74
## @code{squeeze()} is applied to arguments with more than two dimensions,
75
## but no more than two singleton dimensions.
78
## If both arguments are vectors, the elements of @var{y} are plotted versus
79
## the elements of @var{x}.
82
## If @var{x} is a vector and @var{y} is a matrix, then
83
## the columns (or rows) of @var{y} are plotted versus @var{x}.
84
## (using whichever combination matches, with columns tried first.)
87
## If the @var{x} is a matrix and @var{y} is a vector,
88
## @var{y} is plotted versus the columns (or rows) of @var{x}.
89
## (using whichever combination matches, with columns tried first.)
92
## If both arguments are matrices, the columns of @var{y} are plotted
93
## versus the columns of @var{x}. In this case, both matrices must have
94
## the same number of rows and columns and no attempt is made to transpose
95
## the arguments to make the number of rows match.
98
## Multiple property-value pairs may be specified, but they must appear
99
## in pairs. These arguments are applied to the line objects drawn by
100
## @code{plot}. Useful properties to modify are @qcode{"linestyle"},
101
## @qcode{"linewidth"}, @qcode{"color"}, @qcode{"marker"},
102
## @qcode{"markersize"}, @qcode{"markeredgecolor"}, @qcode{"markerfacecolor"}.
104
## The @var{fmt} format argument can also be used to control the plot style.
105
## The format is composed of three parts: linestyle, markerstyle, color.
106
## When a markerstyle is specified, but no linestyle, only the markers are
107
## plotted. Similarly, if a linestyle is specified, but no markerstyle, then
108
## only lines are drawn. If both are specified then lines and markers will
109
## be plotted. If no @var{fmt} and no @var{property}/@var{value} pairs are
110
## given, then the default plot style is solid lines with no markers and the
111
## color determined by the @qcode{"colororder"} property of the current axes.
118
## @multitable @columnfractions 0.06 0.94
119
## @item @samp{-} @tab Use solid lines (default).
120
## @item @samp{--} @tab Use dashed lines.
121
## @item @samp{:} @tab Use dotted lines.
122
## @item @samp{-.} @tab Use dash-dotted lines.
127
## @multitable @columnfractions 0.06 0.94
128
## @item @samp{+} @tab crosshair
129
## @item @samp{o} @tab circle
130
## @item @samp{*} @tab star
131
## @item @samp{.} @tab point
132
## @item @samp{x} @tab cross
133
## @item @samp{s} @tab square
134
## @item @samp{d} @tab diamond
135
## @item @samp{^} @tab upward-facing triangle
136
## @item @samp{v} @tab downward-facing triangle
137
## @item @samp{>} @tab right-facing triangle
138
## @item @samp{<} @tab left-facing triangle
139
## @item @samp{p} @tab pentagram
140
## @item @samp{h} @tab hexagram
145
## @multitable @columnfractions 0.06 0.94
146
## @item @samp{k} @tab blacK
147
## @item @samp{r} @tab Red
148
## @item @samp{g} @tab Green
149
## @item @samp{b} @tab Blue
150
## @item @samp{m} @tab Magenta
151
## @item @samp{c} @tab Cyan
152
## @item @samp{w} @tab White
155
## @item @qcode{";key;"}
156
## Here @qcode{"key"} is the label to use for the plot legend.
159
## The @var{fmt} argument may also be used to assign legend keys.
160
## To do so, include the desired label between semicolons after the
161
## formatting sequence described above, e.g., @qcode{"+b;Key Title;"}.
162
## Note that the last semicolon is required and Octave will generate
163
## an error if it is left out.
165
## Here are some plot examples:
168
## plot (x, y, "or", x, y2, x, y3, "m", x, y4, "+")
171
## This command will plot @code{y} with red circles, @code{y2} with solid
172
## lines, @code{y3} with solid magenta lines, and @code{y4} with points
173
## displayed as @samp{+}.
176
## plot (b, "*", "markersize", 10)
179
## This command will plot the data in the variable @code{b},
180
## with points displayed as @samp{*} and a marker size of 10.
185
## plot (t, cos(t), "-;cos(t);", t, sin(t), "-b;sin(t);");
189
## This will plot the cosine and sine functions and label them accordingly
192
## If the first argument @var{hax} is an axes handle, then plot into this axis,
193
## rather than the current axes returned by @code{gca}.
195
## The optional return value @var{h} is a vector of graphics handles to
196
## the created line objects.
198
## To save a plot, in one of several image formats such as PostScript
199
## or PNG, use the @code{print} command.
201
## @seealso{axis, box, grid, hold, legend, title, xlabel, ylabel, xlim, ylim, ezplot, errorbar, fplot, line, plot3, polar, loglog, semilogx, semilogy, subplot}
206
function h = plot (varargin)
208
[hax, varargin, nargs] = __plt_get_axis_arg__ ("plot", varargin{:});
216
oldfig = get (0, "currentfigure");
220
htmp = __plt__ ("plot", hax, varargin{:});
221
unwind_protect_cleanup
222
if (! isempty (oldfig))
223
set (0, "currentfigure", oldfig);
237
%! title ('plot() of green line at 45 degrees');
242
%! title ('plot() of green stars along a line at 45 degrees');
245
%! x1 = 1:5; y1 = 1:5;
246
%! x2 = 5:9; y2 = 5:-1:1;
247
%! plot (x1,y1,'bo-', x2,y2,'rs-');
249
%! title ({'plot() of blue circles ascending and red squares descending';
250
%! 'connecting lines drawn'});
254
%! plot (x, rand (numel (x), 3))
256
%! title ({'Three random variables', 'x[1x11], y[11x3]'})
260
%! plot (x, rand (3, numel (x)))
262
%! title ({'Three random variables', 'x[1x11], y[3x11]'})
266
%! plot (repmat (x, 2, 1), rand (2, numel (x)), '-s')
268
%! title ({'Vertical lines with random height and lengths', ...
269
%! 'x[2x11], y[2,11]'})
273
%! plot (repmat (x(:), 1, 2), rand (numel (x), 2))
275
%! title ({'Two random variables', 'x[11x2], y[11x2]'})
279
%! shape = [1, 1, numel(x), 2];
280
%! x = reshape (repmat (x(:), 1, 2), shape);
284
%! title ({'Two random variables', 'squeezed from 4-d arrays'})