obkData: Formal class "obkData"
In OutbreakTools: Basic Tools for the Analysis of Disease Outbreaks

Description Usage Arguments Objects from the class obkData Slots Methods Author(s) See Also Examples

The class obkData is a formal (S4) class for storing data collected during outbreaks. This includes:

individual data (age, sex, onset of symptoms, ...)
time-stamped samples and records (swabs, serology, accession numbers, ...)
genetic sequences
contact information
contextual information
phylogenetic trees

## S4 method for signature 'obkData'
initialize(.Object, individuals=NULL, records=NULL,
          dna=NULL, trees=NULL, contacts=NULL, context=NULL,
          contacts.start=NULL, contacts.end=NULL,
          contacts.duration=NULL, contacts.directed=FALSE,
          date.format=NULL, dna.individualID=NULL, dna.date=NULL,
          dna.date.format=date.format, dna.sep="_", quiet=FALSE,
          check=TRUE, individuals=NULL, records=NULL, ...)

get.nrecords(x, ...)
get.records(x, ...)
## S4 method for signature 'obkData'
get.records(x, ...)
## S4 method for signature 'obkData'
get.nrecords(x, ...)

get.ncontext(x, ...)
get.context(x, ...)
## S4 method for signature 'obkData'
get.context(x, ...)
## S4 method for signature 'obkData'
get.ncontext(x, ...)

get.ntrees(x, ...)
get.trees(x, ...)
## S4 method for signature 'obkData'
get.ntrees(x, ...)
## S4 method for signature 'obkData'
get.trees(x, ...)

## S4 method for signature 'obkData'
get.dna(x, locus=NULL, id=NULL, ...)

## S4 method for signature 'obkData'
get.ncontacts(x, from=NULL, to=NULL, ...)
## S4 method for signature 'obkData'
get.contacts(x, from=NULL, to=NULL, ...)

`.Object`	the prototype of an `obkData` object, created automatically by `new`.
`individuals`	a data.frame with a mandatory column named 'individualID', providing unique identifiers for the individuals; if missing, row names are used as identifiers.
`records`	a list of data.frames, each of which has 2 mandatory fields, 'individualID' and 'date'. Dates can be specified as `Date` or `characters`, in which case they will be converted to dates. Most sensible formats will be detected automatically and processed. Unusual formats should be provided through the argument `date.format`. Each item of the list should be named according to the type of information recorded, e.g. 'swabs', 'temperature', or 'hospitalisation' (admission / discharge events).
`dna`	a list matrices of DNA sequences in `DNAbin` or `character` format, each component of the list being a different gene. A matrix can be provided if there is a single gene.
`dna.date`	a vector of collection dates for the DNA sequences; see obkSequences manpage for more information.
`dna.individualID`	a vector of individual from which DNA sequences where obtained; see obkSequences manpage for more information.
`dna.date.format`	a character string indicating the format of the date in `dna.date` if ambiguous; see obkSequences manpage for more information.
`dna.sep`	the character string used to separate fields (e.g. sequenceID/individualID/date) in sequences labels; see obkSequences manpage for more information.
`contacts`	a matrix of characters indicating contacts using two columns; if contacts are directed, the first column is 'from', the second is 'to'; values should match individual IDs (as returned by get.individuals(x)); if numeric values are provided, these are converted to integers and assumed to correspond to individuals returned by get.individuals(x).
`context`	a list of data.frames, each of which has 1 mandatory field: 'date'. Each item of the list should be named according to the type of information recorded, e.g. 'intervention', 'vaccination', 'climat' (temperature, humidity, etc.), or schools (opening/closure).
`contacts.start`	a vector of dates indicating the beginning of each contact.
`contacts.end`	a vector of dates indicating the end of each contact.
`contacts.duration`	another way to specify contacts.end, as duration of contact in days.
`contacts.directed`	a logical indicating if contacts are directed; defaults to FALSE.
`trees`	a list of phylogenetic trees with the class `multiPhylo` (from the ape package)
`date.format`	a character string indicating the date format (see `as.Date`); if `NULL`, date format is detected automatically, which is usually a sensible option.
`x`	an `obkData` object.
`locus`	an indication of the locus, either by its name, or using integers or logicals matching `get.locus`.
`id`	an indication of the sequences, either by their names, or using integers or logicals matching `get.sequences`.
`from,to`	dates indicating the time span to consider for active contacts (for dynamic networks only).
`...`	arguments passed to other methods.
`quiet`	a logical indicating whether informative messages should be displayed to the screen.
`check`	a logical indicating whether supplementary consistency checks should be performed.

obkData objects can be created using new("obkData", ...), where '...' corresponds to the arguments of the corresponding initialize method (see 'Usage' section in this page).

obkData contain the following slots; note that in most cases, it is better to retrieve information via accessors (see below), rather than by accessing the slots manually. Empty slots are all NULL.

individuals:: a data.frame containing individual information, with individual labels stored as row names.
records:: a list of data.frame, each containing records of a particular type; the first two columns are 'individualID'and 'date'.
contacts:: an object of the class obkContacts storing contact information.
dna:: an object of the class obkSequences storing DNA sequences.
context:: a list of data.frame, each member of the list containing contextual information related to the population of a particular type; the first column is 'date'.
trees:: an object of the class multiphylo storing list of trees.

Here is a list of accessors available for obkData objects. These functions are used to retrieve the content of the object. Specific manpages can exist for the more complex functions. These are indicated by a '*' symbol next to the method's name.

show: signature(x = "obkData"): printing of the object's contents.
head: signature(x = "obkData"): printing of the object's contents - showing only the firt lines of each record.
tail: signature(x = "obkData"): printing of the object's contents - showing only the last lines of each record.
summary: signature(x = "obkData"): printing a summary of the object.
get.individuals*: signature(x = "obkData"): returns the itendifiers of individuals in a given source of data (see manpage of get.individuals for details).
get.nindividuals*: signature(x = "obkData"): returns the number of individuals in a given source of data (see manpage of get.individuals for details).
get.dates*: signature(x = "obkData"): returns the dates in a given source of data (see manpage of get.dates for details).
get.dates*: signature(x = "obkData"): returns the number of dates in a given source of data (see manpage of get.dates for details).
get.records: signature(x = "obkData"): returns the names of existing records tables in the data.
get.nrecords: signature(x = "obkData"): returns the number of records tables in the data.
get.locus: signature(x = "obkData"): returns the names of the sequenced loci.
get.nlocus: signature(x = "obkData"): returns the number of sequenced loci.
get.nsequences*: signature(x = "obkData"): returns the number of sequences in the data; see obkSequences manpage for further details.
get.dna*: signature(x = "obkData"): returns the sequences for a given locus (locus argument, required if more than one locus was sequenced)see obkSequences manpage for further details.
get.context: signature(x = "obkData"): returns the names of existing context tables in the data.
get.ncontext: signature(x = "obkData"): returns the number of context tables in the data.
get.trees: signature(x = "obkData"): return a list of trees of the class multiPhylo, if present, and NULL otherwise.
get.trees: signature(x = "obkData"): return the number of trees present in the data.
get.contacts*: signature(x = "obkData"): returns the contacts (as network or networkDynamic); for dynamic contact networks, starting dates can be specified by the argument from, and end date by the argument to; see obkContacts manpage for further details.
get.ncontacts*: signature(x = "obkData"): returns the number of contacts; for dynamic contact networks, starting dates can be specified by the argument from, and end date by the argument to; see obkContacts manpage for further details.
get.data*: signature(x = "obkData"): search for a matching fields in the object and returns the corresponding values; in the absence of match, NULL is returned. Several values can be provided; they can be names of the slots, or any variable stored within the data.frames samples or individuals.

Thibaut Jombart, Simon Frost, Lulla Opatowski, Paul Birrell, Anne Cori, Marc Baguelin, Caroline Colijn

subset.obkData to subset the data in various ways.
plot.obkData to plot the data.

## LOAD DATA ##
data(ToyOutbreakRaw)
attach(ToyOutbreakRaw)

## CONSTRUCTING AN OBKDATA OBJECT ##
x <- new ("obkData", individuals=individuals, records=records,
          contacts=contacts, contacts.start=contacts.start,
          contacts.end=contacts.end, dna=dna,
          dna.individualID=dna.info$individualID,
          dna.date=dna.info$date, sample=dna.info$sample, trees=trees)

detach(ToyOutbreakRaw)


## EXAMINING THE OBJECT ##
head(x@individuals)
names(x@records)
lapply(x@records, head)
x@contacts
x@dna
x@trees


## HEAD, TAIL, SUMMARY ##
head(x)
tail(x)
summary(x)


##  ACCESSORS
get.nlocus(x)
get.locus(x)
get.nindividuals(x)
head(get.individuals(x))
get.individuals(x, data="contacts")
get.nsequences(x)
get.dna(x, locus="gene2")
get.dna(x, locus=1)
head(get.data(x, "Fever"))
head(get.data(x, "Age", showSource=TRUE))
head(get.data(x, c("Age","Sex", "infector"), showSource=TRUE))


## GRAPHICS ##
## default plot (timeline of information) ##
plot(x)
plot(x, colorBy='Sex')
plot(x, colorBy='Sex', orderBy='Sex')
plot(subset(x, 1:50), colorBy='Sex', size=4)

## plot contacts ##
plot(x, "contacts", main="Contacts")

## Not run: 
## visualize data on a map ##
plot(x,'geo',location=c('lon','lat'),zoom=15,colorBy='Sex')

## plot the tree ##
plotggphy(x)
plotggphy(subset(x, 1:50), tip.color="Sex", color.pal="Set1")

## End(Not run)