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