<?xml version='1.0' encoding='UTF-8'?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier: added data output
 * Copyright (C) INRIA - Serge Steer
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 --><!-- This document was created with Syntext Serna Free. -->
<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">
    <refnamediv>
        <refname>histplot</refname>
        <refpurpose>plot a histogram</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            histplot(n, data [,normalization] [,polygon], &lt;opt_args&gt;)
            histplot(x, data [,normalization] [,polygon], &lt;opt_args&gt;)
            cf = histplot(..)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>n</term>
                <listitem>
                    <para>positive integer (number of classes)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>
                        increasing vector defining the classes (<literal>x</literal> may have at least 2 components)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>data</term>
                <listitem>
                    <para>vector (data to be analysed)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>normalization</term>
                <listitem>
                    <para>a boolean (%t (default value) or %f)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>polygon</term>
                <listitem>
                    <para>a boolean (%t or %f (default value))</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>
                        This represents a sequence of statements <literal>key1=value1,key2=value2</literal>
                        ,... where <literal>key1</literal>,
                        <literal>key2,...</literal> can be any optional <link linkend="plot2d">plot2d</link> parameter (<literal>style,strf,leg, rect,nax, logflag,frameflag, axesflag </literal>
                        ).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>cf</term>
                <listitem>
                    <para>Computed frequencies (bins heighs)
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            This function plots a histogram of the <literal>data</literal> vector using the
            classes <literal>x</literal>. When the number <literal>n</literal> of classes is provided
            instead of <literal>x</literal>, the classes are chosen equally spaced and
            <emphasis>x(1) = min(data) &lt; x(2) = x(1) + dx &lt; ... &lt; x(n+1) = max(data)</emphasis>
            with <emphasis>dx = (x(n+1)-x(1))/n</emphasis>.
        </para>
        <para> The classes are defined by C1 = [x(1), x(2)] and  Ci = ( x(i), x(i+1)] for i &gt;= 2.
            Noting Nmax the total number of <literal>data</literal> (Nmax = length(data)) and Ni the number
            of <literal>data</literal> components falling in Ci, the value of the histogram for x in Ci
            is equal to <emphasis>Ni/(Nmax (x(i+1)-x(i)))</emphasis> when <literal>normalization</literal> is true
            (default case) and else, simply equal to <emphasis>Ni</emphasis>. When normalization occurs the
            histogram verifies:
        </para>
        <para>
            <latex style="display"><![CDATA[ \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1 ]]></latex>
        </para>
        <para>
            when <emphasis>x(1)&lt;=min(data)</emphasis> and <emphasis>max(data) &lt;= x(n+1)</emphasis>
        </para>
        <para>
            Any <link linkend="plot2d">plot2d</link> (optional) parameter may be provided; for instance to
            plot a histogram with the color number 2 (blue if std colormap is used) and
            to restrict the plot inside the rectangle [-3,3]x[0,0.5],
            you may use <literal>histplot(n,data, style=2, rect=[-3,0,3,0.5])</literal>.
        </para>
        <para>
            Frequency polygon is a line graph drawn by joining all the midpoints of the top of the bins of a histogram.
            Therefore we can use <literal>histplot</literal> function to plot a polygon frequency chart.
        </para>
        <para>
            The optional argument <literal>polygon</literal> connects the midpoint of the top of each bar of a histogram with straight lines.
        </para>
        <para>
            If <literal>polygon=%t</literal> we will have a histogram with frequency polygon chart.
        </para>
        <para>
            Enter the command <literal>histplot()</literal> to see a demo.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
            <para>
                <emphasis role="bold">Example #1</emphasis>:
                variations around a histogram of a gaussian random sample
            </para>
            <programlisting role="example"><![CDATA[
d = rand(1,10000,'normal');  // the gaussian random sample

clf(); histplot(20,d);
clf(); histplot(20,d,normalization=%f);
clf(); histplot(20,d,leg='rand(1,10000,''normal'')',style=5);
clf(); histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]);
]]></programlisting>
                <scilab:image>
                    d=rand(1,10000,'normal');
                    clf();histplot(20,d,leg='rand(1,10000,''normal'')',style=16, rect=[-3,0,3,0.5]);
                </scilab:image>
            <para/>
            <para>
                <emphasis role="bold">Example #2</emphasis>:
                histogram of a binomial (B(6,0.5)) random sample
            </para>
            <programlisting role="example"><![CDATA[
d = grand(1000,1,"bin", 6, 0.5);
c = linspace(-0.5,6.5,8);

clf()
subplot(2,1,1)
histplot(c, d, style=2);
xtitle("Normalized histogram")

subplot(2,1,2)
histplot(c, d, normalization=%f, style=5);
xtitle("Non normalized histogram")
]]></programlisting>
                <scilab:image localized="true">
                    d = grand(1000,1,"bin", 6, 0.5);
                    c = linspace(-0.5,6.5,8);
                    clf()
                    subplot(2,1,1)
                    histplot(c, d, style=2)
                    xtitle("normalized histogram")
                    subplot(2,1,2)
                    histplot(c, d, normalization=%f, style=5)
                    xtitle("non normalized histogram")
                </scilab:image>
            <para/>
            <para>
                <emphasis role="bold">Example #3</emphasis>:
                histogram of an exponential random sample
            </para>
            <programlisting role="example"><![CDATA[
lambda = 2;
X = grand(100000,1,"exp", 1/lambda);
Xmax = max(X);

clf()
histplot(40, X, style=2);
x = linspace(0,max(Xmax),100)';
plot2d(x,lambda*exp(-lambda*x),strf="000",style=5)
legend(["exponential random sample histogram" "exact density curve"]);
]]></programlisting>
            <scilab:image localized="true">
                lambda = 2;
                X = grand(100000,1,"exp", 1/lambda);
                Xmax = max(X);
                clf()
                histplot(40, X, style=2)
                x = linspace(0,max(Xmax),100)';
                plot2d(x,lambda*exp(-lambda*x),strf="000",style=5)
                legend(["exponential random sample histogram" "exact density curve"]);
            </scilab:image>
            <para/>
            <para>
                <emphasis role="bold">Example #4</emphasis>:
                the frequency polygon chart and the histogram of a gaussian random sample
            </para>
            <programlisting role="example"><![CDATA[
n = 10;
data = rand(1,1000,"normal");

clf(); histplot(n, data, style=12, polygon=%t);
legend(["normalized histogram" "frequency polygon chart"],"lower_caption");
]]></programlisting>
            <scilab:image localized="true">
                n=10;
                data=rand(1,1000,"normal");
                clf(); histplot(n,data,style=12,polygon=%t);
                legend(["normalized histogram" "frequency polygon chart"],"lower_caption");
            </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="histc">histc</link>
            </member>
            <member>
                <link linkend="bar3d">bar3d</link>
            </member>
            <member>
                <link linkend="bar">bar</link>
            </member>
            <member>
                <link linkend="plot2d">plot2d</link>
            </member>
            <member>
                <link linkend="dsearch">dsearch</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revdescription>
                    <literal>polygon</literal> option and <literal>cf</literal> output added.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
