runMatrixTSMA {transite}R Documentation

Matrix-based Transcript Set Motif Analysis

Description

Calculates motif enrichment in foreground sets versus a background set using position weight matrices to identify putative binding sites

Usage

runMatrixTSMA(foreground.sets, background.set, motifs = NULL,
  max.hits = 5, threshold.method = "p.value",
  threshold.value = 0.25^6, max.fg.permutations = 1e+06,
  min.fg.permutations = 1000, e = 5, p.adjust.method = "BH",
  n.cores = 1, cache = paste0(tempdir(), "/sc/"))

Arguments

foreground.sets

a list of named character vectors of foreground sequences (only containing upper case characters A, C, G, T), where the names are RefSeq identifiers and sequence type qualifiers ("3UTR", "5UTR", "mRNA"), e.g. "NM_010356|3UTR". Names are only used to cache results.

background.set

a named character vector of background sequences (naming follows same rules as foreground set sequences)

motifs

a list of motifs that is used to score the specified sequences. If is.null(motifs) then all Transite motifs are used.

max.hits

maximum number of putative binding sites per mRNA that are counted

threshold.method

either "p.value" (default) or "relative". If threshold.method equals "p.value", the default threshold.value is 0.25^6, which is lowest p-value that can be achieved by hexamer motifs, the shortest supported motifs. If threshold.method equals "relative", the default threshold.value is 0.9, which is 90% of the maximum PWM score.

threshold.value

semantics of the threshold.value depend on threshold.method (default is 0.25^6)

max.fg.permutations

maximum number of foreground permutations performed in Monte Carlo test for enrichment score

min.fg.permutations

minimum number of foreground permutations performed in Monte Carlo test for enrichment score

e

integer-valued stop criterion for enrichment score Monte Carlo test: aborting permutation process after observing e random enrichment values with more extreme values than the actual enrichment value

p.adjust.method

adjustment of p-values from Monte Carlo tests to avoid alpha error accumulation, see p.adjust

n.cores

the number of cores that are used

cache

either logical or path to a directory where scores are cached. The scores of each motif are stored in a separate file that contains a hash table with RefSeq identifiers and sequence type qualifiers as keys and the number of putative binding sites as values. If cache is FALSE, scores will not be cached.

Details

Motif transcript set analysis can be used to identify RNA binding proteins, whose targets are significantly overrepresented or underrepresented in certain sets of transcripts.

The aim of Transcript Set Motif Analysis (TSMA) is to identify the overrepresentation and underrepresentation of potential RBP targets (binding sites) in a set (or sets) of sequences, i.e., the foreground set, relative to the entire population of sequences. The latter is called background set, which can be composed of all sequences of the genes of a microarray platform or all sequences of an organism or any other meaningful superset of the foreground sets.

The matrix-based approach skips the k-merization step of the k-mer-based approach and instead scores the transcript sequence as a whole with a position specific scoring matrix.

For each sequence in foreground and background sets and each sequence motif, the scoring algorithm evaluates the score for each sequence position. Positions with a relative score greater than a certain threshold are considered hits, i.e., putative binding sites.

By scoring all sequences in foreground and background sets, a hit count for each motif and each set is obtained, which is used to calculate enrichment values and associated p-values in the same way in which motif-compatible hexamer enrichment values are calculated in the k -mer-based approach. P-values are adjusted with one of the available adjustment methods.

An advantage of the matrix-based approach is the possibility of detecting clusters of binding sites. This can be done by counting regions with many hits using positional hit information or by simply applying a hit count threshold per sequence, e.g., only sequences with more than some number of hits are considered. Homotypic clusters of RBP binding sites may play a similar role as clusters of transcription factors.

Value

A list with the following components:

foreground.scores the result of scoreTranscripts for the foreground sets
background.scores the result of scoreTranscripts for the background set
enrichment.dfs a list of data frames, returned by calculateMotifEnrichment

See Also

Other TSMA functions: drawVolcanoPlot, runKmerTSMA

Other matrix functions: calculateMotifEnrichment, runMatrixSPMA, scoreTranscriptsSingleMotif, scoreTranscripts

Examples

# define simple sequence sets for foreground and background
foreground.set1 <- c(
  "CAACAGCCUUAAUU", "CAGUCAAGACUCC", "CUUUGGGGAAU",
  "UCAUUUUAUUAAA", "AAUUGGUGUCUGGAUACUUCCCUGUACAU",
  "AUCAAAUUA", "AGAU", "GACACUUAAAGAUCCU",
  "UAGCAUUAACUUAAUG", "AUGGA", "GAAGAGUGCUCA",
  "AUAGAC", "AGUUC", "CCAGUAA"
)
names(foreground.set1) <- c(
  "NM_1_DUMMY|3UTR", "NM_2_DUMMY|3UTR", "NM_3_DUMMY|3UTR",
  "NM_4_DUMMY|3UTR", "NM_5_DUMMY|3UTR", "NM_6_DUMMY|3UTR",
  "NM_7_DUMMY|3UTR",
  "NM_8_DUMMY|3UTR", "NM_9_DUMMY|3UTR", "NM_10_DUMMY|3UTR",
  "NM_11_DUMMY|3UTR",
  "NM_12_DUMMY|3UTR", "NM_13_DUMMY|3UTR", "NM_14_DUMMY|3UTR"
)

foreground.set2 <- c("UUAUUUA", "AUCCUUUACA", "UUUUUUU", "UUUCAUCAUU")
names(foreground.set2) <- c(
  "NM_15_DUMMY|3UTR", "NM_16_DUMMY|3UTR", "NM_17_DUMMY|3UTR",
  "NM_18_DUMMY|3UTR"
)

foreground.sets <- list(foreground.set1, foreground.set2)

background.set <- c(
  "CAACAGCCUUAAUU", "CAGUCAAGACUCC", "CUUUGGGGAAU",
  "UCAUUUUAUUAAA", "AAUUGGUGUCUGGAUACUUCCCUGUACAU",
  "AUCAAAUUA", "AGAU", "GACACUUAAAGAUCCU",
  "UAGCAUUAACUUAAUG", "AUGGA", "GAAGAGUGCUCA",
  "AUAGAC", "AGUUC", "CCAGUAA",
  "UUAUUUA", "AUCCUUUACA", "UUUUUUU", "UUUCAUCAUU",
  "CCACACAC", "CUCAUUGGAG", "ACUUUGGGACA", "CAGGUCAGCA"
)
names(background.set) <- c(
  "NM_1_DUMMY|3UTR", "NM_2_DUMMY|3UTR", "NM_3_DUMMY|3UTR",
  "NM_4_DUMMY|3UTR", "NM_5_DUMMY|3UTR", "NM_6_DUMMY|3UTR",
  "NM_7_DUMMY|3UTR",
  "NM_8_DUMMY|3UTR", "NM_9_DUMMY|3UTR", "NM_10_DUMMY|3UTR",
  "NM_11_DUMMY|3UTR",
  "NM_12_DUMMY|3UTR", "NM_13_DUMMY|3UTR", "NM_14_DUMMY|3UTR",
  "NM_15_DUMMY|3UTR",
  "NM_16_DUMMY|3UTR", "NM_17_DUMMY|3UTR", "NM_18_DUMMY|3UTR",
  "NM_19_DUMMY|3UTR",
  "NM_20_DUMMY|3UTR", "NM_21_DUMMY|3UTR", "NM_22_DUMMY|3UTR"
)

# run cached version of TSMA with all Transite motifs (recommended):
# results <- runMatrixTSMA(foreground.sets, background.set)

# run uncached version with one motif:
motif.db <- getMotifById("M178_0.6")
results <- runMatrixTSMA(foreground.sets, background.set, motifs = motif.db,
cache = FALSE)

## Not run: 
# define example sequence sets for foreground and background
foreground1.df <- transite:::ge$foreground1
foreground.set1 <- gsub("T", "U", foreground1.df$seq)
names(foreground.set1) <- paste0(foreground1.df$refseq, "|",
  foreground1.df$seq.type)

foreground2.df <- transite:::ge$foreground2
foreground.set2 <- gsub("T", "U", foreground2.df$seq)
names(foreground.set2) <- paste0(foreground2.df$refseq, "|",
  foreground2.df$seq.type)

foreground.sets <- list(foreground.set1, foreground.set2)

background.df <- transite:::ge$background
background.set <- gsub("T", "U", background.df$seq)
names(background.set) <- paste0(background.df$refseq, "|",
  background.df$seq.type)

# run cached version of TSMA with all Transite motifs (recommended)
results <- runMatrixTSMA(foreground.sets, background.set)

# run uncached version of TSMA with all Transite motifs
results <- runMatrixTSMA(foreground.sets, background.set, cache = FALSE)

# run TSMA with a subset of Transite motifs
results <- runMatrixTSMA(foreground.sets, background.set,
  motifs = getMotifByRBP("ELAVL1"))

# run TSMA with user-defined motif
toy.motif <- createMatrixMotif(
  "toy.motif", "example RBP", toy.motif.matrix,
  "example type", "example species", "user"
)
results <- runMatrixTSMA(foreground.sets, background.set,
  motifs = list(toy.motif))

## End(Not run)


[Package transite version 1.2.1 Index]