obkSequences: Formal class "obkSequences"
In thibautjombart/OutbreakTools: Basic Tools for the Analysis of Disease Outbreaks

Description Usage Arguments Details Objects from the class obkSequences Slots Methods Author(s) Examples

The class obkSequences is a formal (S4) class for storing a DNA sequences obtained from a sample during a disease outbreak. Sequences from different loci can be stored, alonside meta-information on the sequences.

An obkSequences object can be constructed from a list of matrices containing each a set of sequences of a given gene/locus. Sequences may be stored as character strings or as DNAbin objects. Information on individuals and collection dates, as well as other meta data for the sequences, can be provided.

get.nlocus(x, ...)
get.locus(x, ...)

get.nsequences(x, ...)
get.sequences(x, ...)

get.dna(x, ...)

## S4 method for signature 'obkSequences'
get.nsequences(x, what=c("total","bylocus"), ...)

## S4 method for signature 'obkSequences'
get.sequences(x, ...)

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

## S4 method for signature 'obkSequences'
show(object)

`x,object`	an `obkSequences` object.
`what`	a character string indicating whether numbers of sequences should be provided in total, or per locus.
`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`.
`...`	arguments passed to other methods.

obkSequences are meant to store DNA sequences for which patient/individual IDs and collection dates are known. This information can be provided using the arguments individualID and date, or through the labels of the sequences. In that case, the expected format is:
[sequenceID][sep][individualID][sep][date]
By default, the separator is "_", so a valid name would look like:
"seq123_John Doe_2013/06/23"

obkSequences objects can be created by calls to new("obkSequences", ...), where '...' can be the following arguments:

dna: a list of DNA sequence matrices in DNAbin or character format.
individualID: an optional vector providing IDs of patients/individuals for each sequence; its length must match the total number of sequences; if missing, will be seeked from the labels of the sequences (see details).
date: an optional vector providing collection dates each sequence; its length must match the total number of sequences; if missing, will be seeked from the labels of the sequences (see details).
...: an optional list of vectors or a data.frame providing other information about each sequence; vector lengths / number of rows of the data.frame must match the total number of sequences.
date.format: a character string indicating the date format (see as.Date); if NULL, date format is detected automatically.
quiet: a logical indicating whether informative messages should be hidden; this does not affect warnings or error messages.
sep: a character used to separate fields in the labels of the sequences (see details).

The following slots are the content of instances of the class obkSequences; note that in most cases, it is better to retrieve information via accessors (see below), rather than by accessing the slots manually.

dna:: a list of DNAbin matrices.
meta:: a data.frame where the first two columns are individualID and date, with optional further columns, and one row per sequence; rows are named after sequence labels.

Here is a list of methods available for obkSequences objects. Most of these methods are accessors, that is, functions which are used to retrieve the content of the object. Accessors with more than one argument are indicated by a '*' symbol next to the method's name. This list also contains methods for conversion from obkSequences to other classes.

show: signature(x = "obkSequences"): printing of the object.
get.nlocus: signature(x = "obkSequences"): returns the number of loci in the sample.
get.nsequences: signature(x = "obkSequences"): returns the number of sequences in the sample; the argument what can be "total" (default), in which case the total number of sequences is returned, or "bylocus", in which case the number of sequences per locus is returned.
get.locus: signature(x = "obkSequences"): returns the names of the loci in the sample.
get.dna: signature(x = "obkSequences"): returns dna sequences, which can be optionally specified by locus (argument locus) or by sequence identifier (argument id); loci can be indicated by index or by name (use get.locus to know available loci); sequence IDs must be characters.

Thibaut Jombart (t.jombart@imperial.ac.uk)

## construct an obkSequences object ##

data(ToyOutbreakRaw)
attach(ToyOutbreakRaw)
x <- new("obkSequences", dna, individualID=dna.info$individualID,
    date=dna.info$date)
x
detach(ToyOutbreakRaw)

## Load ToyOutbreak, a simulated outbreak stored in a obkData object  ##
data(ToyOutbreak)
x <- ToyOutbreak

## show obkObject
##summary(x) # generates an error

## access raw content
get.dna(x)

## access data by locus
get.nlocus(x)
get.locus(x)
get.dna(x, locus=1)
get.dna(x, locus="gene2")
get.dna(x, locus=1:2)
get.nsequences(x)
get.nsequences(x, "bylocus")

get.sequences(x)

## access data by sequence ID
get.dna(x, id=c("10"))
get.dna(x, id=c("100","354"))
get.dna(x, id=c(100:105))