\name{ds.table2d}
\alias{ds.table2d}
\title{Creates 2-dimensional contingency tables - potentially disclosive data are suppressed}
\usage{
ds.table2d(datasources = NULL, xvect = NULL, yvect = NULL,
  type = "combine")
}
\arguments{
  \item{datasources}{a list of opal object(s) obtained
  after login in to opal servers; these objects hold also
  the data assign to R, as \code{dataframe}, from opal
  datasources.}

  \item{xvect}{a numerical vector with discrete values -
  usually a factor}

  \item{yvect}{a numerical vector with discrete values -
  usually a factor}

  \item{type}{a character which represent the type of graph
  to display If \code{type} is set to 'combine', a
  histogram that merges the single plot is displayed. Each
  histogram is plotted separately if If \code{type} is set
  to 'split'.}
}
\value{
A list object containing the following items (depending on
the type of analysis specified -'combined' or 'split- some
of these items may not be returned):
\item{OPALS.DATA.OVERVIEW}{For each study contains
$study.name (ie name of study), $is.table.valid (TRUE if
all cells valid otherwise FALSE), $safe.table (the safe
contingency table that contains all cells if all are valid,
but otherwise obscures invalid cells by outputting a cell
count of "-1" and making the two category indicators for
that cell = "-9". In other words OPALS.DATA.OVERVIEW
provides the information generated by the server side
subfunction table2d.ds on its own.}
\item{ALL.VALID.TABLES.BY.STUDY}{Counts, column percents,
row percents and global percents for each study separately
(if separate.and.combined.studies=TRUE) and for all valid
studies combined}
\item{CHI2.TESTS.FOR.HOMOGENEITY}{Chi-squared test for
homogeneity, for each study separately (if
separate.and.combined.studies=TRUE) and for all valid
studies combined} \item{VALIDITY.WARNING - IF
NEEDED}{Either reports that all studies are valid, or else
lists the studies that contain at least one cell that is
invalid, or else reports "NO STUDIES HAVE VALID DATA - SO
NO ATTEMPT TO COMBINE"} \item{TABLES.VALID.DATA.COUNTS}{If
all.output.configurations=TRUE, cell counts, for each study
separately and for all valid studies combined}
\item{TABLES.VALID.DATA.COLUMN.PERCENTS}{If
all.output.configurations=TRUE, column percents, for each
study separately and for all valid studies combined}
\item{TABLES.VALID.DATA.ROW.PERCENTS}{If
all.output.configurations=TRUE, row percents, for each
study separately and for all valid studies combined}
\item{TABLES.VALID.DATA.GLOBAL.PERCENTS}{If
all.output.configurations=TRUE, global percents, for each
study separately and for all valid studies combined}
}
\description{
The function ds.table2d is a client-side wrapper function.
It calls the server-side subfunction table2d.ds to generate
2-dimensional tables for all data sources. Valid
(non-disclosive) data are defined as data from sources
where no table cells have counts between 1 and 4 (the upper
value [4] can in principle be changed but only by rewriting
the underlying function - it cannot be changed by a
standard DataSHIELD user). If the count in any cell in the
table produced by a given data source IS invalid, that cell
count is changed to "-1" and the name of the two categories
that correspond to it are both changed to "-9". Each source
is flagged as having only valid data, or at least some
invalid data. The function ds.table2d prints out counts,
column percents, row percents, global percents and a
chi-squared test for homogeneity on (nc-1)*(nr-1) degrees
of freedom where nc is the number of columns and nr is the
number of rows. These calaculations are done separately for
each source and, in addition, all valid sources are
combined to produce a single overarching contingency for
all valid data collectively. Missing data are treated as
na.action=na.omit (default for table function), if missing
data are to be treated as a separate and visible category,
the variable should first be transformed to convert NAs to
the a new value.
}
\details{

}
\examples{
{
# load the file that contains the login details
data(logindata)

# login and assign the required variables to R
myvar  <-  list("DIS_DIAB", "DIS_CVA", "GENDER", "LAB_HDL")
opals  <-  datashield.login(logins=logindata,assign=TRUE,variables=myvar)

# Example 1: generate a two dimensional table, outputting combined contingency tables - default behaviour
ds.table2d(datasources=opals, xvect=quote(D$DIS_DIAB), yvect=quote(D$GENDER))

# Example 2: generate a two dimensional table, outputting study specific contingency tables
ds.table2d(datasources=opals, xvect=quote(D$DIS_DIAB), yvect=quote(D$GENDER), type="split")

# Example 3: generate a two dimensional table, outputting study specific contingency tables for the first two studies
ds.table2d(datasources=opals[1:2], quote(D$DIS_DIAB), quote(D$GENDER), type="split")

# Example 4: generate a two dimensional table, outputting combined contingency tables (in this case some studies are invalid)
ds.table2d(datasources=opals, quote(D$DIS_CVA), quote(D$GENDER))

# Example 5: generate a two dimensional table, outputting study specific contingency tables (in this case some studies are invalid)
ds.table2d(datasources=opals, quote(D$DIS_CVA), quote(D$GENDER), type="split")
# Example 6: generate a two dimensional table, outputting study specific and combined contingency tables, see what happens if
# you try to tabulate a quantitative variable with unique values for many individuals. The standard table() function in R would print out
# all observed "values" as category names in ascending order with a count (generally 1) for each unique number, but ds.table2d prints
# out all values where there are between 1 and 4 observations as -1 and gives the category name -9. It is only when the count is
# 5 or more that the actual value can be observed, and then it is non-disclosive
ds.table2d(datasources=opals, quote(D$GENDER), quote(D$LAB_HDL))
ds.table2d(datasources=opals, quote(D$GENDER), quote(D$LAB_HDL), type="split")
}
}
\author{
Burton P.; Gaye, A.
}

