OutbreakTools (version 0.1-16)

obkData-class: Formal class "obkData"

Description

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

Usage

# S4 method for 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 obkData
get.records(x, …)
# S4 method for obkData
get.nrecords(x, …)
get.ncontext(x, …)
get.context(x, …)
# S4 method for obkData
get.context(x, …)
# S4 method for obkData
get.ncontext(x, …)
get.ntrees(x, …)
get.trees(x, …)
# S4 method for obkData
get.ntrees(x, …)
# S4 method for obkData
get.trees(x, …)
# S4 method for obkData
get.dna(x, locus=NULL, id=NULL, …)
# S4 method for obkData
get.ncontacts(x, from=NULL, to=NULL, …)
# S4 method for obkData
get.contacts(x, from=NULL, to=NULL, …)

Arguments

.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.

Objects from the class obkData

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

Slots

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.

Methods

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.

See Also

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

• plot.obkData to plot the data.

Examples

# NOT RUN {
## 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")
# }