utils-motif {universalmotif} | R Documentation

## Motif-related utility functions.

### Description

Motif-related utility functions.

### Usage

    consensus_to_ppm(letter)

    consensus_to_ppmAA(letter)

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

    get_consensusAA(position, type = "PPM", pseudocount = 0)

    get_matches(motif, score)

    icm_to_ppm(position)

    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)

    motif_score(motif, threshold = c(0, 1))

    pcm_to_ppm(position, pseudocount = 0)

    position_icscore(position, bkg = 0, type = "PPM", pseudocount = 1,
      nsites = 100, relative_entropy = FALSE)

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

    ppm_to_pcm(position, nsites = 100)

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

    pwm_to_ppm(position, bkg)

    score_match(motif, match)

    summarise_motifs(motifs, na.rm = TRUE)

### Arguments

`letter` | `character(1)` Any DNA, RNA, or AA IUPAC letter. Ambiguity letters are accepted.
`position` | `numeric` A numeric vector representing the frequency or probability for each alphabet letter at a specific position.
`alphabet` | `character(1)` One of `c('DNA', 'RNA')`.
`type` | `character(1)` One of `c('PCM', 'PPM', 'PWM' 'ICM')`.
`pseudocount` | `numeric(1)` Used to prevent zeroes in motif matrix.
`motif` | Motif object to calculate scores from.
`score` | `numeric(1)` Logodds motif score.
`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.
`threshold` | `numeric(1)` Any number of numeric values between 0 and 1 representing score percentage.
`bkg` | `Numeric` Should be the same length as the alphabet length.
`nsites` | `numeric(1)` Number of sites motif originated from.
`relative_entropy` | `logical(1)` Calculate information content as relative entropy or Kullback-Leibler divergence.
`schneider_correction` | `logical(1)` Apply sample size correction.
`smooth` | `logical(1)` Apply pseudocount correction.
`match` | `character(1)` Sequence string to calculate score from.
`motifs` | `list` A list of universalmotif motifs.
`na.rm` | `logical` Remove columns where all values are `NA`.

### Value

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

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

For `get_matches()`: a `character` vector of motif matches.

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

For `motif_score()`: a named `numeric` vector of motif scores.

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

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 `score_match()`: a `numeric` vector with the match motif score.

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()`

### Examples

    #######################################################################
    ## Setting up some variables
    data(examplemotif)
    m <- normalize(examplemotif)
    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))
    motif.ppm <- apply(motif.icm, 2, icm_to_ppm)
    motif.consensus <- apply(motif.ppm, 2, get_consensus)
    motif.aa <- create_motif(alphabet = "AA")["motif"]
    motif.aa.consensus <- apply(motif.aa, 2, get_consensusAA, type = "PPM")
    #######################################################################

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

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

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

    #######################################################################
    ## 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")

    #######################################################################
    ## get_match
    ## Get all possible motif matches above input score
    get_matches(m, 10)

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

    #######################################################################
    ## 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)

    #######################################################################
    ## motif_score
    ## Calculate motif score from different thresholds
    data(examplemotif)
    m <- normalize(examplemotif)
    motif_score(m, c(0, 0.8, 1))

    #######################################################################
    ## 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)

    #######################################################################
    ## 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))

    #######################################################################
    ## 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))

    #######################################################################
    ## 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)

    #######################################################################
    ## score_match
    ## Calculate score of a particular match
    score_match(m, "TATATAT")
    score_match(m, "TATATAG")

    #######################################################################
    ## 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.2.1 Index]