<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) Scilab Enterprises - 2015 - 2012 - Juergen Koch
 * 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: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="scatter">
    <refnamediv>
        <refname>scatter</refname>
        <refpurpose>2D scatter plot</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            scatter()   // Example
            scatter(x, y)
            scatter(x, y, msizes)
            scatter(x, y, msizes, mcolors)
            scatter(.., "fill")
            scatter(.., "smallOnTop")
            scatter(.., marker)
            scatter(..., &lt;marker_property, value>)
            scatter(axes, ..)
            polyline = scatter(..)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x, y</term>
                <listitem>
                    <para>
                        Columns or rows vectors of n real numbers specifying the abscissae and the
                        ordinates of the centers of markers.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>axes</term>
                <listitem>
                    Handle of the graphical axes in which the scatter plot must be drawn.
                    By default, the current axes is targeted.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>polyline</term>
                <listitem>
                    Handle of the created polyline.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>msizes</term>
                <listitem>
                    <para>
                        Sizes of the markers, as of the area of the circle surrounding the marker,
                        in point-square. Default value = 36. If it is scalar,
                        the same size is used for all markers. Otherwise <varname>msizes</varname>
                        and <varname>x</varname> must have the same number of elements.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mcolors</term>
                <listitem>
                    <para>
                        Colors of markers. If it is scalar, the same color is used for all markers.
                        Otherwise, <varname>mcolors</varname> and <varname>x</varname> must have
                        the same number of elements.
                    </para>
                    <para>
                        The same color is used for filling the body and drawing the edge of markers.
                    </para>
                    <para>
                        The values of <varname>mcolors</varname> are linearly mapped to the colors
                        in the current colormap.
                    </para>
                    <para>
                        A color can be specified by one of the following:
                        <itemizedlist>
                            <listitem>
                                Its name, among the predefined names colors
                                (see the <link linkend="color_list">color_list</link>).
                            </listitem>
                            <listitem>
                                Its standard hexadecimal RGB code as a string, like "#A532FB".
                            </listitem>
                            <listitem>
                                A matrix of RGB values with 3 columns and n rows, with Red Green and
                                Blue intensities in [0,1].
                            </listitem>
                            <listitem>
                                Its index in the current color map
                            </listitem>
                        </itemizedlist>
                        The default color is "blue".
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"fill"</term>
                <listitem>
                    <para>
                        By default, only the edge of markers is drawn, unless this keyword or the
                        <varname>"markerFaceColor"</varname> or
                        <varname>"markerBackgroundColor"</varname> properties are set.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"smallOnTop"</term>
                <listitem>
                    <para>
                        When markers have not all the same size and the population of points becomes
                        crowdy, big markers can hide smaller ones located around the same place.
                        This option can be used to avoid such masking effects. Then points are
                        priorly sorted by decreasing sizes, in order to plot the smallest points
                        at the end, on top of bigger ones.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>marker</term>
                <listitem>
                    <para>
                        Selects the shape of the markers. The same shape is used for all
                        specified points. The figure below shows the different marker shapes.
                    </para>
                    <para>
                        <inlinemediaobject>
                            <imageobject>
                                <imagedata fileref="../../images/marks.svg"/>
                            </imageobject>
                        </inlinemediaobject>
                    </para>
                    <para>
                        Each marker shape is specified either by its index (list above) or by
                        its string symbol (table below).
                    </para>
                    <para>
                        <informaltable border="1">
                            <tr><td>Index</td>
                                <td>String</td>
                                <td>Marker type</td>
                            </tr>
                            <tr>
                                <td>0</td>
                                <td><literal>"."</literal></td>
                                <td>Point</td>
                            </tr>
                            <tr>
                                <td>1</td>
                                <td><literal>"+"</literal></td>
                                <td>Plus sign</td>
                            </tr>
                            <tr>
                                <td>2</td>
                                <td><literal>"x"</literal></td>
                                <td>Cross</td>
                            </tr>
                            <tr>
                                <td>3</td>
                                <td><literal>"circle plus"</literal></td>
                                <td>Circle with plus</td>
                            </tr>
                            <tr>
                                <td>4</td>
                                <td><literal>"filled diamond"</literal></td>
                                <td>Filled diamond</td>
                            </tr>
                            <tr>
                                <td>5</td>
                                <td><literal>"d"</literal> or <literal>"diamond"</literal></td>
                                <td>Diamond</td>
                            </tr>
                            <tr>
                                <td>6</td>
                                <td><literal>"^"</literal></td>
                                <td>Upward-pointing centered triangle</td>
                            </tr>
                            <tr>
                                <td>7</td>
                                <td><literal>"v"</literal></td>
                                <td>Downward-pointing centered triangle</td>
                            </tr>
                            <tr>
                                <td>8</td>
                                <td><literal>"diamond plus"</literal></td>
                                <td>Diamond with plus</td>
                            </tr>
                            <tr>
                                <td>9</td>
                                <td><literal>"o"</literal></td>
                                <td>Circle (default)</td>
                            </tr>
                            <tr>
                                <td>10</td>
                                <td><literal>"*"</literal></td>
                                <td>Asterisk</td>
                            </tr>
                            <tr>
                                <td>11</td>
                                <td><literal>"s"</literal> or <literal>"square"</literal></td>
                                <td>Square</td>
                            </tr>
                            <tr>
                                <td>12</td>
                                <td><literal>">"</literal></td>
                                <td>Right-pointing centered triangle</td>
                            </tr>
                            <tr>
                                <td>13</td>
                                <td><literal>"&lt;"</literal></td>
                                <td>Left-pointing centered triangle</td>
                            </tr>
                            <tr>
                                <td>14</td>
                                <td><literal>"pentagram"</literal> or <literal>"p"</literal></td>
                                <td>Five-pointed star</td>
                            </tr>
                            <tr>
                                <td>15</td>
                                <td><literal>"^."</literal></td>
                                <td>Upward-pointing triangle</td>
                            </tr>
                            <tr>
                                <td>16</td>
                                <td><literal>"v."</literal></td>
                                <td>Downward-pointing triangle</td>
                            </tr>
                            <tr>
                                <td>17</td>
                                <td><literal>">."</literal></td>
                                <td>Right-pointing triangle</td>
                            </tr>
                            <tr>
                                <td>18</td>
                                <td><literal>"&lt;."</literal></td>
                                <td>Left-pointing triangle</td>
                            </tr>
                            <tr>
                                <td>19</td>
                                <td><literal>"minus" or "m"</literal></td>
                                <td>Horizontal line (Minus sign)</td>
                            </tr>
                            <tr>
                                <td>20</td>
                                <td><literal>"|"</literal></td>
                                <td>Vertical line</td>
                            </tr>
                        </informaltable>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <refsect3>
            <title>Property Name, Value pairs</title>
            <para>
                A series of property &lt;Name,Value> pairs can be used to specify
                the filling color of markers body, the color and thickness of the markers edges,
                or the points on which a datatip must be created.
            </para>
        </refsect3>
        <variablelist>
            <varlistentry>
                <term>"marker",value  or  "markerStyle",value</term>
                <listitem>
                    <para>
                        Shape of the marker (index or string keyword). See the table above.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"markerEdgeColor",value  or  "markerForeground",value</term>
                <listitem>
                    <para>
                        Color of the edge of markers. Colors can be specified as for
                        <varname>mcolors</varname>.
                        This option supersedes <varname>mcolors</varname>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"markerFaceColor",value  or  "markerBackground",value</term>
                <listitem>
                    <para>
                        Color filling the body of markers. Colors can be specified as for
                        <varname>mcolors</varname>.
                        This option supersedes <varname>mcolors</varname>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"linewidth",value  or  "thickness",value</term>
                <listitem>
                    <para>
                        Specify the thickness of the edge for all markers.
                        The unit for the value is one point.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"datatips", k</term>
                <listitem>
                    <para>
                        Creates a datatip for all (X,Y) points whose indices are in the vector
                        <varname>k</varname>. 1:$ targets all existing points.
                    </para>
                    <para>
                        The <literal>datatip_display_mode</literal> is set to
                        <literal>"mouseover"</literal>. The datatip anchor is reduced to a point
                        set at the middle of the marker. The default datatips display the
                        (x,y) coordinates of the point. If <varname>msizes</varname> is a vector,
                        the size of each marker is also displayed.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>scatter(x,y)</literal> creates a scatter plot with markers centered at
            the <literal>(x, y)</literal> set of coordinates.
            The default type of the marker is a circle, the default color is "blue" and the default
            size is 36.
            This means the circle surrounding the marker has an area of 36 points squared.
        </para>
        <para>
            Different sizes and colors for each marker can be specified with
            <literal>scatter(x,y,msizes,mcolors)</literal>.
            There are many different ways to specify marker types, marker colors and marker sizes.
            For more details see the description of the arguments and the examples.
        </para>
        <note>
          To skip an argument, just .. skip it, or replace it with <literal>[]</literal>, like in
          <literal>scatter3d(x,y, , mcolors)</literal> or <literal>scatter3d(x,y,[], mcolors)</literal>.
        </note>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>You can easily categorize a dataset using colors.</para>
        <programlisting role="example"><![CDATA[
// results between -1 and 1
t = linspace(0, 25, 200);
simResults = grand(200, 2, 'unf', -1, 1);
x = simResults(:,1)';
y = simResults(:,2)';

// categorize
c = 9*ones(x);
c(0.4 < x & x < 0.7 & 0.2 < y & y < 0.5) = 2;
c(0.8 < x & x < 1 & 0.3 < y & y < 1) = 3;
c(y > 2*x+0.3) = 4;
c(1 < y.*y + x.*x) = 5;

scatter(x, y, [], c, "fill");
 ]]></programlisting>
        <scilab:image><![CDATA[
// results between -1 and 1
t = linspace(0, 25, 200);
simResults = grand(200, 2, 'unf', -1, 1);
x = simResults(:,1)';
y = simResults(:,2)';

// categorize
c = 9*ones(x);
c(0.4 < x & x < 0.7 & 0.2 < y & y < 0.5) = 2;
c(0.8 < x & x < 1 & 0.3 < y & y < 1) = 3;
c(y > 2*x+0.3) = 4;
c(1 < y.*y + x.*x) = 5;

scatter(x, y, [], c, "fill");
         ]]></scilab:image>

        <para>
            With the default circle shape, and the same color for all points:
        </para>
        <programlisting role="example"><![CDATA[
n = 130;
x = rand(1,n);
y = rand(1,n);

clf
subplot(2,3,1)
scatter(x, y)
title("scatter(x, y)", "fontsize",3)

subplot(2,3,2)
scatter(x, y, 100)
title("scatter(x, y, 100)", "fontsize",3)

subplot(2,3,3)
mAreas = 10.^grand(1,n,"unf",1,2.4);
scatter(x, y, mAreas)
title("scatter(x, y, mAreas)", "fontsize",3)

subplot(2,3,4)
scatter(x, y, , "orange")
tit = "scatter(x, y, ,""orange"")";
title(tit, "fontsize",3)

subplot(2,3,5)
scatter(x, y, "fill")
tit = "scatter(x, y, ""fill"")";
title(tit, "fontsize",3)

subplot(2,3,6)
scatter(x, y, mAreas, "markerBackground", "yellow")
tit = "scatter(x, y, mAreas,""markerBackground"", ""yellow"")";
title(tit, "fontsize",1)
 ]]></programlisting>
        <scilab:image>
            n = 130;
            x = rand(1,n);
            y = rand(1,n);

            clf
            subplot(2,3,1)
            scatter(x, y)
            title("scatter(x, y)", "fontsize",3)

            subplot(2,3,2)
            scatter(x, y, 100)
            title("scatter(x, y, 100)", "fontsize",3)

            subplot(2,3,3)
            mAreas = 10.^grand(1,n,"unf",1,2.4);
            scatter(x, y, mAreas)
            title("scatter(x, y, mAreas)", "fontsize",3)

            subplot(2,3,4)
            scatter(x, y, , "orange")
            tit = "scatter(x, y, ,""orange"")";
            title(tit, "fontsize",3)

            subplot(2,3,5)
            scatter(x, y, "fill")
            tit = "scatter(x, y, ""fill"")";
            title(tit, "fontsize",3)

            subplot(2,3,6)
            scatter(x, y, mAreas, "markerBackground", "yellow")
            tit = "scatter(x, y, mAreas,""markerBackground"", ""yellow"")";
            title(tit, "fontsize",1)

            gcf().axes_size = [750 500];
        </scilab:image>
        <para>
            <emphasis role="bold">Option "smallOnTop"</emphasis>, avoiding intermasking effects:
        </para>
        <programlisting role="example"><![CDATA[
n = 170;
x = rand(1,n);
y = rand(1,n);
mAreas = 10.^grand(1,n,"unf",1,2.8);

clf
subplot(1,2,1)
scatter(x, y, mAreas, "wheat", "fill", "markerEdgeColor", "red")
title("Raw display", "fontsize",3)

subplot(1,2,2)
scatter(x, y, mAreas, "wheat", "fill", "smallOnTop", "markerEdgeColor", "red")
title("""SmallOnTop"" option", "fontsize",3)
 ]]></programlisting>
        <scilab:image>
            n = 170;
            x = rand(1,n);
            y = rand(1,n);
            mAreas = 10.^grand(1,n,"unf",1,2.8);

            clf
            subplot(1,2,1)
            scatter(x, y, mAreas, "wheat", "fill", "markerEdgeColor", "red")
            title("Raw display", "fontsize",3)

            subplot(1,2,2)
            scatter(x, y, mAreas, "wheat", "fill", "SmallOnTop", "markerEdgeColor", "red")
            title("""SmallOnTop"" option", "fontsize",3)

            gcf().axes_size = [600 270];
        </scilab:image>

        <para>
            Vary marker size and color
        </para>
        <programlisting role="example"><![CDATA[
x = linspace(0, 2, 200);
y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x));

s = linspace(1, 30, length(x));     // specify different sizes
gcf().color_map = cool(64); // set color map
c = x;                  // colors according to x values
subplot(1,2,1)
scatter(x, y, s, c);    // create 2D scatter plot

// Fill the markers
subplot(1,2,2)
scatter(x, y, s, c, "fill");
 ]]></programlisting>
        <scilab:image>
            x = linspace(0, 2, 200);
            y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x));

            s = linspace(1, 30, length(x));     // specify different sizes
            gcf().color_map = cool(64); // set color map
            c = x;                  // colors according to x values
            subplot(1,2,1)
            scatter(x, y, s, c);    // create 2D scatter plot

            // Fill the markers
            subplot(1,2,2)
            scatter(x, y, s, c, "fill");
            gcf().axes_size = [700 350];
        </scilab:image>
        <para>
            Specify the marker
        </para>
        <programlisting role="example"><![CDATA[
x = rand(1, 200);
y = rand(1, 200);

subplot(2,2,1)
scatter(x, y, "d");

subplot(2,2,2)
scatter(x, y, "markerEdgeColor",[0 .4 .4],...
              "markerFaceColor","magenta",...
              "linewidth",1.5);

subplot(2,2,3)
scatter(x, y, 60, "red", "+");  // Marker's symbol

subplot(2,2,4)
scatter(x, y, 60, "green", 14); // Marker's index
 ]]></programlisting>
        <scilab:image>
            x = rand(1, 200);
            y = rand(1, 200);

            subplot(2,2,1)
            scatter(x, y, "d");

            subplot(2,2,2)
            scatter(x, y, "markerEdgeColor",[0 .4 .4],...
                          "markerFaceColor","magenta",...
                          "linewidth",1.5);

            subplot(2,2,3)
            scatter(x, y, 60, "red", "+");  // Marker's symbol

            subplot(2,2,4)
            scatter(x, y, 60, "green", 14); // Marker's index

            gcf().axes_size = [600 500];
        </scilab:image>
        <para>
            Post-processing a scatter plot:
        </para>
        <programlisting role="example"><![CDATA[
n = 150;
x = rand(1,n);
y = rand(1,n);
mAreas = 10.^grand(1,n,"unf",1,2.8);

clf
p = scatter(x, y, mAreas, "yel", "fill", "markerEdgeColor", "red")

// Post-processing
k = mAreas<median(mAreas)*2;
bg = ones(1,n) * p.mark_background;
bg(k) = color("orange");
p.mark_background = bg;
     ]]></programlisting>
        <scilab:image><![CDATA[
            n = 150;
            x = rand(1,n);
            y = rand(1,n);
            mAreas = 10.^grand(1,n,"unf",1,2.8);

            clf
            p = scatter(x, y, mAreas, "yel", "fill", "markerEdgeColor", "red")

            // Post-processing
            k = mAreas<median(mAreas)*2;
            bg = ones(1,n) * p.mark_background;
            bg(k) = color("orange");
            p.mark_background = bg;

            gcf().axes_size = [450 300];
        ]]></scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="scatter3d">scatter3d</link>
            </member>
            <member>
                <link linkend="plot">plot</link>
            </member>
            <member>
                <link linkend="gca">gca</link>
            </member>
            <member>
                <link linkend="gcf">gcf</link>
            </member>
            <member>
                <link linkend="color_list">color_list</link>
            </member>
            <member>
                <link linkend="polyline_properties">polyline_properties</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0.0</revnumber>
                <revremark>
                    Function scatter() introduced.
                </revremark>
            </revision>
            <revision>
                <revnumber>6.1.1</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>
                            Colors can be specified as well with their "#RRGGBB" hexadecimal
                            standard code, or their index in the color map.
                        </listitem>
                        <listitem>
                            Options <emphasis>SmallOnTop</emphasis> and
                            <emphasis>"datatips"</emphasis> added.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
