<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
<?xml-stylesheet type="text/xsl" href="file:///usr/local/lib/scilab/man/eng/html-rev.xsl"?>
<MAN>
  <LANGUAGE>eng</LANGUAGE>

  <TITLE>plot</TITLE>

  <TYPE>Scilab Function</TYPE>

  <DATE>February 2005</DATE>

  <SHORT_DESCRIPTION name="plot">2D plot</SHORT_DESCRIPTION>

  <CALLING_SEQUENCE>
    <CALLING_SEQUENCE_ITEM>plot(y,&lt;LineSpec&gt;,&lt;GlobalProperty&gt;)</CALLING_SEQUENCE_ITEM>

    <CALLING_SEQUENCE_ITEM>plot(x,y,&lt;LineSpec&gt;,&lt;GlobalProperty&gt;)</CALLING_SEQUENCE_ITEM>

    <CALLING_SEQUENCE_ITEM>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;)</CALLING_SEQUENCE_ITEM>

    <CALLING_SEQUENCE_ITEM>plot(&lt;axes_handle&gt;,...)</CALLING_SEQUENCE_ITEM>
  </CALLING_SEQUENCE>

  <PARAM>
    <PARAM_INDENT>
      <PARAM_ITEM>
        <PARAM_NAME>x</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: a real matrice or vector. If omitted, it is assumed to be the
          vector <VERB>1:n</VERB> where <VERB>n</VERB> is the number of curve
          points given by the <VERB>y</VERB> parameter.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
        <PARAM_NAME>y</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: a real matrice or vector. <VERB>y</VERB> can also be a
          function defined as a macro or a primitive.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
        <PARAM_NAME>&lt;LineSpec&gt;</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: This optional argument must be a string that will be used as a
          shortcut to specify a way of drawing a line. We can have one
          <VERB>LineSpec</VERB> per<VERB> y</VERB> or <VERB>{x,y}</VERB>
          previously entered. <VERB>LineSpec</VERB> options deals with
          LineStyle, Marker and Color specifiers (see <LINK>LineSpec</LINK>).
          Those specifiers determine the line style, mark style and color of
          the plotted lines.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
        <PARAM_NAME>&lt;GlobalProperty&gt;</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: This optional argument represents a sequence of couple
          statements <VERB>{PropertyName,PropertyValue}</VERB> that defines
          global objects' properties applied to all the curves created by this
          plot. For a complete view of the available properties (see
          <LINK>GlobalProperty</LINK>).</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
        <PARAM_NAME>&lt;axes_handle&gt;</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: This optional argument forces the plot to appear inside the
          selected axes given by <VERB>axes_handle</VERB> rather than the
          current axes (see <LINK>gca</LINK>).</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
    </PARAM_INDENT>
  </PARAM>

  <DESCRIPTION>
    <P><VERB>plot</VERB> plots a set of 2D curves. <VERB>plot</VERB> has been
    rebuild to better handle Matlab syntax. To improve graphical
    compatibility, Matlab users should use <VERB>plot</VERB> (rather than
    <LINK>plot2d</LINK>).</P>

    <P>Data entry specification :</P>

    <P>In this paragraph and to be more clear, we won't mention
    <VERB>LineSpec</VERB> nor <VERB>GlobalProperty</VERB> optional arguments
    as they do not interfer with entry data (except for <VERB>"Xdata"</VERB>,
    <VERB>"Ydata"</VERB> and <VERB>"Zdata"</VERB> property, see
    <LINK>GlobalProperty</LINK>). It is assumed that all those optional
    arguments could be present too.</P>

    <P>If <VERB>y</VERB> is a vector, plot(y) plots vector <VERB>y</VERB>
    versus vector <VERB>1:size(y,'*')</VERB>.</P>

    <P>If <VERB>y</VERB> is a matrix, plot(y) plots each columns of
    <VERB>y</VERB> versus vector <VERB>1:size(y,1)</VERB>.</P>

    <P>If <VERB>x</VERB> and <VERB>y</VERB> are vectors, plot(x,y) plots
    vector <VERB>y</VERB> versus vector <VERB>x</VERB>. <VERB>x</VERB> and
    <VERB>y</VERB> vectors should have the same number of entries.</P>

    <P>If <VERB>x</VERB> is a vector and <VERB>y</VERB> a matrix plot(x,y)
    plots each columns of <VERB>y</VERB> versus vector <VERB>x</VERB>. In this
    case the number of columns of <VERB>y</VERB> should be equal to the number
    of <VERB>x</VERB> entries.</P>

    <P>If <VERB>x</VERB> and <VERB>y</VERB> are matrices, plot(x,y) plots each
    columns of <VERB>y</VERB> versus corresponding column of <VERB>x</VERB>.
    In this case the <VERB>x</VERB> and <VERB>y</VERB> sizes should be the
    same.</P>

    <P>Finally, if only <VERB>x</VERB> or <VERB>y</VERB> is a matrix, the
    vector is plotted versus the rows or columns of the matrix. The choice is
    made depending on whether the vector's row or column dimension matches the
    matrix row or column dimension. In case of a square matrix (on
    <VERB>x</VERB> or <VERB>y</VERB> only), priority is given to columns
    rather than lines (see examples below).</P>

    <P><VERB>y</VERB> can also be a function defined as a macro or a
    primitive. In this case, <VERB>x</VERB> data must be given (as a vector or
    matrix) and the corresponding computation <VERB>y(x)</VERB> is done
    implicitly.</P>

    <P>The <VERB>LineSpec</VERB> and <VERB>GlobalProperty</VERB> arguments
    sould be used to customize the plot. Here is a complete list of the
    available options.</P>

    <DESCRIPTION_INDENT>
      <DESCRIPTION_ITEM></DESCRIPTION_ITEM>
    </DESCRIPTION_INDENT>

    <DESCRIPTION_INDENT>
      <DESCRIPTION_ITEM label="LineSpec">
        <SP>: This option may be used to specify, in a short and easy manner,
        how the curves are drawn. It must always be a string containing
        references to LineStyle, Marker and Color specifiers.</SP>

        <SP>These references must be set inside the string (order is not
        important) in an unambiguous way. For example, to specify a red
        long-dashed line with the diamond mark enabled, you can write :
        <VERB>'r--d'</VERB> or <VERB>'--dire'</VERB> or
        <VERB>'--reddiam'</VERB> or another unambiguous statement... or to be
        totally complete <VERB>'diamondred--'</VERB> (see
        <LINK>LineSpec</LINK>).</SP>

        <P>Note that the line style and color, marks color (and sizes) can
        also be (re-)set throught the polyline entity properties (see
        <LINK>polyline_properties</LINK>).</P>

        <DESCRIPTION_INDENT>
          <DESCRIPTION_ITEM></DESCRIPTION_ITEM>
        </DESCRIPTION_INDENT>

        <DESCRIPTION_INDENT>
          <DESCRIPTION_ITEM></DESCRIPTION_ITEM>
        </DESCRIPTION_INDENT>
      </DESCRIPTION_ITEM>

      <DESCRIPTION_ITEM label="GlobalProperty">
        <SP>: This option may be used to specify how all the curves are
        plotted using more option than via <VERB>LineSpec</VERB>. It must
        always be a couple statement constituted of a string defining the
        <VERB>PropertyName</VERB>, and its associated value
        <VERB>PropertyValue</VERB> (which can be a string or an integer or...
        as well depending on the type of the <VERB>PropertyName</VERB>). Using
        <VERB>GlobalProperty</VERB>, you can set multiple properties : every
        properties available via LineSpec and more : the marker color
        (foreground and background), the visibility, clipping and thickness of
        the curves. (see <LINK>GlobalProperty</LINK>)</SP>

        <P>Note that all these properties can be (re-)set throught the
        polyline entity properties (see <LINK>polyline_properties</LINK>).</P>
      </DESCRIPTION_ITEM>
    </DESCRIPTION_INDENT>
  </DESCRIPTION>

  <SECTION label="Remarks">
    <P>By default, successive plots are superposed. To clear the previous
    plot, use <VERB>clf()</VERB>. To enable <VERB>auto_clear</VERB> mode as
    the default mode, edit your default axes doing:</P>

    <P>da=gda();</P>

    <P>da.auto_clear = 'on'</P>

    <P>A default color table is used to color plotted curves if you do not
    specify a color. When drawing multiple lines, the plot command
    automatically cycles through this table. Here are the used colors:</P>

    <TABLE>
      <TABLE_NEW_ROW>
        <TABLE_NEW_COLUMN><VERB>R</VERB></TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN><VERB>G</VERB></TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN><VERB>B</VERB></TABLE_NEW_COLUMN>
      </TABLE_NEW_ROW>

      <TABLE_NEW_ROW>
        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>1.</TABLE_NEW_COLUMN>
      </TABLE_NEW_ROW>

      <TABLE_NEW_ROW>
        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.5</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>
      </TABLE_NEW_ROW>

      <TABLE_NEW_ROW>
        <TABLE_NEW_COLUMN>1.</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>
      </TABLE_NEW_ROW>

      <TABLE_NEW_ROW>
        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.75</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.75</TABLE_NEW_COLUMN>
      </TABLE_NEW_ROW>

      <TABLE_NEW_ROW>
        <TABLE_NEW_COLUMN>0.75</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.75</TABLE_NEW_COLUMN>
      </TABLE_NEW_ROW>

      <TABLE_NEW_ROW>
        <TABLE_NEW_COLUMN>0.75</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.75</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.</TABLE_NEW_COLUMN>
      </TABLE_NEW_ROW>

      <TABLE_NEW_ROW>
        <TABLE_NEW_COLUMN>0.25</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.25</TABLE_NEW_COLUMN>

        <TABLE_NEW_COLUMN>0.25</TABLE_NEW_COLUMN>
      </TABLE_NEW_ROW>
    </TABLE>

    <P></P>

    <P>Enter the command <VERB>plot</VERB> to see a demo.</P>
  </SECTION>

  <EXAMPLE><![CDATA[
// x initialisation 
x=[0:0.1:2*%pi]';
//simple plot
plot(sin(x))
clf()
plot(x,sin(x))
//multiple plot
clf()
plot(x,[sin(x) sin(2*x) sin(3*x)])
clf()

// axis on the right 
plot(x,sin(x)) 
a=gca(); // Handle on current axes entity 
a.y_location ="right"; 
clf()

// axis centered at (0,0)
plot(x-4,sin(x),x+2,cos(x))
a=gca(); // Handle on axes entity
a.x_location = "middle"; 
a.y_location = "middle"; 

// Some operations on entities created by plot ...
a=gca();
a.isoview='on'; 
a.children // list the children of the axes : here it is an Compound child composed of 2 entities 
poly1= a.children.children(2); //store polyline handle into poly1 
poly1.foreground = 4; // another way to change the style...
poly1.thickness = 3;  // ...and the tickness of a curve.
poly1.clip_state='off' // clipping control
a.isoview='off'; 

//LineSpec and GlobalProperty examples:
clf();
t=0:%pi/20:2*%pi;
plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
scf(2)
plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
scf(3)
axfig3 = gca();
scf(4) // should remain blank
plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
xdel(winsid())

//Data specification
t=-%pi:0.1:%pi;
size(t)
plot(t) // simply plots y versus t vector size
clf(); // clear figure

plot(t,sin(t)); // plots sin(t) versus t
clf();

t=[1     1     1     1
   2     3     4     5
   3     4     5     6
   4     5     6     7];

plot(t) // plots each t column versus row size
clf();

subplot(221)
plot(t,sin(t)); // plots sin(t) versus t column by column this time
xtitle("sin(t) versus t")
subplot(222)
plot(t,sin(t)')
xtitle("sin(t)'' versus t")
subplot(223)
plot(t',sin(t))
a=gca();
a.data_bounds=[0 -1;7 1]; // to see the vertical line hiddden by the y axis
xtitle("sin(t) versus t''")
subplot(224)
plot(t',sin(t)')
xtitle("sin(t)'' versus t''")

clf();

//Special case 1
//x : vector ([5 6 7 8]) and y : matrix (t)
x=[5 6 7 8]
plot(x,t);
plot(x',t); // idem, x is automatically transposed to match t (here the columns)
clf()

// Only one matching possibility case : how to make 4 identical plots in 4 manners...
// x is 1x4 (vector) and y is 4x5 (non square matrix)
subplot(221);
plot(x,[t [8;9;10;12]]');
subplot(222);
plot(x',[t [8;9;10;12]]');
subplot(223);
plot(x,[t [8;9;10;12]]');
subplot(224);
plot(x',[t [8;9;10;12]]');
clf()


//Special case 2
// Case where only x or y is a square matrix
//x : matrix (t) and y  : vector ([1 2 3 4])
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])
plot(t,[1;2;3;4]) // the same plot
clf();

// t is transposed : notice the priority given to the columns treatment
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]) 
plot(t',[1 2 3 4]') // the same plot 
clf();

// y is a function defined by..
// ..a primitive
plot(1:0.1:10,sin) // equivalent to plot(1:0.1:10,sin(1:0.1:10))
clf();

// ..a macro:
deff('[y]=toto(x)','y=x.*x')
plot(1:10,toto)
 
]]></EXAMPLE>

  <SEE_ALSO>
    <SEE_ALSO_ITEM>
      <LINK>plot2d</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>surf</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>scf</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>clf</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>xdel</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>delete</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>LineSpec</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>GlobalProperty</LINK>
    </SEE_ALSO_ITEM>
  </SEE_ALSO>

  <AUTHOR>F.Leray</AUTHOR>
</MAN>