<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
<MAN>
  <LANGUAGE>eng</LANGUAGE>
  <TITLE>tabul</TITLE>
  <TYPE>  </TYPE>
  <DATE>July 2000</DATE>
  <SHORT_DESCRIPTION name="tabul"> frequency of values of a matrix or vector</SHORT_DESCRIPTION>
  <CALLING_SEQUENCE>
    <CALLING_SEQUENCE_ITEM>[m]=tabul(X [,order])</CALLING_SEQUENCE_ITEM>
  </CALLING_SEQUENCE>
  <PARAM>
    <PARAM_INDENT>
      <PARAM_ITEM>
        <PARAM_NAME>X</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: vector or matrix (of real or complex numbers or strings)</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>order</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: (optionnal) a character equal to &quot;d&quot; or &quot;i&quot; (default value &quot;d&quot;)</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>m</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: a 2 columns matrix (if <VERB>X</VERB> is a numerical vector or matrix) or 
      a list with 2 members (if <VERB>X</VERB> is a string vector or matrix).</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
    </PARAM_INDENT>
  </PARAM>
  <DESCRIPTION>
    <P>
   This function computes the frequency of values of 
   the components of a vector or matrix <VERB>X</VERB> of numbers or
   string characters :
   </P>
    <DESCRIPTION_INDENT>
      <DESCRIPTION_ITEM label="if X is a numerical vector or matrix">
        <SP>then <VERB>m</VERB>  is a  two column matrix who contains in 
           the first column the distinct values of <VERB>X</VERB> 
           and  in the other column the number of occurrences 
           of those values (m(i,2) is the number of occurrences
           of m(i,1)).</SP>
      </DESCRIPTION_ITEM>
      <DESCRIPTION_ITEM label="if X is a string vector or matrix">
        <SP>then <VERB>m</VERB> is  a list whose  first member is a 
           string (column) vector composed with the distinct 
           values of <VERB>X</VERB> and the second member is a 
           (column) vector whose components are the number of 
           occurrences of those values ( m(i)(2) is the number 
           of occurrences of the string m(i)(1) ).</SP>
      </DESCRIPTION_ITEM>
    </DESCRIPTION_INDENT>
    <P>
   The optional parameter <VERB>order</VERB> must be  &quot;d&quot; or &quot;i&quot; (by default 
   order=&quot;d&quot;) and gives the order (decreasing or increasing) the distinct 
   values of X will be sorted.</P>
  </DESCRIPTION>
  <EXAMPLE>
<![CDATA[
// first example
X = [2 8 0 3 7 6 8 7 9 1 6 7 7 2 5 2 2 2 9 7]
m1 = tabul(X)
m2 = tabul(X, "i")

// second example 
X = ["ba" "baba" "a" "A" "AA" "a" "aa" "aa" "aa" "A" "ba"]
m = tabul(X,"i")

// third example
n = 50000;
X = grand(n,1,"bin",70,0.5);
m = tabul(X,"i");
xbasc()
plot2d3(m(:,1), m(:,2)/n)
xtitle("empiral probabilities of B(70,0.5)")

// last example : computes the occurrences of words of the scilab license
text = read(SCI+"/license.txt",-1,1,"(A)"); // read the scilab license
bigstr = strcat(text," ");                  // put all the lines in a big string
sep =  [" " "," "." ";" "*" ":" "-" """"];  // words separators 
words = tokens(bigstr, sep);                // cut the big string into words
m = tabul(words);                           // computes occurrences of each word
[occ , p] = sort(m(2));                     // sort by decreasing frequencies
results = [m(1)(p) string(occ)]             // display result
 ]]>
  </EXAMPLE>
  <SEE_ALSO>
    <SEE_ALSO_ITEM>
      <LINK>dsearch</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>histplot</LINK>
    </SEE_ALSO_ITEM>
  </SEE_ALSO>
  <AUTHORS>
    <AUTHORS_ITEM> Carlos Klimann (original author)</AUTHORS_ITEM>
    <AUTHORS_ITEM> J.S. Giet and B. Pincon (new version)</AUTHORS_ITEM>
  </AUTHORS>
  <BIBLIO>
    <P>
     Wonacott, T.H. &amp; Wonacott, R.J.; Introductory Statistics, 
     fifth edition, J.Wiley &amp; Sons, 1990.</P>
  </BIBLIO>
</MAN>
