read.ftable              package:stats              R Documentation

_M_a_n_i_p_u_l_a_t_e _F_l_a_t _C_o_n_t_i_n_g_e_n_c_y _T_a_b_l_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Read, write and coerce 'flat' contingency tables.

_U_s_a_g_e:

     read.ftable(file, sep = "", quote = "\"",
                 row.var.names, col.vars, skip = 0)

     write.ftable(x, file = "", quote = TRUE, append = FALSE,
                  digits = getOption("digits"))

     ## S3 method for class 'ftable':
     format(x, quote = TRUE, digits = getOption("digits"), ...)

_A_r_g_u_m_e_n_t_s:

    file: either a character string naming a file or a connection which
          the data are to be read from or written to.  '""' indicates
          input from the console for reading and output to the console
          for writing.

     sep: the field separator string.  Values on each line of the file
          are separated by this string.

   quote: a character string giving the set of quoting characters for
          'read.ftable'; to disable quoting altogether, use 'quote=""'.
           For 'write.table', a logical indicating whether strings in
          the data will be surrounded by double quotes.

row.var.names: a character vector with the names of the row variables,
          in case these cannot be determined automatically.

col.vars: a list giving the names and levels of the column variables,
          in case these cannot be determined automatically.

    skip: the number of lines of the data file to skip before beginning
          to read data.

       x: an object of class '"ftable"'.

  append: logical.  If 'TRUE' and 'file' is the name of a file (and not
          a connection or '"|cmd"'), the output from 'write.ftable' is
          appended to the file.  If 'FALSE', the contents of 'file'
          will be overwritten.

  digits: an integer giving the number of significant digits to use for
          (the cell entries of) 'x'.

     ...: further arguments to be passed to or from methods.

_D_e_t_a_i_l_s:

     'read.ftable' reads in a flat-like contingency table from a file. 
     If the file contains the written representation of a flat table
     (more precisely, a header with all information on names and levels
     of column variables, followed by a line with the names of the row
     variables), no further arguments are needed.  Similarly, flat
     tables with only one column variable the name of which is the only
     entry in the first line are handled automatically.  Other variants
     can be dealt with by skipping all header information using 'skip',
     and providing the names of the row variables and the names and
     levels of the column variable using 'row.var.names' and
     'col.vars', respectively.  See the examples below.

     Note that flat tables are characterized by their 'ragged' display
     of row (and maybe also column) labels.  If the full grid of levels
     of the row variables is given, one should instead use 'read.table'
     to read in the data, and create the contingency table from this
     using 'xtabs'.

     'write.ftable' writes a flat table to a file, which is useful for
     generating 'pretty' ASCII representations of contingency tables.

_R_e_f_e_r_e_n_c_e_s:

     Agresti, A. (1990) _Categorical data analysis_. New York: Wiley.

_S_e_e _A_l_s_o:

     'ftable' for more information on flat contingency tables.

_E_x_a_m_p_l_e_s:

     ## Agresti (1990), page 157, Table 5.8.
     ## Not in ftable standard format, but o.k.
     file <- tempfile()
     cat("             Intercourse\n",
         "Race  Gender     Yes  No\n",
         "White Male        43 134\n",
         "      Female      26 149\n",
         "Black Male        29  23\n",
         "      Female      22  36\n",
         file = file)
     file.show(file)
     ft <- read.ftable(file)
     ft
     unlink(file)

     ## Agresti (1990), page 297, Table 8.16.
     ## Almost o.k., but misses the name of the row variable.
     file <- tempfile()
     cat("                      \"Tonsil Size\"\n",
         "            \"Not Enl.\" \"Enl.\" \"Greatly Enl.\"\n",
         "Noncarriers       497     560           269\n",
         "Carriers           19      29            24\n",
         file = file)
     file.show(file)
     ft <- read.ftable(file, skip = 2,
                       row.var.names = "Status",
                       col.vars = list("Tonsil Size" =
                           c("Not Enl.", "Enl.", "Greatly Enl.")))
     ft
     unlink(file)

     ft22 <- ftable(Titanic, row.vars = 2:1, col.vars = 4:3)
     write.ftable(ft22, quote = FALSE)