merge_motifs {universalmotif} | R Documentation

## Merge motifs.

### Description

Aligns the motifs using `compare_motifs()`, then averages the motif PPMs. Currently the `multifreq` slot, if filled in any of the motifs, will be dropped. Only 0-order background probabilities will be kept. Motifs are merged one at a time, starting with the first entry in the list.

### Usage

    merge_motifs(motifs, method = "PCC", use.type = "PPM", min.overlap = 6,
      min.mean.ic = 0.25, tryRC = TRUE, relative_entropy = FALSE,
      normalise.scores = FALSE, min.position.ic = 0, score.strat = "sum",
      new.name = NULL)

### Arguments

`motifs` | See `convert_motifs()` for acceptable motif formats.
`method` | `character(1)` One of PCC, EUCL, SW, KL, ALLR, BHAT, HELL, SEUCL, MAN, ALLR_LL, WEUCL, WPCC. See details.
`use.type` | `character(1)` One of `'PPM'` and `'ICM'`. The latter allows for taking into account the background frequencies if `relative_entropy = TRUE`. Note that `'ICM'` is not allowed when `method = c("ALLR", "ALLR_LL")`.
`min.overlap` | `numeric(1)` Minimum overlap required when aligning the motifs. Setting this to a number higher then the width of the motifs will not allow any overhangs. Can also be a number between 0 and 1, representing the minimum fraction that the motifs must overlap.
`min.mean.ic` | `numeric(1)` Minimum mean information content between the two motifs for an alignment to be scored. This helps prevent scoring alignments between low information content regions of two motifs.
`tryRC` | `logical(1)` Try the reverse complement of the motifs as well, report the best score.
`relative_entropy` | `logical(1)` Change the ICM calculation affecting `min.position.ic` and `min.mean.ic`. See `convert_type()`.
`normalise.scores` | `logical(1)` Favour alignments which leave fewer unaligned positions, as well as alignments between motifs of similar length. Similarity scores are multiplied by the ratio of aligned positions to the total number of positions in the larger motif, and the inverse for distance scores.
`min.position.ic` | `numeric(1)` Minimum information content required between individual alignment positions for it to be counted in the final alignment score. It is recommended to use this together with `normalise.scores = TRUE`, as this will help punish scores resulting from only a fraction of an alignment.
`score.strat` | `character(1)` How to handle column scores calculated from motif alignments. "sum": add up all scores. "a.mean": take the arithmetic mean. "g.mean": take the geometric mean. "median": take the median. "wa.mean", "wg.mean": weighted arithmetic/geometric mean. "fzt": Fisher Z-transform. Weights are the total information content shared between aligned columns.
`new.name` | `character(1)`, `NULL` Instead of collapsing existing names (if `NULL`), assign a new for the merged motif.

### Details

See `compare_motifs()` for more info on comparison parameters.

If using a comparison metric where 0s are not allowed (`KL`, `ALLR`, `ALLR_LL`), then keep in mind that the final merged motif may include added pseudocounts to previously empty positions.

Note: `score.strat = "a.mean"` is NOT recommended, as `merge_motifs()` will not discriminate between two alignments with equal mean scores, even if one alignment is longer than the other.

### Value

A single motif object. See `convert_motifs()` for available formats.

### Author(s)

Benjamin Jean-Marie Tremblay, b2tremblay@uwaterloo.ca

### See Also

`compare_motifs()`

### Examples

    ## Not run:
    library(MotifDb)
    merged.motif <- merge_motifs(MotifDb[1:5])

    ## End(Not run)

    # Using ALLR or KL will add a pseudocount to the input motifs. Compare:
    m1 <- create_motif("TTAAACCCC", name = "1")
    m2 <- create_motif("AACC", name = "2")
    m3 <- create_motif("AACCCCGG", name = "3")
    view_motifs(merge_motifs(c(m1, m2, m3), method = "PCC"))
    view_motifs(merge_motifs(c(m1, m2, m3), method = "ALLR"))

[Package universalmotif version 1.5.36 Index]