20dbd2816669f06c1bdef26a034cf8f6961509da
[scilab.git] / scilab / modules / statistics / help / en_US / descriptive_statistics / histc.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) 2013 - Scilab Enterprises - Paul Bignier
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  --><!-- This document was created with Syntext Serna Free. -->
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="histc">
17     <refnamediv>
18         <refname>histc</refname>
19         <refpurpose>computes an histogram</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>
24             [cf, ind] = histc(n, data [,normalization])
25             [cf, ind] = histc(x, data [,normalization])
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>n</term>
33                 <listitem>
34                     <para>positive integer (number of classes)</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>x</term>
39                 <listitem>
40                     <para>
41                         increasing vector defining the classes (<literal>x</literal> may have at least 2 components)
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>data</term>
47                 <listitem>
48                     <para>
49                         vector (data to be analysed)
50                     </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>cf</term>
55                 <listitem>
56                     <para>
57                         vector representing the number of values of <varname>data</varname>
58                         falling in the classes defined by <varname>n</varname> or <varname>x</varname>
59                     </para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>ind</term>
64                 <listitem>
65                     <para>
66                         vector or matrix of same size as <varname>data</varname>,
67                         representing the repective belonging of each element of data <varname>data</varname>
68                         to the classes defined by <varname>n</varname> or <varname>x</varname>
69                     </para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>normalization</term>
74                 <listitem>
75                     <para>
76                         scalar boolean.
77                         <varname>normalization=%f (default)</varname>: <varname>cf</varname> represents the total number of points in each class,
78                         <varname>normalization=%t</varname>: <varname>cf</varname> represents the number of points in each class, relatively to the total number of points
79                     </para>
80                 </listitem>
81             </varlistentry>
82         </variablelist>
83     </refsection>
84     <refsection>
85         <title>Description</title>
86         <para>
87             This function computes a histogram of the <literal>data</literal> vector using the
88             classes <literal>x</literal>. When the number <literal>n</literal> of classes is provided
89             instead of <literal>x</literal>, the classes are chosen equally spaced and
90             <emphasis>x(1) = min(data) &lt; x(2) = x(1) + dx &lt; ... &lt; x(n+1) = max(data)</emphasis>
91             with <emphasis>dx = (x(n+1)-x(1))/n</emphasis>.
92         </para>
93         <para>
94             The classes are defined by <literal>C1 = [x(1), x(2)]</literal> and <literal>Ci = ( x(i), x(i+1)]</literal> for i &gt;= 2.
95             Noting <literal>Nmax</literal> the total number of <literal>data</literal> (Nmax = length(data))
96             and <literal>Ni</literal> the number of <literal>data</literal> components falling in
97             <literal>Ci</literal>, the value of the histogram for <literal>x</literal> in
98             <literal>Ci</literal> is equal to <emphasis>Ni/(Nmax (x(i+1)-x(i)))</emphasis> when
99             <literal>"normalized"</literal> is selected and else, simply equal to <emphasis>Ni</emphasis>.
100             When normalization occurs the histogram verifies:
101         </para>
102         <para>
103             <latex style="display"><![CDATA[ \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1 ]]></latex>
104         </para>
105         <para>
106             when <emphasis>x(1)&lt;=min(data)</emphasis> and <emphasis>max(data) &lt;= x(n+1)</emphasis>
107         </para>
108     </refsection>
109     <refsection>
110         <title>Examples</title>
111         <simplelist>
112             <member> Example #1: variations around a histogram of a gaussian random sample
113                 <programlisting role="example"><![CDATA[
114 // The gaussian random sample
115 d = rand(1, 10000, 'normal');
116
117 [cf, ind] = histc(20, d, normalization=%f)
118 // We use histplot to show a graphic representation
119 clf(); histplot(20, d, normalization=%f);
120
121 [cf, ind] = histc(20, d)
122 clf(); histplot(20, d);
123 ]]></programlisting>
124                 <scilab:image>
125                     d = rand(1, 10000, 'normal');
126                     [cf, ind] = histc(20, d)
127                     clf(); histplot(20, d);
128                 </scilab:image>
129             </member>
130             <member>
131                 Example #2: histogram of a binomial (B(6,0.5)) random sample
132                 <programlisting role="example"><![CDATA[
133 d = grand(1000,1,"bin", 6, 0.5);
134 c = linspace(-0.5,6.5,8);
135 clf()
136 subplot(2,1,1)
137 [cf, ind] = histc(c, d)
138 histplot(c, d, style=2);
139 xtitle("Normalized histogram")
140 subplot(2,1,2)
141 [cf, ind] = histc(c, d, normalization=%f)
142 histplot(c, d, normalization=%f, style=5);
143 xtitle("Non normalized histogram")
144 ]]></programlisting>
145                 <scilab:image localized="true">
146                     d = grand(1000,1,"bin", 6, 0.5);
147                     c = linspace(-0.5,6.5,8);
148                     clf()
149                     subplot(2,1,1)
150                     [cf, ind] = histc(c, d)
151                     histplot(c, d, style=2);
152                     xtitle("Normalized histogram")
153                     subplot(2,1,2)
154                     [cf, ind] = histc(c, d, normalization=%f)
155                     histplot(c, d, normalization=%f, style=5);
156                     xtitle("Non normalized histogram")
157                 </scilab:image>
158             </member>
159             <member>
160                 Example #3: histogram of an exponential random sample
161                 <programlisting role="example"><![CDATA[
162 lambda = 2;
163 X = grand(100000,1,"exp", 1/lambda);
164 Xmax = max(X);
165 [cf, ind] = histc(40, X)
166 clf()
167 histplot(40, X, style=2);
168 x = linspace(0, max(Xmax), 100)';
169 plot2d(x, lambda*exp(-lambda*x), strf="000", style=5)
170 legend(["exponential random sample histogram" "exact density curve"]);
171 ]]></programlisting>
172                 <scilab:image localized="true">
173                     lambda = 2;
174                     X = grand(100000,1,"exp", 1/lambda);
175                     Xmax = max(X);
176                     [cf, ind] = histc(40, X)
177                     clf()
178                     histplot(40, X, style=2);
179                     x = linspace(0, max(Xmax), 100)';
180                     plot2d(x, lambda*exp(-lambda*x), strf="000", style=5)
181                     legend(["exponential random sample histogram" "exact density curve"]);
182                 </scilab:image>
183             </member>
184             <member>
185                 Example #4: the frequency polygon chart and the histogram of a gaussian random sample
186                 <programlisting role="example"><![CDATA[
187 n = 10;
188 data = rand(1, 1000, "normal");
189 [cf, ind] = histc(n, data)
190 clf(); histplot(n, data, style=12, polygon=%t);
191 legend(["normalized histogram" "frequency polygon chart"]);
192 ]]></programlisting>
193                 <scilab:image localized="true">
194                     n = 10;
195                     data = rand(1, 1000, "normal");
196                     [cf, ind] = histc(n, data)
197                     clf(); histplot(n, data, style=12, polygon=%t);
198                     legend(["normalized histogram" "frequency polygon chart"]);
199                 </scilab:image>
200             </member>
201         </simplelist>
202     </refsection>
203     <refsection role="see also">
204         <title>See Also</title>
205         <simplelist type="inline">
206             <member>
207                 <link linkend="histplot">histplot</link>
208             </member>
209             <member>
210                 <link linkend="hist3d">hist3d</link>
211             </member>
212             <member>
213                 <link linkend="plot2d">plot2d</link>
214             </member>
215             <member>
216                 <link linkend="dsearch">dsearch</link>
217             </member>
218         </simplelist>
219     </refsection>
220     <refsection>
221         <title>History</title>
222         <revhistory>
223             <revision>
224                 <revnumber>5.5.0</revnumber>
225                 <revdescription>
226                     Introduction
227                 </revdescription>
228             </revision>
229         </revhistory>
230     </refsection>
231 </refentry>