create_motif {universalmotif} | R Documentation

## Create a motif.

### Description

Create a motif from a set of sequences, a matrix, or generate a random motif.

### 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`, `numberic`, `matrix`, `XStringSet`, or `missing`
`alphabet` | `character(1)` One of `c('DNA', 'RNA', 'AA', 'custom')`, or a combined string representing the letters.
`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 apearing in PWM matrices.
`bkg` | `numeric` Must sum to 1 and be equal in length to the alphabet length.
`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(1)` If the motif is created from a set of sequences, then the `add_multifreq()` function can be run at the same type.

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

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

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