9b8971ece3d6e3e1a701fcf7849c0d29fa20a28f
[scilab.git] / 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" 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">
17     <refnamediv>
18         <refname>scatter</refname>
19         <refpurpose>2D scatter plot</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>
24             p = scatter(x,y,&lt;s&gt;,&lt;c&gt;,&lt;"fill"&gt;,&lt;marker&gt;,&lt;marker_property,value&gt;)
25             p = scatter(&lt;axes_handle&gt;,...)
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>x</term>
33                 <listitem>
34                     <para>
35                         A column or row vector of n real numbers
36                         specifying the x positions of the markers center.
37                         x and y must be vectors of the same length.
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>y</term>
43                 <listitem>
44                     <para>
45                         A column or row vector of n real numbers
46                         specifying the y positions of the markers center.
47                         x and y must be vectors of the same length.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>&lt;s&gt;</term>
53                 <listitem>
54                     <para>
55                         Specifying the sizes of the markers.
56                         To plot each marker with equal size, specify s as a scalar.
57                         To plot each marker with a different size, specify s as a vector with length equal to the length of x and y.
58                         The units for s is points squared with a default value of 36 points squared.
59                         The size equals the area of the circle surrounding the marker.
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>&lt;c&gt;</term>
65                 <listitem>
66                     <para>
67                         Specifying the colors of the markers.
68                         To plot each marker with the same color, specify c as a string representing a known color, see <link linkend="color_list">color_list</link>.
69                         A color can also be specified by a vector of 3 RGB values.
70                         RGB values correspond to red, green and blue intensity between 0 and 1.
71                         To plot each marker with a different color, specify c as a vector with length equal to the length of x and y.
72                         The values of c are linarly mapped to the colors in the current colormap.
73                         Colors can also by specified by a matrix of RGB values or a vector of strings representing known colors.
74                         A matrix of RGB values has 3 columns and the number of rows equals the length of x and y.
75                         The default color is "blue".
76                     </para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>&lt;"fill"&gt;</term>
81                 <listitem>
82                     <para>
83                         This string indicates that the markers are filled with colors.
84                         The markers background colors are set using the values of c.
85                         If c is not specified the fill color can be defined by the marker property "markerFaceColor" or "markerBackgroundColor".
86                         The default color is "blue".
87                     </para>
88                 </listitem>
89             </varlistentry>
90             <varlistentry>
91                 <term>&lt;marker&gt;</term>
92                 <listitem>
93                     <para>
94                         Select the type of the marker.
95                         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 line width of the markers.
219                     </para>
220                 </listitem>
221             </varlistentry>
222             <varlistentry>
223                 <term>&lt;"marker",value&gt; or &lt;"markerStyle",value&gt;</term>
224                 <listitem>
225                     <para>
226                         Specify the type of the marker, see the table above.
227                     </para>
228                 </listitem>
229             </varlistentry>
230             <varlistentry>
231                 <term>&lt;"markerEdgeColor",value&gt; or &lt;"markerForeground",value&gt;</term>
232                 <listitem>
233                     <para>
234                         Specify the foreground color of the marker.
235                         A color can be specified by a string representing a known color, see <link linkend="color_list">color_list</link>.
236                         A color can also be specified by a vector of 3 RGB values.
237                         RGB values correspond to red, green and blue intensity between 0 and 1.
238                         This option is superseded by argument c.
239                     </para>
240                 </listitem>
241             </varlistentry>
242             <varlistentry>
243                 <term>&lt;"markerFaceColor",value&gt; or &lt;"markerBackground",value&gt;</term>
244                 <listitem>
245                     <para>
246                         Specify the background color of the marker.
247                         A color can be specified by a string representing a known color, see <link linkend="color_list">color_list</link>.
248                         A color can also be specified by a vector of 3 RGB values.
249                         RGB values correspond to red, green and blue intensity between 0 and 1.
250                         This option is superseded by argument c.
251                     </para>
252                 </listitem>
253             </varlistentry>
254             <varlistentry>
255                 <term>&lt;"linewidth",value&gt; or &lt;"thickness",value&gt;</term>
256                 <listitem>
257                     <para>
258                         Specify the thickness of the edge of the marker.
259                         The unit for the value is one point.
260                     </para>
261                 </listitem>
262             </varlistentry>
263             <varlistentry>
264                 <term>&lt;axes_handle&gt;</term>
265                 <listitem>
266                     <para>This optional argument forces the scatter plot to appear inside the
267                         selected axes given by <literal>axes_handle</literal> rather than inside the
268                         current axes, see <link linkend="gca">gca</link>.
269                     </para>
270                 </listitem>
271             </varlistentry>
272             <varlistentry>
273                 <term>&lt;p&gt;</term>
274                 <listitem>
275                     <para>
276                         Returns a handle to the created polyline.
277                     </para>
278                 </listitem>
279             </varlistentry>
280         </variablelist>
281     </refsection>
282     <refsection>
283         <title>Description</title>
284         <para>
285             <literal>scatter(x,y)</literal> creates a scatter plot with markers at the locations specified by x and y.
286             The default type of the marker is a circle, the default color is "blue" and the default size is 36.
287             This means the circle surrounding the marker has an area of 36 points squared.
288         </para>
289         <para>
290             Using <literal>scatter(x,y,s,c)</literal> different sizes and colors for each marker can be specified.
291             There are many different ways to specify marker types, marker colors and marker sizes.
292             For more details see the description of the arguments and the examples.
293         </para>
294     </refsection>
295     <refsection>
296         <title>Remarks</title>
297         <para>
298             If you want to specify colors without specifying sizes use <literal>scatter(x,y,[],c)</literal>.
299         </para>
300     </refsection>
301     <refsection>
302         <title>Examples</title>
303         <para>
304             Create 2D scatter plot
305         </para>
306         <programlisting role="example"><![CDATA[
307 // x and y initialisation
308 x = linspace(0,2,200)
309 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
310 // create 2D scatter plot
311 scatter(x,y)
312  ]]></programlisting>
313         <scilab:image>
314             x = linspace(0,2,200)
315             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
316             scatter(x,y)
317         </scilab:image>
318         <para>
319             Vary marker size
320         </para>
321         <programlisting role="example"><![CDATA[
322 // x and y initialisation
323 x = linspace(0,2,200)
324 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
325 // specify different sizes
326 s = linspace(1,30,length(x))
327 // create 2D scatter plot
328 scatter(x,y,s)
329  ]]></programlisting>
330         <scilab:image>
331             x = linspace(0,2,200)
332             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
333             s = linspace(1,30,length(x))
334             scatter(x,y,s)
335         </scilab:image>
336         <para>
337             Vary marker size and color
338         </para>
339         <programlisting role="example"><![CDATA[
340 // x and y initialisation
341 x = linspace(0,2,200)
342 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
343 // specify different sizes
344 s = linspace(1,30,length(x))
345 // set color map
346 set(gcf(),"color_map",coolcolormap(64))
347 // colors according to x values
348 c = x
349 // create 2D scatter plot
350 scatter(x,y,s,c)
351  ]]></programlisting>
352         <scilab:image>
353             x = linspace(0,2,200)
354             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
355             s = linspace(1,30,length(x))
356             set(gcf(),"color_map",coolcolormap(64))
357             c = x
358             scatter(x,y,s,c)
359         </scilab:image>
360         <para>
361             Fill the markers
362         </para>
363         <programlisting role="example"><![CDATA[
364 // x and y initialisation
365 x = linspace(0,2,200)
366 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
367 // specify different sizes
368 s = linspace(1,30,length(x))
369 // set color map
370 set(gcf(),"color_map",coolcolormap(64))
371 // colors according to y values
372 c = y
373 // create 2D scatter plot
374 scatter(x,y,s,c,"fill")
375  ]]></programlisting>
376         <scilab:image>
377             x = linspace(0,2,200)
378             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
379             s = linspace(1,30,length(x))
380             set(gcf(),"color_map",coolcolormap(64))
381             c = y
382             scatter(x,y,s,c,"fill")
383         </scilab:image>
384         <para>
385             Specify marker symbol
386         </para>
387         <programlisting role="example"><![CDATA[
388 // x and y initialisation
389 x = rand(1,200)
390 y = rand(1,200)
391 // create 2D scatter plot
392 scatter(x,y,"d")
393  ]]></programlisting>
394         <scilab:image>
395             x = rand(1,200)
396             y = rand(1,200)
397             scatter(x,y,"d")
398         </scilab:image>
399         <para>
400             Change marker color and line width
401         </para>
402         <programlisting role="example"><![CDATA[
403 // x and y initialisation
404 x = rand(1,200)
405 y = rand(1,200)
406 // create 2D scatter plot
407 scatter(x,y,"markerEdgeColor",[0 .4 .4],...
408             "markerFaceColor",[0 .8 .8],...
409             "linewidth",1.5)
410  ]]></programlisting>
411         <scilab:image>
412             x = rand(1,200)
413             y = rand(1,200)
414             scatter(x,y,"markerEdgeColor",[0 .4 .4],...
415             "markerFaceColor",[0 .8 .8],...
416             "linewidth",1.5)
417         </scilab:image>
418         <para>
419             Specify subplot for scatter plot
420         </para>
421         <programlisting role="example"><![CDATA[
422 // x and y initialisation
423 x = linspace(0,2,100)
424 y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
425 // create 2D scatter subplot
426 subplot(2,1,1)
427 scatter(gca(),x,y)
428 // create 2D scatter subplot
429 subplot(2,1,2)
430 scatter(gca(),x,y,"fill","s")
431  ]]></programlisting>
432         <scilab:image>
433             x = linspace(0,2,100)
434             y = exp(-x).*cos(10*x) + 0.2*rand(1,length(x))
435             subplot(2,1,1)
436             scatter(gca(),x,y)
437             subplot(2,1,2)
438             scatter(gca(),x,y,"fill","s")
439         </scilab:image>
440         <para>
441             Modify scatter plot after creation
442         </para>
443         <programlisting role="example"><![CDATA[
444 // x and y initialisation
445 t = linspace(0,1,200)
446 x = t.*cos(10*%pi*t)
447 y = t.*sin(10*%pi*t)
448 // create 2D scatter plot
449 p = scatter(x,y)
450  ]]></programlisting>
451         <scilab:image>
452             t = linspace(0,25,200)
453             x = t.*cos(t)
454             y = t.*sin(t)
455             p = scatter(x,y,t)
456         </scilab:image>
457         <programlisting role="example"><![CDATA[
458 // modify ployline
459 p.thickness = 0.5
460 p.mark_foreground = addcolor(name2rgb("darkblue")/255)
461 p.mark_background = addcolor(name2rgb("darkcyan")/255)
462  ]]></programlisting>
463         <scilab:image>
464             t = linspace(0,25,200)
465             x = t.*cos(t)
466             y = t.*sin(t)
467             p = scatter(x,y,t)
468             p.thickness = 0.5
469             p.mark_foreground = addcolor(name2rgb("darkblue")/255)
470             p.mark_background = addcolor(name2rgb("darkcyan")/255)
471         </scilab:image>
472     </refsection>
473     <refsection role="see also">
474         <title>See also</title>
475         <simplelist type="inline">
476             <member>
477                 <link linkend="scatter3">scatter3</link>
478             </member>
479             <member>
480                 <link linkend="plot">plot</link>
481             </member>
482             <member>
483                 <link linkend="gca">gca</link>
484             </member>
485             <member>
486                 <link linkend="gcf">gcf</link>
487             </member>
488             <member>
489                 <link linkend="color_list">color_list</link>
490             </member>
491             <member>
492                 <link linkend="polyline_properties">polyline_properties</link>
493             </member>
494         </simplelist>
495     </refsection>
496     <refsection>
497         <title>History</title>
498         <revhistory>
499             <revision>
500                 <revnumber>6.0.0</revnumber>
501                 <revremark>
502                     Function <function>scatter</function> introduced.
503                 </revremark>
504             </revision>
505         </revhistory>
506     </refsection>
507 </refentry>