4ed8185a7163704c09fb7897ab99a7f8afbc7319
[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) 2013 - Scilab Enterprises - Paul Bignier: added data output
5  * Copyright (C) INRIA - Serge Steer
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  --><!-- This document was created with Syntext Serna Free. -->
14 <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="histplot">
15     <refnamediv>
16         <refname>histplot</refname>
17         <refpurpose>plot a histogram</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>
22             [cf, ind] = histplot(n, data [,normalization] [,polygon], &lt;opt_args&gt;)
23             [cf, ind] = histplot(x, data [,normalization] [,polygon], &lt;opt_args&gt;)
24         </synopsis>
25     </refsynopsisdiv>
26     <refsection>
27         <title>Arguments</title>
28         <variablelist>
29             <varlistentry>
30                 <term>n</term>
31                 <listitem>
32                     <para>positive integer (number of classes)</para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>x</term>
37                 <listitem>
38                     <para>
39                         increasing vector defining the classes (<literal>x</literal> may have at least 2 components)
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>data</term>
45                 <listitem>
46                     <para>vector (data to be analysed)</para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>normalization</term>
51                 <listitem>
52                     <para>a boolean (%t (default value) or %f)</para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>polygon</term>
57                 <listitem>
58                     <para>a boolean (%t or %f (default value))</para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>&lt;opt_args&gt;</term>
63                 <listitem>
64                     <para>
65                         This represents a sequence of statements <literal>key1=value1,key2=value2</literal>
66                         ,... where <literal>key1</literal>,
67                         <literal>key2,...</literal> can be any optional <link linkend="plot2d">plot2d</link> parameter (<literal>style,strf,leg, rect,nax, logflag,frameflag, axesflag </literal>
68                         ).
69                     </para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>cf</term>
74                 <listitem>
75                     <para>
76                         This represents a sequence of statements <literal>key1=value1,key2=value2</literal>
77                         ,... where <literal>key1</literal>,
78                         <literal>key2,...</literal> can be any optional <link linkend="plot2d">plot2d</link> parameter (<literal>style,strf,leg, rect,nax, logflag,frameflag, axesflag </literal>
79                         ).
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>ind</term>
85                 <listitem>
86                     <para>
87                         This represents a sequence of statements <literal>key1=value1,key2=value2</literal>
88                         ,... where <literal>key1</literal>,
89                         <literal>key2,...</literal> can be any optional <link linkend="plot2d">plot2d</link> parameter (<literal>style,strf,leg, rect,nax, logflag,frameflag, axesflag </literal>
90                         ).
91                     </para>
92                 </listitem>
93             </varlistentry>
94         </variablelist>
95     </refsection>
96     <refsection>
97         <title>Description</title>
98         <para>
99             This function plots a histogram of the <literal>data</literal> vector using the
100             classes <literal>x</literal>. When the number <literal>n</literal> of classes is provided
101             instead of <literal>x</literal>, the classes are chosen equally spaced and
102             <emphasis>x(1) = min(data) &lt; x(2) = x(1) + dx &lt; ... &lt; x(n+1) = max(data)</emphasis>
103             with <emphasis>dx = (x(n+1)-x(1))/n</emphasis>.
104         </para>
105         <para> The classes are defined by C1 = [x(1), x(2)] and  Ci = ( x(i), x(i+1)] for i &gt;= 2.
106             Noting Nmax the total number of <literal>data</literal> (Nmax = length(data)) and Ni the number
107             of <literal>data</literal> components falling in Ci, the value of the histogram for x in Ci
108             is equal to <emphasis>Ni/(Nmax (x(i+1)-x(i)))</emphasis> when <literal>normalization</literal> is true
109             (default case) and else, simply equal to <emphasis>Ni</emphasis>. When normalization occurs the
110             histogram verifies:
111         </para>
112         <para>
113             <latex style="display"><![CDATA[ \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1 ]]></latex>
114         </para>
115         <para>
116             when <emphasis>x(1)&lt;=min(data)</emphasis> and <emphasis>max(data) &lt;= x(n+1)</emphasis>
117         </para>
118         <para>
119             Any <link linkend="plot2d">plot2d</link> (optional) parameter may be provided; for instance to
120             plot a histogram with the color number 2 (blue if std colormap is used) and
121             to restrict the plot inside the rectangle [-3,3]x[0,0.5],
122             you may use <literal>histplot(n,data, style=2, rect=[-3,0,3,0.5])</literal>.
123         </para>
124         <para>
125             Frequency polygon is a line graph drawn by joining all the midpoints of the top of the bins of a histogram.
126             Therefore we can use <literal>histplot</literal> function to plot a polygon frequency chart.
127         </para>
128         <para>
129             The optional argument <literal>polygon</literal> connects the midpoint of the top of each bar of a histogram with straight lines.
130         </para>
131         <para>
132             If <literal>polygon=%t</literal> we will have a histogram with frequency polygon chart.
133         </para>
134         <para>
135             Enter the command <literal>histplot()</literal> to see a demo.
136         </para>
137     </refsection>
138     <refsection>
139         <title>Examples</title>
140         <simplelist>
141             <member> Example #1: variations around a histogram of a gaussian random sample
142                 <programlisting role="example"><![CDATA[
143 d=rand(1,10000,'normal');  // the gaussian random sample
144 clf(); histplot(20,d)
145 clf(); histplot(20,d,normalization=%f)
146 clf(); histplot(20,d,leg='rand(1,10000,''normal'')',style=5)
147 clf(); histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]);
148 ]]></programlisting>
149                 <scilab:image>
150                     d=rand(1,10000,'normal');
151                     clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]);
152                 </scilab:image>
153             </member>
154             <member>
155                 Example #2: histogram of a binomial (B(6,0.5)) random sample
156                 <programlisting role="example"><![CDATA[
157 d = grand(1000,1,"bin", 6, 0.5);
158 c = linspace(-0.5,6.5,8);
159 clf()
160 subplot(2,1,1)
161 histplot(c, d, style=2)
162 xtitle("Normalized histogram")
163 subplot(2,1,2)
164 histplot(c, d, normalization=%f, style=5)
165 xtitle("Non normalized histogram")
166 ]]></programlisting>
167                 <scilab:image localized="true">
168                     d = grand(1000,1,"bin", 6, 0.5);
169                     c = linspace(-0.5,6.5,8);
170                     clf()
171                     subplot(2,1,1)
172                     histplot(c, d, style=2)
173                     xtitle("normalized histogram")
174                     subplot(2,1,2)
175                     histplot(c, d, normalization=%f, style=5)
176                     xtitle("non normalized histogram")
177                 </scilab:image>
178             </member>
179             <member>
180                 Example #3: histogram of an exponential random sample
181                 <programlisting role="example"><![CDATA[
182 lambda = 2;
183 X = grand(100000,1,"exp", 1/lambda);
184 Xmax = max(X);
185 clf()
186 histplot(40, X, style=2)
187 x = linspace(0,max(Xmax),100)';
188 plot2d(x,lambda*exp(-lambda*x),strf="000",style=5)
189 legend(["exponential random sample histogram" "exact density curve"]);
190 ]]></programlisting>
191                 <scilab:image localized="true">
192                     lambda = 2;
193                     X = grand(100000,1,"exp", 1/lambda);
194                     Xmax = max(X);
195                     clf()
196                     histplot(40, X, style=2)
197                     x = linspace(0,max(Xmax),100)';
198                     plot2d(x,lambda*exp(-lambda*x),strf="000",style=5)
199                     legend(["exponential random sample histogram" "exact density curve"]);
200                 </scilab:image>
201             </member>
202             <member>
203                 Example #4: the frequency polygon chart and the histogram of a gaussian random sample
204                 <programlisting role="example"><![CDATA[
205 n=10;
206 data=rand(1,1000,"normal");
207 clf(); histplot(n, data, style=12, polygon=%t);
208 legend(["normalized histogram" "frequency polygon chart"]);
209 ]]></programlisting>
210                 <scilab:image localized="true">
211                     n=10;
212                     data=rand(1,1000,"normal");
213                     clf(); histplot(n,data,style=12,polygon=%t);
214                     legend(["normalized histogram" "frequency polygon chart"]);
215                 </scilab:image>
216             </member>
217         </simplelist>
218     </refsection>
219     <refsection role="see also">
220         <title>See Also</title>
221         <simplelist type="inline">
222             <member>
223                 <link linkend="histc">histc</link>
224             </member>
225             <member>
226                 <link linkend="hist3d">hist3d</link>
227             </member>
228             <member>
229                 <link linkend="plot2d">plot2d</link>
230             </member>
231             <member>
232                 <link linkend="dsearch">dsearch</link>
233             </member>
234         </simplelist>
235     </refsection>
236 </refentry>