<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 * Copyright (C) 2009 - DIGITEO - Pierre Lando
 * Copyright (C) 2010 - DIGITEO - Yann Collette
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2020 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org"  xml:id="plot2d" xml:lang="en">
    <refnamediv>
        <refname>plot2d</refname>
        <refpurpose>2D plot</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            plot2d()   // example
            plot2d(y)
            plot2d(x, y)
            plot2d(logflag, x, y)
            plot2d(.., y, style)
            plot2d(.., y, style, strf)
            plot2d(.., y, style, strf, leg)
            plot2d(.., y, style, strf, leg, rect)
            plot2d(.., y, style, strf, leg, rect, nax)
            plot2d(.., y, key1=value1, key2=value2, ..)
        </synopsis>
    </refsynopsisdiv>
    <refsection role="arguments">
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x</term>
                <listitem>
                    a real matrix or vector of abscissae. If omitted, abscissae are assumed to
                    be  <literal>1:n</literal> for all curves, where <literal>n</literal> is the
                    number of points in curves, as given by <varname>y</varname>.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    real matrix or vector: Ordinates
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>key1=value1, key2=value2, ...</term>
                <listitem>
                    <para>
                        The following options <varname>logflag</varname>, <varname>style</varname>,
                        <varname>strf</varname>, <varname>leg</varname>, <varname>rect</varname>,
                        <varname>nax</varname>, <varname>frameflag</varname>, and
                        <varname>axesflag</varname> described below can either be listed in the
                        right order as listed in the synopses, or provided in any order after
                        <varname>y</varname> as named arguments, for instance like in
                        <literal>plot(y, frameflag=3, leg="Curve 1@Curve 2")</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>logflag</term>
                <listitem>
                    <para>
                        Sets the linear or logarithmic scale for both X and Y axes.
                        Possible values are <literal>"nn"</literal>, <literal>"nl"</literal> ,
                        <literal>"ln"</literal> or <literal>"ll"</literal>.
                        <literal>"n"</literal> stands for
                        <emphasis role="bold">n</emphasis>ormal scale ;
                        <literal>"l"</literal> stands for
                        <emphasis role="bold">l</emphasis>ogarithmic.
                        The first letter set the X axis. The second one sets the Y axis.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>style</term>
                <listitem>
                    <para>
                        Sets the respective line or mark styles of the curves.
                        It is a vector of decimal integers with one element per curve:
                    </para>
                    <itemizedlist>
                        <listitem>
                            if <literal>style(i)</literal> is strictly positive, the
                            curve is drawn as plain line and <literal>style(i)</literal>
                            defines the index of the color used to draw the curve
                            (see <link linkend="getcolor">getcolor</link>).
                        </listitem>
                        <listitem>
                            if <literal>style(i)</literal> is negative or zero, the
                            given curve points are drawn using marks. Then
                            <literal>abs(style(i))</literal> is the mark's id.
                            <para/>
                        </listitem>
                    </itemizedlist>
                    <para>
                        Note that all curves properties -- like also their color,
                        thickness, marks colors, etc -- can be set through their handles
                        (see <link linkend="polyline_properties">polyline_properties</link>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>strf</term>
                <listitem>
                    3-character-long string <literal>"abc"</literal> specifying all
                    together if legends must be displayed, and the values of
                    <varname>frameflag</varname> and <varname>axesflag</varname>.
                    By default, <literal>strf= "081"</literal>. "a", "b" and "c" are:
                    <para/>
                    <table cellpadding="0">
                        <tr valign="top">
                            <th>a :</th>
                            <td>controls the display of captions:
                                <table cellpadding="0">
                                    <tr><th>a=0 :</th><td>no caption.</td></tr>
                                    <tr><th>a=1 :</th>
                                        <td>captions given by the optional argument
                                            <varname>leg</varname> are displayed.</td>
                                    </tr>
                                </table>
                            </td>
                        </tr>
                        <tr valign="top">
                            <th>b :</th>
                            <td>
                                <varname>frameflag</varname> integer code in [0,9],
                                controlling the computation the actual coordinate ranges,
                                as described below.
                            </td>
                        </tr>
                        <tr valign="top">
                            <th>c :</th>
                            <td>
                                <varname>axesflag</varname> integer code in [0:5 9],
                                controlling the display and position of X and Y axes,
                                as described below.
                            </td>
                        </tr>
                    </table>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>leg</term>
                <listitem>
                    <para>
                        Single string <literal>"leg1@leg2@...."</literal> setting
                        the legends leg1, leg2, etc for the respective curves #1, #2,
                        etc. The default is <literal> " "</literal>. The block
                        of legends is drawn on the bottom, below the x-axis.
                    </para>
                    <para>
                        After plotting, the handle of the block of legends can be
                        retrieved with <literal>gca().children(2)</literal>.
                        <link linkend="captions">captions</link>,
                        <link linkend="legend">legend</link> or
                        <link linkend="legends">legends</link> can also be used
                        instead of <varname>leg</varname>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rect</term>
                <listitem>
                    <para>
                        Vector of decimal numbers <literal>[xmin, ymin, xmax, ymax]</literal>
                        setting the minimal bounds requested for the plot.
                        <literal>[xmin, xmax]</literal> is the X-axis range, and
                        <literal>[ymin, ymax]</literal> is the Y-axis one.
                    </para>
                    <para>
                        This argument works with the  <varname>frameflag</varname>
                        option to specify how the actual axes boundaries are computed.
                        If the <varname>frameflag</varname> option is not given,
                        it is supposed to be <literal>frameflag=7</literal>.
                    </para>
                    <para>
                        The axes boundaries can also be customized through the
                        <literal>gca().data_bounds</literal> property of the axes
                        (see <link linkend="axes_properties">axes_properties</link>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nax</term>
                <listitem>
                    <para>
                        Vector of decimal integers <literal>[nx,Nx,ny,Ny]</literal>
                        specifying the numbers Nx and Ny of major ticks, and the
                        numbers nx and ny of minor ticks between 2 majors, for both
                        respective axes. To use autoticking on an axis, set Nx=-1 or Ny=-1.
                    </para>
                    <para>
                        If the <varname>axesflag</varname> option is not specified,
                        using <varname>nax</varname> sets and uses
                        <literal>axesflag=9</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>frameflag</term>
                <listitem>
                    <para>controls the computation of the actual coordinate ranges
                        from the minimal requested values. The associated value should
                        be an integer ranging from 0 to 8.
                    </para>
                    <para>
                <table border="1" cellpadding="2">
                    <tr><th>frameflag</th><th>axes bounds</th>      <th>other actions</th></tr>
                    <tr align="center">
                        <th>0</th>        <td>unchanged</td>        <td></td></tr>
                    <tr align="center">
                        <th>1</th>        <td>from rect</td>        <td></td></tr>
                    <tr align="center">
                        <th>2</th>        <td>from input x,y</td>   <td></td></tr>
                    <tr align="center">
                        <th>3</th>        <td>from rect</td>        <td>isometric axes</td></tr>
                    <tr align="center">
                        <th>4</th>        <td>from input x,y</td>   <td>isometric axes</td></tr>
                    <tr align="center">
                        <th>5</th>        <td>from rect</td>        <td>pretty axes</td></tr>
                    <tr align="center">
                        <th>6</th>        <td>from input x,y</td>   <td>pretty axes</td></tr>
                    <tr align="center">
                        <th>7</th>        <td>from rect</td>        <td>all replot with new scales</td></tr>
                    <tr align="center">
                        <th>8</th>        <td>from input x,y</td>   <td>all replot with new scales</td></tr>
                    <tr align="center">
                        <th>9</th>        <td>from input x,y</td>   <td>Pretty axes. All replot with new scales</td></tr>
                </table>
                    </para>
                    <para>
                        The setting of axes boundaries can also be customized through
                        the <literal>gca().data_bounds</literal>,
                        <literal>gca().tight_limits</literal>,
                        <literal>gca().data_bounds</literal>, and
                        <literal>gca().isoview</literal> properties
                        (see <link linkend="axes_properties">axes_properties</link>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>axesflag</term>
                <listitem>
                    <para>
                        integer code in [0:5 9], controlling the display and position of
                        X and Y axes.
                    </para>
                    <para>
                        The axes aspect can also be customized directly through the
                        <literal>gca().box</literal>, <literal>gca().axes_visible</literal>,
                        <literal>gca().x_location</literal>, and <literal>gca().y_location</literal>,
                        properties (see <link linkend="axes_properties">axes_properties</link>).
                    </para>
        <table border="1" cellpadding="2">
            <tr><th>axesFlag</th><th>.box</th><th>.axes_visible</th><th>axes position</th><th>comments</th></tr>
            <tr align="center">
                <th>0</th><td>"off"</td><td>["off" "off"]</td><td></td>     <td>Naked plot</td></tr>
            <tr align="center">
                <th>1</th><td>"on"</td> <td>["on" "on"]</td>  <td></td>     <td></td></tr>
            <tr align="center">
                <th>2</th><td>"on"</td> <td>["off" "off"]</td><td></td>     <td>Naked box</td></tr>
            <tr align="center">
                <th>3</th><td>"off"</td><td>["on" "on"]</td>  <td>y_location="right"</td><td></td></tr>
            <tr align="center">
                <th>4</th><td>"off"</td><td>["on" "on"]</td>  <td>crossed @ middle</td><td></td></tr>
            <tr align="center">
                <th>5</th><td>"on"</td> <td>["on" "on"]</td>  <td>crossed @ middle</td><td></td></tr>
            <tr align="center">
                <th>9</th><td>"off"</td><td>["on" "on"]</td>  <td></td>     <td>(default setting)</td></tr>
        </table>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Description</title>
        <para>
            <literal>plot2d</literal> plots a set of 2D curves. Piecewise linear interpolation
            is done between the given curve points.
        </para>
        <para>
            Any point with <literal>y(i)=Nan</literal> is masked: no mark and no segment to its
            neighboors are displayed.
        </para>
        <para>
            For any point with <literal>y(i)=±Inf</literal>, a vertical segment starting
            from each of its both neighboors is drawn in the ± direction, up to the current ceil
            or down to the current floor of the axes.
        </para>
        <para>
            By default, successive calls to plot2d() overplots new curves over existing ones.
            Autoclearing for each new plot can be set using <literal>gca().auto_clear="on"</literal>.
            Please see <link linkend="axes_properties">axes properties</link>.
            <literal><link linkend="clf">clf</link></literal> can also be used to manually clear
            the whole figure.
        </para>
        <para>
            If you are familiar with Matlab <literal>plot</literal> syntax, you should use
            <link linkend="plot">plot</link> instead.
        </para>
        <para>
            If <literal>x</literal> and <literal>y</literal> are vectors,
            plot2d(x,y,…) plots vector <literal>y</literal> versus
            vector <literal>x</literal>. <literal>x</literal> and <literal>y</literal>
            vectors should have the same number of entries.
        </para>
        <para>
            If <literal>x</literal> is a vector and <literal>y</literal> a
            matrix plot2d(x,y,…) plots each columns of
            <literal>y</literal> versus vector <literal>x</literal>. The
            number of rows of <literal>y</literal> must be equal to the number of
            <literal>x</literal> entries.
        </para>
        <para>
            If <literal>x</literal> and <literal>y</literal> are matrices,
            plot2d(x,y,…) plots each columns of <literal>y</literal>
            versus corresponding column of <literal>x</literal>.
            <literal>x</literal> and <literal>y</literal> must then have the same sizes.
        </para>
        <para>
            If <literal>y</literal> is a vector, plot2d(y,…)
            plots vector <literal>y</literal> versus vector
            <literal>1:size(y,'*')</literal>.
        </para>
        <para>
            If <literal>y</literal> is a matrix, plot2d(y,…)
            plots each columns of <literal>y</literal> versus vector
            <literal>1:size(y,1)</literal>.
        </para>
        <para>
            Enter the command <literal>plot2d()</literal> to see a demo.
        </para>
        <para>Other high level plot2d functions exist:</para>
        <itemizedlist>
            <listitem>
                <para>
                    plot2d2 same as <literal>plot2d</literal> but the curve is
                    supposed to be piecewise constant.
                </para>
            </listitem>
            <listitem>
                <para>
                    plot2d3 same as <literal>plot2d</literal> but the curve is
                    plotted with vertical bars.
                </para>
            </listitem>
            <listitem>
                <para>
                    plot2d4 same as <literal>plot2d</literal> but the curve is
                    plotted with vertical arrows.
                </para>
            </listitem>
        </itemizedlist>
    </refsection>
    <refsection role="examples">
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// x initialisation
x=[0:0.1:2*%pi]';
//simple plot
plot2d(sin(x));
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(sin(x));
        </scilab:image>
        <programlisting role="example"><![CDATA[
clf();
x=[0:0.1:2*%pi]';
plot2d(x,sin(x));
//multiple plot
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,sin(x));
        </scilab:image>
        <programlisting role="example"><![CDATA[
clf();
x=[0:0.1:2*%pi]';
plot2d(x,[sin(x) sin(2*x) sin(3*x)])
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,[sin(x) sin(2*x) sin(3*x)])
        </scilab:image>
        <programlisting role="example"><![CDATA[
// multiple plot giving the dimensions of the frame
clf();
x=[0:0.1:2*%pi]';
plot2d(x,[sin(x) sin(2*x) sin(3*x)],rect=[0,0,6,0.5]);
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,[sin(x) sin(2*x) sin(3*x)],rect=[0,0,6,0.5]);
        </scilab:image>
        <programlisting role="example"><![CDATA[
//multiple plot with captions and given tics + style
clf();
x=[0:0.1:2*%pi]';
plot2d(x,[sin(x) sin(2*x) sin(3*x)],..
       [1,2,3],leg="L1@L2@L3",nax=[2,10,2,10],rect=[0,-2,2*%pi,2]);
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,[sin(x) sin(2*x) sin(3*x)],..
            [1,2,3],leg="L1@L2@L3",nax=[2,10,2,10],rect=[0,-2,2*%pi,2]);
        </scilab:image>
        <programlisting role="example"><![CDATA[
// isoview
clf();
x=[0:0.1:2*%pi]';
plot2d(x,sin(x),1,frameflag= 4);
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,sin(x),1,frameflag= 4);
        </scilab:image>
        <programlisting role="example"><![CDATA[
// scale
clf();
x=[0:0.1:2*%pi]';
plot2d(x,sin(x),1,frameflag= 6);
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,sin(x),1,frameflag= 6);
        </scilab:image>
        <programlisting role="example"><![CDATA[
// auto scaling with previous plots + style
clf();
x=[0:0.1:2*%pi]';
plot2d(x,sin(x),-1);
plot2d(x,2*sin(x),12);
plot2d(2*x,cos(x),3);
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,sin(x),-1);
            plot2d(x,2*sin(x),12);
            plot2d(2*x,cos(x),3);
        </scilab:image>
        <programlisting role="example"><![CDATA[
// axis on the right
clf();
x=[0:0.1:2*%pi]';
plot2d(x,sin(x),leg="sin(x)");
a=gca(); // Handle on axes entity
a.y_location ="right";
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,sin(x),leg="sin(x)");
            a=gca(); // Handle on axes entity
            a.y_location ="right";
        </scilab:image>
        <programlisting role="example"><![CDATA[

// axis centered at (0,0)
clf();
x=[0:0.1:2*%pi]';
plot2d(x-4,sin(x),1,leg="sin(x)");
a=gca(); // Handle on axes entity
a.x_location = "origin";
a.y_location = "origin";
// Some operations on entities created by plot2d ...
isoview
a=gca();
a.children // list the children of the axes.
// There are a compound made of two polylines and a legend
poly1= a.children(1).children(1); //store polyline handle into poly1
poly1.foreground = 4; // another way to change the style...
poly1.thickness = 3;  // ...and the thickness of a curve.
poly1.clip_state='off'; // clipping control
leg = a.children(2); // store legend handle into leg
leg.font_style = 9;
leg.line_mode = "on";
isoview off
 ]]></programlisting>
        <scilab:image>
            // axis centered at (0,0)
            clf();
            x=[0:0.1:2*%pi]';
            plot2d(x-4,sin(x),1,leg="sin(x)");
            a=gca(); // Handle on axes entity
            a.x_location = "origin";
            a.y_location = "origin";
            // Some operations on entities created by plot2d ...
            isoview()
            a=gca();
            a.children // list the children of the axes.
            // There are a compound made of two polylines and a legend
            poly1= a.children(1).children(1); //store polyline handle into poly1
            poly1.foreground = 4; // another way to change the style...
            poly1.thickness = 3;  // ...and the thickness of a curve.
            poly1.clip_state='off'; // clipping control
            leg = a.children(2); // store legend handle into leg
            leg.font_style = 9;
            leg.line_mode = "on";
            isoview("off")
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="plot">plot</link>
            </member>
            <member>
                <link linkend="polyline_properties">.polyline_style</link>
            </member>
            <member>
                <link linkend="plot2d2">plot2d2</link>
            </member>
            <member>
                <link linkend="plot2d3">plot2d3</link>
            </member>
            <member>
                <link linkend="plot2d4">plot2d4</link>
            </member>
            <member>
                <link linkend="polarplot">polarplot</link>
            </member>
            <member>
                <link linkend="gca">gca</link>
            </member>
            <member>
                <link linkend="close">close</link>
            </member>
            <member>
                <link linkend="axes_properties">axes_properties</link>
            </member>
            <member>
                <link linkend="clf">clf</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
