Add more images and improves the examples
[scilab.git] / scilab / modules / statistics / help / en_US / summaries / tabul.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) 2000 - INRIA - Carlos Klimann
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" xmlns:scilab="http://www.scilab.org" xml:id="tabul">
14     <refnamediv>
15         <refname>tabul</refname>
16         <refpurpose> frequency of values of a matrix or vector</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>[m]=tabul(X [,order])</synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>X</term>
27                 <listitem>
28                     <para>vector or matrix (of real or complex numbers or strings)</para>
29                 </listitem>
30             </varlistentry>
31             <varlistentry>
32                 <term>order</term>
33                 <listitem>
34                     <para>(optional) a character equal to "d" or "i" (default value "d")</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>m</term>
39                 <listitem>
40                     <para>
41                         a 2 columns matrix (if <literal>X</literal> is a numerical vector or matrix) or 
42                         a list with 2 members (if <literal>X</literal> is a string vector or matrix).
43                     </para>
44                 </listitem>
45             </varlistentry>
46         </variablelist>
47     </refsection>
48     <refsection>
49         <title>Description</title>
50         <para>
51             This function computes the frequency of values of 
52             the components of a vector or matrix <literal>X</literal> of numbers or
53             string characters :
54         </para>
55         <variablelist>
56             <varlistentry>
57                 <term>if X is a numerical vector or matrix</term>
58                 <listitem>
59                     <para>
60                         then <literal>m</literal>  is a  two column matrix who contains in 
61                         the first column the distinct values of <literal>X</literal> 
62                         and  in the other column the number of occurrences 
63                         of those values (m(i,2) is the number of occurrences
64                         of m(i,1)).
65                     </para>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>if X is a string vector or matrix</term>
70                 <listitem>
71                     <para>
72                         then <literal>m</literal> is  a list whose  first member is a 
73                         string (column) vector composed with the distinct 
74                         values of <literal>X</literal> and the second member is a 
75                         (column) vector whose components are the number of 
76                         occurrences of those values ( m(i)(2) is the number 
77                         of occurrences of the string m(i)(1) ).
78                     </para>
79                 </listitem>
80             </varlistentry>
81         </variablelist>
82         <para>
83             The optional parameter <literal>order</literal> must be  "d" or "i" (by default 
84             order="d") and gives the order (decreasing or increasing) the distinct 
85             values of X will be sorted.
86         </para>
87     </refsection>
88     <refsection>
89         <title>Examples</title>
90         <programlisting role="example"><![CDATA[ 
91 X = [2 8 0 3 7 6 8 7 9 1 6 7 7 2 5 2 2 2 9 7]
92 m1 = tabul(X)
93 m2 = tabul(X, "i")
94  ]]></programlisting>
95         <programlisting role="example"><![CDATA[ 
96
97 X = ["ba" "baba" "a" "A" "AA" "a" "aa" "aa" "aa" "A" "ba"]
98 m = tabul(X,"i")
99  ]]></programlisting>
100         <programlisting role="example"><![CDATA[ 
101
102 n = 50000;
103 X = grand(n,1,"bin",70,0.5);
104 m = tabul(X,"i");
105 clf()
106 plot2d3(m(:,1), m(:,2)/n)
107 xtitle("empirical probabilities of B(70,0.5)")
108  ]]></programlisting>
109         <scilab:image>
110             
111             n = 50000;
112             X = grand(n,1,"bin",70,0.5);
113             m = tabul(X,"i");
114             clf()
115             plot2d3(m(:,1), m(:,2)/n)
116             xtitle("empirical probabilities of B(70,0.5)")
117             
118         </scilab:image>
119         <programlisting role="example"><![CDATA[ 
120
121 // computes the occurrences of words of the license of scilab 
122 text = read(SCI+"/license.txt",-1,1,"(A)"); // read the scilab license
123 bigstr = strcat(text," ");                  // put all the lines in a big string
124 sep =  [" " "," "." ";" "*" ":" "-" """"];  // words separators 
125 words = tokens(bigstr, sep);                // cut the big string into words
126 m = tabul(words);                           // computes occurrences of each word
127 [occ , p] = gsort(m(2));                     // sort by decreasing frequencies
128 results = [m(1)(p) string(occ)]             // display result
129  ]]></programlisting>
130     </refsection>
131     <refsection role="see also">
132         <title>See Also</title>
133         <simplelist type="inline">
134             <member>
135                 <link linkend="dsearch">dsearch</link>
136             </member>
137             <member>
138                 <link linkend="histplot">histplot</link>
139             </member>
140         </simplelist>
141     </refsection>
142     <refsection>
143         <title>Bibliography</title>
144         <para>
145             Wonacott, T.H. &amp; Wonacott, R.J.; Introductory Statistics, 
146             fifth edition, J.Wiley &amp; Sons, 1990.
147         </para>
148     </refsection>
149 </refentry>