add.known {TRAMPR}

Add Knowns To TRAMPknowns Databases

Description

Add a single known or many knowns to a knowns database in a TRAMPknowns object. add.known takes a TRAMPknowns object, and adds the peak profile of a single sample from a TRAMPsamples object. combine.TRAMPknowns combines two TRAMPknowns objects (similar to combine.TRAMPsamples). add.known and combine are generic, so if x argument is a TRAMP object, then the knowns component of that object will be updated.

Usage

add.known(x, ...)
## S3 method for class 'TRAMPknowns'
add.known(x, samples, sample.fk, prompt=TRUE, default.species=NULL, ...)
## S3 method for class 'TRAMP'
add.known(x, sample.fk, rebuild=TRUE, ...)

## S3 method for class 'TRAMPknowns'
combine(x, y, rewrite.knowns.pk=FALSE, ...)
## S3 method for class 'TRAMP'
combine(x, y, rebuild=TRUE, ...)

Arguments

x

A TRAMPknowns or TRAMP object, containing identified TRFLP patterns.

samples

A TRAMPsamples object, containing unidentified samples.

sample.fk

sample.fk of sample in samples to add to the knowns database. If x is a TRAMP object, then sample.fk refers to a sample in the TRAMPsamples object used in the creation of that TRAMP object (stored as x$samples: see labels(x$samples) for codes).

prompt

Logical: Should the function interactively prompt for a new species name?

default.species

Default species name. If NULL (the default), the name chosen will be the value of samples$info$species for the current sample. Set to NA if no name is currently known (see group.knowns - identical non-NA names are considered related).

y

A second TRAMPknowns object, containing knowns to add to x.

rewrite.knowns.pk

Logical: If the new knowns data contain knowns.pk values that conflict with those in the original TRAMPknowns object, should the new knowns be renumbered? If this is TRUE, do not rely on any knowns.pk values staying the same for the newly added knowns. knowns.pk values in the original TRAMPknowns object will never be changed.

rebuild

Logical: should the TRAMP object be rebuilt after adding knowns, by running rebuild.TRAMP on it? This is important to determine if the new known(s) match any of the samples in the TRAMP object. This should be left as TRUE unless you plan on manually rebuilding the object later.

...

Additional arguments passed to future methods.

Details

(add.known only): When adding the profile of a single individual via add.known, if more than one peak per enzyme/primer combination is present we select the most likely profile by picking the highest peak (largest height value) for each enzyme/primer combination (a warning will be given). If two peaks are of the same height, then the peak taken is unspecified (similar to build.knowns with min.ratio=0).

(combine only): rewrite.knowns.pk provides a simple way of merging knowns databases that use the same values of knowns.pk. Because knowns.pk must be unique, if y (the new knowns database) uses knowns.pk values present in x (the original database), then the knowns.pk values in y must be rewritten. This will be done by adding max(labels(x)) to every knowns.pk value in y$info and knowns.fk value in y$data.

If retaining knowns.pk information is important, we suggest saving the value of knowns.pk before running this function, e.g.

info$knowns.pk.old <- info$knowns.pk

If more control over the renaming process is required, manually adjust y$info$knowns.pk yourself before calling this function. However, by default no translation will be done, and an error will occur if x and y share knowns.pk values.

For add.known, only a subset of columns are passed to the knowns object (a future version may be more inclusive):

• From samples$info: sample.pk (as knowns.pk.)

• From samples$data: sample.fk (as knowns.fk), primer, enzyme, size.

For combine, the data and info elements of the resulting TRAMPknowns object will have the union of the columns present in both sets of knowns. If any additional elements exist as part of the second TRAMPknowns object (e.g. passed as ... to TRAMPknowns when creating y), these will be ignored.

Value

An object of the same class as x: if a TRAMP object is supplied, a new TRAMP object with an updated TRAMPknowns component will be returned, and if the object is a TRAMPknowns object an updated TRAMPknowns object will be returned.

Note

If the TRAMPknowns object has a file.pat element (see TRAMPknowns), then the new knowns database will be written to file. This may be confusing when operating on TRAMP objects directly, since both the TRAMPknowns object used in the TRAMP object and the original TRAMPknowns object will share the same file.pat argument, but contain different data as soon as add.known or combine is used. In short - be careful! To avoid this issue, either set file.pat to NULL before using add.known or combine.

See Also

build.knowns, which automatically builds a knowns database, and TRAMPknowns, which documents the object containing the knowns database.

combine.TRAMPsamples, which combines a pair of TRAMPsamples objects.

Examples

data(demo.knowns)
data(demo.samples)

## (1) Using add.known(), to add a single known:

## Sample "101" looks like a potential known, add it to our knowns
## database:
plot(demo.samples, 101)

## Add this to a knowns database:
## Because there is more than one peak per enzyme/primer combination, a
## warning will be given.  In this case, since there are clear peaks it
## is harmless.
demo.knowns.2 <- add.known(demo.knowns, demo.samples, 101,
                           prompt=FALSE)

## The known has been added:
demo.knowns.2[101]
try(demo.knowns[101]) # error - known didn't exist in original knowns

## Same, but adding to an existing TRAMP object.
res <- TRAMP(demo.samples, demo.knowns)
plot(res, 101)
res2 <- add.known(res, 101, prompt=FALSE, default.species="New known")

## Now the new known matches itself.
plot(res2, 101)

## (2) Using combine() to combine knowns databases.

## Let's split the original knowns database in two:
demo.knowns.a <- demo.knowns[head(labels(demo.knowns), 10)]
demo.knowns.b <- demo.knowns[tail(labels(demo.knowns), 10)]

## Combining these is easy:
demo.knowns.c <- combine(demo.knowns.a, demo.knowns.b)

## Knowns from both the small database are present in the new one:
identical(c(labels(demo.knowns.a), labels(demo.knowns.b)),
          labels(demo.knowns.c))


## Demonstration of knowns rewriting:
demo.knowns.d <- demo.knowns.a
demo.knowns.a$info$from <- "a"
demo.knowns.d$info$from <- "d"

try(combine(demo.knowns.a, demo.knowns.d)) # error
demo.knowns.e <- combine(demo.knowns.a, demo.knowns.d,
                         rewrite.knowns.pk=TRUE)

## See that both data sets are here (check the "from" column).
demo.knowns.e$info

## Note that a better approach in might be to manually resolve
## conficting knowns.pk values before combining.