424029efd7bef8e82c285d22e08b571312f03c46
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / plot.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Fabrice Leray
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="plot">
17     <refnamediv>
18         <refname>plot</refname>
19         <refpurpose>2D plot</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>plot(y,&lt;LineSpec&gt;,&lt;GlobalProperty&gt;)
24             plot(x,y,&lt;LineSpec&gt;,&lt;GlobalProperty&gt;)
25             plot(x1,y1,&lt;LineSpec1&gt;,x2,y2,&lt;LineSpec2&gt;,...xN,yN,&lt;LineSpecN&gt;,&lt;GlobalProperty1&gt;,&lt;GlobalProperty2&gt;,..&lt;GlobalPropertyM&gt;)
26             plot(&lt;axes_handle&gt;,...)
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>x</term>
34                 <listitem>
35                     <para>a real matrix or vector. If omitted, it is assumed to be the
36                         vector <literal>1:n</literal> where <literal>n</literal> is the number of curve
37                         points given by the <literal>y</literal> parameter.
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>y</term>
43                 <listitem>
44                     <para>
45                         a real matrix or vector. <literal>y</literal> can also be a
46                         function defined as a macro or a primitive.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>&lt;LineSpec&gt;</term>
52                 <listitem>
53                     <para>This optional argument must be a string that will be used as a
54                         shortcut to specify a way of drawing a line. We can have one
55                         <literal>LineSpec</literal> per <literal>y</literal> or <literal>{x,y}</literal>
56                         previously entered. <literal>LineSpec</literal> options deals with
57                         LineStyle, Marker and Color specifiers (see <link linkend="LineSpec">LineSpec</link>).
58                         Those specifiers determine the line style, mark style and color of
59                         the plotted lines.
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>&lt;GlobalProperty&gt;</term>
65                 <listitem>
66                     <para>This optional argument represents a sequence of couple
67                         statements <literal>{PropertyName,PropertyValue}</literal> that defines
68                         global objects' properties applied to all the curves created by this
69                         plot. For a complete view of the available properties (see
70                         <link linkend="GlobalProperty">GlobalProperty</link>).
71                     </para>
72                 </listitem>
73             </varlistentry>
74             <varlistentry>
75                 <term>&lt;axes_handle&gt;</term>
76                 <listitem>
77                     <para>This optional argument forces the plot to appear inside the
78                         selected axes given by <literal>axes_handle</literal> rather than the
79                         current axes (see <link linkend="gca">gca</link>).
80                     </para>
81                 </listitem>
82             </varlistentry>
83         </variablelist>
84     </refsection>
85     <refsection>
86         <title>Description</title>
87         <para>
88             <literal>plot</literal> plots a set of 2D curves. <literal>plot</literal> has been
89             rebuild to better handle Matlab syntax. To improve graphical
90             compatibility, Matlab users should use <literal>plot</literal> (rather than
91             <link linkend="plot2d">plot2d</link>).
92         </para>
93         <para>Data entry specification :</para>
94         <para>In this paragraph and to be more clear, we won't mention
95             <literal>LineSpec</literal> nor <literal>GlobalProperty</literal> optional arguments
96             as they do not interfere with entry data (except for <literal>"Xdata"</literal>,
97             <literal>"Ydata"</literal> and <literal>"Zdata"</literal> property, see
98             <link linkend="GlobalProperty">GlobalProperty</link>). It is assumed that all those optional
99             arguments could be present too.
100         </para>
101         <para>
102             If <literal>y</literal> is a vector, plot(y) plots vector <literal>y</literal>
103             versus vector <literal>1:size(y,'*')</literal>.
104         </para>
105         <para>
106             If <literal>y</literal> is a matrix, plot(y) plots each columns of
107             <literal>y</literal> versus vector <literal>1:size(y,1)</literal>.
108         </para>
109         <para>
110             If <literal>x</literal> and <literal>y</literal> are vectors, plot(x,y) plots
111             vector <literal>y</literal> versus vector <literal>x</literal>. <literal>x</literal> and
112             <literal>y</literal> vectors should have the same number of entries.
113         </para>
114         <para>
115             If <literal>x</literal> is a vector and <literal>y</literal> a matrix plot(x,y)
116             plots each columns of <literal>y</literal> versus vector <literal>x</literal>. In this
117             case the number of columns of <literal>y</literal> should be equal to the number
118             of <literal>x</literal> entries.
119         </para>
120         <para>
121             If <literal>x</literal> and <literal>y</literal> are matrices, plot(x,y) plots each
122             columns of <literal>y</literal> versus corresponding column of <literal>x</literal>.
123             In this case the <literal>x</literal> and <literal>y</literal> sizes should be the
124             same.
125         </para>
126         <para>
127             Finally, if only <literal>x</literal> or <literal>y</literal> is a matrix, the
128             vector is plotted versus the rows or columns of the matrix. The choice is
129             made depending on whether the vector's row or column dimension matches the
130             matrix row or column dimension. In case of a square matrix (on
131             <literal>x</literal> or <literal>y</literal> only), priority is given to columns
132             rather than lines (see examples below).
133         </para>
134         <para>
135             <warning>
136                 When it is necessary and possible, <literal>plot</literal> transposes <literal>x</literal> and <literal>y</literal>,
137                 to get compatible dimensions; a warning is then issued. For instance,
138                 when <literal>x</literal> has as many rows as <literal>y</literal> has columns.
139                 If <literal>y</literal> is square, it is never transposed.
140             </warning>
141         </para>
142         <para>
143             <literal>y</literal> can also be a function defined as a macro or a
144             primitive. In this case, <literal>x</literal> data must be given (as a vector or
145             matrix) and the corresponding computation <literal>y(x)</literal> is done
146             implicitly.
147         </para>
148         <para>
149             The <literal>LineSpec</literal> and <literal>GlobalProperty</literal> arguments
150             should be used to customize the plot. Here is a complete list of the
151             available options.
152         </para>
153         <variablelist>
154             <varlistentry>
155                 <term>LineSpec</term>
156                 <listitem>
157                     <para>This option may be used to specify, in a short and easy manner,
158                         how the curves are drawn. It must always be a string containing
159                         references to LineStyle, Marker and Color specifiers.
160                     </para>
161                     <para>These references must be set inside the string (order is not
162                         important) in an unambiguous way. For example, to specify a red
163                         long-dashed line with the diamond mark enabled, you can write :
164                         <literal>'r--d'</literal> or <literal>'--dire'</literal> or
165                         <literal>'--reddiam'</literal> or another unambiguous statement... or to be
166                         totally complete <literal>'diamondred--'</literal> (see
167                         <link linkend="LineSpec">LineSpec</link>).
168                     </para>
169                     <para>Note that the line style and color, marks color (and sizes) can
170                         also be (re-)set through the polyline entity properties (see
171                         <link linkend="polyline_properties">polyline_properties</link>).
172                     </para>
173                 </listitem>
174             </varlistentry>
175             <varlistentry>
176                 <term>GlobalProperty</term>
177                 <listitem>
178                     <para>This option may be used to specify how all the curves are
179                         plotted using more option than via <literal>LineSpec</literal>. It must
180                         always be a couple statement constituted of a string defining the
181                         <literal>PropertyName</literal>, and its associated value
182                         <literal>PropertyValue</literal> (which can be a string or an integer or...
183                         as well depending on the type of the <literal>PropertyName</literal>). Using
184                         <literal>GlobalProperty</literal>, you can set multiple properties : every
185                         properties available via LineSpec and more : the marker color
186                         (foreground and background), the visibility, clipping and thickness of
187                         the curves. (see <link linkend="GlobalProperty">GlobalProperty</link>)
188                     </para>
189                     <para>Note that all these properties can be (re-)set through the
190                         polyline entity properties (see <link linkend="polyline_properties">polyline_properties</link>).
191                     </para>
192                 </listitem>
193             </varlistentry>
194         </variablelist>
195     </refsection>
196     <refsection>
197         <title>Remarks</title>
198         <para>By default, successive plots are superposed. To clear the previous
199             plot, use <literal>clf()</literal>. To enable <literal>auto_clear</literal> mode as
200             the default mode, edit your default axes doing:
201         </para>
202         <para>da=gda();</para>
203         <para>da.auto_clear = 'on'</para>
204         <para>
205             For a better display <literal>plot</literal> function may modify the <literal>box</literal> property of
206             its parent Axes. This happens when the parent Axes were created by the call to <literal>plot</literal> or were empty
207             before the call. If one of the axis is centered at origin,
208             the box is disabled.
209             Otherwise, the box is enabled.
210         </para>
211         <para>
212             For more information about box property and axis positioning see <link linkend="axes_properties">axes_properties</link>
213         </para>
214         <para>A default color table is used to color plotted curves if you do not
215             specify a color. When drawing multiple lines, the plot command
216             automatically cycles through this table. Here are the used colors:
217         </para>
218         <informaltable border="1">
219             <tr>
220                 <td>
221                     <literal>R</literal>
222                 </td>
223                 <td>
224                     <literal>G</literal>
225                 </td>
226                 <td>
227                     <literal>B</literal>
228                 </td>
229             </tr>
230             <tr>
231                 <td>0.</td>
232                 <td>0.</td>
233                 <td>1.</td>
234             </tr>
235             <tr>
236                 <td>0.</td>
237                 <td>0.5</td>
238                 <td>0.</td>
239             </tr>
240             <tr>
241                 <td>1.</td>
242                 <td>0.</td>
243                 <td>0.</td>
244             </tr>
245             <tr>
246                 <td>0.</td>
247                 <td>0.75</td>
248                 <td>0.75</td>
249             </tr>
250             <tr>
251                 <td>0.75</td>
252                 <td>0.</td>
253                 <td>0.75</td>
254             </tr>
255             <tr>
256                 <td>0.75</td>
257                 <td>0.75</td>
258                 <td>0.</td>
259             </tr>
260             <tr>
261                 <td>0.25</td>
262                 <td>0.25</td>
263                 <td>0.25</td>
264             </tr>
265         </informaltable>
266         <para/>
267         <para>
268             Enter the command <literal>plot</literal> to see a demo.
269         </para>
270     </refsection>
271     <refsection>
272         <title>Examples</title>
273         <programlisting role="example"><![CDATA[
274 // x initialisation
275 x=[0:0.1:2*%pi]';
276 //simple plot
277 plot(sin(x))
278  ]]></programlisting>
279         <scilab:image>
280             x=[0:0.1:2*%pi]';
281             plot(sin(x))
282         </scilab:image>
283         <programlisting role="example"><![CDATA[
284 clf()
285 x=[0:0.1:2*%pi]';
286 plot(x,sin(x))
287  ]]></programlisting>
288         <scilab:image>
289             x=[0:0.1:2*%pi]';
290             plot(x,sin(x))
291         </scilab:image>
292         <programlisting role="example"><![CDATA[
293 clf()
294 //multiple plot
295 x=[0:0.1:2*%pi]';
296 plot(x,[sin(x) sin(2*x) sin(3*x)])
297  ]]></programlisting>
298         <scilab:image>
299             x=[0:0.1:2*%pi]';
300             plot(x,[sin(x) sin(2*x) sin(3*x)])
301         </scilab:image>
302         <programlisting role="example"><![CDATA[
303 clf()
304 x=[0:0.1:2*%pi]';
305 // axis on the right
306 plot(x,sin(x))
307 a=gca(); // Handle on current axes entity
308 a.y_location ="right";
309 clf()
310  ]]></programlisting>
311         <scilab:image>
312             x=[0:0.1:2*%pi]';
313             plot(x,sin(x))
314             a=gca();
315             a.y_location ="right";
316         </scilab:image>
317         <programlisting role="example"><![CDATA[
318 x=[0:0.1:2*%pi]';
319 // axis centered at (0,0)
320 plot(x-4,sin(x),x+2,cos(x))
321 a=gca(); // Handle on axes entity
322 a.x_location = "origin";
323 a.y_location = "origin";
324
325 // Some operations on entities created by plot ...
326 isoview("on");
327 a.children // list the children of the axes : here it is an Compound child composed of 2 entities
328 poly1= a.children.children(2); //store polyline handle into poly1
329 poly1.foreground = 4; // another way to change the style...
330 poly1.thickness = 3;  // ...and the thickness of a curve.
331 poly1.clip_state='off' // clipping control
332 isoview("off");
333  ]]></programlisting>
334         <scilab:image>
335             x=[0:0.1:2*%pi]';
336             plot(x-4,sin(x),x+2,cos(x))
337             isoview()
338             a=gca();
339             a.x_location = "origin";
340             a.y_location = "origin";
341             a.children
342             poly1= a.children.children(2);
343             poly1.foreground = 4;
344             poly1.thickness = 3;
345             poly1.clip_state='off'
346             isoview("off");
347         </scilab:image>
348         <programlisting role="example"><![CDATA[
349
350 //LineSpec and GlobalProperty examples:
351 clf();
352 t=0:%pi/20:2*%pi;
353 plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
354 scf(2)
355 plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
356 scf(3)
357 axfig3 = gca();
358 scf(4) // should remain blank
359 plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
360 xdel(winsid())
361  ]]></programlisting>
362         <scilab:image>
363             t=0:%pi/20:2*%pi;
364             plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
365             scf(2)
366             plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
367             scf(3)
368             axfig3 = gca();
369             scf(4) // should remain blank
370             plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
371         </scilab:image>
372         <programlisting role="example"><![CDATA[
373 //Data specification
374 t=-%pi:0.1:%pi;
375 size(t)
376 plot(t) // simply plots y versus t vector size
377  ]]></programlisting>
378         <scilab:image>
379             t=-%pi:0.1:%pi;
380             size(t)
381             plot(t)
382         </scilab:image>
383         <programlisting role="example"><![CDATA[
384 clf(); // clear figure
385 t=-%pi:0.1:%pi;
386 plot(t,sin(t)); // plots sin(t) versus t
387
388  ]]></programlisting>
389         <scilab:image>
390             t=-%pi:0.1:%pi;
391             plot(t,sin(t));
392         </scilab:image>
393         <programlisting role="example"><![CDATA[
394 clf();
395 t=[1     1     1     1
396    2     3     4     5
397    3     4     5     6
398    4     5     6     7];
399
400 plot(t) // plots each t column versus row size
401  ]]></programlisting>
402         <scilab:image>
403             t=[1     1     1     1
404             2     3     4     5
405             3     4     5     6
406             4     5     6     7];
407
408             plot(t) // plots each t column versus row size
409         </scilab:image>
410         <programlisting role="example"><![CDATA[
411 clf();
412 t=[1     1     1     1
413    2     3     4     5
414    3     4     5     6
415    4     5     6     7];
416
417 subplot(221)
418 plot(t,sin(t)); // plots sin(t) versus t column by column this time
419 xtitle("sin(t) versus t")
420 subplot(222)
421 plot(t,sin(t)')
422 xtitle("sin(t)'' versus t")
423 subplot(223)
424 plot(t',sin(t))
425 a=gca();
426 a.data_bounds=[0 -1;7 1]; // to see the vertical line hidden by the y axis
427 xtitle("sin(t) versus t''")
428 subplot(224)
429 plot(t',sin(t)')
430 xtitle("sin(t)'' versus t''")
431
432  ]]></programlisting>
433         <scilab:image>
434             t=[1     1     1     1
435             2     3     4     5
436             3     4     5     6
437             4     5     6     7];
438
439             subplot(221)
440             plot(t,sin(t)); // plots sin(t) versus t column by column this time
441             xtitle("sin(t) versus t")
442             subplot(222)
443             plot(t,sin(t)')
444             xtitle("sin(t)'' versus t")
445             subplot(223)
446             plot(t',sin(t))
447             a=gca();
448             a.data_bounds=[0 -1;7 1]; // to see the vertical line hidden by the y axis
449             xtitle("sin(t) versus t''")
450             subplot(224)
451             plot(t',sin(t)')
452             xtitle("sin(t)'' versus t''")
453         </scilab:image>
454         <programlisting role="example"><![CDATA[
455
456 clf();
457 t=[1     1     1     1
458    2     3     4     5
459    3     4     5     6
460    4     5     6     7];
461
462 //Special case 1
463 //x : vector ([5 6 7 8]) and y : matrix (t)
464 x=[5 6 7 8]
465 plot(x,t);
466 plot(x',t); // idem, x is automatically transposed to match t (here the columns)
467  ]]></programlisting>
468         <scilab:image>
469             t=[1     1     1     1
470             2     3     4     5
471             3     4     5     6
472             4     5     6     7];
473
474             x=[5 6 7 8];
475             plot(x',t);
476         </scilab:image>
477         <programlisting role="example"><![CDATA[
478 clf()
479 x=[5 6 7 8]
480
481 t=[1     1     1     1
482    2     3     4     5
483    3     4     5     6
484    4     5     6     7];
485
486 // Only one matching possibility case: how to make 4 identical plots in 4 manners...
487 // x is 1x4 (vector) and y is 4x5 (non square matrix)
488 subplot(221);
489 plot(x,[t [8;9;10;12]]');
490 subplot(222);
491 plot(x',[t [8;9;10;12]]);
492 subplot(223);
493 plot(x,[t [8;9;10;12]]');
494 subplot(224);
495 plot(x',[t [8;9;10;12]]');
496  ]]></programlisting>
497         <scilab:image>
498             x=[5 6 7 8]
499
500             t=[1     1     1     1
501             2     3     4     5
502             3     4     5     6
503             4     5     6     7];
504
505             // Only one matching possibility case : how to make 4 identical plots in 4 manners...
506             // x is 1x4 (vector) and y is 4x5 (non square matrix)
507             subplot(221);
508             plot(x',[t [8;9;10;12]]);
509             subplot(222);
510             plot(x',[t [8;9;10;12]]);
511             subplot(223);
512             plot(x',[t [8;9;10;12]]);
513             subplot(224);
514             plot(x',[t [8;9;10;12]]);
515         </scilab:image>
516         <programlisting role="example"><![CDATA[
517 clf()
518
519 t=[1     1     1     1
520    2     3     4     5
521    3     4     5     6
522    4     5     6     7];
523
524 //Special case 2
525 // Case where only x or y is a square matrix
526 //x : matrix (t) and y  : vector ([1 2 3 4])
527 plot(t,[1 2 3 4]') // equivalent to plot(t,[1 1 1 1;2 2 2 2;3 3 3 3;4 4 4 4])
528 plot(t,[1;2;3;4]') // the same plot, but here Y needs to be transposed
529  ]]></programlisting>
530         <scilab:image>
531             t=[1     1     1     1
532             2     3     4     5
533             3     4     5     6
534             4     5     6     7];
535
536             //Special case 2
537             // Case where only x or y is a square matrix
538             //x : matrix (t) and y  : vector ([1 2 3 4])
539             plot(t,[1 2 3 4]') // equivalent to plot(t,[1 1 1 1;2 2 2 2;3 3 3 3;4 4 4 4])
540         </scilab:image>
541         <programlisting role="example"><![CDATA[
542 t=[1     1     1     1
543    2     3     4     5
544    3     4     5     6
545    4     5     6     7];
546 clf();
547 cols = 1:4;
548
549 // cols is transposed : notice the priority given to the columns treatment
550 plot(t', cols) // equivalent to plot(t',[1 1 1 1;2 2 2 2;3 3 3 3;4 4 4 4])
551 plot(t', cols') // the same plot
552  ]]></programlisting>
553         <scilab:image>
554             t=[1     1     1     1
555             2     3     4     5
556             3     4     5     6
557             4     5     6     7];
558             clf();
559             cols = 1:4;
560
561             // cols is transposed : notice the priority given to the columns treatment
562             plot(t',cols') // the same plot
563         </scilab:image>
564         <programlisting role="example"><![CDATA[
565 clf();
566 // y is a function defined by..
567 // ..a primitive
568 plot(1:0.1:10,sin) // equivalent to plot(1:0.1:10,sin(1:0.1:10))
569
570  ]]></programlisting>
571         <scilab:image>
572             plot(1:0.1:10,sin)
573         </scilab:image>
574         <programlisting role="example"><![CDATA[
575 clf();
576 // ..a macro:
577 deff('[y]=toto(x)','y=x.*x')
578 plot(1:10,toto)
579  ]]></programlisting>
580         <scilab:image>
581             deff('[y]=toto(x)','y=x.*x')
582             plot(1:10,toto)
583         </scilab:image>
584     </refsection>
585     <refsection role="see also">
586         <title>See also</title>
587         <simplelist type="inline">
588             <member>
589                 <link linkend="plot2d">plot2d</link>
590             </member>
591             <member>
592                 <link linkend="surf">surf</link>
593             </member>
594             <member>
595                 <link linkend="scf">scf</link>
596             </member>
597             <member>
598                 <link linkend="clf">clf</link>
599             </member>
600             <member>
601                 <link linkend="xdel">xdel</link>
602             </member>
603             <member>
604                 <link linkend="delete">delete</link>
605             </member>
606             <member>
607                 <link linkend="LineSpec">LineSpec</link>
608             </member>
609             <member>
610                 <link linkend="GlobalProperty">GlobalProperty</link>
611             </member>
612         </simplelist>
613     </refsection>
614 </refentry>