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