More samples in the graphic help pages Note that they are automatically generated...
[scilab.git] / scilab / modules / graphics / help / en_US / bar_histogram / bar.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 - Farid Belahcene
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="bar">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>bar</refname>
19     <refpurpose>bar histogram</refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>bar(y)
24       bar(x,y)
25       bar([h],x,y [,width [,color [,style]]])
26     </synopsis>
27   </refsynopsisdiv>
28   <refsection>
29     <title>Arguments</title>
30     <variablelist>
31       <varlistentry>
32         <term>h</term>
33         <listitem>
34           <para>an axes handle, (default: h=gca() ).</para>
35         </listitem>
36       </varlistentry>
37       <varlistentry>
38         <term>y</term>
39         <listitem>
40           <para>a real scalar, vector of size N, or a matrice N*M.</para>
41         </listitem>
42       </varlistentry>
43       <varlistentry>
44         <term>x</term>
45         <listitem>
46           <para>a real scalar or a vector of size N, (default: if y is a
47             vector then x is a vector and x length equals to y length. If y is a
48             matrix then x is a vector and x length equals to the lines number of
49             y.
50           </para>
51         </listitem>
52       </varlistentry>
53       <varlistentry>
54         <term>width</term>
55         <listitem>
56           <para>(optional), a real scalar, defines the width (a percentage of
57             the available room) for the bar (default: 0.8, i.e 80%).
58           </para>
59         </listitem>
60       </varlistentry>
61       <varlistentry>
62         <term>color</term>
63         <listitem>
64           <para>(optional), a string (default: 'blue'), specifying the inside
65             color bar.
66           </para>
67         </listitem>
68       </varlistentry>
69       <varlistentry>
70         <term>style:</term>
71         <listitem>
72           <para>a string, 'grouped' or 'stacked' (default: 'grouped').</para>
73         </listitem>
74       </varlistentry>
75     </variablelist>
76   </refsection>
77   <refsection>
78     <title>Description</title>
79     <para>
80       <literal>bar(y,...) :</literal> if y is a vector then bar function draws a
81       polyline which has the <literal>polyline_style</literal> type 6. If y is a
82       vector, bar draws vector y versus vector 1:size(y,'*') . If y is a matrix
83       N*M, bar draws M polylines (type 6), each polyline corresponds to a column
84       of y versus vector x=1:size(y,1).
85     </para>
86     <para>
87       <literal>bar(x,y,...) :</literal> if y is a vector then bar function draws a
88       polyline which has the <literal>polyline_style</literal> type 6, where x length
89       = y length.If y is a matrix NxM then bar function draws M polylines which
90       have the type 6. Each polyline corresponds to a column of y versus vector
91       x.
92     </para>
93     <para>
94       <literal>bar(h,...) :</literal> defines the current axes where the drawing is
95       performed.
96     </para>
97     <para>
98       <literal>bar(...,width,...) :</literal> defines the width of the bar(s) in
99       percentage (generally: 0&lt;width&lt;=1).
100     </para>
101     <para>
102       <literal>bar(...,style,...) :</literal> defines how the bar is drawn. If y is
103       a matrix N*M (so M polylines of type 6) then there are two ways to draw
104       the M bars. the style option = 'grouped' allows to center the M polylines
105       versus each components of x, and the style option 'stacked' allows to
106       stack them.
107     </para>
108     <para>
109       <literal>bar(...,color,...) : </literal>defines the bar color. Bar functions
110       uses the same colormap than in the <literal>plot</literal> function.
111     </para>
112     <para>
113       If there are several bar calls, the <literal>barhomogenize</literal> function
114       allows to homegenize the width and style of all bars (i.e polylines of
115       type 6) included in the current working axes.
116     </para>
117   </refsection>
118   <refsection>
119     <title>Sample</title>
120     <scilab:image>
121       x=[1 2 5];
122       y=[1 4 7;2 5 8;3 6  9];
123       bar(x,y,'stacked');
124     </scilab:image>
125   </refsection>
126   <refsection>
127     <title>Examples</title>
128     <programlisting role="example"><![CDATA[ 
129 // First example: draw a bar (i.e a polyline with polyline_style type =6) with
130 // width=0.5 and color='yellow' and default style='grouped', x=1:length(y).
131 scf(0);
132 y=[1 -3 5];
133 bar(y,0.5,'yellow');
134  ]]></programlisting>
135     <programlisting role="example"><![CDATA[ 
136
137 // Second example: draw 3 bars (i.e 3 polylines with polyline_style type =6),default style='grouped'
138 scf(1);
139 x=[1 2 5];
140 y=[1  -5 6;3 -2 7;4  -3 8];
141 bar(x,y);
142  ]]></programlisting>
143     
144     <programlisting role="example"><![CDATA[ 
145 // Third example : style='stacked'.
146 scf(2);
147 x=[1 2 5];
148 y=[1 4 7;2 5 8;3 6  9];
149 bar(x,y,'stacked');
150  ]]></programlisting>
151     
152     <programlisting role="example"><![CDATA[ 
153 // Fourth example: width=0.2;color='green'; default style='grouped'
154 scf(3);
155 x=[1 2 5];
156 y=[1 4 7;2 5 8;3 6 9];
157 bar(x,y,0.2,'green');
158  ]]></programlisting>
159   </refsection>
160   <refsection role="see also">
161     <title>See Also</title>
162     <simplelist type="inline">
163       <member>
164         <link linkend="barh">barh</link>
165       </member>
166       <member>
167         <link linkend="barhomogenize">barhomogenize</link>
168       </member>
169       <member>
170         <link linkend="plot">plot</link>
171       </member>
172       <member>
173         <link linkend="polyline_properties">polyline_properties</link>
174       </member>
175     </simplelist>
176   </refsection>
177 </refentry>