<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Farid Belahcene
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * 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.
 *
 -->
<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="bar">
    <refnamediv>
        <refname>bar</refname>
        <refpurpose>bar histogram</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>bar(y)
            bar(x, y)
            bar(x, y, width, colors, style)
            bar(x, y [,width] [,colors] [,style])
            bar(h, ..)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>h</term>
                <listitem>
                    <para>an axes handle, (default: h=gca() ).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>
                        scalar, vector of size N, or matrix N*M of real numbers or encoded integers,
                      with
                      <itemizedlist>
                        <listitem>
                          N : number of groups (each group of bars gathered on/around an x position)
                        </listitem>
                        <listitem>
                          M : number of categories in each group
                        </listitem>
                      </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>a real scalar or a vector of size N. By default,
                      <itemizedlist>
                        <listitem>
                          If <varname>y</varname> is a vector: <literal>x=1:length(y)</literal>
                        </listitem>
                        <listitem>
                          If <varname>y</varname> is a matrix: <literal>x=1:size(y,"r")</literal>
                        </listitem>
                      </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>width</term>
                <listitem>
                    <para>(optional), a real scalar, defines the width (a percentage of
                        the available room) for the bar (default: 0.8, i.e 80%).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>colors</term>
                <listitem>
                    <para>
                        (optional) Single string or vector of M strings: colors names (among
                        predefined ones) or "#RRGGBB" hexadecimal codes of categories colors.
                        Default = default plot() colors series, starting with "blue".
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>style</term>
                <listitem>
                    <para>a string, 'grouped' (default), or 'stacked'.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>bar(y,...) :</literal> if y is a vector, then bar() draws a
            polyline which has the <literal>polyline_style</literal> type 6, versus x=1:length(y).
            If y is a matrix N*M, bar() draws M polylines (type 6), versus x=1:size(y,1).
            Each polyline represents a category, with a specific color.
        </para>
        <para>
            <literal>bar(x,y,...) :</literal> if y is a vector, then bar() draws a
            polyline which has the <literal>polyline_style</literal> type 6, where x length
            = y length. If y is a matrix NxM then bar function draws M polylines which
            have the type 6. Each polyline corresponds to a column of y versus vector
            x.
        </para>
        <para>
            <literal>bar(h,...) :</literal> specifies the targeted axes where the drawing is
            performed.
        </para>
        <para>
            <literal>bar(...,width,...) :</literal> defines the relative width of the bar(s):
            0&lt;width&lt;=1.
        </para>
        <para>
            <literal>bar(...,style,...) :</literal> defines how the bar is drawn. If y is
            a matrix N*M (so M polylines of type 6), then there are two ways to draw
            the M bars. the style option = 'grouped' allows to center the M polylines
            versus each components of x, and the style option 'stacked' allows to
            stack them.
        </para>
        <para>
            <literal>bar(...,colors,...) : </literal> defines the colors identifying categories
            and filling the corresponding subsets of bars.
        </para>
        <para>
            If there are several bar() calls, the <literal>barhomogenize</literal> function
            allows to homogenize the width and style of all bars (i.e polylines of
            type 6) included in the current working axes.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// First example: draw a bar (i.e a polyline with polyline_style type =6) with
// width=0.5 and colors='yellow' and default style='grouped', x=1:length(y).
scf(0);
y=[1 -3 5];
bar(y,0.5,'yellow');
 ]]></programlisting>
        <scilab:image>
            y=[1 -3 5];
            bar(y,0.5,'yellow');
        </scilab:image>
        <programlisting role="example"><![CDATA[

// Second example: draw 3 bars (i.e 3 polylines with polyline_style type =6),default style='grouped'
scf(1);
x=[1 2 5];
y=[1  -5 6;3 -2 7;4  -3 8];
bar(x,y);
 ]]></programlisting>
        <scilab:image>
            x=[1 2 5];
            y=[1  -5 6;3 -2 7;4  -3 8];
            bar(x,y);
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Third example : style='stacked'.
scf(2);
x=[1 2 5];
y=[1 4 7;2 5 8;3 6  9];
bar(x,y,'stacked');
 ]]></programlisting>
        <scilab:image>
            x=[1 2 5];
            y=[1 4 7;2 5 8;3 6  9];
            bar(x,y,'stacked');
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Fourth example: width=0.2;colors='green'; default style='grouped'
scf(3);
x=[1 2 5];
y=[1 4 7;2 5 8;3 6 9];
bar(x,y,0.2,'green');
 ]]></programlisting>
        <scilab:image>
            x=[1 2 5];
            y=[1 4 7;2 5 8;3 6 9];
            bar(x,y,0.2,'green');
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="barh">barh</link>
            </member>
            <member>
                <link linkend="barhomogenize">barhomogenize</link>
            </member>
            <member>
                <link linkend="histplot">histplot</link>
            </member>
            <member>
                <link linkend="plot">plot</link>
            </member>
            <member>
                <link linkend="color_list">named colors</link>
            </member>
            <member>
                <link linkend="polyline_properties">polyline_properties</link>
            </member>
            <member>
                <link linkend="bar3d">bar3d</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0.1</revnumber>
                <revdescription>
                    <itemizedlist>
                      <listitem>
                        A vector of M colors can now be provided, one for each category.
                      </listitem>
                      <listitem>
                        Available colors are no longer restricted to the 10 major colors. All the
                        predefined colors names can now be used.
                      </listitem>
                      <listitem>
                        Colors can now be specified also by their "#RRGGBB" hexadecimal codes.
                      </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
