aggregateTagClusters: Aggregate TCs across all samples

In CAGEr: Analysis of CAGE (Cap Analysis of Gene Expression) sequencing data for precise mapping of transcription start sites and promoterome mining

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

object	A CAGEr object
tpmThreshold	Ignore tag clusters with normalized signal < tpmThreshold when constructing the consensus clusters.
excludeSignalBelowThreshold	When TRUE the tag clusters with normalized signal < tpmThreshold will not contribute to the total CAGE signal of a consensus cluster. When set to FALSE all TCs that overlap consensus clusters will contribute to the total signal, regardless whether they pass the threshold for constructing the clusters or not.
qLow, qUp	Set which "lower" (or "upper") quantile should be used as 5' (or 3') boundary of the tag cluster. If NULL the start (for qLow) or end (for qUp) position of the TC is used.
maxDist	Maximal length of the gap (in base-pairs) between two tag clusters for them to be part of the same consensus clusters.
useMulticore	Logical, should multicore be used (supported only on Unix-like platforms).
nrCores	Number of cores to use when useMulticore = TRUE. Default (NULL) uses all detected cores.

Details

Since the tag clusters (TCs) returned by the clusterCTSS 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

For CAGEset objects, the consensusClusters slot will be populated with a data frame indicating the cluster name, chromosome, start and end coordinates, the strand, and the normalised expression score of the cluster. This table is returned by the consensusClusters function.

For CAGEexp objects, the experiment consensusClusters will be occupied by a RangedSummarizedExperiment containing the cluster coodinates as row ranges, and their expression levels in the counts and normalized assays. These genomic ranges are returned by the consensusClustersGR 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. This table is returned by the consensusClusters function.

Author(s)

Vanja Haberle

Charles Plessy

See Also

Other CAGEr object modifiers: CTSStoGenes, CustomConsensusClusters, annotateCTSS, clusterCTSS, cumulativeCTSSdistribution, getCTSS, normalizeTagCount, quantilePositions, summariseChrExpr

Other CAGEr clusters functions: CTSSclusteringMethod, CTSScumulativesTagClusters, CustomConsensusClusters, clusterCTSS, consensusClustersDESeq2, consensusClustersGR, cumulativeCTSSdistribution, plotInterquantileWidth, quantilePositions, tagClusters

Examples

head(consensusClusters(exampleCAGEset))
aggregateTagClusters( exampleCAGEset, tpmThreshold = 50
                    , excludeSignalBelowThreshold = FALSE, maxDist = 100)
head(consensusClusters(exampleCAGEset))

aggregateTagClusters(object = exampleCAGEset, tpmThreshold = 50,
  excludeSignalBelowThreshold = FALSE, qLow = 0.1, qUp = 0.9, maxDist = 100)
head(consensusClusters(exampleCAGEset))

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

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

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

CAGEr documentation built on Jan. 17, 2021, 2 a.m.