\name{ds.table1d}
\alias{ds.table1d}
\title{Creates 1-dimensional contingency tables - potentially disclosive data are suppressed}
\usage{
ds.table1d(datasources = NULL, xvect = 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 as well as the tables representing only
  the valid data. If TRUE then only outputs the valid
  data.}

  \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 (eg. named out.obj) containing the following
items: \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
subfunctiontable1d.ds on its own.} \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}{Cell counts, for each study
separately and for all valid studies combined}
\item{TABLES.VALID.DATA.COLUMN.PERCENTS}{Column percents,
for each study separately and for all valid studies
combined} \item{TABLES.VALID.DATA.ROW.PERCENTS}{Row
percents, for each study separately and for all valid
studies combined}
\item{TABLES.VALID.DATA.GLOBAL.PERCENTS}{Global percents,
for each study separately and for all valid studies
combined}
}
\description{
The functionds.table1d is a client-side wrapper function.
It calls the server-side subfunction table1d.ds to generate
1-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 category in
which it falls is changed to "-9". Each source is flagged
as having only valid data, or at least some invalid data.
The functionds.table1d prints out tables of study against
xvect category detailing: counts; column percents; row
percents; and global percents. The final column represents
all valid studies combined. 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_CVA","LAB_HDL")
opals  <-  datashield.login(logins=logindata,assign=TRUE,variables=myvar)

# Example 1: generate a one dimensional table, outputting combined contingency tables
ds.table1d(datasources=opals, xvect=quote(D$DIS_CVA))

# Example 2: generate a one dimensional table, outputting study specific contingency tables
ds.table1d(datasources=opals, xvect=quote(D$DIS_CVA), type="split")

# Example 3: generate a one dimensional table, outputting study specific contingency tables for study 1 and 2
ds.table1d(datasources=opals[1:2], xvect=quote(D$DIS_CVA), type="split")

# Example 4: generate a one 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 \\code{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, butds.table1d 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.table1d(datasources=opals, xvect=quote(D$LAB_HDL))
}
}
\author{
Burton, P.; Gaye, A.
}

