create_motif {universalmotif} | R Documentation

## Create a motif.

### Description

Create a motif from a set of sequences, a matrix, or generate a random motif. See the "Motif import, export and manipulation" vignette for details.

### Usage

    create_motif(input, alphabet, type = "PPM", name = "motif",
      pseudocount = 0, bkg, nsites, altname, family, organism, bkgsites,
      strand, pval, qval, eval, extrainfo, add.multifreq)

    ## S4 method for signature 'missing'
    create_motif(input, alphabet, type = "PPM",
      name = "motif", pseudocount = 0, bkg, nsites, altname, family,
      organism, bkgsites, strand, pval, qval, eval, extrainfo, add.multifreq)

    ## S4 method for signature 'numeric'
    create_motif(input, alphabet, type = "PPM",
      name = "motif", pseudocount = 0, bkg, nsites, altname, family,
      organism, bkgsites, strand, pval, qval, eval, extrainfo, add.multifreq)

    ## S4 method for signature 'character'
    create_motif(input, alphabet, type = "PPM",
      name = "motif", pseudocount = 0, bkg, nsites, altname, family,
      organism, bkgsites, strand, pval, qval, eval, extrainfo, add.multifreq)

    ## S4 method for signature 'matrix'
    create_motif(input, alphabet, type = "PPM",
      name = "motif", pseudocount = 0, bkg, nsites, altname, family,
      organism, bkgsites, strand, pval, qval, eval, extrainfo, add.multifreq)

    ## S4 method for signature 'DNAStringSet'
    create_motif(input, alphabet, type = "PPM",
      name = "motif", pseudocount = 0, bkg, nsites, altname, family,
      organism, bkgsites, strand, pval, qval, eval, extrainfo, add.multifreq)

    ## S4 method for signature 'RNAStringSet'
    create_motif(input, alphabet, type = "PPM",
      name = "motif", pseudocount = 0, bkg, nsites, altname, family,
      organism, bkgsites, strand, pval, qval, eval, extrainfo, add.multifreq)

    ## S4 method for signature 'AAStringSet'
    create_motif(input, alphabet, type = "PPM",
      name = "motif", pseudocount = 0, bkg, nsites, altname, family,
      organism, bkgsites, strand, pval, qval, eval, extrainfo, add.multifreq)

    ## S4 method for signature 'BStringSet'
    create_motif(input, alphabet, type = "PPM",
      name = "motif", pseudocount = 0, bkg, nsites, altname, family,
      organism, bkgsites, strand, pval, qval, eval, extrainfo, add.multifreq)

### Arguments

`input` | `character`, `numeric`, `matrix`, `XStringSet`, or `missing`
`alphabet` | `character(1)` One of `c('DNA', 'RNA', 'AA')`, or a combined string representing the letters. If no alphabet is provided then it will try and guess the alphabet from the input.
`type` | `character(1)` One of `c('PCM', 'PPM', 'PWM', 'ICM')`.
`name` | `character(1)` Motif name.
`pseudocount` | `numeric(1)` Correction to be applied to prevent `-Inf` from appearing in PWM matrices.
`bkg` | `numeric` A vector of probabilities, each between 0 and 1. If higher order backgrounds are provided, then the elements of the vector must be named. If unnamed, then the order of probabilities must be in the same order as the alphabetically sorted sequence alphabet.
`nsites` | `numeric(1)` Number of sites the motif was constructed from.
`altname` | `character(1)` Alternate motif name.
`family` | `character(1)` Transcription factor family.
`organism` | `character(1)` Species of origin.
`bkgsites` | `numeric(1)` Total number of sites used to find the motif.
`strand` | `character(1)` Whether the motif is specific to a certain strand.
`pval` | `numeric(1)` P-value associated with motif.
`qval` | `numeric(1)` Adjusted P-value associated with motif.
`eval` | `numeric(1)` E-value associated with motif.
`extrainfo` | `character` Any other extra information, represented as a named character vector.
`add.multifreq` | `numeric` If the motif is created from a set of sequences, then the `add_multifreq()` function can be run at the same time (with `RC = FALSE`).

### Details

The aim of this function is provide an easy interface to creating universalmotif motifs, as an alternative to the default class constructor (i.e. `new('universalmotif', name=...)`). See examples for potential use cases.

Note: when generating random motifs, the `nsites` slot is also given a random value. Furthermore, be careful about the `nsites` slot when creating motifs from consensus strings: for example, the following call `create_motif("TAAAT")` generates a motif with `nsites = 1`.

See the `examples` section for more info on motif creation.

### Value

universalmotif object.

### Methods (by class)

- `missing`: Create a random motif of length 10.

- `numeric`: Create a random motif with a specified length.

- `character`: Create motif from a consensus string.

- `matrix`: Create motif from a matrix.

- `DNAStringSet`: Create motif from a `DNAStringSet`.

- `RNAStringSet`: Create motif from a `RNAStringSet`.

- `AAStringSet`: Create motif from a `AAStringSet`.

- `BStringSet`: Create motif from a `BStringSet`.

### Author(s)

Benjamin Jean-Marie Tremblay, b2tremblay@uwaterloo.ca

### See Also

`convert_type()`, `add_multifreq()`, `create_sequences()`, `shuffle_motifs()`.

`create_sequences()`

### Examples

    ##### create motifs from a single string

    # motif is by default generated as a PPM; change final type as desired
    DNA.motif <- create_motif("TATAWAW")
    DNA.motif <- create_motif("TATAWAW", type = "PCM")

    # nsites will be set to the number of input sequences unless specified
    DNA.motif <- create_motif("TTTTTTT", nsites = 10)

    # if ambiguity letters are found and nsites is not specified, nsites will
    # be set to the minimum required to respect amibiguity letters
    DNA.motif <- create_motif("TATAWAW")
    DNA.motif <- create_motif("NNVVWWAAWWDDN")

    # be careful about setting nsites when using ambiguity letters!
    DNA.motif <- create_motif("NNVVWWAAWWDDN", nsites = 1)

    RNA.motif <- create_motif("UUUCCG")

    # 'create_motif' will try to detect the alphabet type; this can be
    # unreliable for AA and custom alphabets as DNA and RNA alphabets are
    # detected first
    AA.motif <- create_motif("AVLK", alphabet = "AA")

    custom.motif <- create_motif("QWER", alphabet = "QWER")
    # specify custom alphabet
    custom.motif <- create_motif("QWER", alphabet = "QWERASDF")

    ###### create motifs from multiple strings of equal length

    DNA.motif <- create_motif(c("TTTT", "AAAA", "AACC", "TTGG"), type = "PPM")
    DNA.motif <- create_motif(c("TTTT", "AAAA", "AACC", "TTGG"), nsites = 20)
    RNA.motif <- create_motif(c("UUUU", "AAAA", "AACC", "UUGG"), type = "PWM")
    AA.motif <- create_motif(c("ARNDCQ", "EGHILK", "ARNDCQ"), alphabet = "AA")
    custom.motif <- create_motif(c("POIU", "LKJH", "POIU", "CVBN"),
                                 alphabet = "POIULKJHCVBN")

    # ambiguity letters are only allowed for single consensus strings; the
    # following fails
    ## Not run:
    create_motif(c("WWTT", "CCGG"))
    create_motif(c("XXXX", "XXXX"), alphabet = "AA")

    ## End(Not run)

    ##### create motifs from XStringSet objects

    library(Biostrings)

    DNA.set <- DNAStringSet(c("TTTT", "AAAA", "AACC", "TTGG"))
    DNA.motif <- create_motif(DNA.set)
    RNA.set <- RNAStringSet(c("UUUU", "AACC", "UUCC"))
    RNA.motif <- create_motif(RNA.set)
    AA.set <- AAStringSet(c("VVVLLL", "AAAIII"))
    AA.motif <- create_motif(AA.set)

    # custom motifs can be created from BStringSet objects
    B.set <- BStringSet(c("QWER", "ASDF", "ZXCV", "TYUI"))
    custom.motif <- create_motif(B.set)

    ##### create motifs with filled 'multifreq' slot

    DNA.motif.k2 <- create_motif(DNA.set, add.multifreq = 2)

    ##### create motifs from matrices

    mat <- matrix(c(1, 1, 1, 1,
                    2, 0, 2, 0,
                    0, 2, 0, 2,
                    0, 0, 0, 0),
                    nrow = 4, byrow = TRUE)
    DNA.motif <- create_motif(mat, alphabet = "DNA")
    RNA.motif <- create_motif(mat, alphabet = "RNA", nsites = 20)
    custom.motif <- create_motif(mat, alphabet = "QWER")

    # specify custom alphabet
    custom.motif <- create_motif(mat, alphabet = "QWER")

    # alphabet can be detected from rownames
    rownames(mat) <- DNA_BASES
    DNA.motif <- create_motif(mat)
    rownames(mat) <- c("Q", "W", "E", "R")
    custom.motif <- create_motif(mat)

    # matrices can also be used as input
    mat.ppm <- matrix(c(0.1, 0.1, 0.1, 0.1,
                        0.5, 0.5, 0.5, 0.5,
                        0.1, 0.1, 0.1, 0.1,
                        0.3, 0.3, 0.3, 0.3),
                        nrow = 4, byrow = TRUE)

    DNA.motif <- create_motif(mat.ppm, alphabet = "DNA", type = "PPM")

    ##### create random motifs

    # these are generated as PPMs with 10 positions

    DNA.motif <- create_motif()
    RNA.motif <- create_motif(alphabet = "RNA")
    AA.motif <- create_motif(alphabet = "AA")
    custom.motif <- create_motif(alphabet = "QWER")

    # the number of positions can be specified

    DNA.motif <- create_motif(5)

    # If the background frequencies are not provided, they are generated
    # using `rpois`; positions are created using `rdirichlet(1, bkg)`.
    # (calling `create_motif()` creates motifs with an average
    # positional IC of 1)

    DNA.motif <- create_motif(bkg = c(0.3, 0.2, 0.2, 0.3))
    DNA.motif <- create_motif(10, bkg = c(0.1, 0.4, 0.4, 0.1))

[Package universalmotif version 1.4.10 Index]