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