1 <?xml version='1.0' encoding='UTF-8'?>
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
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
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">
16 <refname>histplot</refname>
17 <refpurpose>plot a histogram</refpurpose>
20 <title>Calling Sequence</title>
22 [cf, ind] = histplot(n, data [,normalization] [,polygon], <opt_args>)
23 [cf, ind] = histplot(x, data [,normalization] [,polygon], <opt_args>)
27 <title>Arguments</title>
32 <para>positive integer (number of classes)</para>
39 increasing vector defining the classes (<literal>x</literal> may have at least 2 components)
46 <para>vector (data to be analysed)</para>
50 <term>normalization</term>
52 <para>a boolean (%t (default value) or %f)</para>
58 <para>a boolean (%t or %f (default value))</para>
62 <term><opt_args></term>
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>
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>
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>
97 <title>Description</title>
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) < x(2) = x(1) + dx < ... < x(n+1) = max(data)</emphasis>
103 with <emphasis>dx = (x(n+1)-x(1))/n</emphasis>.
105 <para> The classes are defined by C1 = [x(1), x(2)] and Ci = ( x(i), x(i+1)] for i >= 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
113 <latex style="display"><![CDATA[ \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1 ]]></latex>
116 when <emphasis>x(1)<=min(data)</emphasis> and <emphasis>max(data) <= x(n+1)</emphasis>
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>.
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.
129 The optional argument <literal>polygon</literal> connects the midpoint of the top of each bar of a histogram with straight lines.
132 If <literal>polygon=%t</literal> we will have a histogram with frequency polygon chart.
135 Enter the command <literal>histplot()</literal> to see a demo.
139 <title>Examples</title>
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]);
150 d=rand(1,10000,'normal');
151 clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]);
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);
161 histplot(c, d, style=2)
162 xtitle("Normalized histogram")
164 histplot(c, d, normalization=%f, style=5)
165 xtitle("Non normalized histogram")
167 <scilab:image localized="true">
168 d = grand(1000,1,"bin", 6, 0.5);
169 c = linspace(-0.5,6.5,8);
172 histplot(c, d, style=2)
173 xtitle("normalized histogram")
175 histplot(c, d, normalization=%f, style=5)
176 xtitle("non normalized histogram")
180 Example #3: histogram of an exponential random sample
181 <programlisting role="example"><![CDATA[
183 X = grand(100000,1,"exp", 1/lambda);
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"]);
191 <scilab:image localized="true">
193 X = grand(100000,1,"exp", 1/lambda);
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"]);
203 Example #4: the frequency polygon chart and the histogram of a gaussian random sample
204 <programlisting role="example"><![CDATA[
206 data=rand(1,1000,"normal");
207 clf(); histplot(n, data, style=12, polygon=%t);
208 legend(["normalized histogram" "frequency polygon chart"]);
210 <scilab:image localized="true">
212 data=rand(1,1000,"normal");
213 clf(); histplot(n,data,style=12,polygon=%t);
214 legend(["normalized histogram" "frequency polygon chart"]);
219 <refsection role="see also">
220 <title>See Also</title>
221 <simplelist type="inline">
223 <link linkend="histc">histc</link>
226 <link linkend="hist3d">hist3d</link>
229 <link linkend="plot2d">plot2d</link>
232 <link linkend="dsearch">dsearch</link>