Package 'CAGEr'

Description

.byCTSS is a private function using data.table objects to preform grouping operations at a high performance. These functions use non-standard evaluation in a context that raises warnings in R CMD check. By separating these functions from the rest of the code, I hope to make the workarounds easier to manage.

Usage

.byCtss(ctssDT, colName, fun)

## S4 method for signature 'data.table'
.byCtss(ctssDT, colName, fun)

Arguments

Examples

ctssDT <- data.table::data.table(
  chr       = c("chr1", "chr1", "chr1", "chr2"),
  pos       = c(1     , 1     , 2     , 1     ),
  strand    = c("+"   , "+"   , "-"   , "-"   ),
  tag_count = c(1     , 1     , 1     , 1     ))
ctssDT
CAGEr:::.byCtss(ctssDT, "tag_count", sum)

Description

Summarise CTSSs included in clusters

Usage

.ctss_summary_for_clusters(ctss, clusters)

Arguments

Value

The clusters object with a new dominant_CTSS metadata in CTSS format reporting the genomic coordinate and expression score of most highly expressed position in each cluster, plus a nr_ctss metadata reporting the number of expressed CTSSs in each cluster.

Examples

# See also benchmarks/dominant_ctss.md
(ctss <- CTSS( 'chr1', IRanges(start = 1:10, end = 1:10)
             , '+', score = c(1, 0, 0, 1, 2, 0, 2, 1, 0, 1)))
(clusters <- GRanges( 'chr1', IRanges(start = c(1,9)
                    , end = c(8,10)), '+')) |> as("TagClusters")

# The function assumes that all CTSSes have a score above zero
.ctss_summary_for_clusters(ctss[score(ctss)>0], clusters)
# If not the case, it will give incorrect nr_ctss and  fail to remove singletons
.ctss_summary_for_clusters(ctss, clusters)

# The function needs its output to be sorted and is not going to check it.
.ctss_summary_for_clusters(rev(ctss), clusters)
.ctss_summary_for_clusters(ctss, rev(clusters))

# Ties are resolved with 5' preference for both plus and minus strands.
# This may create a small bias.
ctss_minus <- ctss
strand(ctss_minus) <- '-'
clusters_minus <- clusters
strand(clusters_minus) <- '-'
.ctss_summary_for_clusters(ctss_minus, clusters_minus)

Description

Private function that calculates position of quantiles for CTSS clusters based on distribution of tags within the clusters.

Usage

.get.quant.pos(cum.sums, clusters, q)

Arguments

Value

Returns the clusters object with one more metadata column per value in q, containing Rle integers giving the relative distance of the quantile boundaries to the start position.

Examples

cum.sums  <- RleList(`1` = Rle(1), `2` = cumsum(Rle(c(1, 1, 1, 2, 4, 0, 1, 1))))
clusters <- GRanges(c("chr1:100-101", "chr1:120-127"))
CAGEr:::.get.quant.pos(cum.sums, clusters, c(.2, .8))

Description

Private funtion for normalizing CAGE tag count to a referent power-law distribution.

Usage

.powerLaw(tag.counts, fitInRange = c(10, 1000), alpha = 1.25, T = 10^6)

Arguments

Details

S4 Methods are provided for integer vectors, Rle objects, data.frame objects and DataFrame objects, so that the most complex objects can be deconstructed in simpler parts, normalized and reconstructed.

Value

Normalized values (vector of the same length as input values); i.e. what would be the value of input values in the referent distribution. Ouptut objects are numeric, possibly Rle-encoded or wrapped in data.frames or DataFrames according to the input.

References

Balwierz, P. J., Carninci, P., Daub, C. O., Kawai, J., Hayashizaki, Y., Van Belle, W., Beisel, C., et al. (2009). Methods for analyzing deep sequencing expression data: constructing the human and mouse promoterome with deepCAGE data. Genome Biology, 10(7), R79.

Description

Aggregates tag clusters (TCs) across all CAGE datasets within the CAGEr object to create a referent set of consensus clusters.

Usage

aggregateTagClusters(
  object,
  tpmThreshold = 5,
  excludeSignalBelowThreshold = TRUE,
  qLow = NULL,
  qUp = NULL,
  maxDist = 100,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'CAGEr'
aggregateTagClusters(
  object,
  tpmThreshold = 5,
  excludeSignalBelowThreshold = TRUE,
  qLow = NULL,
  qUp = NULL,
  maxDist = 100,
  useMulticore = FALSE,
  nrCores = NULL
)

Arguments

Details

Since the tag clusters (TCs) returned by the CTSS clustering functions function are constructed separately for every CAGE sample within the CAGEr object, they can differ between samples in both their number, genomic coordinates, position of dominant TSS and overall signal. To be able to compare all samples at the level of clusters of TSSs, TCs from all CAGE datasets are aggregated into a single set of consensus clusters. First, TCs with signal ⁠>= tpmThreshold⁠ from all CAGE datasets are selected, and their 5' and 3' boundaries are determined based on provided qLow and qUp parameter (or the start and end coordinates, if they are set to NULL). Finally, the defined set of TCs from all CAGE datasets is reduced to a non-overlapping set of consensus clusters by merging overlapping TCs and TCs ⁠<= maxDist⁠ base-pairs apart. Consensus clusters represent a referent set of promoters that can be further used for expression profiling or detecting "shifting" (differentially used) promoters between different CAGE samples.

Value

Returns the object in which the experiment consensusClusters will be occupied by a RangedSummarizedExperiment containing the cluster coordinates as row ranges, and their expression levels in the counts and normalized assays. These genomic ranges are returned by the consensusClustersGR function and the whole object can be accessed with the consensusClustersSE function. The CTSS ranges of the tagCountMatrix experiment will gain a cluster column indicating which cluster they belong to. Lastly, the number of CTSS outside clusters will be documented in the outOfClusters column data.

Author(s)

Vanja Haberle

Charles Plessy

See Also

Other CAGEr object modifiers: CTSStoGenes(), CustomConsensusClusters(), annotateCTSS(), cumulativeCTSSdistribution(), distclu(), getCTSS(), normalizeTagCount(), paraclu(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Other CAGEr clusters functions: CTSScumulativesTagClusters(), CustomConsensusClusters(), consensusClustersDESeq2(), consensusClustersGR(), cumulativeCTSSdistribution(), distclu(), paraclu(), plotInterquantileWidth(), quantilePositions(), tagClustersGR()

Examples

consensusClustersGR(exampleCAGEexp)
ce <- aggregateTagClusters( exampleCAGEexp, tpmThreshold = 50
                          , excludeSignalBelowThreshold = FALSE, maxDist = 100)
consensusClustersGR(ce)

ce <- aggregateTagClusters( exampleCAGEexp, tpmThreshold = 50
                          , excludeSignalBelowThreshold = TRUE, maxDist = 100)
consensusClustersGR(ce)

ce <- aggregateTagClusters( exampleCAGEexp, tpmThreshold = 50
                          , excludeSignalBelowThreshold = TRUE, maxDist = 100
                          , qLow = 0.1, qUp = 0.9)
consensusClustersGR(ce)

Description

annotateCTSS annotates the CTSS of a CAGEexp object and computes annotation statistics.

annotateConsensusClusters annotates the consensus clusters of a CAGEr object.

Usage

annotateCTSS(object, ranges, upstream = 500, downstream = 500)

## S4 method for signature 'CAGEexp,GRanges'
annotateCTSS(object, ranges, upstream = 500, downstream = 500)

annotateTagClusters(object, ranges, upstream = 500, downstream = 500)

## S4 method for signature 'CAGEexp,GRanges'
annotateTagClusters(object, ranges, upstream = 500, downstream = 500)

annotateConsensusClusters(object, ranges, upstream = 500, downstream = 500)

## S4 method for signature 'CAGEexp,GRanges'
annotateConsensusClusters(object, ranges, upstream = 500, downstream = 500)

Arguments

Value

annotateCTSS returns the input object with the following modifications:

• The Genomic Ranges of the tagCountMatrix experiment gains an annotation metadata column, with levels such as promoter, exon, intron and unknown. If the annotation has a gene_name metadata, then a genes column is also added, with gene symbols from the annotation.

• The sample metadata gets new columns, indicating total counts in each of the annotation levels. If the annotation has a gene_name metadata, then a genes column is added to indicate the number of different gene symbols detected.

annotateTagClusters returns the input object with the same modifications as above.

annotateConsensusClusters returns the input object with the same modifications as above.

Author(s)

Charles Plessy

See Also

CTSStoGenes, and the exampleZv9_annot example data.

Other CAGEr object modifiers: CTSStoGenes(), CustomConsensusClusters(), aggregateTagClusters(), cumulativeCTSSdistribution(), distclu(), getCTSS(), normalizeTagCount(), paraclu(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Other CAGEr annotation functions: plotAnnot(), ranges2annot(), ranges2genes(), ranges2names()

Examples

annotateCTSS(exampleCAGEexp, exampleZv9_annot)
colData(exampleCAGEexp)

exampleCAGEexp <- annotateTagClusters(exampleCAGEexp, exampleZv9_annot)
tagClustersGR(exampleCAGEexp, 1)

annotateConsensusClusters(exampleCAGEexp, exampleZv9_annot)
consensusClustersGR(exampleCAGEexp)

Description

Converts from BAM to CTSS

Usage

bam2CTSS(gr, removeFirstG, correctSystematicG, genome)

Arguments

Details

Converts genomic ranges representing SAM/BAM alignments into a CTSS object.

Value

Returns a CTSS object.

See Also

Other loadFileIntoGPos: import.CTSS(), import.bam(), import.bam.ctss(), import.bedCTSS(), import.bedScore(), import.bedmolecule(), loadFileIntoGPos(), moleculesGR2CTSS()

Description

The CAGEr class is a MultiAssayExperiment object containing all data and metadata about a set of CAGE libraries. It replaced the CAGEset class in 2017. The main difference is that the expression data is stored in DataFrame objects of Rle-encoded expression values, instead of plain data.frames. With large datasets, this saves considerable amounts of memory.

Details

If genomeName is NULL, checks of chromosome names will be disabled and G-correction will not be possible. See https://support.bioconductor.org/p/86437/ for an example on how to create a BSgenome package.

Sample labels must be syntactically valid in the sense of the make.names() function, because they will be used as column names in some tables.

Slots

metadata

A list that must at least contain a genomeName member.

See Also

make.names

Examples

pathsToInputFiles <- list.files( system.file("extdata", package = "CAGEr")
                               , "ctss$"
                               , full.names = TRUE)
sampleLabels <- sub( ".chr17.ctss", "", basename(pathsToInputFiles))

# The CAGEexp object can be created using specific constructor commands
                              
exampleCAGEexp <-
  CAGEexp( genomeName     = "BSgenome.Drerio.UCSC.danRer7"
         , inputFiles     = pathsToInputFiles
         , inputFilesType = "ctss"
         , sampleLabels   = sub( ".chr17.ctss", "", basename(pathsToInputFiles)))
         
# Alternatively, it can be created just like another MultiAssayExperiment.
# This is useful when providing pre-existing colData with many columns.

exampleCAGEexp <-
  CAGEexp( metadata = list(genomeName = "BSgenome.Drerio.UCSC.danRer7")
         , colData  = DataFrame( inputFiles     = pathsToInputFiles
                               , sampleLabels   = sampleLabels
                               , inputFilesType = "ctss"
                               , row.names      = sampleLabels))


# Expression data is loaded by the getCTSS() function, that also calculates
# library sizes and store them in the object's column data.

exampleCAGEexp <- getCTSS(exampleCAGEexp)
librarySizes(exampleCAGEexp)
colData(exampleCAGEexp)

# CTSS data is stored internally as a SummarizedExperiemnt that can be retreived
# as a whole, or as GRanges, or as an expression DataFrame.

CTSStagCountSE(exampleCAGEexp)
CTSScoordinatesGR(exampleCAGEexp)
CTSStagCountDF(exampleCAGEexp)

# Columns of the "colData" table are accessible directly via the "$" operator.

exampleCAGEexp$l1 <- CTSStagCountDF(exampleCAGEexp) |> sapply ( \(col) sum(col > 0) )
exampleCAGEexp$l1

Description

CAGEr is in the transition towards using the BiocParallel for multicore parallelisation. On Windows platforms, the multicore support is disabled transparently, that is, attempts to use multiple cores are silently ignored.

Usage

CAGEr_Multicore(useMulticore = FALSE, nrCores = NULL)

Arguments

Value

Returns either a MulticoreParam object or a SerialParam object.

Author(s)

Charles Plessy

Examples

CAGEr:::CAGEr_Multicore()
CAGEr:::CAGEr_Multicore(TRUE,)
CAGEr:::CAGEr_Multicore(TRUE,  2)
CAGEr:::CAGEr_Multicore(FALSE, 2)

Description

The CAGEr package provides one class of objects to load, contain and process CAGE data: the CAGEexp class, introduced 2017, which is based on the MultiAssayExperiment class. In comparison with the original CAGEset class (removed in 2021) CAGEexp objects benefit from a a more efficient data storage, using DataFrames of run-length-encoded (Rle) integers, allowing for the loading and use of much larger transcriptome datasets.

References

Haberle V, Forrest ARR, Hayashizaki Y, Carninci P and Lenhard B (2015). “CAGEr: precise TSS data retrieval and high-resolution promoterome mining for integrative analyses.” Nucleic Acids Research, 43, pp. e51., http://nar.oxfordjournals.org/content/43/8/e51

Description

A private (non-exported) function to discard any range that is not compatible with the CAGEr object's BSgenome.

Usage

coerceInBSgenome(gr, genome)

Arguments

Value

A GRanges object in which every range is guaranteed to be compatible with the given BSgenome object. The sequnames of the GRanges are also set accordingly to the BSgenome.

Description

The ConsensusClusters class represents consensus clusters. It is used internally by CAGEr for type safety.

Details

Consensus clusters must not overlap, so that a single TSS in the genome can only be attributed to a single cluster.

Description

Set the information on consensus clusters in a CAGEr object.

Usage

consensusClustersSE(object) <- value

## S4 replacement method for signature 'CAGEexp,RangedSummarizedExperiment'
consensusClustersSE(object) <- value

consensusClustersGR(object) <- value

## S4 replacement method for signature 'CAGEexp'
consensusClustersGR(object) <- value

Arguments

Details

These setter methods are mostly for internal use, but are exported in case they may be useful to advanced users.

Author(s)

Vanja Haberle

Charles Plessy

Description

Creates a DESeqDataSet using the consensus cluster expression data in the experiment slot consensusClusters and the sample metadata of the CAGEexp object. The formula must be built using factors already present in the sample metadata.

Usage

consensusClustersDESeq2(object, design)

## S4 method for signature 'CAGEexp'
consensusClustersDESeq2(object, design)

Arguments

Author(s)

Charles Plessy

See Also

DESeqDataSet in the DESeq2 package.

Other CAGEr clusters functions: CTSScumulativesTagClusters(), CustomConsensusClusters(), aggregateTagClusters(), consensusClustersGR(), cumulativeCTSSdistribution(), distclu(), paraclu(), plotInterquantileWidth(), quantilePositions(), tagClustersGR()

Examples

exampleCAGEexp$group <- c("a", "a", "b", "b", "a")
consensusClustersDESeq2(exampleCAGEexp, ~group)

Description

Extracts the information on consensus clusters from a CAGEr object.

Usage

consensusClustersGR(object, sample = NULL, qLow = NULL, qUp = NULL)

## S4 method for signature 'CAGEexp'
consensusClustersGR(object, sample = NULL, qLow = NULL, qUp = NULL)

consensusClustersSE(object)

## S4 method for signature 'CAGEexp'
consensusClustersSE(object)

Arguments

Value

consensusClustersGR returns a ConsensusClusters object, which wraps the GRanges class. The score columns indicates the normalised expression value of each cluster, either across all samples (sample = NULL), or for the selected sample. The legacy tpm column may be removed in the future. When sample argument is NOT specified, total CAGE signal across all CAGE datasets (samples) is returned in the tpm column. When sample argument is specified, the tpm column contains CAGE signal of consensus clusters in that specific sample. In addition, sample-specific information is returned, including position of the dominant TSS, and (if applicable) interquantile width of the consensus clusters in the specified sample or otherwise, sample-agnostic information is returned.

consensusClustersSE returns the SummarizedExperiment stored in the consensusClusters experiment slot of the CAGEexp object.

Author(s)

Vanja Haberle

Charles Plessy

See Also

consensusClusters<-()

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), expressionClasses(), genomeName(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Other CAGEr clusters functions: CTSScumulativesTagClusters(), CustomConsensusClusters(), aggregateTagClusters(), consensusClustersDESeq2(), cumulativeCTSSdistribution(), distclu(), paraclu(), plotInterquantileWidth(), quantilePositions(), tagClustersGR()

Examples

consensusClustersGR( exampleCAGEexp, sample = 2
                   , qLow = 0.1, qUp = 0.9)

Description

Accessors for consensus cluster quantile data in CAGEr objects.

Usage

consensusClustersQuantileLow(object, samples = NULL)

## S4 method for signature 'CAGEexp'
consensusClustersQuantileLow(object, samples = NULL)

consensusClustersQuantileUp(object, samples = NULL)

## S4 method for signature 'CAGEexp'
consensusClustersQuantileUp(object, samples = NULL)

consensusClustersQuantile(object, sample = NULL, q)

## S4 method for signature 'CAGEexp'
consensusClustersQuantile(object, sample = NULL, q)

consensusClustersQuantileLow(object, samples = NULL) <- value

consensusClustersQuantileUp(object, samples = NULL) <- value

Arguments

Description

Extracts a table with normalized CAGE tag values for consensus clusters across all samples from a CAGEr object.

Usage

consensusClustersTpm(object)

## S4 method for signature 'CAGEexp'
consensusClustersTpm(object)

Arguments

Value

Returns the matrix of normalized expression values of CAGE clusters across all samples.

Author(s)

Vanja Haberle

See Also

consensusClustersSE

Other CAGEr clustering methods: distclu(), paraclu()

Examples

head(consensusClustersTpm(exampleCAGEexp))

Description

The CTSS class represents CAGE transcription start sites (CTSS) at single-nucleotide resolution, using GenomicRanges::UnstitchedGPos as base class. It is used by CAGEr for type safety.

The CTSS constructor takes the same arguments as GenomicRanges::GPos, plus bsgenomeName, and minus stitch, which is hardcoded to FALSE.

Usage

## S4 method for signature 'CTSS'
show(object)

## S4 method for signature 'CTSS'
initialize(.Object, ..., bsgenomeName = NULL)

CTSS(
  seqnames = NULL,
  pos = NULL,
  strand = NULL,
  ...,
  seqinfo = NULL,
  seqlengths = NULL,
  bsgenomeName = NULL
)

## S4 method for signature 'CTSS,GRanges'
coerce(from, to = "GRanges", strict = TRUE)

## S4 method for signature 'GRanges,CTSS'
coerce(from, to = "CTSS", strict = TRUE)

Arguments

Details

The genomeName element of the metadata slot is used to store the name of the BSgenome package used when constructing the CAGEr object.

Coercion from GRanges to CTSS loses information, but it seems to be fine, since other coercions like as(1.2, "integer") do the same.

Author(s)

Charles Plessy

Examples

# Convert an UnstitchedGPos object using the new() constructor.
gp <- GPos("chr1:2:-", stitch = FALSE)
ctss <- new("CTSS", gp, bsgenomeName = "BSgenome.Drerio.UCSC.danRer7")
genomeName(ctss)

# Create a new object using the CTSS() constructor.
CTSS("chr1", 2, "-", bsgenomeName = "BSgenome.Drerio.UCSC.danRer7")

# Coerce CTSS to GRanges
as(ctss, "GRanges")

# Coerce a GRanges object to CTSS using the as() method.
gr <- GRanges("chr1:1-10:-")
gr$seq <- "AAAAAAAAAA"
seqlengths(gr) <- 100
genome(gr) <- "foo"
as(gr, "CTSS")
identical(seqinfo(gr), seqinfo(as(gr, "CTSS")))
as(as(gr, "CTSS"), "CTSS") # Make sure it works twice in a row

Description

Extracts the genomic coordinates of all detected TSSs from CAGEexp objects.

Usage

CTSScoordinatesGR(object)

## S4 method for signature 'CAGEexp'
CTSScoordinatesGR(object)

CTSScoordinatesGR(object) <- value

## S4 replacement method for signature 'CAGEexp'
CTSScoordinatesGR(object) <- value

CTSStagCountSE(object) <- value

## S4 replacement method for signature 'CAGEexp'
CTSStagCountSE(object) <- value

Arguments

Value

CTSScoordinatesGR returns the coordinates as a CTSS() object wrapping genomic ranges. A filteredCTSSidx column metadata will be present if filterLowExpCTSS was ran earlier.

Author(s)

Vanja Haberle

Charles Plessy

See Also

getCTSS

Other CAGEr accessor methods: CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), expressionClasses(), genomeName(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Examples

CTSScoordinatesGR(exampleCAGEexp)

CTSScoordinatesGR(exampleCAGEexp)

Description

Accessor function.

Usage

CTSScumulativesTagClusters(object, samples = NULL)

## S4 method for signature 'CAGEexp'
CTSScumulativesTagClusters(object, samples = NULL)

CTSScumulativesCC(object, samples = NULL)

## S4 method for signature 'CAGEexp'
CTSScumulativesCC(object, samples = NULL)

CTSScumulativesTagClusters(object) <- value

## S4 replacement method for signature 'CAGEexp'
CTSScumulativesTagClusters(object) <- value

Arguments

Value

List of numeric Rle.

See Also

Other CAGEr clusters functions: CustomConsensusClusters(), aggregateTagClusters(), consensusClustersDESeq2(), consensusClustersGR(), cumulativeCTSSdistribution(), distclu(), paraclu(), plotInterquantileWidth(), quantilePositions(), tagClustersGR()

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), expressionClasses(), genomeName(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Description

Extracts the normalized CAGE signal for all detected TSSs in all CAGE datasets from CAGEexp objects.

Usage

CTSSnormalizedTpmDF(object)

## S4 method for signature 'CAGEexp'
CTSSnormalizedTpmDF(object)

CTSSnormalizedTpmGR(object, samples)

## S4 method for signature 'CAGEexp'
CTSSnormalizedTpmGR(object, samples)

Arguments

Value

CTSSnormalizedTpmDF returns a DataFrame of normalised expression values.

Author(s)

Vanja Haberle

Charles Plessy

See Also

normalizeTagCount

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), expressionClasses(), genomeName(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Examples

CTSSnormalizedTpmDF(exampleCAGEexp)

CTSSnormalizedTpmGR(exampleCAGEexp, 1)
exampleCAGEexp |> CTSSnormalizedTpmGR("all")

Description

Extracts the tag count for all detected TSSs in all CAGE datasets from CAGEexp objects.

Usage

CTSStagCountDF(object)

## S4 method for signature 'CAGEexp'
CTSStagCountDF(object)

CTSStagCountGR(object, samples)

## S4 method for signature 'CAGEexp'
CTSStagCountGR(object, samples)

CTSStagCountSE(object)

## S4 method for signature 'CAGEexp'
CTSStagCountSE(object)

Arguments

Value

Returns an object with number of CAGE tags supporting each TSS (rows) in every CAGE dataset (columns). The class of the object depends on the function being called:

• CTSStagCountDF: A DataFrame of Rle integers.

• CTSStagCountSE: A RangedSummarizedExperiment⁠containing a⁠DataFrameofRle' integers.

• CTSStagCountGR: A CTSS object (wrapping GRanges) containing a score column indicating expression values for a given sample, or a GRangesList of CTSS objects.

Author(s)

Vanja Haberle

Charles Plessy

See Also

getCTSS()

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), expressionClasses(), genomeName(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Examples

CTSStagCountDF(exampleCAGEexp)
 
CTSStagCountGR(exampleCAGEexp, 1)
CTSStagCountGR(exampleCAGEexp, "all")
 
CTSStagCountSE(exampleCAGEexp)

Description

Add a gene expression table in the GeneExpSE experiment slot of an annotated CAGEexp object.

Usage

CTSStoGenes(object)

## S4 method for signature 'CAGEexp'
CTSStoGenes(object)

Arguments

Value

The input object with the following modifications:

• A new geneExpMatrix experiment containing gene expression levels as a SummarizedExperiment object with one assay called counts, which is plain matrix of integers. (This plays better than ⁠Rle DataFrames⁠ when interfacing with downstream packages like DESeq2, and since the number of genes is limited, a matrix will not cause problems of performance.)

• New genes column data added, indicating total number of gene symbols detected per library.

• New unannotated column data added, indicating for each sample the number of counts that did not overlap with a known gene.

Author(s)

Charles Plessy

See Also

annotateCTSS().

Other CAGEr object modifiers: CustomConsensusClusters(), aggregateTagClusters(), annotateCTSS(), cumulativeCTSSdistribution(), distclu(), getCTSS(), normalizeTagCount(), paraclu(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Other CAGEr gene expression analysis functions: GeneExpDESeq2(), ranges2genes()

Examples

CTSStoGenes(exampleCAGEexp)
all( librarySizes(exampleCAGEexp) -
     colSums(SummarizedExperiment::assay(GeneExpSE(exampleCAGEexp))) ==
     exampleCAGEexp$unannotated)

Description

Calculates the cumulative sum of normalised CAGE counts along each tag cluster or consensus cluster in every sample within a CAGEr object.

Usage

cumulativeCTSSdistribution(
  object,
  clusters = c("tagClusters", "consensusClusters"),
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'CAGEexp'
cumulativeCTSSdistribution(
  object,
  clusters = c("tagClusters", "consensusClusters"),
  useMulticore = FALSE,
  nrCores = NULL
)

Arguments

Value

In CAGEexp objects, cumulative sums for the tag clusters are stored in the metadata slot using the RleList class. For consensus clusters, they are stored in assays of the consensusClusters experiment slot of the CAGEexp object.

Author(s)

Vanja Haberle

Charles Plessy

See Also

Other CAGEr object modifiers: CTSStoGenes(), CustomConsensusClusters(), aggregateTagClusters(), annotateCTSS(), distclu(), getCTSS(), normalizeTagCount(), paraclu(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Other CAGEr clusters functions: CTSScumulativesTagClusters(), CustomConsensusClusters(), aggregateTagClusters(), consensusClustersDESeq2(), consensusClustersGR(), distclu(), paraclu(), plotInterquantileWidth(), quantilePositions(), tagClustersGR()

Examples

cumulativeCTSSdistribution(exampleCAGEexp, clusters = "tagClusters")
CTSScumulativesTagClusters(exampleCAGEexp)[[1]][1:6]
cumulativeCTSSdistribution(exampleCAGEexp, clusters = "consensusClusters")
CTSScumulativesCC(exampleCAGEexp)[[1]][1:6]

Description

Intersects custom consensus clusters with the CTSS data in a CAGEexp object, and stores the result as a expression matrices (raw and normalised tag counts).

Usage

CustomConsensusClusters(
  object,
  clusters,
  threshold = 0,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

## S4 method for signature 'CAGEexp,GRanges'
CustomConsensusClusters(
  object,
  clusters,
  threshold = 0,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

Arguments

Details

Consensus clusters must not overlap, so that a single base of the genome can only be attributed to a single cluster. This is enforced by the .ConsensusClusters constructor.

Value

stores the result as a new RangedSummarizedExperiment in the experiment slot of the object. The assays of the new experiment are called counts and normalized. An outOfClusters column is added to the sample metadata to reflect the number of molecules that do not have their TSS in a consensus cluster.

Author(s)

Charles Plessy

See Also

Other CAGEr object modifiers: CTSStoGenes(), aggregateTagClusters(), annotateCTSS(), cumulativeCTSSdistribution(), distclu(), getCTSS(), normalizeTagCount(), paraclu(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Other CAGEr clusters functions: CTSScumulativesTagClusters(), aggregateTagClusters(), consensusClustersDESeq2(), consensusClustersGR(), cumulativeCTSSdistribution(), distclu(), paraclu(), plotInterquantileWidth(), quantilePositions(), tagClustersGR()

Examples

cc <- consensusClustersGR(exampleCAGEexp)
CustomConsensusClusters(exampleCAGEexp, cc)

Description

The "distclu" method is an implementation of simple distance-based clustering of data attached to sequences, where two neighbouring TSSs are joined together if they are closer than some specified distance (see GenomicRanges::reduce for implementation details.

Usage

distclu(object, maxDist = 20, keepSingletonsAbove = 0)

## S4 method for signature 'SummarizedExperiment'
distclu(object, maxDist = 20, keepSingletonsAbove = 0)

## S4 method for signature 'CTSS'
distclu(object, maxDist = 20, keepSingletonsAbove = 0)

## S4 method for signature 'CAGEexp'
distclu(object, maxDist = 20, keepSingletonsAbove = 0)

Arguments

Details

Clustering is done for every CAGE dataset within the CAGEr object separately, resulting in a different set of tag clusters for every CAGE dataset. TCs from different datasets can further be aggregated into a single referent set of consensus clusters by calling the aggregateTagClusters function.

Value

For CTSS input, a TagClusters object, for SummarizedExperiment input, a GRangesList of TagClusters objects, and for CAGEexp input, a modified object containing the tag clusters stored as a GRangesList of TagClusters objects in its metadata slot tagClusters.

Author(s)

Vanja Haberle

Charles Plessy

See Also

aggregateTagClusters

Other CAGEr clustering methods: consensusClustersTpm(), paraclu()

Other CAGEr object modifiers: CTSStoGenes(), CustomConsensusClusters(), aggregateTagClusters(), annotateCTSS(), cumulativeCTSSdistribution(), getCTSS(), normalizeTagCount(), paraclu(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Other CAGEr clusters functions: CTSScumulativesTagClusters(), CustomConsensusClusters(), aggregateTagClusters(), consensusClustersDESeq2(), consensusClustersGR(), cumulativeCTSSdistribution(), paraclu(), plotInterquantileWidth(), quantilePositions(), tagClustersGR()

Examples

distclu(CTSSnormalizedTpmGR(exampleCAGEexp, 1)[1:10])
distclu(CTSStagCountSE(exampleCAGEexp)[1:25,])
ce <- distclu(exampleCAGEexp, maxDist = 20, keepSingletonsAbove = 100)
tagClustersGR(ce, "Zf.30p.dome")

Description

Lazy-loaded example CAGEexp object, containing most of the CAGEr data structures created with the CAGEr modifier functions.

Usage

exampleCAGEexp

Format

A CAGEexp object.

Examples

## Not run: 
pathsToInputFiles <- list.files( system.file("extdata", package = "CAGEr")
                               , "ctss$"
                               , full.names = TRUE)
sampleLabels <- sub( ".chr17.ctss", "", basename(pathsToInputFiles))
exampleCAGEexp <-
  CAGEexp( genomeName     = "BSgenome.Drerio.UCSC.danRer7"
         , inputFiles     = pathsToInputFiles
         , inputFilesType = "ctss"
         , sampleLabels   = sub( ".chr17.ctss", "", basename(pathsToInputFiles)))
exampleCAGEexp <- getCTSS(exampleCAGEexp)
librarySizes(exampleCAGEexp)
colData(exampleCAGEexp)
exampleCAGEexp$l1 <- NULL
exampleCAGEexp <- exampleCAGEexp[,c(5, 2, 1, 3, 4)] # Non-aplhabetic order may help catch bugs
CTSStagCountSE(exampleCAGEexp) <- CTSStagCountSE(exampleCAGEexp)[1:5000,]  # Slim the object
exampleCAGEexp$librarySizes <- sapply(CTSStagCountDF(exampleCAGEexp), sum) # Repair metadata
exampleCAGEexp <- 
  summariseChrExpr(exampleCAGEexp)                |>
  annotateCTSS(exampleZv9_annot)                  |>
  CTSStoGenes()                                   |>
  normalizeTagCount()                             |>
  getExpressionProfiles("CTSS")                   |>
  filterLowExpCTSS()                              |>
  distclu()                                       |>
  annotateTagClusters(exampleZv9_annot)           |>
  cumulativeCTSSdistribution("tagClusters")       |>
  quantilePositions("tagClusters")                |>
  aggregateTagClusters()                          |>
  annotateConsensusClusters(exampleZv9_annot)     |>
  cumulativeCTSSdistribution("consensusClusters") |>
  quantilePositions("consensusClusters")          |>
  getExpressionProfiles("consensusClusters")      |>
  scoreShift( groupX = c("Zf.unfertilized.egg")
            , groupY = "Zf.30p.dome"
            , testKS = TRUE, useTpmKS = FALSE)
save(exampleCAGEexp, file = "data/exampleCAGEexp.RData", compress = "xz")

## End(Not run)

Description

Annotation data for zebrafish's chromosome 17's interval 26000000-54000000 (Zv9/danRer7 genome), to be used in documentation examples.

Usage

exampleZv9_annot

Format

An object of class GRanges of length 7467.

Details

Data was retreived from ENSEMBL's Biomart server using a query to extract gene, transcripts and exon coordinates. For the record, here it is as URL (long, possibly overflowing).

http://mar2015.archive.ensembl.org/biomart/martview/78d86c1d6b4ef51568ba6d46f7d8b254?VIRTUALSCHEMANAME=default&ATTRIBUTES=drerio_gene_ensembl.default.structure.ensembl_gene_id|drerio_gene_ensembl.default.structure.ensembl_transcript_id|drerio_gene_ensembl.default.structure.start_position|drerio_gene_ensembl.default.structure.end_position|drerio_gene_ensembl.default.structure.transcript_start|drerio_gene_ensembl.default.structure.transcript_end|drerio_gene_ensembl.default.structure.strand|drerio_gene_ensembl.default.structure.chromosome_name|drerio_gene_ensembl.default.structure.external_gene_name|drerio_gene_ensembl.default.structure.gene_biotype|drerio_gene_ensembl.default.structure.exon_chrom_start|drerio_gene_ensembl.default.structure.exon_chrom_end|drerio_gene_ensembl.default.structure.is_constitutive|drerio_gene_ensembl.default.structure.rank&FILTERS=&VISIBLEPANEL=resultspanel

And here it is as XML.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Query>
<Query  virtualSchemaName = "default" formatter = "TSV" header = "0" uniqueRows = "0" count = "" datasetConfigVersion = "0.6" >
  <Dataset name = "drerio_gene_ensembl" interface = "default" >
    <Attribute name = "ensembl_gene_id" />
    <Attribute name = "ensembl_transcript_id" />
    <Attribute name = "start_position" />
    <Attribute name = "end_position" />
    <Attribute name = "transcript_start" />
    <Attribute name = "transcript_end" />
    <Attribute name = "strand" />
    <Attribute name = "chromosome_name" />
    <Attribute name = "external_gene_name" />
    <Attribute name = "gene_biotype" />
    <Attribute name = "exon_chrom_start" />
    <Attribute name = "exon_chrom_end" />
    <Attribute name = "is_constitutive" />
    <Attribute name = "rank" />
  </Dataset>
</Query>

The downloaded file was then transformed as follows.

x <- read.delim("~/Downloads/mart_export.txt", stringsAsFactors = FALSE)
e <- GRanges(paste0("chr", x$Chromosome.Name), IRanges(x$Exon.Chr.Start..bp., x$Exon.Chr.End..bp.), ifelse(x$Strand + 1, "+", "-"))
e$gene_name <- Rle(x$Associated.Gene.Name)
e$transcript_type <- Rle(x$Gene.type)
e$type <- "exon"
e$type <- Rle(e$type)

e <- GRanges(paste0("chr", x$Chromosome.Name), IRanges(x$Exon.Chr.Start..bp., x$Exon.Chr.End..bp.), ifelse(x$Strand + 1, "+", "-"))
e$gene_name <- Rle(x$Associated.Gene.Name)
e$transcript_type <- Rle(x$Gene.type)
e$type <- "exon"
e$type <- Rle(e$type)
e <- sort(unique(e))

g <- GRanges( paste0("chr", x$Chromosome.Name)
            , IRanges(x$Gene.Start..bp., x$Gene.End..bp.)
            , ifelse( x$Strand + 1, "+", "-"))
            
g$gene_name <- Rle(x$Associated.Gene.Name)
g$transcript_type <- Rle(x$Gene.type)
g$type <- "gene"
g$type <- Rle(g$type)
g <- sort(unique(g))

t <- GRanges( paste0("chr", x$Chromosome.Name)
            , IRanges(x$Transcript.Start..bp., x$Transcript.End..bp.)
            , ifelse( x$Strand + 1, "+", "-"))
            
t$gene_name <- Rle(x$Associated.Gene.Name)
t$transcript_type <- Rle(x$Gene.type)
t$type <- "transcript"
t$type <- Rle(t$type)
t <- sort(unique(t))

gff <- sort(c(g, t, e))
gff <- gff[seqnames(gff) == "chr17"]
gff <- gff[start(gff) > 26000000 & end(gff) < 54000000]
seqlevels(gff) <- seqlevelsInUse(gff)

save(gff, "data/exampleZv9_annot.RData", compress = "xz")

Author(s)

Prepared by Charles Plessy [email protected] using archive ENSEMBL data.

References

http://mar2015.archive.ensembl.org/biomart/

Description

Converts CTSS, tag clusters or consensus clusters to the UCSCData format of the rtracklayer package, that can be exported to BED file(s) with track information for genome browsers. CTSSes and consensus clusters are optionally colored by their expression class. Tag clusters and consensus clusters can be displayed in a whiskerplot-like representation with a line showing full span on the cluster, filled block showing interquantile range and a thick box denoting position of the dominant (most frequently) used TSS.

Usage

exportToTrack(
  object,
  what = c("CTSS", "tagClusters", "consensusClusters"),
  qLow = NULL,
  qUp = NULL,
  colorByExpressionProfile = FALSE,
  oneTrack = TRUE
)

## S4 method for signature 'CAGEexp'
exportToTrack(
  object,
  what = c("CTSS", "tagClusters", "consensusClusters"),
  qLow = NULL,
  qUp = NULL,
  colorByExpressionProfile = FALSE,
  oneTrack = TRUE
)

## S4 method for signature 'GRangesList'
exportToTrack(
  object,
  what = c("CTSS", "tagClusters", "consensusClusters"),
  qLow = NULL,
  qUp = NULL,
  colorByExpressionProfile = FALSE,
  oneTrack = TRUE
)

## S4 method for signature 'GRanges'
exportToTrack(
  object,
  what = c("CTSS", "tagClusters", "consensusClusters"),
  qLow = NULL,
  qUp = NULL,
  colorByExpressionProfile = FALSE,
  oneTrack = TRUE
)

## S4 method for signature 'CTSS'
exportToTrack(
  object,
  what = c("CTSS", "tagClusters", "consensusClusters"),
  qLow = NULL,
  qUp = NULL,
  colorByExpressionProfile = FALSE,
  oneTrack = TRUE
)

## S4 method for signature 'TagClusters'
exportToTrack(
  object,
  what = c("CTSS", "tagClusters", "consensusClusters"),
  qLow = NULL,
  qUp = NULL,
  colorByExpressionProfile = FALSE,
  oneTrack = TRUE
)

## S4 method for signature 'ConsensusClusters'
exportToTrack(
  object,
  what = c("CTSS", "tagClusters", "consensusClusters"),
  qLow = NULL,
  qUp = NULL,
  colorByExpressionProfile = FALSE,
  oneTrack = TRUE
)

Arguments

Details

The BED representations of CTSSs, tag cluster and consensus clusters can be directly visualised in the ZENBU or UCSC Genome Browsers.

When what = "CTSS", one UCSCData object with single track of 1 bp blocks representing all detected CTSSs (in all CAGE samples) is created. CTSSs can be colored according to their expression class (see getExpressionProfiles and plotExpressionProfiles). For colorByExpressionProfile = FALSE, CTSSs included in the clusters are shown in black and CTSSs that were filtered out in gray.

When what = "tagClusters", one track per CAGE dataset is created, which can be exported to a single UCSCData object (by setting oneFile = TRUE) or separate ones (FALSE). If no quantile boundaries were provided (qLow and qUp are NULL, TCs are represented as simple blocks showing the full span of TC fromthe start to the end. Setting qLow and/or qUp parameters to a value of the desired quantile creates a gene-like representation with a line showing full span of the TC, filled block showing specified interquantile range and a thick 1 bp block denoting position of the dominant (most frequently used) TSS. All TCs in one track (one CAGE dataset) are shown in the same color.

When what = "consensusClusters" consensus clusters are exported. Since there is only one set of consensus clusters common to all CAGE datasets, only one track is created in case of a simple representation. This means that when qLow = NULL and qUp = NULL one track with blocks showing the full span of consensus cluster from the start to the end is created. However, the distribution of the CAGE signal within consensus cluster can be different in different CAGE samples, resulting in different positions of quantiles and dominant TSS. Thus, when qLow and/or qUp parameters are set to a value of the desired quantile, a separate track with a gene-like representation is created for every CAGE dataset. These tracks can be exported to a single UCSCData object (by setting oneFile = TRUE) or separate ones (by setting oneFile = FALSE). The gene-like representation is analogous to the one described above for the TCs. In all cases consensus clusters can be colored according to their expression class (provided the expression profiling of consensus clusters was done by calling getExpressionProfiles function). Colors of expression classes match the colors in which they are shown in the plot returned by the plotExpressionProfiles function. For colorByExpressionProfile = FALSE all consensus clusters are shown in black.

Value

Returns either a rtracklayer UCSCData object, or a GRangesList of them.

Author(s)

Vanja Haberle

Charles Plessy

Examples

# You can export from a CAGEexp object or from a cluster object directly:
exportToTrack(exampleCAGEexp, what = "CTSS")  # Is same as:
exportToTrack(CTSScoordinatesGR(exampleCAGEexp))  # Or:
exampleCAGEexp |> CTSScoordinatesGR() |> exportToTrack()

# Export a single sample, 
exampleCAGEexp |> CTSStagCountGR(2)      |> exportToTrack()
exampleCAGEexp |> CTSSnormalizedTpmGR(2) |> exportToTrack()

# Exporting multiple samples results in a GRangesList of UCSCData objects.
exportToTrack(exampleCAGEexp, what = "CTSS", oneTrack = FALSE)
exampleCAGEexp |> CTSStagCountGR("all")  |> exportToTrack()
exampleCAGEexp |> CTSSnormalizedTpmGR("all")  |> exportToTrack()

### exporting CTSSs colored by expression class
# Temporarly disabled
# exportToTrack(exampleCAGEexp, what = "CTSS", colorByExpressionProfile = TRUE)

### exporting tag clusters in gene-like representation
exportToTrack(exampleCAGEexp, what = "tagClusters", qLow = 0.1, qUp = 0.9)
tagClustersGR(exampleCAGEexp, 1) |> exportToTrack(qLow = 0.1, qUp = 0.9)
           
### exporting consensus clusters
exportToTrack( exampleCAGEexp, what = "consensusClusters")
exampleCAGEexp |>
  consensusClustersGR("Zf.high", qLow = .1, qUp = .9) |>
  exportToTrack(qLow = .1, qUp = .9)
exportToTrack( exampleCAGEexp, what = "consensusClusters"
             , qLow = 0.1, qUp = 0.9, oneTrack = FALSE)

Description

Retrieves labels of expression classes of individual CTSSs or consensus clusters from a CAGEr object.

Usage

expressionClasses(object)

## S4 method for signature 'CTSS'
expressionClasses(object)

## S4 method for signature 'ConsensusClusters'
expressionClasses(object)

Arguments

Value

Returns a Rle-encoded vector of labels of expression classes. The number of labels matches the number of expression clusters returned by getExpressionProfiles function.

See Also

Other CAGEr expression clustering functions: getExpressionProfiles(), plotExpressionProfiles()

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), genomeName(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Examples

expressionClasses(CTSScoordinatesGR(exampleCAGEexp))
exampleCAGEexp |> consensusClustersGR() |> expressionClasses()

Description

Lazy-loaded data.frame object, containing information about FANTOM5 libraries. Its use is described in more details in the vignette “Use of CAGE resources with CAGEr”.

Usage

FANTOM5humanSamples

Format

A data.frame with sample, type, description, library_id and data_url columns.

See Also

Other FANTOM data: FANTOM5mouseSamples, importPublicData()

Description

Lazy-loaded data.frame object, containing information about FANTOM5 libraries. Its use is described in more details in the vignette “Use of CAGE resources with CAGEr”.

Usage

FANTOM5mouseSamples

Format

A data.frame with sample, type, description, library_id and data_url columns.

See Also

Other FANTOM data: FANTOM5humanSamples, importPublicData()

Description

Looks up the bases directly upstream provided genomic ranges and searches for a gapless match with a target seqence within a given edit distance.

Usage

flagByUpstreamSequences(object, target, distance = 0)

## S4 method for signature 'CTSS'
flagByUpstreamSequences(object, target, distance = 0)

## S4 method for signature 'TagClusters'
flagByUpstreamSequences(object, target, distance = 0)

## S4 method for signature 'ConsensusClusters'
flagByUpstreamSequences(object, target, distance = 0)

## S4 method for signature 'GRanges'
flagByUpstreamSequences(object, target, distance = 0)

Arguments

Details

If the provided object represents tag clusters or consensus clusters, the search will be done upstream its dominant peak. Convert the object to the GRanges class if this is not the behaviour you want.

Value

A logical-RLe vector indicating if ranges matched the target.

Author(s)

Charles Plessy

Description

Flag CTSSes for that do not pass an expression threshold in at least a given number of samples. This is typically used to ignore CTSSes that have been seen only once in a single sample, as they can be considered to not be reproduced.

Usage

flagLowExpCTSS(
  object,
  threshold = 1,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

## S4 method for signature 'CAGEr'
flagLowExpCTSS(
  object,
  threshold = 1,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

## S4 method for signature 'RangedSummarizedExperiment'
flagLowExpCTSS(
  object,
  threshold = 1,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

## S4 method for signature 'DataFrame'
flagLowExpCTSS(
  object,
  threshold = 1,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

## S4 method for signature 'matrix'
flagLowExpCTSS(
  object,
  threshold = 1,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

filterLowExpCTSS(
  object,
  threshold = 1,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

## S4 method for signature 'CAGEr'
filterLowExpCTSS(
  object,
  threshold = 1,
  nrPassThreshold = 1,
  thresholdIsTpm = TRUE
)

Arguments

Value

flagLowExpCTSS returns a Rle vector where TRUE indicates the index of a CTSS that passes the filter.

filterLowExpCTSS returns the CAGEr object where the output of flagLowExpCTSS was stored internally.

Examples

flagLowExpCTSS(exampleCAGEexp, threshold = 100, nrPassThreshold = 2)

Description

Creates a DESeqDataSet using the gene expression data in the experiment slot geneExpMatrix and the sample metadata of the CAGEexp object. The formula must be built using factors already present in the sample metadata.

Usage

GeneExpDESeq2(object, design)

## S4 method for signature 'CAGEexp'
GeneExpDESeq2(object, design)

Arguments

Author(s)

Charles Plessy

See Also

DESeqDataSet in the DESeq2 package.

Other CAGEr gene expression analysis functions: CTSStoGenes(), ranges2genes()

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpSE(), consensusClustersGR(), expressionClasses(), genomeName(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Examples

exampleCAGEexp$group <- factor(c("a", "a", "b", "b", "a"))
GeneExpDESeq2(exampleCAGEexp, ~group)

Description

Get or set a SummarizedExperiment using the gene expression data in the experiment slot geneExpMatrix and the sample metadata of the CAGEexp object.

Usage

GeneExpSE(object)

## S4 method for signature 'CAGEexp'
GeneExpSE(object)

Arguments

Author(s)

Charles Plessy

See Also

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), consensusClustersGR(), expressionClasses(), genomeName(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Examples

GeneExpSE(exampleCAGEexp)

Description

Extracts the name of a referent genome from a CAGEexp or a CTSS object.

Usage

genomeName(object)

## S4 method for signature 'CAGEexp'
genomeName(object)

## S4 method for signature 'CTSS'
genomeName(object)

genomeName(object) <- value

## S4 replacement method for signature 'CAGEexp'
genomeName(object) <- value

## S4 replacement method for signature 'CTSS'
genomeName(object) <- value

Arguments

Details

CAGEexp objects constructed with NULL in place of the genome name can not run some commands that need access to genomic data, such as BigWig export or G-correction.

Value

Returns a name of a BSgenome package used as a referent genome.

Author(s)

Vanja Haberle

Charles Plessy

See Also

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), expressionClasses(), inputFiles(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Other CAGEr setter methods: inputFiles(), inputFilesType(), sampleLabels(), setColors()

Examples

genomeName(exampleCAGEexp)

Description

Reads input CAGE datasets into CAGEr object, constructs CAGE transcriptions start sites (CTSSs) and counts number of CAGE tags supporting every CTSS in each input experiment. See inputFilesType for details on the supported input formats. Preprocessing and quality filtering of input CAGE tags, as well as correction of CAGE-specific 'G' nucleotide addition bias can be also performed before constructing TSSs.

Usage

getCTSS(
  object,
  sequencingQualityThreshold = 10,
  mappingQualityThreshold = 20,
  removeFirstG = TRUE,
  correctSystematicG = TRUE,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'CAGEexp'
getCTSS(
  object,
  sequencingQualityThreshold = 10,
  mappingQualityThreshold = 20,
  removeFirstG = TRUE,
  correctSystematicG = TRUE,
  useMulticore = FALSE,
  nrCores = NULL
)

Arguments

Details

In the CAGE experimental protocol an additional G nucleotide is often attached to the 5' end of the tag by the template-free activity of the reverse transcriptase used to prepare cDNA (Harbers and Carninci, Nature Methods 2005). In cases where there is a G at the 5' end of the CAGE tag that does not map to the corresponding genome sequence, it can confidently be considered spurious and should be removed from the tag to avoid misannotating actual TSS. Thus, setting removeFirstG = TRUE is highly recommended.

However, when there is a G both at the beginning of the CAGE tag and in the genome, it is not clear whether the original CAGE tag really starts at this position or the G nucleotide was added later in the experimental protocol. To systematically correct CAGE tags mapping at such positions, a general frequency of adding a G to CAGE tags can be calculated from mismatch cases and applied to estimate the number of CAGE tags that have G added and should actually start at the next nucleotide/position. The option correctSystematicG is an implementation of the correction algorithm described in Carninci et al., Nature Genetics 2006, Supplementary Information section 3-e.

Value

Returns the object, in which the tagCountMatrix experiment will be occupied by a RangedSummarizedExperiment containing the expression data as a DataFrame of Rle integers, and the CTSS coordinates as genomic ranges in a CTSS object. The expression data can be retrieved with the CTSStagCountDF function. In addition, the library sizes are calculated and stored in the object's sample data (see librarySizes).

Author(s)

Vanja Haberle

References

Harbers and Carninci (2005) Tag-based approaches for transcriptome research and genome annotation, Nature Methods 2(7):495-502.

Carninci et al. (2006) Genome-wide analysis of mammalian promoter architecture and evolution, Nature Genetics 38(7):626-635.

See Also

inputFilesType, librarySizes.

Other CAGEr object modifiers: CTSStoGenes(), CustomConsensusClusters(), aggregateTagClusters(), annotateCTSS(), cumulativeCTSSdistribution(), distclu(), normalizeTagCount(), paraclu(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Examples

library(BSgenome.Drerio.UCSC.danRer7)

pathsToInputFiles <- system.file("extdata", c("Zf.unfertilized.egg.chr17.ctss",
  "Zf.30p.dome.chr17.ctss", "Zf.prim6.rep1.chr17.ctss"), package="CAGEr")
  
labels <- paste("sample", seq(1,3,1), sep = "")

myCAGEexp <- new("CAGEexp", genomeName = "BSgenome.Drerio.UCSC.danRer7",
 inputFiles = pathsToInputFiles, inputFilesType = "ctss", sampleLabels = labels)

myCAGEexp <- getCTSS(myCAGEexp)

Description

Clusters CAGE expression across multiple experiments, both at level of individual TSSs or entire clusters of TSSs.

Usage

getExpressionProfiles(
  object,
  what = c("CTSS", "consensusClusters"),
  tpmThreshold = 5,
  nrPassThreshold = 1,
  method = c("som", "kmeans"),
  xDim = 5,
  yDim = 5
)

## S4 method for signature 'CAGEexp'
getExpressionProfiles(
  object,
  what = c("CTSS", "consensusClusters"),
  tpmThreshold = 5,
  nrPassThreshold = 1,
  method = c("som", "kmeans"),
  xDim = 5,
  yDim = 5
)

## S4 method for signature 'matrix'
getExpressionProfiles(
  object,
  what = c("CTSS", "consensusClusters"),
  tpmThreshold = 5,
  nrPassThreshold = 1,
  method = c("som", "kmeans"),
  xDim = 5,
  yDim = 5
)

Arguments

Details

Expression clustering can be done at level of individual CTSSs, in which case the feature vector used as input for clustering algorithm contains log-transformed and scaled (divided by standard deviation) normalized CAGE signal at individual TSS across multiple experiments. Only TSSs with normalized CAGE signal ⁠>= tpmThreshold⁠ in at least nrPassThreshold CAGE experiments are used for expression clustering. However, CTSSs along the genome can be spatially clustered into tag clusters for each experiment separately using a CTSS clustering function, and then aggregated across experiments into consensus clusters using aggregateTagClusters function. Once the consensus clusters have been created, expression clustering at the level of these wider genomic regions (representing entire promoters rather than individual TSSs) can be performed. In that case the feature vector used as input for clustering algorithm contains normalized CAGE signal within entire consensus cluster across multiple experiments, and threshold values in tpmThreshold and nrPassThreshold are applied to entire consensus clusters.

Value

Returns a modified CAGEexp object. If what = "CTSS" the objects's metadata elements CTSSexpressionClusteringMethod and CTSSexpressionClasses will be set accordingly, and if what = "consensusClusters" the elements consensusClustersExpressionClusteringMethod and consensusClustersExpressionClasses will be set. Labels of expression classes (clusters) can be retrieved using expressionClasses function.

Author(s)

Vanja Haberle

Charles Plessy

References

Toronen et al. (1999) Analysis of gene expression data using self-organizing maps, FEBS Letters 451:142-146.

See Also

Other CAGEr expression clustering functions: expressionClasses(), plotExpressionProfiles()

Examples

getExpressionProfiles( exampleCAGEexp, "CTSS"
                     , tpmThreshold = 50, nrPassThreshold = 1
                     , method = "som", xDim = 3, yDim = 3)
                     
getExpressionProfiles( exampleCAGEexp, "CTSS"
                     , tpmThreshold = 50, nrPassThreshold = 1
                     , method = "kmeans", xDim = 3)

getExpressionProfiles(exampleCAGEexp, "consensusClusters")

Description

Extracts consensus clusters with shifting score and/or FDR (adjusted P-value from Kolmogorov-Smirnov test) above specified threshold. Returns their genomic coordinates, total CAGE signal and the position of dominant TSS in the two compared groups of CAGE samples, along with the value of the shifting score, P-value and FDR. Scores and P-values/FDR have to be calculated beforehand by calling scoreShift function.

Usage

getShiftingPromoters(
  object,
  groupX,
  groupY,
  tpmThreshold = 0,
  scoreThreshold = -Inf,
  fdrThreshold = 1
)

## S4 method for signature 'CAGEexp'
getShiftingPromoters(
  object,
  groupX,
  groupY,
  tpmThreshold = 0,
  scoreThreshold = -Inf,
  fdrThreshold = 1
)

Arguments

Value

Returns a data.frame of shifting promoters with genomic coordinates and positions of dominant TSS and CAGE signal in the two compared (groups of) samples, along with shifting score and adjusted P-value (FDR).

Author(s)

Vanja Haberle

Sarvesh Nikumbh

See Also

Other CAGEr promoter shift functions: scoreShift()

Examples

getShiftingPromoters( exampleCAGEexp
                    , groupX = "Zf.unfertilized.egg"
                    , groupY = "Zf.30p.dome") |> head()

Description

Rarefy data at multiple sample sizes using the vegan package and return a ‘hanabi’ object that can be passed to plot functions.

The computation can be long, so the steps of rarefaction and plotting are kept separate.

Usage

hanabi(
  x,
  n = 20,
  step = 0.75,
  from = NULL,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'Rle'
hanabi(
  x,
  n = 20,
  step = 0.75,
  from = NULL,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'numeric'
hanabi(
  x,
  n = 20,
  step = 0.75,
  from = NULL,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'integer'
hanabi(
  x,
  n = 20,
  step = 0.75,
  from = NULL,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'GRanges'
hanabi(
  x,
  n = 20,
  step = 0.75,
  from = NULL,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'List'
hanabi(
  x,
  n = 20,
  step = 0.75,
  from = NULL,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'list'
hanabi(
  x,
  n = 20,
  step = 0.75,
  from = NULL,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'matrix'
hanabi(
  x,
  n = 20,
  step = 0.75,
  from = NULL,
  useMulticore = FALSE,
  nrCores = NULL
)

Arguments

Details

This function does not take directly CAGEr objects as input, because hanabi plots can be made from CTSS, clustered or gene-level data, therefore it is not possible to guess which one to use.

Value

A list-based object of class "hanabi".

Author(s)

Charles Plessy

See Also

vegan::rarecurve.

Other CAGEr richness functions: hanabiPlot(), plot.hanabi()

Examples

h <- hanabi(CTSStagCountDF(exampleCAGEexp))
h
plot(h)
hanabi(CTSStagCountGR(exampleCAGEexp, 2))

Description

TBD

Details

TBD

Description

Plot feature discovery curves

Usage

hanabiPlot(x, group, col = NULL, legend.pos = "topleft", pch = 1, ...)

Arguments

Details

Plots the number of features (genes, transcripts, ...) detected for a given number of counts (reads, unique molecules, ...). Each library is sub-sampled by rarefaction at various sample sizes, picked to provide enough points so that the curves look smooth. The final point is plotted as an open circle, hence the name "hanabi", which means fireworks in Japanese.

The rarefactions take time to do, so this step is done by a separate function, so that the result is easily cached.

Author(s)

Charles Plessy

See Also

Other CAGEr richness functions: hanabi, plot.hanabi()

Other CAGEr richness functions: hanabi, plot.hanabi()

Other CAGEr plot functions: TSSlogo(), plotAnnot(), plotCorrelation(), plotExpressionProfiles(), plotInterquantileWidth(), plotReverseCumulatives()

Examples

h <- hanabi(CTSStagCountDF(exampleCAGEexp))
hanabiPlot(h, group = 1:5)
hanabiPlot(hanabi(CTSStagCountDF(exampleCAGEexp), n = 20, step = 0.8, from = 25000), group = 1:5)
hanabiPlot(hanabi(CTSStagCountDF(exampleCAGEexp), n = 10, step = 0.98), group = 1:5)
hanabiPlot(h, group=c("A", "A", "B", "C", "B"), col=c("red", "green", "blue"))
hanabiPlot(h, group = 1:5, pch=1:5, col="purple")

Description

Imports CTSS data from a BAM file.

Usage

import.bam(
  filepath,
  filetype,
  sequencingQualityThreshold = 10,
  mappingQualityThreshold = 20
)

Arguments

See Also

Other loadFileIntoGPos: bam2CTSS(), import.CTSS(), import.bam.ctss(), import.bedCTSS(), import.bedScore(), import.bedmolecule(), loadFileIntoGPos(), moleculesGR2CTSS()

Examples

# TODO: add exmaple file
# import.bam(system.file("extdata", "example.bam", package = "CAGEr"))

Description

Imports CTSS data from a BAM file.

Usage

import.bam.ctss(
  filepath,
  filetype,
  sequencingQualityThreshold,
  mappingQualityThreshold,
  removeFirstG,
  correctSystematicG,
  genome
)

Arguments

Value

Returns a CTSS object.

See Also

Other loadFileIntoGPos: bam2CTSS(), import.CTSS(), import.bam(), import.bedCTSS(), import.bedScore(), import.bedmolecule(), loadFileIntoGPos(), moleculesGR2CTSS()

Description

Imports a BED file where each line represents a single base, with a score counting the number of CAGE transcription start sites (CTSS).

Usage

import.bedCTSS(filepath)

Arguments

Value

A GRanges object where each line represents one nucleotide.

See Also

Other loadFileIntoGPos: bam2CTSS(), import.CTSS(), import.bam(), import.bam.ctss(), import.bedScore(), import.bedmolecule(), loadFileIntoGPos(), moleculesGR2CTSS()

Examples

# TODO: add exmaple file
# import.BED(system.file("extdata", "example.bed", package = "CAGEr"))

Description

Imports a BED file where each line counts for one molecule in a GRanges object where each line represents one nucleotide.

Usage

import.bedmolecule(filepath)

Arguments

Value

Returns a CTSS object.

See Also

Other loadFileIntoGPos: bam2CTSS(), import.CTSS(), import.bam(), import.bam.ctss(), import.bedCTSS(), import.bedScore(), loadFileIntoGPos(), moleculesGR2CTSS()

Examples

# TODO: add exmaple file
# import.BED(system.file("extdata", "example.bed", package = "CAGEr"))

Description

Imports a BED file where the score indicates a number of counts for a given alignment.

Usage

import.bedScore(filepath)

Arguments

Value

A GRanges object where each line represents one nucleotide.

See Also

Other loadFileIntoGPos: bam2CTSS(), import.CTSS(), import.bam(), import.bam.ctss(), import.bedCTSS(), import.bedmolecule(), loadFileIntoGPos(), moleculesGR2CTSS()

Examples

# TODO: add exmaple file
# import.bedScore(system.file("extdata", "example.bed", package = "CAGEr"))

Description

Imports a CAGEscan “molecule” file in a GRanges object

Usage

import.CAGEscanMolecule(filepath)

Arguments

See Also

parseCAGEscanBlocksToGrangeTSS

Examples

# TODO import.CAGEscanMolecule(system.file("extdata", "example.molecule.txt", package = "CAGEr"))

Description

Imports a "CTSS" file in a GPos object

Usage

import.CTSS(filepath)

Arguments

See Also

Other loadFileIntoGPos: bam2CTSS(), import.bam(), import.bam.ctss(), import.bedCTSS(), import.bedScore(), import.bedmolecule(), loadFileIntoGPos(), moleculesGR2CTSS()

Examples

CAGEr:::import.CTSS(system.file("extdata", "Zf.high.chr17.ctss", package = "CAGEr"))

Description

Imports CAGE data from different sources into a CAGEexp object. After the object has been created the data can be further manipulated and visualized using other functions available in the CAGEr package and integrated with other analyses in R. Available resources include:

Usage

importPublicData(
  origin = c("FANTOM5", "FANTOM3and4", "ENCODE", "ZebrafishDevelopment"),
  dataset,
  group,
  sample
)

## S4 method for signature 'character,character,ANY,character'
importPublicData(
  origin = c("FANTOM5", "FANTOM3and4", "ENCODE", "ZebrafishDevelopment"),
  dataset,
  group,
  sample
)

Arguments

Details

• FANTOM5 datasets (Forrest et al., Nature 2014) for numerous human and mouse samples (primary cells, cell lines and tissues), which are fetched directly from FANTOM5 online resource at https://fantom.gsc.riken.jp/5/data.

• FANTOM3 and 4 datasets (Carninci _et al., _ Science 2005, Faulkner et al., Nature Genetics 2009, Suzuki et al. Nature Genetics 2009) from FANTOM3and4CAGE data package available from Bioconductor.

• ENCODE datasets (Djebali et al. Nature 2012) for numerous human cell lines from ENCODEprojectCAGE data package, which is available for download from http://promshift.genereg.net/CAGEr/.

• Zebrafish (Danio rerio) developmental timecourse datasets (Nepal et al. Genome Research 2013) from ZebrafishDevelopmentalCAGE data package, which is available for download from http://promshift.genereg.net/CAGEr/.

Value

A CAGEexp object is returned, containing information on library size, CTSS coordinates and tag count matrix. The object is ready for CAGEr analysis (normalisation, tag clustering, …).

Author(s)

Vanja Haberle

Charles Plessy

References

• Carninci et al., (2005). The Transcriptional Landscape of the Mammalian Genome. Science 309(5740):1559-1563.

• Djebali et al., (2012). Landscape of transcription in human cells. Nature 488(7414):101-108.

• Faulkner et al., (2009). The regulated retrotransposon transcriptome of mammalian cells., Nature Genetics 41:563-571.

• Forrest et al., (2014). A promoter-level mammalian expression atlas. Nature 507(7493):462-470.

• Nepal et al., (2013). Dynamic regulation of the transcription initiation landscape at single nucleotide resolution during vertebrate embryogenesis. Genome Research 23(11):1938-1950.

• Suzuki_et al.,_ (2009). The transcriptional network that controls growth arrest and differentiation in a human myeloid leukemia cell line_. Nature Genetics 41:553-562.

See Also

Other FANTOM data: FANTOM5humanSamples, FANTOM5mouseSamples

Examples

## Not run: 
### importing FANTOM5 data

# list of FANTOM5 human tissue samples

data(FANTOM5humanSamples)
head(subset(FANTOM5humanSamples, type == "tissue"))

# import selected samples
f5 <- importPublicData(
  origin="FANTOM5", dataset = "human",
  sample = c("adipose_tissue__adult__pool1", "adrenal_gland__adult__pool1",
             "aorta__adult__pool1"))

CTSScoordinatesGR(f5)

### importing FANTOM3/4 data from a data package

library(FANTOM3and4CAGE)

# list of mouse datasets available in this package

data(FANTOMmouseSamples)
unique(FANTOMmouseSamples$dataset)
head(subset(FANTOMmouseSamples, dataset == "FANTOMtissueCAGEmouse"))
head(subset(FANTOMmouseSamples, dataset == "FANTOMtimecourseCAGEmouse"))

# import selected samples from two different mouse datasets

f34 <- importPublicData(
  origin="FANTOM3and4", dataset = c("FANTOMtissueCAGEmouse", "FANTOMtimecourseCAGEmouse"),
  group = c("brain", "adipogenic_induction"),
  sample = c("CCL-131_Neuro-2a_treatment_for_6hr_with_MPP+", "DFAT-D1_preadipocytes_2days"))

f34 <- importPublicData(
  origin="FANTOM3and4", dataset = c("FANTOMtissueCAGEmouse"),
  group = c("brain"),
  sample = c("CCL-131_Neuro-2a_treatment_for_6hr_with_MPP+"))

CTSScoordinatesGR(f34)


## End(Not run)

Description

Extracts the paths to CAGE data input files from CAGEexp objects.

Usage

inputFiles(object)

## S4 method for signature 'CAGEexp'
inputFiles(object)

inputFiles(object) <- value

## S4 replacement method for signature 'CAGEexp'
inputFiles(object) <- value

Arguments

Value

Returns a character vector of paths to CAGE data input files.

Author(s)

Vanja Haberle

Charles Plessy

See Also

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), expressionClasses(), genomeName(), inputFilesType(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Other CAGEr setter methods: genomeName(), inputFilesType(), sampleLabels(), setColors()

Examples

inputFiles(exampleCAGEexp)

Description

Get or set the information on the type of CAGE data input files from CAGEexp objects.

Usage

inputFilesType(object)

## S4 method for signature 'CAGEexp'
inputFilesType(object)

inputFilesType(object) <- value

## S4 replacement method for signature 'CAGEexp'
inputFilesType(object) <- value

Arguments

Details

The following input file types are supported:

• bam: A single-ended BAM file.

• bamPairedEnd: A paired-ended BAM file.

• bed: A BED file where each line counts for one molecule.

• bedScore: A BED file where the score indicates a number of counts for a given alignment.

• CAGEscanMolecule: Experimental. For the CAGEscan 3.0 pipeline.

• ctss: A tabulation-delimited file describing CAGE Transcription Start Sites (CTSS) with four columns indicating chromosome, 1-based coordinate, strand and score respectively.

• CTSStable

• FANTOM5

• ENCODE

• FANTOM3and4

• ZebrafishDevelopment

Value

Returns the type of the file format of CAGE data input files, e.g. "bam" or "ctss". In the case of CAGEexp objects, the return value is character vector with one member per sample.

Author(s)

Vanja Haberle

Charles Plessy

See Also

getCTSS

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), expressionClasses(), genomeName(), inputFiles(), librarySizes(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Other CAGEr setter methods: genomeName(), inputFiles(), sampleLabels(), setColors()

Examples

inputFilesType(exampleCAGEexp)

Description

Extracts the library sizes (total number of CAGE tags) for all CAGE datasets from CAGEexp objects.

Usage

librarySizes(object)

## S4 method for signature 'CAGEexp'
librarySizes(object)

Arguments

Details

Library sizes are calculated when loading data with the getCTSS function and stored in the librarySizes column of the colData of CAGEexp objects.

Value

Returns an integer vector of total number of CAGE tags (library size) for all CAGE datasets in the CAGEr object.

Author(s)

Vanja Haberle

See Also

getCTSS

Other CAGEr accessor methods: CTSScoordinatesGR(), CTSScumulativesTagClusters(), CTSSnormalizedTpmDF(), CTSStagCountDF(), GeneExpDESeq2(), GeneExpSE(), consensusClustersGR(), expressionClasses(), genomeName(), inputFiles(), inputFilesType(), sampleLabels(), seqNameTotalsSE(), tagClustersGR()

Examples

librarySizes(exampleCAGEexp)

Description

A private (non-exported) function to load from each file format supported by CAGEr

Usage

loadFileIntoGPos(
  filepath,
  filetype = c("bam", "bamPairedEnd", "bed", "bedctss", "bedScore", "CAGEscanMolecule",
    "ctss"),
  sequencingQualityThreshold,
  mappingQualityThreshold,
  removeFirstG,
  correctSystematicG,
  genome
)

Arguments

Value

A GPos() object where the score represents the number of CAGE tags starting on that nucleotide.

See Also

import.CTSS

Other loadFileIntoGPos: bam2CTSS(), import.CTSS(), import.bam(), import.bam.ctss(), import.bedCTSS(), import.bedScore(), import.bedmolecule(), moleculesGR2CTSS()

Description

Using a data frame containing mapping statistics in counts, transform the data in percentages that can be used for stacked barplots.

Usage

mapStats(libs, scope, group = "sampleLabels", facet = NULL, normalise = TRUE)

Arguments

Details

See the plotAnnot vignette and the mapStatsScopes() help page for details on what the scopes are.

See http://stackoverflow.com/questions/10417003/stacked-barplot-with-errorbars-using-ggplot2 about stacked barplot.

Value

Returns a data frame with mean and standard deviation of normalised mapping statistics, plus absolute positions for the error bars. The first column, group, is a vector of factors sorted with the gtools::mixedorder() function. The facet column, if any, is always called facet.

Author(s)

Charles Plessy

See Also

plotAnnot, mapStatsScopes

Examples

CAGEr:::mapStats(as.data.frame(colData(exampleCAGEexp)), "counts", sampleLabels(exampleCAGEexp))
CAGEr:::mapStats(as.data.frame(colData(exampleCAGEexp)), "counts", c("A", "A", "B", "B", "C"))

Description

Functions implementing the scope parameter of the ⁠\link{mapStats}⁠ function.

Usage

msScope_counts(libs)

msScope_mapped(libs)

msScope_qc(libs)

msScope_steps(libs)

msScope_all(libs)

msScope_annotation(libs)

Arguments

Details

The counts scope reports the number of molecules aligning in promoter, exon, intron and otherwise intergenic. regions.

The mapped scope reports the number of molecules aligning in promoter, exon, intron and otherwise intergenic, plus the number of PCR duplicates (mapped tags minus molecule counts), plus the number of non-properly paired mapped tags.

The qc scope reports the number of tags removed as tag dust, rRNA, spikes, plus the unmapped tags, plus the number of non-properly paired mapped tags, plus the number of PCR duplicates (mapped tags minus molecule counts), plus the number of unique molecule counts.

The steps scope reports the number of tags removed by cleaning, mapping, and deduplication, plus the number of unique molecule counts.

The legacy all scope reports the number of tags in promoters, exons, introns, or mapped elswhere, or removed because they match rRNA or are likely primer artefacts, normalised by the total nubmer of extracted tags.

The legacy annotation scope reports the number of tags in promoters, exons, introns, or mapped elswhere, or removed because they match rRNA or are likely primer artefacts, normalised by the total nubmer of mapped tags.

Value

Returns a list with three elements: libs contains a modified version of the input data frame where columns have been reorganised as needed, colums contains the names of the columns to use for plotting and provides the order of the stacked bars of the plotAnnot function, total indicates the total counts used for normalising the data.

Description

Merges two CAGEr objects into one by combining the CTSS genomic coordinates and raw tag counts. The resulting object will contain a union of TSS positions present in the two input objects and raw tag counts for those TSSs in all samples from both input objects.

Usage

mergeCAGEsets(cs1, cs2)

## S4 method for signature 'CAGEexp,CAGEexp'
mergeCAGEsets(cs1, cs2)

Arguments

Value

Note that merging discards all other information present in the two CAGEr objects, that is, the merged object will not contain any normalised tag counts, CTSS clusters, quantile positions, etc., so these have to be calculated again by calling the appropriate functions on the merged object. Also, it is only possible to merge two objects that contain TSS information for the same reference genome and do not share any sample names.

Returns a CAGEexp object, which contains a union of TSS positions present in the two input objects and raw tag counts for those TSSs in all samples from both input objects.

Author(s)

Vanja Haberle

Charles Plessy

See Also

CAGEexp

Examples

library(BSgenome.Drerio.UCSC.danRer7)

pathsToInputFiles <- system.file("extdata", c("Zf.unfertilized.egg.chr17.ctss",
  "Zf.30p.dome.chr17.ctss", "Zf.prim6.rep1.chr17.ctss"), package="CAGEr")
  
ce1 <- CAGEexp(genomeName = "BSgenome.Drerio.UCSC.danRer7",
inputFiles = pathsToInputFiles[1:2], inputFilesType = "ctss", sampleLabels =
c("sample1", "sample2"))
ce1 <- getCTSS(ce1)

ce2 <- CAGEexp(genomeName = "BSgenome.Drerio.UCSC.danRer7",
inputFiles = pathsToInputFiles[3], inputFilesType = "ctss", sampleLabels =
"sample3")

ce2 <- getCTSS(ce2)

ce <- mergeCAGEsets(ce1, ce2)

Description

Merges individual CAGE samples (datasets, experiments) within the CAGEr object into specified groups.

Usage

mergeSamples(object, mergeIndex, mergedSampleLabels)

## S4 method for signature 'CAGEexp'
mergeSamples(object, mergeIndex, mergedSampleLabels)

Arguments

Details

The samples within the CAGEr object are merged by adding the raw tag counts of individual CTSS that belong tho the same group. After merging, all other slots in the CAGEr object will be reset and any previous data for individual experiments will be removed.

mergeIndex controls which samples will be merged. It is an integer vector that assigns a group identifier to each sample, in the same order as they are returned by sampleLabels(object). For example, if there are 8 CAGE samples in the CAGEr object and mergeIndex = c(1,1,2,2,3,2,4,4), this will merge a) samples 1 and 2, b) samples 3, 4 and 6, c) samples 7 and 8, and d) it will leave sample 5 as it is, resulting in 4 final merged datasets.

Labels provided in mergedSampleLabels will be assigned to merged datasets in the ascending order of mergeIndex values, i.e. first label will be assigned to a dataset created by merging datasets labeled with lowest mergeIndex value (in this case 1), etc.

Value

The slots sampleLabels, librarySizes and tagCountMatrix of the provided CAGEr object will be updated with the information on merged CAGE datasets and will replace the previous information on individual CAGE datasets. All further slots with downstream information will be reset.

Author(s)

Vanja Haberle

Charles Plessy

Examples

mergeSamples( exampleCAGEexp
            , mergeIndex = c(3,2,4,4,1)
            , mergedSampleLabels = c("zf_unfertilized", "zf_high", "zf_30p_dome", "zf_prim6"))
exampleCAGEexp

Description

Calculates CTSS positions from a GenomicRanges object where each element represents a single molecule.

Usage

moleculesGR2CTSS(gr)

Arguments

Value

Returns a GRanges object.

See Also

Other loadFileIntoGPos: bam2CTSS(), import.CTSS(), import.bam(), import.bam.ctss(), import.bedCTSS(), import.bedScore(), import.bedmolecule(), loadFileIntoGPos()

Examples

gr <- GenomicRanges::GRanges("chr1", IRanges::IRanges(1, 10), c("+", "-", "+"))
CAGEr:::moleculesGR2CTSS(gr)

Description

Normalizes raw CAGE tag count per CTSS in all experiments to a same referent distribution. A simple tag per million normalization or normalization to a referent power-law distribution (Balwierz et al., Genome Biology 2009) can be specified.

Usage

normalizeTagCount(
  object,
  method = c("powerLaw", "simpleTpm", "none"),
  fitInRange = c(10, 1000),
  alpha = 1.25,
  T = 10^6
)

## S4 method for signature 'CAGEexp'
normalizeTagCount(
  object,
  method = c("powerLaw", "simpleTpm", "none"),
  fitInRange = c(10, 1000),
  alpha = 1.25,
  T = 10^6
)

Arguments

Details

It has been shown that many CAGE datasets follow a power-law distribution (Balwierz et al., Genome Biology 2009). Plotting the number of CAGE tags (X-axis) against the number of TSSs that are supported by >= of that number of tags (Y-axis) results in a distribution that can be approximated by a power-law. On a log-log scale this theoretical referent distribution can be described by a monotonically decreasing linear function y = -1 * alpha * x + beta, which is fully determined by the slope alpha and total number of tags T (which together with alpha determines the value of beta). Thus, by specifying parameters alpha and T a desired referent power-law distribution can be selected. However, real CAGE datasets deviate from the power-law in the areas of very low and very high number of tags, so it is advisable to discard these areas before fitting a power-law distribution. fitInRange parameter allows to specify a range of values (lower and upper limit of the number of CAGE tags) that will be used to fit a power-law. Plotting reverse cumulatives using plotReverseCumulatives function can help in choosing the best range of values. After fitting a power-law distribution to each CAGE dataset individually, all datasets are normalized to a referent distribution specified by alpha and T. When T = 10^6, normalized values are expressed as tags per million (tpm).

Value

The slot normalizedTpmMatrix of the provided CAGEexp object will be occupied by normalized CAGE signal values per CTSS across all experiments, or with the raw tag counts (in case method = "none").

Author(s)

Vanja Haberle

References

Balwierz et al. (2009) Methods for analyzing deep sequencing expression data: constructing the human and mouse promoterome with deepCAGE data, Genome Biology 10(7):R79.

See Also

plotReverseCumulatives, CTSSnormalizedTpmDF

Other CAGEr object modifiers: CTSStoGenes(), CustomConsensusClusters(), aggregateTagClusters(), annotateCTSS(), cumulativeCTSSdistribution(), distclu(), getCTSS(), paraclu(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Other CAGEr normalised data functions: plotReverseCumulatives()

Examples

ce1 <- normalizeTagCount(exampleCAGEexp, method = "simpleTpm")
ce2 <- normalizeTagCount(exampleCAGEexp, method = "powerLaw")

Description

"paraclu" is an implementation of Paraclu algorithm for parametric clustering of data attached to sequences (Frith et al., Genome Research, 2007). Since Paraclu finds clusters within clusters (unlike distclu), additional parameters (minStability, maxLength and reduceToNonoverlapping) can be specified to simplify the output by discarding too big clusters, and to reduce the clusters to a final set of non-overlapping clusters.

Usage

paraclu(
  object,
  minStability = 1,
  maxLength = 500,
  keepSingletonsAbove = 0,
  reduceToNonoverlapping = TRUE,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'Pairs'
paraclu(
  object,
  minStability = 1,
  maxLength = 500,
  keepSingletonsAbove = 0,
  reduceToNonoverlapping = TRUE,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'CTSS'
paraclu(
  object,
  minStability = 1,
  maxLength = 500,
  keepSingletonsAbove = 0,
  reduceToNonoverlapping = TRUE,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'GRanges'
paraclu(
  object,
  minStability = 1,
  maxLength = 500,
  keepSingletonsAbove = 0,
  reduceToNonoverlapping = TRUE,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'SummarizedExperiment'
paraclu(
  object,
  minStability = 1,
  maxLength = 500,
  keepSingletonsAbove = 0,
  reduceToNonoverlapping = TRUE,
  useMulticore = FALSE,
  nrCores = NULL
)

## S4 method for signature 'CAGEexp'
paraclu(
  object,
  minStability = 1,
  maxLength = 500,
  keepSingletonsAbove = 0,
  reduceToNonoverlapping = TRUE,
  useMulticore = FALSE,
  nrCores = NULL
)

Arguments

Details

Clustering is done for every CAGE dataset within the CAGEr object separately, resulting in a different set of tag clusters for every CAGE dataset. TCs from different datasets can further be aggregated into a single referent set of consensus clusters by calling the aggregateTagClusters function.

Value

Running Paraclu on a Pairs object containing positions and scores returns an IRanges object containing the start and end positions of the clusters, as well as the minimum and maximum density in min_d and max_d metadata columns.

Running Paraclu on a CTSS object dispatches the computation on each strand of each sequence level of the object, collects the IRanges and assemble them back in a TagClusters object after filtering them by size and by expression following the minStability, maxLength, keepSingletonsAbove and reduceToNonoverlapping parameters.

Running Paraclu on a RangedSummarizedExperiment object will loop on each sample, and return the results as a GRangesList of TagClusters.

Running Paraclu on a CAGEexp returnts is with the clusters stored as a GRangesList of TagClusters objects in its metadata slot tagClusters.

Author(s)

Vanja Haberle

Charles Plessy

References

MC Frith, E Valen, A Krogh, Y Hayashizaki, P Carninci, A Sandelin. A code for transcription initiation in mammalian genomes. Genome Research 2008 18(1):1-12)

See Also

aggregateTagClusters

Other CAGEr clustering methods: consensusClustersTpm(), distclu()

Other CAGEr object modifiers: CTSStoGenes(), CustomConsensusClusters(), aggregateTagClusters(), annotateCTSS(), cumulativeCTSSdistribution(), distclu(), getCTSS(), normalizeTagCount(), quantilePositions(), quickEnhancers(), resetCAGEexp(), summariseChrExpr()

Other CAGEr clusters functions: CTSScumulativesTagClusters(), CustomConsensusClusters(), aggregateTagClusters(), consensusClustersDESeq2(), consensusClustersGR(), cumulativeCTSSdistribution(), distclu(), plotInterquantileWidth(), quantilePositions(), tagClustersGR()

Examples

(ctss <- CTSSnormalizedTpmGR(exampleCAGEexp,1))
(pair <- Pairs(pos(ctss), score(ctss)))
CAGEr:::.paraclu_params(first(pair), second(pair))
CAGEr:::.paraclu(first(pair)[1:10], second(pair)[1:10])
paraclu(pair[1:10])
paraclu(ctss[1:10])
paraclu(CTSStagCountSE(exampleCAGEexp)[1:25,])
ce <- paraclu( exampleCAGEexp,
             , keepSingletonsAbove = 100
             , maxLength = 500, minStability = 1
             , reduceToNonoverlapping = TRUE)
tagClustersGR(ce, "Zf.30p.dome")

Description

Parse a string describing a block in a CAGEscan molecule, as output by the "CAGEscan 3.0" pipeline.

Usage

parseCAGEscanBlocksToGrangeTSS(blocks)

Arguments

Value

A GRanges object representing a TSS.

In CAGEscan molecules, blocks are separated by ‘|’, ‘,’ or ‘;’ for gap of coverage, splice junction (confident) and splice junction (maybe) respectively. Strand is "+" if first coordinate is lower than the second one, and "-" otherwise.

See Also

import.CAGEscanMolecule

Examples

myMolecule <- paste0( "chr11:66268633-66268693,"
                    , "chr11:66271796-66271869;"
                    , "chr11:66272156-66272252|"
                    , "chr11:66272364-66272460")
myFirstBlock <- sub("[,;|].*", "", myMolecule)

CAGEr:::parseCAGEscanBlocksToGrangeTSS(myFirstBlock)

Description

S3 method to plot hanabi objects. Used by the hanabiPlot function.

Usage

## S3 method for class 'hanabi'
plot(
  x,
  alpha = 0.5,
  col = "black",
  xlab = "Total counts",
  ylab = "Unique features",
  main = "Hanabi plot",
  pch = 1,
  ...
)

## S3 method for class 'hanabi'
points(x, ...)

## S3 method for class 'hanabi'
lines(x, ...)

Arguments

Author(s)

Charles Plessy

See Also

Other CAGEr richness functions: hanabi, hanabiPlot()

Description

Extracts processing and alignment statistics from a CAGEr object and plots them as counts or percentages in stacked barplots.

Usage

plotAnnot(
  x,
  scope,
  title,
  group = "sampleLabels",
  facet = NULL,
  normalise = TRUE
)

## S4 method for signature 'data.frame'
plotAnnot(
  x,
  scope,
  title,
  group = "sampleLabels",
  facet = NULL,
  normalise = TRUE
)

## S4 method for signature 'DataFrame'
plotAnnot(
  x,
  scope,
  title,
  group = "sampleLabels",
  facet = NULL,
  normalise = TRUE
)

## S4 method for signature 'CAGEexp'
plotAnnot(
  x,
  scope,
  title,
  group = "sampleLabels",
  facet = NULL,
  normalise = TRUE
)

## S4 method for signature 'GRangesList'
plotAnnot(
  x,
  scope,
  title,
  group = "sampleLabels",
  facet = NULL,
  normalise = TRUE
)

Arguments

Details

When given a CAGEexp object or its column data, what will be counted is the number of CAGE tags. When given cluster objects (CTSS, TagClusters or ConsensusClusters) wrapped as a GenomicRanges::GRangesList, what will be counted is the number of clusters.

Stacked barplots with error bars inspired from http://stackoverflow.com/questions/10417003/stacked-barplot-with-errorbars-using-ggplot2. See http://www.biomedcentral.com/1471-2164/14/665/figure/F1 for example.

Value

Returns a ggplot2::ggplot object.

Author(s)

Charles Plessy

See Also

mapStats for a list of scopes.

Other CAGEr annotation functions: annotateCTSS(), ranges2annot(), ranges2genes(), ranges2names()

Other CAGEr plot functions: TSSlogo(), hanabiPlot(), plotCorrelation(), plotExpressionProfiles(), plotInterquantileWidth(), plotReverseCumulatives()

Examples

p <- plotAnnot(exampleCAGEexp, 'counts', 'Here is the title')
print(p)
p + ggplot2::theme_bw()
ggplot2::theme_set(ggplot2::theme_bw()) ; p
plotAnnot(exampleCAGEexp, 'counts', 'Same, non-normalised', normalise = FALSE)
exampleCAGEexp$myGroups <- factor(c("A", "A", "B", "B", "C"))
plotAnnot(exampleCAGEexp, 'counts', group = "myGroups")
plotAnnot(exampleCAGEexp, 'counts', group = ~myGroups)
plotAnnot(exampleCAGEexp, 'counts', group = ~sampleLabels + myGroups)
plotAnnot(exampleCAGEexp, CAGEr:::msScope_counts , group = "myGroups")

Description

Calculates the pairwise correlation between samples and creates a plot matrix showing the correlation coeficients in the upper triangle, the sample names in the diagonal, and the catter plots in the lower triangle.

Usage

plotCorrelation(
  object,
  what = c("CTSS", "consensusClusters"),
  values = c("raw", "normalized"),
  samples = "all",
  method = "pearson",
  tagCountThreshold = 1,
  applyThresholdBoth = FALSE,
  plotSize = 800
)

## S4 method for signature 'CAGEr'
plotCorrelation(
  object,
  what = c("CTSS", "consensusClusters"),
  values = c("raw", "normalized"),
  samples = "all",
  method = "pearson",
  tagCountThreshold = 1,
  applyThresholdBoth = FALSE,
  plotSize = 800
)

plotCorrelation2(
  object,
  what = c("CTSS", "consensusClusters"),
  values = c("raw", "normalized"),
  samples = "all",
  method = "pearson",
  tagCountThreshold = 1,
  applyThresholdBoth = FALSE,
  digits = 3
)

## S4 method for signature 'CAGEexp'
plotCorrelation2(
  object,
  what = c("CTSS", "consensusClusters"),
  values = c("raw", "normalized"),
  samples = "all",
  method = "pearson",
  tagCountThreshold = 1,
  applyThresholdBoth = FALSE,
  digits = 3
)

## S4 method for signature 'SummarizedExperiment'
plotCorrelation2(
  object,
  what = c("CTSS", "consensusClusters"),
  values = c("raw", "normalized"),
  samples = "all",
  method = "pearson",
  tagCountThreshold = 1,
  applyThresholdBoth = FALSE,
  digits = 3
)

## S4 method for signature 'DataFrame'
plotCorrelation2(
  object,
  what = c("CTSS", "consensusClusters"),
  values = c("raw", "normalized"),
  samples = "all",
  method = "pearson",
  tagCountThreshold = 1,
  applyThresholdBoth = FALSE,
  digits = 3
)

## S4 method for signature 'data.frame'
plotCorrelation2(
  object,
  what = c("CTSS", "consensusClusters"),
  values = c("raw", "normalized"),
  samples = "all",
  method = "pearson",
  tagCountThreshold = 1,
  applyThresholdBoth = FALSE,
  digits = 3
)

## S4 method for signature 'matrix'
plotCorrelation2(
  object,
  what = c("CTSS", "consensusClusters"),
  values = c("raw", "normalized"),
  samples = "all",
  method = "pearson",
  tagCountThreshold = 1,
  applyThresholdBoth = FALSE,
  digits = 3
)