make_DBscores {universalmotif} | R Documentation

## Utility functions.

### Description

Various small functions used for motif creation. Note that all of the functions described here (with the following exceptions: `make_DBscores()`, `summarise_motifs()`) are here only for demonstration purposes; internally the universalmotif package uses faster C++ code for type conversion and consensus manipulation.

### Usage

    make_DBscores(db.motifs, method, shuffle.db = TRUE, shuffle.k = 3,
      shuffle.method = "linear", shuffle.leftovers = "asis",
      rand.tries = 1000, normalise.scores = TRUE, min.overlap = 6,
      min.mean.ic = 0, progress = TRUE, BP = FALSE)

    ppm_to_icm(position, bkg, schneider_correction = FALSE, nsites,
      relative_entropy = FALSE)

    icm_to_ppm(position)

    pcm_to_ppm(position, pseudocount = 0.8)

    ppm_to_pcm(position, nsites = 100)

    ppm_to_pwm(position, bkg, pseudocount = 0.8, nsites = 100,
      smooth = TRUE)

    pwm_to_ppm(position, bkg)

    position_icscore(position, bkg, type, pseudocount = 0.8, nsites = 100,
      relative_entropy = FALSE)

    get_consensus(position, alphabet = "DNA", type = "PPM",
      pseudocount = 0.8)

    consensus_to_ppm(letter)

    consensus_to_ppmAA(letter)

    get_consensusAA(position, type, pseudocount)

    summarise_motifs(motifs, na.rm = TRUE)

### Arguments

`db.motifs` | `list` Database motifs.
`method` | `character(1)` One of `c('PCC', 'MPCC', 'EUCL', 'MEUCL', 'SW', 'MSW', 'KL', 'MKL')`. See `compare_motifs()`.
`shuffle.db` | `logical(1)` Shuffle `db.motifs` rather than generate random motifs with `create_motif()`.
`shuffle.k` | `numeric(1)` See `shuffle_motifs()`.
`shuffle.method` | `character(1)` See `shuffle_motifs()`.
`shuffle.leftovers` | `character(1)` See `shuffle_motifs()`.
`rand.tries` | `numeric(1)` Number of random motifs to create for P-value computation.
`normalise.scores` | `logical(1)` See `compare_motifs()`.
`min.overlap` | `numeric(1)` Minimum required motif overlap. See `compare_motifs()`.
`min.mean.ic` | `numeric(1)` See `compare_motifs()`.
`progress` | `logical(1)` Show progress. Not recommended if `BP = TRUE`.
`BP` | `logical(1)` Use the BiocParallel package. See `BiocParallel::register()` to change the default backend.
`position` | `numeric` A numeric vector representing the frequency or probability for each alphabet letter at a specific position.
`bkg` | `Numeric` Should be the same length as the alphabet length.
`schneider_correction` | `logical(1)` Apply sample size correction.
`nsites` | `numeric(1)` Number of sites motif originated from.
`relative_entropy` | `logical(1)` Calculate information content as relative entropy or Kullback-Leibler divergence.
`pseudocount` | `numeric(1)` Used to prevent zeroes in motif matrix.
`smooth` | `logical(1)` Apply pseudocount correction.
`type` | `character(1)` One of `c('PCM', 'PPM', 'PWM' 'ICM')`.
`alphabet` | `character(1)` One of `c('DNA', 'RNA')`.
`letter` | `character(1)` Any DNA, RNA, or AA IUPAC letter. Ambiguity letters are accepted.
`motifs` | `list` A list of universalmotif motifs.
`na.rm` | `logical` Remove columns where all values are `NA`.

### Value

For `ppm_to_icm()`, `icm_to_ppm()`, `pcm_to_ppm()`, `ppm_to_pcm()`, `ppm_to_pwm()`, and `pwm_to_ppm()`: a `numeric` vector with length equal to input `numeric` vector.

For `consensus_to_ppm()` and `consensus_to_ppmAA()`: a numeric vector of length 4 and 20, respectively.

For `position_icscore()`: a `numeric` vector of length 1.

For `get_consensus()` and `get_consensusAA()`: a character vector of length 1.

For `make_DBscores()`: a `data.frame` with score distributions for the input database.

For `summarise_motifs()`: a `data.frame` with columns representing the universalmotif slots.

### Author(s)

Benjamin Jean-Marie Tremblay, b2tremblay@uwaterloo.ca

### See Also

`create_motif()`, `compare_motifs()`

### Examples

    ## make_DBscores
    ## Generate P-value database for use with compare_motifs. Note that these
    ## must be created individually for all combinations of methods and
    ## normalisation.
    ## Not run:
    library(MotifDb)
    motifs <- convert_motifs(MotifDb[1:100])
    make_DBscores(motifs, method = "PCC")

    ## End(Not run)

    ## ppm_to_icm
    ## Convert one column from a probability type motif to an information
    ## content type motif.
    motif <- create_motif(nsites = 100, pseudocount = 0.8)["motif"]
    motif.icm <- apply(motif, 2, ppm_to_icm, nsites = 100,
                       bkg = c(0.25, 0.25, 0.25, 0.25))

    ## icm_to_ppm
    ## Do the opposite of ppm_to_icm.
    motif.ppm <- apply(motif.icm, 2, icm_to_ppm)

    ## pcm_to_ppm
    ## Go from a count type motif to a probability type motif.
    motif.pcm <- create_motif(type = "PCM", nsites = 50)["motif"]
    motif.ppm2 <- apply(motif.pcm, 2, pcm_to_ppm, pseudocount = 1)

    ## ppm_to_pcm
    ## Do the opposite of pcm_to_ppm.
    motif.pcm2 <- apply(motif.ppm2, 2, ppm_to_pcm, nsites = 50)

    ## ppm_to_pwm
    ## Go from a probability type motif to a weight type motif.
    motif.pwm <- apply(motif.ppm, 2, ppm_to_pwm, nsites = 100,
                       bkg = c(0.25, 0.25, 0.25, 0.25))

    ## pwm_to_ppm
    ## Do the opposite of ppm_to_pwm.
    motif.ppm3 <- apply(motif.pwm, 2, pwm_to_ppm,
                        bkg = c(0.25, 0.25, 0.25, 0.25))

    ## Note that not all type conversions can be done directly; for those
    ## type conversions which are unavailable, universalmotif just chains
    ## together others (i.e. from PCM -> ICM => pcm_to_ppm -> ppm_to_icm)

    ## position_icscore
    ## Similar to ppm_to_icm, except this calculates a sum for the position.
    ic.scores <- apply(motif.ppm, 2, position_icscore, type = "PPM",
                       bkg = c(0.25, 0.25, 0.25, 0.25))

    ## get_consensus
    ## Get a consensus string from a DNA/RNA motif.
    motif.consensus <- apply(motif.ppm, 2, get_consensus)

    ## consensus_to_ppm
    ## Do the opposite of get_consensus. Note that loss of information is
    ## inevitable.
    motif.ppm4 <- sapply(motif.consensus, consensus_to_ppm)

    ## get_consensusAA
    ## Get a consensus string from an amino acid motif. Unless each position
    ## is clearly dominated by a single amino acid, the resulting string will
    ## likely be useless.
    motif.aa <- create_motif(alphabet = "AA")["motif"]
    motif.aa.consensus <- apply(motif.aa, 2, get_consensusAA, type = "PPM")

    ## consensus_to_ppmAA
    ## Do the opposite of get_consensusAA.
    motif.aa2 <- sapply(motif.aa.consensus, consensus_to_ppmAA)

    ## summarise_motifs
    ## Create a data.frame of information based on a list of motifs.
    m1 <- create_motif()
    m2 <- create_motif()
    m3 <- create_motif()
    summarise_motifs(list(m1, m2, m3))

[Package universalmotif version 1.0.22 Index]