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