# Add Knowns To TRAMPknowns Databases 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. ```r 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. ## Returns 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 ```r 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. ```

add.known function