aggregateTagClusters {CAGEr} | R Documentation

## Aggregate TCs across all samples

### 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 cluster 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 `qLow = NULL` or `qUp = NULL`, the start (or end) 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. `useMulticore = TRUE` is supported only on Unix-like platforms.
`nrCores` | Number of cores to use when `useMulticore = TRUE`. Default value `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 `qLow = NULL` and `qUp = 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)

[Package CAGEr version 1.22.3 Index]