2d89c2a9ef636d57a354812d70c2b6497f406e15
[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 a=gca();
327 a.isoview='on';
328 a.children // list the children of the axes : here it is an Compound child composed of 2 entities
329 poly1= a.children.children(2); //store polyline handle into poly1
330 poly1.foreground = 4; // another way to change the style...
331 poly1.thickness = 3;  // ...and the thickness of a curve.
332 poly1.clip_state='off' // clipping control
333 a.isoview='off';
334  ]]></programlisting>
335         <scilab:image>
336             x=[0:0.1:2*%pi]';
337             plot(x-4,sin(x),x+2,cos(x))
338             a=gca();
339             a.x_location = "origin";
340             a.y_location = "origin";
341             
342             a=gca();
343             a.isoview='on';
344             a.children
345             poly1= a.children.children(2);
346             poly1.foreground = 4;
347             poly1.thickness = 3;
348             poly1.clip_state='off'
349             a.isoview='off';
350             
351         </scilab:image>
352         <programlisting role="example"><![CDATA[
353
354 //LineSpec and GlobalProperty examples:
355 clf();
356 t=0:%pi/20:2*%pi;
357 plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
358 scf(2)
359 plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
360 scf(3)
361 axfig3 = gca();
362 scf(4) // should remain blank
363 plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
364 xdel(winsid())
365  ]]></programlisting>
366         <scilab:image>
367             t=0:%pi/20:2*%pi;
368             plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
369             scf(2)
370             plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
371             scf(3)
372             axfig3 = gca();
373             scf(4) // should remain blank
374             plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
375         </scilab:image>
376         <programlisting role="example"><![CDATA[
377 //Data specification
378 t=-%pi:0.1:%pi;
379 size(t)
380 plot(t) // simply plots y versus t vector size
381  ]]></programlisting>
382         <scilab:image>
383             t=-%pi:0.1:%pi;
384             size(t)
385             plot(t)
386         </scilab:image>
387         <programlisting role="example"><![CDATA[
388 clf(); // clear figure
389 t=-%pi:0.1:%pi;
390 plot(t,sin(t)); // plots sin(t) versus t
391
392  ]]></programlisting>
393         <scilab:image>
394             t=-%pi:0.1:%pi;
395             plot(t,sin(t));
396         </scilab:image>
397         <programlisting role="example"><![CDATA[
398 clf();
399 t=[1     1     1     1
400    2     3     4     5
401    3     4     5     6
402    4     5     6     7];
403
404 plot(t) // plots each t column versus row size
405  ]]></programlisting>
406         <scilab:image>
407             t=[1     1     1     1
408             2     3     4     5
409             3     4     5     6
410             4     5     6     7];
411             
412             plot(t) // plots each t column versus row size
413         </scilab:image>
414         <programlisting role="example"><![CDATA[
415 clf();
416 t=[1     1     1     1
417    2     3     4     5
418    3     4     5     6
419    4     5     6     7];
420
421 subplot(221)
422 plot(t,sin(t)); // plots sin(t) versus t column by column this time
423 xtitle("sin(t) versus t")
424 subplot(222)
425 plot(t,sin(t)')
426 xtitle("sin(t)'' versus t")
427 subplot(223)
428 plot(t',sin(t))
429 a=gca();
430 a.data_bounds=[0 -1;7 1]; // to see the vertical line hidden by the y axis
431 xtitle("sin(t) versus t''")
432 subplot(224)
433 plot(t',sin(t)')
434 xtitle("sin(t)'' versus t''")
435
436  ]]></programlisting>
437         <scilab:image>
438             t=[1     1     1     1
439             2     3     4     5
440             3     4     5     6
441             4     5     6     7];
442             
443             subplot(221)
444             plot(t,sin(t)); // plots sin(t) versus t column by column this time
445             xtitle("sin(t) versus t")
446             subplot(222)
447             plot(t,sin(t)')
448             xtitle("sin(t)'' versus t")
449             subplot(223)
450             plot(t',sin(t))
451             a=gca();
452             a.data_bounds=[0 -1;7 1]; // to see the vertical line hidden by the y axis
453             xtitle("sin(t) versus t''")
454             subplot(224)
455             plot(t',sin(t)')
456             xtitle("sin(t)'' versus t''")
457         </scilab:image>
458         <programlisting role="example"><![CDATA[
459
460 clf();
461 t=[1     1     1     1
462    2     3     4     5
463    3     4     5     6
464    4     5     6     7];
465
466 //Special case 1
467 //x : vector ([5 6 7 8]) and y : matrix (t)
468 x=[5 6 7 8]
469 plot(x,t);
470 plot(x',t); // idem, x is automatically transposed to match t (here the columns)
471  ]]></programlisting>
472         <scilab:image>
473             t=[1     1     1     1
474             2     3     4     5
475             3     4     5     6
476             4     5     6     7];
477             
478             x=[5 6 7 8];
479             plot(x',t);
480         </scilab:image>
481         <programlisting role="example"><![CDATA[
482 clf()
483 x=[5 6 7 8]
484
485 t=[1     1     1     1
486    2     3     4     5
487    3     4     5     6
488    4     5     6     7];
489
490 // Only one matching possibility case: how to make 4 identical plots in 4 manners...
491 // x is 1x4 (vector) and y is 4x5 (non square matrix)
492 subplot(221);
493 plot(x,[t [8;9;10;12]]');
494 subplot(222);
495 plot(x',[t [8;9;10;12]]);
496 subplot(223);
497 plot(x,[t [8;9;10;12]]');
498 subplot(224);
499 plot(x',[t [8;9;10;12]]');
500  ]]></programlisting>
501         <scilab:image>
502             x=[5 6 7 8]
503             
504             t=[1     1     1     1
505             2     3     4     5
506             3     4     5     6
507             4     5     6     7];
508             
509             // Only one matching possibility case : how to make 4 identical plots in 4 manners...
510             // x is 1x4 (vector) and y is 4x5 (non square matrix)
511             subplot(221);
512             plot(x',[t [8;9;10;12]]);
513             subplot(222);
514             plot(x',[t [8;9;10;12]]);
515             subplot(223);
516             plot(x',[t [8;9;10;12]]);
517             subplot(224);
518             plot(x',[t [8;9;10;12]]);
519         </scilab:image>
520         <programlisting role="example"><![CDATA[
521 clf()
522
523 t=[1     1     1     1
524    2     3     4     5
525    3     4     5     6
526    4     5     6     7];
527
528 //Special case 2
529 // Case where only x or y is a square matrix
530 //x : matrix (t) and y  : vector ([1 2 3 4])
531 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])
532 plot(t,[1;2;3;4]') // the same plot, but here Y needs to be transposed
533  ]]></programlisting>
534         <scilab:image>
535             t=[1     1     1     1
536             2     3     4     5
537             3     4     5     6
538             4     5     6     7];
539             
540             //Special case 2
541             // Case where only x or y is a square matrix
542             //x : matrix (t) and y  : vector ([1 2 3 4])
543             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])
544         </scilab:image>
545         <programlisting role="example"><![CDATA[
546 t=[1     1     1     1
547    2     3     4     5
548    3     4     5     6
549    4     5     6     7];
550 clf();
551 cols = 1:4;
552
553 // cols is transposed : notice the priority given to the columns treatment
554 plot(t', cols) // equivalent to plot(t',[1 1 1 1;2 2 2 2;3 3 3 3;4 4 4 4])
555 plot(t', cols') // the same plot
556  ]]></programlisting>
557         <scilab:image>
558             t=[1     1     1     1
559             2     3     4     5
560             3     4     5     6
561             4     5     6     7];
562             clf();
563             cols = 1:4;
564             
565             // cols is transposed : notice the priority given to the columns treatment
566             plot(t',cols') // the same plot
567         </scilab:image>
568         <programlisting role="example"><![CDATA[
569 clf();
570 // y is a function defined by..
571 // ..a primitive
572 plot(1:0.1:10,sin) // equivalent to plot(1:0.1:10,sin(1:0.1:10))
573
574  ]]></programlisting>
575         <scilab:image>
576             plot(1:0.1:10,sin)
577         </scilab:image>
578         <programlisting role="example"><![CDATA[
579 clf();
580 // ..a macro:
581 deff('[y]=toto(x)','y=x.*x')
582 plot(1:10,toto)
583  ]]></programlisting>
584         <scilab:image>
585             deff('[y]=toto(x)','y=x.*x')
586             plot(1:10,toto)
587         </scilab:image>
588     </refsection>
589     <refsection role="see also">
590         <title>See Also</title>
591         <simplelist type="inline">
592             <member>
593                 <link linkend="plot2d">plot2d</link>
594             </member>
595             <member>
596                 <link linkend="surf">surf</link>
597             </member>
598             <member>
599                 <link linkend="scf">scf</link>
600             </member>
601             <member>
602                 <link linkend="clf">clf</link>
603             </member>
604             <member>
605                 <link linkend="xdel">xdel</link>
606             </member>
607             <member>
608                 <link linkend="delete">delete</link>
609             </member>
610             <member>
611                 <link linkend="LineSpec">LineSpec</link>
612             </member>
613             <member>
614                 <link linkend="GlobalProperty">GlobalProperty</link>
615             </member>
616         </simplelist>
617     </refsection>
618 </refentry>