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