* Bug #12880 fixed - Graphics: issue a warning when transposing
[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             <warning>
133                 When it is necessary and possible, <literal>plot</literal> transposes <literal>x</literal> and <literal>y</literal>,
134                 to get compatible dimensions; a warning is then issued. For instance,
135                 when <literal>x</literal> has as many rows as <literal>y</literal> has columns.
136                 If <literal>y</literal> is square, it is never transposed.
137             </warning>
138         </para>
139         <para>
140             <literal>y</literal> can also be a function defined as a macro or a
141             primitive. In this case, <literal>x</literal> data must be given (as a vector or
142             matrix) and the corresponding computation <literal>y(x)</literal> is done
143             implicitly.
144         </para>
145         <para>
146             The <literal>LineSpec</literal> and <literal>GlobalProperty</literal> arguments
147             sould be used to customize the plot. Here is a complete list of the
148             available options.
149         </para>
150         <variablelist>
151             <varlistentry>
152                 <term>LineSpec</term>
153                 <listitem>
154                     <para>This option may be used to specify, in a short and easy manner,
155                         how the curves are drawn. It must always be a string containing
156                         references to LineStyle, Marker and Color specifiers.
157                     </para>
158                     <para>These references must be set inside the string (order is not
159                         important) in an unambiguous way. For example, to specify a red
160                         long-dashed line with the diamond mark enabled, you can write :
161                         <literal>'r--d'</literal> or <literal>'--dire'</literal> or
162                         <literal>'--reddiam'</literal> or another unambiguous statement... or to be
163                         totally complete <literal>'diamondred--'</literal> (see
164                         <link linkend="LineSpec">LineSpec</link>).
165                     </para>
166                     <para>Note that the line style and color, marks color (and sizes) can
167                         also be (re-)set through the polyline entity properties (see
168                         <link linkend="polyline_properties">polyline_properties</link>).
169                     </para>
170                 </listitem>
171             </varlistentry>
172             <varlistentry>
173                 <term>GlobalProperty</term>
174                 <listitem>
175                     <para>This option may be used to specify how all the curves are
176                         plotted using more option than via <literal>LineSpec</literal>. It must
177                         always be a couple statement constituted of a string defining the
178                         <literal>PropertyName</literal>, and its associated value
179                         <literal>PropertyValue</literal> (which can be a string or an integer or...
180                         as well depending on the type of the <literal>PropertyName</literal>). Using
181                         <literal>GlobalProperty</literal>, you can set multiple properties : every
182                         properties available via LineSpec and more : the marker color
183                         (foreground and background), the visibility, clipping and thickness of
184                         the curves. (see <link linkend="GlobalProperty">GlobalProperty</link>)
185                     </para>
186                     <para>Note that all these properties can be (re-)set through the
187                         polyline entity properties (see <link linkend="polyline_properties">polyline_properties</link>).
188                     </para>
189                 </listitem>
190             </varlistentry>
191         </variablelist>
192     </refsection>
193     <refsection>
194         <title>Remarks</title>
195         <para>By default, successive plots are superposed. To clear the previous
196             plot, use <literal>clf()</literal>. To enable <literal>auto_clear</literal> mode as
197             the default mode, edit your default axes doing:
198         </para>
199         <para>da=gda();</para>
200         <para>da.auto_clear = 'on'</para>
201         <para>
202             For a better display <literal>plot</literal> function may modify the <literal>box</literal> property of
203             its parent Axes. This happens when the parent Axes were created by the call to <literal>plot</literal> or were empty
204             before the call. If one of the axis is centered at origin,
205             the box is disabled.
206             Otherwise, the box is enabled.
207         </para>
208         <para>
209             For more information about box property and axis positionning see <link linkend="axes_properties">axes_properties</link>
210         </para>
211         <para>A default color table is used to color plotted curves if you do not
212             specify a color. When drawing multiple lines, the plot command
213             automatically cycles through this table. Here are the used colors:
214         </para>
215         <informaltable border="1">
216             <tr>
217                 <td>
218                     <literal>R</literal>
219                 </td>
220                 <td>
221                     <literal>G</literal>
222                 </td>
223                 <td>
224                     <literal>B</literal>
225                 </td>
226             </tr>
227             <tr>
228                 <td>0.</td>
229                 <td>0.</td>
230                 <td>1.</td>
231             </tr>
232             <tr>
233                 <td>0.</td>
234                 <td>0.5</td>
235                 <td>0.</td>
236             </tr>
237             <tr>
238                 <td>1.</td>
239                 <td>0.</td>
240                 <td>0.</td>
241             </tr>
242             <tr>
243                 <td>0.</td>
244                 <td>0.75</td>
245                 <td>0.75</td>
246             </tr>
247             <tr>
248                 <td>0.75</td>
249                 <td>0.</td>
250                 <td>0.75</td>
251             </tr>
252             <tr>
253                 <td>0.75</td>
254                 <td>0.75</td>
255                 <td>0.</td>
256             </tr>
257             <tr>
258                 <td>0.25</td>
259                 <td>0.25</td>
260                 <td>0.25</td>
261             </tr>
262         </informaltable>
263         <para/>
264         <para>
265             Enter the command <literal>plot</literal> to see a demo.
266         </para>
267     </refsection>
268     <refsection>
269         <title>Examples</title>
270         <programlisting role="example"><![CDATA[
271 // x initialisation
272 x=[0:0.1:2*%pi]';
273 //simple plot
274 plot(sin(x))
275  ]]></programlisting>
276         <scilab:image>
277             x=[0:0.1:2*%pi]';
278             plot(sin(x))
279         </scilab:image>
280         <programlisting role="example"><![CDATA[
281 clf()
282 x=[0:0.1:2*%pi]';
283 plot(x,sin(x))
284  ]]></programlisting>
285         <scilab:image>
286             x=[0:0.1:2*%pi]';
287             plot(x,sin(x))
288         </scilab:image>
289         <programlisting role="example"><![CDATA[
290 clf()
291 //multiple plot
292 x=[0:0.1:2*%pi]';
293 plot(x,[sin(x) sin(2*x) sin(3*x)])
294  ]]></programlisting>
295         <scilab:image>
296             x=[0:0.1:2*%pi]';
297             plot(x,[sin(x) sin(2*x) sin(3*x)])
298         </scilab:image>
299         <programlisting role="example"><![CDATA[
300 clf()
301 x=[0:0.1:2*%pi]';
302 // axis on the right
303 plot(x,sin(x))
304 a=gca(); // Handle on current axes entity
305 a.y_location ="right";
306 clf()
307  ]]></programlisting>
308         <scilab:image>
309             x=[0:0.1:2*%pi]';
310             plot(x,sin(x))
311             a=gca();
312             a.y_location ="right";
313         </scilab:image>
314         <programlisting role="example"><![CDATA[
315 x=[0:0.1:2*%pi]';
316 // axis centered at (0,0)
317 plot(x-4,sin(x),x+2,cos(x))
318 a=gca(); // Handle on axes entity
319 a.x_location = "origin";
320 a.y_location = "origin";
321
322 // Some operations on entities created by plot ...
323 a=gca();
324 a.isoview='on';
325 a.children // list the children of the axes : here it is an Compound child composed of 2 entities
326 poly1= a.children.children(2); //store polyline handle into poly1
327 poly1.foreground = 4; // another way to change the style...
328 poly1.thickness = 3;  // ...and the tickness of a curve.
329 poly1.clip_state='off' // clipping control
330 a.isoview='off';
331  ]]></programlisting>
332         <scilab:image>
333             x=[0:0.1:2*%pi]';
334             plot(x-4,sin(x),x+2,cos(x))
335             a=gca();
336             a.x_location = "origin";
337             a.y_location = "origin";
338             
339             a=gca();
340             a.isoview='on';
341             a.children
342             poly1= a.children.children(2);
343             poly1.foreground = 4;
344             poly1.thickness = 3;
345             poly1.clip_state='off'
346             a.isoview='off';
347             
348         </scilab:image>
349         <programlisting role="example"><![CDATA[
350
351 //LineSpec and GlobalProperty examples:
352 clf();
353 t=0:%pi/20:2*%pi;
354 plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
355 scf(2)
356 plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
357 scf(3)
358 axfig3 = gca();
359 scf(4) // should remain blank
360 plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
361 xdel(winsid())
362  ]]></programlisting>
363         <scilab:image>
364             t=0:%pi/20:2*%pi;
365             plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
366             scf(2)
367             plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
368             scf(3)
369             axfig3 = gca();
370             scf(4) // should remain blank
371             plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
372         </scilab:image>
373         <programlisting role="example"><![CDATA[
374 //Data specification
375 t=-%pi:0.1:%pi;
376 size(t)
377 plot(t) // simply plots y versus t vector size
378  ]]></programlisting>
379         <scilab:image>
380             t=-%pi:0.1:%pi;
381             size(t)
382             plot(t)
383         </scilab:image>
384         <programlisting role="example"><![CDATA[
385 clf(); // clear figure
386 t=-%pi:0.1:%pi;
387 plot(t,sin(t)); // plots sin(t) versus t
388
389  ]]></programlisting>
390         <scilab:image>
391             t=-%pi:0.1:%pi;
392             plot(t,sin(t));
393         </scilab:image>
394         <programlisting role="example"><![CDATA[
395 clf();
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  ]]></programlisting>
403         <scilab:image>
404             t=[1     1     1     1
405             2     3     4     5
406             3     4     5     6
407             4     5     6     7];
408             
409             plot(t) // plots each t column versus row size
410         </scilab:image>
411         <programlisting role="example"><![CDATA[
412 clf();
413 t=[1     1     1     1
414    2     3     4     5
415    3     4     5     6
416    4     5     6     7];
417
418 subplot(221)
419 plot(t,sin(t)); // plots sin(t) versus t column by column this time
420 xtitle("sin(t) versus t")
421 subplot(222)
422 plot(t,sin(t)')
423 xtitle("sin(t)'' versus t")
424 subplot(223)
425 plot(t',sin(t))
426 a=gca();
427 a.data_bounds=[0 -1;7 1]; // to see the vertical line hiddden by the y axis
428 xtitle("sin(t) versus t''")
429 subplot(224)
430 plot(t',sin(t)')
431 xtitle("sin(t)'' versus t''")
432
433  ]]></programlisting>
434         <scilab:image>
435             t=[1     1     1     1
436             2     3     4     5
437             3     4     5     6
438             4     5     6     7];
439             
440             subplot(221)
441             plot(t,sin(t)); // plots sin(t) versus t column by column this time
442             xtitle("sin(t) versus t")
443             subplot(222)
444             plot(t,sin(t)')
445             xtitle("sin(t)'' versus t")
446             subplot(223)
447             plot(t',sin(t))
448             a=gca();
449             a.data_bounds=[0 -1;7 1]; // to see the vertical line hiddden by the y axis
450             xtitle("sin(t) versus t''")
451             subplot(224)
452             plot(t',sin(t)')
453             xtitle("sin(t)'' versus t''")
454         </scilab:image>
455         <programlisting role="example"><![CDATA[
456
457 clf();
458 t=[1     1     1     1
459    2     3     4     5
460    3     4     5     6
461    4     5     6     7];
462
463 //Special case 1
464 //x : vector ([5 6 7 8]) and y : matrix (t)
465 x=[5 6 7 8]
466 plot(x,t);
467 plot(x',t); // idem, x is automatically transposed to match t (here the columns)
468  ]]></programlisting>
469         <scilab:image>
470             t=[1     1     1     1
471             2     3     4     5
472             3     4     5     6
473             4     5     6     7];
474             
475             x=[5 6 7 8]
476             plot(x,t);
477             plot(x',t);
478         </scilab:image>
479         <programlisting role="example"><![CDATA[
480 clf()
481 x=[5 6 7 8]
482
483 t=[1     1     1     1
484    2     3     4     5
485    3     4     5     6
486    4     5     6     7];
487
488 // Only one matching possibility case : how to make 4 identical plots in 4 manners...
489 // x is 1x4 (vector) and y is 4x5 (non square matrix)
490 subplot(221);
491 plot(x,[t [8;9;10;12]]');
492 subplot(222);
493 plot(x',[t [8;9;10;12]]');
494 subplot(223);
495 plot(x,[t [8;9;10;12]]');
496 subplot(224);
497 plot(x',[t [8;9;10;12]]');
498  ]]></programlisting>
499         <scilab:image>
500             x=[5 6 7 8]
501             
502             t=[1     1     1     1
503             2     3     4     5
504             3     4     5     6
505             4     5     6     7];
506             
507             // Only one matching possibility case : how to make 4 identical plots in 4 manners...
508             // x is 1x4 (vector) and y is 4x5 (non square matrix)
509             subplot(221);
510             plot(x,[t [8;9;10;12]]');
511             subplot(222);
512             plot(x',[t [8;9;10;12]]');
513             subplot(223);
514             plot(x,[t [8;9;10;12]]');
515             subplot(224);
516             plot(x',[t [8;9;10;12]]');
517         </scilab:image>
518         <programlisting role="example"><![CDATA[
519 clf()
520
521 t=[1     1     1     1
522    2     3     4     5
523    3     4     5     6
524    4     5     6     7];
525
526 //Special case 2
527 // Case where only x or y is a square matrix
528 //x : matrix (t) and y  : vector ([1 2 3 4])
529 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])
530 plot(t,[1;2;3;4]) // the same plot
531  ]]></programlisting>
532         <scilab:image>
533             t=[1     1     1     1
534             2     3     4     5
535             3     4     5     6
536             4     5     6     7];
537             
538             //Special case 2
539             // Case where only x or y is a square matrix
540             //x : matrix (t) and y  : vector ([1 2 3 4])
541             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])
542             plot(t,[1;2;3;4]) // the same plot
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
551 // t is transposed : notice the priority given to the columns treatment
552 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])
553 plot(t',[1 2 3 4]') // the same plot
554  ]]></programlisting>
555         <scilab:image>
556             t=[1     1     1     1
557             2     3     4     5
558             3     4     5     6
559             4     5     6     7];
560             clf();
561             
562             // t is transposed : notice the priority given to the columns treatment
563             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])
564             plot(t',[1 2 3 4]') // the same plot
565         </scilab:image>
566         <programlisting role="example"><![CDATA[
567 clf();
568 // y is a function defined by..
569 // ..a primitive
570 plot(1:0.1:10,sin) // equivalent to plot(1:0.1:10,sin(1:0.1:10))
571
572  ]]></programlisting>
573         <scilab:image>
574             plot(1:0.1:10,sin)
575         </scilab:image>
576         <programlisting role="example"><![CDATA[
577 clf();
578 // ..a macro:
579 deff('[y]=toto(x)','y=x.*x')
580 plot(1:10,toto)
581  ]]></programlisting>
582         <scilab:image>
583             deff('[y]=toto(x)','y=x.*x')
584             plot(1:10,toto)
585         </scilab:image>
586     </refsection>
587     <refsection role="see also">
588         <title>See Also</title>
589         <simplelist type="inline">
590             <member>
591                 <link linkend="plot2d">plot2d</link>
592             </member>
593             <member>
594                 <link linkend="surf">surf</link>
595             </member>
596             <member>
597                 <link linkend="scf">scf</link>
598             </member>
599             <member>
600                 <link linkend="clf">clf</link>
601             </member>
602             <member>
603                 <link linkend="xdel">xdel</link>
604             </member>
605             <member>
606                 <link linkend="delete">delete</link>
607             </member>
608             <member>
609                 <link linkend="LineSpec">LineSpec</link>
610             </member>
611             <member>
612                 <link linkend="GlobalProperty">GlobalProperty</link>
613             </member>
614         </simplelist>
615     </refsection>
616 </refentry>