scilab/modules/graphics/help/en_US/2d_plot/scatter.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) Scilab Enterprises - 2015 - 2012 - Juergen Koch
   5  *
   6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   7  *
   8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
   9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  10  * This file was originally licensed under the terms of the CeCILL v2.1,
  11  * and continues to be available under such terms.
  12  * For more information, see the COPYING file which you should have received
  13  * along with this program.
  14  *
  15  -->
  16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
  18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
  19           xml:lang="en" xml:id="scatter">
  20     <refnamediv>
  21         <refname>scatter</refname>
  22         <refpurpose>2D scatter plot</refpurpose>
  23     </refnamediv>
  24     <refsynopsisdiv>
  25         <title>Syntax</title>
  26         <synopsis>
  27             polyline = scatter(x, y, msizes, mcolors, "fill", marker, &lt;marker_property, value&gt;)
  28             polyline = scatter(axes_handle,...)
  29         </synopsis>
  30     </refsynopsisdiv>
  31     <refsection>
  32         <title>Arguments</title>
  33         <variablelist>
  34             <varlistentry>
  35                 <term>x, y</term>
  36                 <listitem>
  37                     <para>
  38                         Columns or rows vectors of n real numbers specifying the abscissae and the
  39                         ordinates of the centers of markers.
  40                     </para>
  41                 </listitem>
  42             </varlistentry>
  43             <varlistentry>
  44                 <term>msizes</term>
  45                 <listitem>
  46                     <para>
  47                         Specifying the sizes of the markers. To plot each marker with equal sizes,
  48                         specify <varname>msizes</varname> as a scalar.
  49                         To plot each marker with a different size, specify <varname>msizes</varname>
  50                         as a vector with length equal to the length of <varname>x</varname> and
  51                         <varname>x</varname>.
  52                         The units for <varname>msizes</varname> is points squared with a default
  53                         value of 36 points squared.
  54                         The size equals the area of the circle surrounding the marker.
  55                     </para>
  56                 </listitem>
  57             </varlistentry>
  58             <varlistentry>
  59                 <term>mcolors</term>
  60                 <listitem>
  61                     <para>
  62                         Specifying the colors of the markers.
  63                         To plot each marker with the same color, specify <varname>mcolors</varname>
  64                         as a string representing a known color, see <link linkend="color_list">color_list</link>.
  65                         A color can also be specified by a vector of 3 RGB values between 0 and 1.
  66                         To plot each marker with a different color, specify <varname>mcolors</varname>
  67                         as a vector with length equal to the length of <varname>x</varname>.
  68                         The values of <varname>mcolors</varname> are linearly mapped to the colors
  69                         in the current colormap.
  70                         Colors can also by specified by a matrix of RGB values or a vector of
  71                         strings representing known colors.
  72                         A matrix of RGB values has 3 columns and the number of rows equals the
  73                         length of <varname>x</varname>.
  74                         The default color is "blue".
  75                     </para>
  76                 </listitem>
  77             </varlistentry>
  78             <varlistentry>
  79                 <term>"fill"</term>
  80                 <listitem>
  81                     <para>
  82                         This string indicates that the markers are filled with some colors.
  83                         By default, the filling colors are the same as the patterns ones.
  84                         Both sets of colors can be defined independently by using the properties
  85                         <varname>"markerFaceColor"</varname> or
  86                         <varname>"markerBackgroundColor"</varname>.
  87                     </para>
  88                 </listitem>
  89             </varlistentry>
  90             <varlistentry>
  91                 <term>marker</term>
  92                 <listitem>
  93                     <para>
  94                         Select the type of the marker. The same marker shape is used for all
  95                         specified points. The figure below shows the 15 different marker types.
  96                     </para>
  97                     <para>
  98                         <inlinemediaobject>
  99                             <imageobject>
 100                                 <imagedata fileref="../../images/marks.svg"/>
 101                             </imageobject>
 102                         </inlinemediaobject>
 103                     </para>
 104                     <para>
 105                         Marker types are specified by strings, see the table below.
 106                     </para>
 107                     <para>
 108                         <informaltable border="1">
 109                             <tr>
 110                                 <td>
 111                                     String
 112                                 </td>
 113                                 <td>
 114                                     Marker type
 115                                 </td>
 116                             </tr>
 117                             <tr>
 118                                 <td>
 119                                     <literal>"."</literal>
 120                                 </td>
 121                                 <td>Point</td>
 122                             </tr>
 123                             <tr>
 124                                 <td>
 125                                     <literal>"+"</literal>
 126                                 </td>
 127                                 <td>Plus sign</td>
 128                             </tr>
 129                             <tr>
 130                                 <td>
 131                                     <literal>"x"</literal>
 132                                 </td>
 133                                 <td>Cross</td>
 134                             </tr>
 135                             <tr>
 136                                 <td>
 137                                     <literal>"circle plus"</literal>
 138                                 </td>
 139                                 <td>Circle with plus</td>
 140                             </tr>
 141                             <tr>
 142                                 <td>
 143                                     <literal>"filled diamond"</literal>
 144                                 </td>
 145                                 <td>Filled diamond</td>
 146                             </tr>
 147                             <tr>
 148                                 <td>
 149                                     <literal>"d"</literal> or
 150                                     <literal>"diamond"</literal>
 151                                 </td>
 152                                 <td>Diamond</td>
 153                             </tr>
 154                             <tr>
 155                                 <td>
 156                                     <literal>"^"</literal>
 157                                 </td>
 158                                 <td>Upward-pointing triangle</td>
 159                             </tr>
 160                             <tr>
 161                                 <td>
 162                                     <literal>"v"</literal>
 163                                 </td>
 164                                 <td>Downward-pointing triangle</td>
 165                             </tr>
 166                             <tr>
 167                                 <td>
 168                                     <literal>"diamond plus"</literal>
 169                                 </td>
 170                                 <td>Diamond with plus</td>
 171                             </tr>
 172                             <tr>
 173                                 <td>
 174                                     <literal>"o"</literal>
 175                                 </td>
 176                                 <td>Circle (default)</td>
 177                             </tr>
 178                             <tr>
 179                                 <td>
 180                                     <literal>"*"</literal>
 181                                 </td>
 182                                 <td>Asterisk</td>
 183                             </tr>
 184                             <tr>
 185                                 <td>
 186                                     <literal>"s"</literal> or
 187                                     <literal>"square"</literal>
 188                                 </td>
 189                                 <td>Square</td>
 190                             </tr>
 191                             <tr>
 192                                 <td>
 193                                     <literal>"&gt;"</literal>
 194                                 </td>
 195                                 <td>Right-pointing triangle</td>
 196                             </tr>
 197                             <tr>
 198                                 <td>
 199                                     <literal>"&lt;"</literal>
 200                                 </td>
 201                                 <td>Left-pointing triangle</td>
 202                             </tr>
 203                             <tr>
 204                                 <td>
 205                                     <literal>"pentagram"</literal> or
 206                                     <literal>"p"</literal>
 207                                 </td>
 208                                 <td>Five-pointed star</td>
 209                             </tr>
 210                         </informaltable>
 211                     </para>
 212                 </listitem>
 213             </varlistentry>
 214             <varlistentry>
 215                 <term>&lt;marker_property, value&gt;</term>
 216                 <listitem>
 217                     <para>
 218                         A sequence of property value pairs can be used to specify type, color and
 219                         line width of the markers.
 220                     </para>
 221                 </listitem>
 222             </varlistentry>
 223             <varlistentry>
 224                 <term>&lt;"marker", value&gt; or &lt;"markerStyle", value&gt;</term>
 225                 <listitem>
 226                     <para>
 227                         Specify the type of the marker, see the table above.
 228                     </para>
 229                 </listitem>
 230             </varlistentry>
 231             <varlistentry>
 232                 <term>&lt;"markerEdgeColor", value&gt; or &lt;"markerForeground", value&gt;</term>
 233                 <listitem>
 234                     <para>
 235                         Specify the foreground color of the marker.
 236                         A color can be specified by a string representing a known color,
 237                         see <link linkend="color_list">color_list</link>.
 238                         A color can also be specified by a vector of 3 RGB values.
 239                         RGB values correspond to red, green and blue intensity between 0 and 1.
 240                         This option is superseded by argument <varname>mcolors</varname>.
 241                     </para>
 242                 </listitem>
 243             </varlistentry>
 244             <varlistentry>
 245                 <term>&lt;"markerFaceColor",value&gt; or &lt;"markerBackground",value&gt;</term>
 246                 <listitem>
 247                     <para>
 248                         Specify the background color of the marker.
 249                         A color can be specified by a string representing a known color
 250                         see <link linkend="color_list">color_list</link>.
 251                         A color can also be specified by a vector of 3 RGB values.
 252                         RGB values correspond to red, green and blue intensity between 0 and 1.
 253                         This option is superseded by argument <varname>mcolors</varname>.
 254                     </para>
 255                 </listitem>
 256             </varlistentry>
 257             <varlistentry>
 258                 <term>&lt;"linewidth",value&gt; or &lt;"thickness",value&gt;</term>
 259                 <listitem>
 260                     <para>
 261                         Specify the thickness of the edge of the marker.
 262                         The unit for the value is one point.
 263                     </para>
 264                 </listitem>
 265             </varlistentry>
 266             <varlistentry>
 267                 <term>&lt;axes_handle&gt;</term>
 268                 <listitem>
 269                     <para>This optional argument forces the scatter plot to appear inside the
 270                         selected axes given by <literal>axes_handle</literal> rather than inside the
 271                         current axes, see <link linkend="gca">gca</link>.
 272                     </para>
 273                 </listitem>
 274             </varlistentry>
 275             <varlistentry>
 276                 <term>polyline</term>
 277                 <listitem>
 278                     <para>
 279                         Handle of the created polyline.
 280                     </para>
 281                 </listitem>
 282             </varlistentry>
 283         </variablelist>
 284     </refsection>
 285     <refsection>
 286         <title>Description</title>
 287         <para>
 288             <literal>scatter(x,y)</literal> creates a scatter plot with markers centered at
 289             the <literal>(x, y)</literal> set of coordinates.
 290             The default type of the marker is a circle, the default color is "blue" and the default
 291             size is 36.
 292             This means the circle surrounding the marker has an area of 36 points squared.
 293         </para>
 294         <para>
 295             Different sizes and colors for each marker can be specified with
 296             <literal>scatter(x,y,msizes,mcolors)</literal>.
 297             There are many different ways to specify marker types, marker colors and marker sizes.
 298             For more details see the description of the arguments and the examples.
 299         </para>
 300         <note>
 301           To skip an argument, just replace it with <literal>[]</literal> like in
 302           <literal>scatter3(x,y,z,[],mcolors)</literal>.
 303         </note>
 304     </refsection>
 305     <refsection>
 306         <title>Examples</title>
 307         <para>
 308             Create 2D scatter plot
 309         </para>
 310         <programlisting role="example"><![CDATA[
 311 // x and y initialisation
 312 x = linspace(0,2,200);
 313 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x));
 314 // create 2D scatter plot
 315 scatter(x,y);
 316  ]]></programlisting>
 317         <scilab:image>
 318             x = linspace(0,2,200)
 319             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
 320             scatter(x,y)
 321         </scilab:image>
 322         <para>
 323             Vary marker size
 324         </para>
 325         <programlisting role="example"><![CDATA[
 326 // x and y initialisation
 327 x = linspace(0,2,200);
 328 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x));
 329 // specify different sizes
 330 s = linspace(1,30,length(x));
 331 // create 2D scatter plot
 332 scatter(x, y, s);
 333  ]]></programlisting>
 334         <scilab:image>
 335             x = linspace(0,2,200)
 336             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
 337             s = linspace(1,30,length(x))
 338             scatter(x,y,s)
 339         </scilab:image>
 340         <para>
 341             Vary marker size and color
 342         </para>
 343         <programlisting role="example"><![CDATA[
 344 // x and y initialisation
 345 x = linspace(0, 2, 200);
 346 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x));
 347 // specify different sizes
 348 s = linspace(1, 30, length(x));
 349 // set color map
 350 gcf().color_map = coolcolormap(64);
 351 // colors according to x values
 352 c = x;
 353 // create 2D scatter plot
 354 scatter(x,y,s,c);
 355  ]]></programlisting>
 356         <scilab:image>
 357             x = linspace(0,2,200)
 358             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
 359             s = linspace(1,30,length(x))
 360             gcf().color_map = coolcolormap(64)
 361             c = x
 362             scatter(x,y,s,c)
 363         </scilab:image>
 364         <para>
 365             Fill the markers
 366         </para>
 367         <programlisting role="example"><![CDATA[
 368 // x and y initialisation
 369 x = linspace(0, 2, 200);
 370 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x));
 371 // specify different sizes
 372 s = linspace(1, 30, length(x));
 373 // set color map
 374 gcf().color_map = coolcolormap(64);
 375 // colors according to y values
 376 c = y;
 377 // create 2D scatter plot
 378 scatter(x, y, s, c, "fill");
 379  ]]></programlisting>
 380         <scilab:image>
 381             x = linspace(0,2,200)
 382             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
 383             s = linspace(1,30,length(x))
 384             gcf().color_map = coolcolormap(64);
 385             c = y
 386             scatter(x,y,s,c,"fill")
 387         </scilab:image>
 388         <para>
 389             Specify marker symbol
 390         </para>
 391         <programlisting role="example"><![CDATA[
 392 // x and y initialisation
 393 x = rand(1, 200);
 394 y = rand(1, 200);
 395 // create 2D scatter plot
 396 scatter(x, y, "d");
 397  ]]></programlisting>
 398         <scilab:image>
 399             x = rand(1,200)
 400             y = rand(1,200)
 401             scatter(x,y,"d")
 402         </scilab:image>
 403         <para>
 404             Change marker color and line width
 405         </para>
 406         <programlisting role="example"><![CDATA[
 407 // x and y initialisation
 408 x = rand(1, 200);
 409 y = rand(1, 200);
 410 // create 2D scatter plot
 411 scatter(x, y, "markerEdgeColor",[0 .4 .4],...
 412               "markerFaceColor",[0 .8 .8],...
 413               "linewidth",1.5);
 414  ]]></programlisting>
 415         <scilab:image>
 416             x = rand(1,200)
 417             y = rand(1,200)
 418             scatter(x,y,"markerEdgeColor",[0 .4 .4],...
 419             "markerFaceColor",[0 .8 .8],...
 420             "linewidth",1.5)
 421         </scilab:image>
 422         <para>
 423             Specify subplot for scatter plot
 424         </para>
 425         <programlisting role="example"><![CDATA[
 426 // x and y initialisation
 427 x = linspace(0, 2, 100);
 428 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x));
 429 // create 2D scatter subplot
 430 subplot(2, 1, 1)
 431 scatter(gca(), x, y);
 432 // create 2D scatter subplot
 433 subplot(2, 1, 2)
 434 scatter(gca(), x, y, "fill", "s");
 435  ]]></programlisting>
 436         <scilab:image>
 437             x = linspace(0,2,100)
 438             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
 439             subplot(2,1,1)
 440             scatter(gca(),x,y)
 441             subplot(2,1,2)
 442             scatter(gca(),x,y,"fill","s")
 443         </scilab:image>
 444         <para>
 445             Modify scatter plot after creation
 446         </para>
 447         <programlisting role="example"><![CDATA[
 448 // x and y initialisation
 449 t = linspace(0,1,200);
 450 x = t .* cos(10*%pi*t);
 451 y = t .* sin(10*%pi*t);
 452 // create 2D scatter plot
 453 p = scatter(x, y);
 454  ]]></programlisting>
 455         <scilab:image>
 456             t = linspace(0,25,200)
 457             x = t.*cos(t)
 458             y = t.*sin(t)
 459             p = scatter(x,y,t)
 460         </scilab:image>
 461         <programlisting role="example"><![CDATA[
 462 // modify polyline
 463 p.thickness = 0.5;
 464 p.mark_foreground = color("darkblue");
 465 p.mark_background = color("darkcyan");
 466  ]]></programlisting>
 467         <scilab:image>
 468             t = linspace(0,25,200)
 469             x = t.*cos(t)
 470             y = t.*sin(t)
 471             p = scatter(x,y,t)
 472             p.thickness = 0.5
 473             p.mark_foreground = color("darkblue")
 474             p.mark_background = color("darkcyan")
 475         </scilab:image>
 476     </refsection>
 477     <refsection role="see also">
 478         <title>See also</title>
 479         <simplelist type="inline">
 480             <member>
 481                 <link linkend="scatter3">scatter3</link>
 482             </member>
 483             <member>
 484                 <link linkend="plot">plot</link>
 485             </member>
 486             <member>
 487                 <link linkend="gca">gca</link>
 488             </member>
 489             <member>
 490                 <link linkend="gcf">gcf</link>
 491             </member>
 492             <member>
 493                 <link linkend="color_list">color_list</link>
 494             </member>
 495             <member>
 496                 <link linkend="polyline_properties">polyline_properties</link>
 497             </member>
 498         </simplelist>
 499     </refsection>
 500     <refsection>
 501         <title>History</title>
 502         <revhistory>
 503             <revision>
 504                 <revnumber>6.0.0</revnumber>
 505                 <revremark>
 506                     Function <function>scatter</function> introduced.
 507                 </revremark>
 508             </revision>
 509         </revhistory>
 510     </refsection>
 511 </refentry>