Add more images and improves the examples
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / histplot.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) INRIA - Serge Steer
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-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" version="5.0-subset Scilab" xml:lang="en" xml:id="histplot">
14     <refnamediv>
15         <refname>histplot</refname>
16         <refpurpose>plot a histogram</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>histplot(n, data, &lt;opt_args&gt;)
21             histplot(x, data, &lt;opt_args&gt;)
22         </synopsis>
23     </refsynopsisdiv>
24     <refsection>
25         <title>Arguments</title>
26         <variablelist>
27             <varlistentry>
28                 <term>n</term>
29                 <listitem>
30                     <para>positive integer (number of classes)</para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>x</term>
35                 <listitem>
36                     <para>
37                         increasing vector defining the classes (<literal>x</literal> may have at least 2 components)
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>data</term>
43                 <listitem>
44                     <para>vector (data to be analysed)</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>&lt;opt_args&gt;</term>
49                 <listitem>
50                     <para>
51                         This represents a sequence of statements <literal>key1=value1,key2=value2</literal>
52                         ,... where <literal>key1</literal>,
53                         <literal>key2,...</literal> can be any optional <link linkend="plot2d">plot2d</link> parameter (<literal>style,strf,leg,
54                             rect,nax, logflag,frameflag, axesflag
55                         </literal>
56                         )or normalization. For this last one the corresponding
57                         value must be a boolean scalar (default value %t). 
58                     </para>
59                 </listitem>
60             </varlistentry>
61         </variablelist>
62     </refsection>
63     <refsection>
64         <title>Description</title>
65         <para>
66             This function plot a histogram of the <literal>data</literal> vector using the
67             classes <literal>x</literal>. When the number <literal>n</literal> of classes is provided
68             instead of <literal>x</literal>, the classes are chosen equally spaced and
69             <emphasis>x(1) = min(data) &lt;  x(2) = x(1) + dx  &lt;  ...  &lt; x(n+1) = max(data)</emphasis>
70             with <emphasis>dx = (x(n+1)-x(1))/n</emphasis>.
71         </para>
72         <para> The classes are defined by C1 = [x(1), x(2)] and  Ci = ( x(i), x(i+1)] for i &gt;= 2.
73             Noting Nmax the total number of <literal>data</literal> (Nmax = length(data)) and Ni the number 
74             of <literal>data</literal> components falling in Ci, the value of the histogram for x in Ci 
75             is equal to <emphasis>Ni/(Nmax (x(i+1)-x(i)))</emphasis> when <literal>normalization</literal> is true
76             (default case) and else, simply equal to <emphasis>Ni</emphasis>. When normalization occurs the
77             histogram verifies: 
78         </para>
79         <para>
80             <latex style="display"><![CDATA[
81     \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1
82     ]]></latex>
83         </para>
84         <para>
85             when <emphasis>x(1)&lt;=min(data)</emphasis> and <emphasis>max(data) &lt;= x(n+1)</emphasis>
86         </para>
87         <para>
88             Any <link linkend="plot2d">plot2d</link> (optional) parameter may be provided; for instance to
89             plot a histogram with the color number 2 (blue if std colormap is used) and
90             to restrict the plot inside the rectangle [-3,3]x[0,0.5],
91             you may use <literal>histplot(n,data, style=2, rect=[-3,0,3,0.5])</literal>.
92         </para>
93         <para>
94             Enter the command <literal>histplot()</literal> to see a demo.
95         </para>
96     </refsection>
97     <refsection>
98         <title>Sample</title>
99         <scilab:image>histplot();</scilab:image>
100     </refsection>
101     <refsection>
102         <title>Examples</title>
103         <simplelist>
104             <member>
105                 Example #1: variations around a histogram of a gaussian random sample 
106                 <programlisting role="example"><![CDATA[ 
107 d=rand(1,10000,'normal');  // the gaussian random sample
108 clf();histplot(20,d)
109 clf();histplot(20,d,normalization=%f)
110 clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=5)
111 clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]); 
112 ]]></programlisting>
113                 <scilab:image>
114                     d=rand(1,10000,'normal'); 
115                     clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]);
116                 </scilab:image>
117             </member>
118             <member>
119                 Example #2: histogram of a binomial (B(6,0.5)) random sample
120                 <programlisting role="example"><![CDATA[
121 d = grand(1000,1,"bin", 6, 0.5);
122 c = linspace(-0.5,6.5,8);
123 clf()
124 subplot(2,1,1)
125 histplot(c, d, style=2)
126 xtitle("normalized histogram")
127 subplot(2,1,2)
128 histplot(c, d, normalization=%f, style=5)
129 xtitle("non normalized histogram")
130 ]]></programlisting>
131                 <scilab:image>
132                     d = grand(1000,1,"bin", 6, 0.5);
133                     c = linspace(-0.5,6.5,8);
134                     clf()
135                     subplot(2,1,1)
136                     histplot(c, d, style=2)
137                     xtitle("normalized histogram")
138                     subplot(2,1,2)
139                     histplot(c, d, normalization=%f, style=5)
140                     xtitle("non normalized histogram")
141                 </scilab:image>
142             </member>
143             <member>
144                 Example #3: histogram of an exponential random sample 
145                 <programlisting role="example"><![CDATA[
146 lambda = 2;
147 X = grand(100000,1,"exp", 1/lambda);
148 Xmax = max(X);
149 clf()
150 histplot(40, X, style=2)
151 x = linspace(0,max(Xmax),100)';
152 plot2d(x,lambda*exp(-lambda*x),strf="000",style=5)
153 legend(["exponential random sample histogram" "exact density curve"]);
154 ]]></programlisting>
155                 <scilab:image>
156                     lambda = 2;
157                     X = grand(100000,1,"exp", 1/lambda);
158                     Xmax = max(X);
159                     clf()
160                     histplot(40, X, style=2)
161                     x = linspace(0,max(Xmax),100)';
162                     plot2d(x,lambda*exp(-lambda*x),strf="000",style=5)
163                     legend(["exponential random sample histogram" "exact density curve"]);
164                 </scilab:image>
165             </member>
166         </simplelist>
167     </refsection>
168     <refsection role="see also">
169         <title>See Also</title>
170         <simplelist type="inline">
171             <member>
172                 <link linkend="hist3d">hist3d</link>
173             </member>
174             <member>
175                 <link linkend="plot2d">plot2d</link>
176             </member>
177             <member>
178                 <link linkend="dsearch">dsearch</link>
179             </member>
180         </simplelist>
181     </refsection>
182 </refentry>