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