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