SearchDB {DECIPHER} | R Documentation

## Obtain Specific Sequences from a Database

### Description

Returns the set of sequences meeting the search criteria.

### Usage

    SearchDB(dbFile,
             tblName = "Seqs",
             identifier = "",
             type = "XStringSet",
             limit = -1,
             replaceChar = NA,
             nameBy = "row_names",
             orderBy = "row_names",
             countOnly = FALSE,
             removeGaps = "none",
             quality = "Phred",
             clause = "",
             processors = 1,
             verbose = TRUE)

### Arguments

`dbFile` | A SQLite connection object or a character string specifying the path to the database file.
`tblName` | Character string specifying the table where the sequences are located.
`identifier` | Optional character string used to narrow the search results to those matching a specific identifier. If "" (the default) then all identifiers are selected.
`type` | The type of `XStringSet` (sequences) to return. This should be (an unambiguous abbreviation of) one of `"XStringSet"`, `"DNAStringSet"`, `"RNAStringSet"`, `"AAStringSet"`, `"BStringSet"`, `"QualityScaledXStringSet"`, `"QualityScaledDNAStringSet"`, `"QualityScaledRNAStringSet"`, `"QualityScaledAAStringSet"`, or `"QualityScaledBStringSet"`. If `type` is `"XStringSet"` or `"QualityScaledXStringSet"` then an attempt is made to guess the type of sequences based on their composition.
`limit` | Number of results to display. The default (`-1`) does not limit the number of results.
`replaceChar` | Optional character used to replace any characters of the sequence that are not present in the `XStringSet`'s alphabet. Not applicable if `type=="BStringSet"`. The default (`NA`) results in an error if an incompatible character exist. (See details section below.)
`nameBy` | Character string giving the column name for naming the `XStringSet`.
`orderBy` | Character string giving the column name for sorting the results. Defaults to the order of entries in the database. Optionally can be followed by `" ASC"` or `" DESC"` to specify ascending (the default) or descending order.
`countOnly` | Logical specifying whether to return only the number of sequences.
`removeGaps` | Determines how gaps ("-" or "." characters) are removed in the sequences. This should be (an unambiguous abbreviation of) one of `"none"`, `"all"` or `"common"`.
`clause` | An optional character string to append to the query as part of a “where clause”.
`quality` | The type of quality object to return if `type` is a `QualityScaledXStringSet`. This should be (an unambiguous abbreviation of) one of `"Phred"`, `"Solexa"`, or `"Illumina"`. Note that recent versions of Illumina software provide `"Phred"` formatted quality scores.
`processors` | The number of processors to use, or `NULL` to automatically detect and use all available processors.
`verbose` | Logical indicating whether to display queries as they are sent to the database.

### Details

If `type` is `"DNAStringSet"` then all U's are converted to T's before creating the `DNAStringSet`, and vise-versa if `type` is `"RNAStringSet"`. All remaining characters not in the `XStringSet`'s alphabet are converted to `replaceChar` or removed if `replaceChar` is `""`. Note that if `replaceChar` is `NA` (the default), it will result in an error when an unexpected character is found. Quality information is interpreted as `PredQuality` scores.

### Value

An `XStringSet` or `QualityScaledXStringSet` with the sequences that meet the specified criteria. The `names` of the object correspond to the value in the `nameBy` column of the database.

### Author(s)

Erik Wright eswright@pitt.edu

### References

ES Wright (2016) "Using DECIPHER v2.0 to Analyze Big Biological Sequence Data in R". The R Journal, 8(1), 352-359.

### See Also

`Seqs2DB`, `DB2Seqs`

### Examples

    db <- system.file("extdata", "Bacteria_175seqs.sqlite", package="DECIPHER")
    # get all sequences in the default table:
    dna <- SearchDB(db)
    # select a random sequence:
    dna <- SearchDB(db, orderBy="random()", limit=1)
    # remove gaps from "Mycobacterium" sequences:
    dna <- SearchDB(db, identifier="Mycobacterium", removeGaps="all")
    # provide a more complex query:
    dna <- SearchDB(db, nameBy="description", orderBy="bases", removeGaps="common",
                    clause="nonbases is 0")

[Package DECIPHER version 2.12.0 Index]