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>