Package 'ChIPseeker'

Description

ChIPseeker is an R/Bioconductor package designed for comprehensive analysis of ChIP-seq (Chromatin Immunoprecipitation followed by sequencing) data. The package provides a complete toolkit for annotating ChIP peaks, comparing datasets, and visualizing results to facilitate biological interpretation.

Details

ChIPseeker offers four main categories of functionality:

1. Peak Annotation:

• annotatePeak: Comprehensive peak annotation including nearest genes, genomic features (promoter, exon, intron, UTR, etc.), distance to TSS, and optional gene annotation from databases

• seq2gene: Many-to-many mapping of genomic regions to genes for functional enrichment analysis, considering host genes, promoter regions, and flanking genes

• readPeakFile: Read peak files in various formats (BED, narrowPeak, broadPeak, etc.)

2. Visualization:

• plotAnnoBar, plotAnnoPie: Visualize genomic annotation distribution

• plotDistToTSS: Distribution of peaks relative to transcription start sites

• covplot: Coverage plot showing peak distribution across chromosomes

• plotAvgProf, plotPeakProf: Average profiles and peak profiles around TSS or gene body

• tagHeatmap, peakHeatmap: Heatmaps of peak binding patterns

• vennplot, upsetplot: Visualize overlap among multiple peak sets

3. Peak Comparison and Overlap Analysis:

• enrichAnnoOverlap: Test significance of gene overlap between ChIP experiments based on nearest gene annotation

• enrichPeakOverlap: Test significance of genomic coordinate overlap using permutation testing

• vennplot, vennpie: Visualize overlaps among peak sets

• shuffle: Shuffle peak positions for permutation testing

4. GEO Database Integration:

• downloadGEObedFiles, downloadGSMbedFiles: Download ChIP-seq data from GEO database

• getGEOInfo, getGEOspecies, getGEOgenomeVersion: Query GEO database metadata

• Access to over 17,000 ChIP-seq datasets from GEO for comparison

Additional Features:

• getTagMatrix: Build tag matrices for profile plotting

• getPromoters: Extract promoter regions

• getBioRegion: Define custom genomic regions

• dplyr verb extensions for GRanges objects: filter, mutate, rename, arrange

• Support for liftOver conversion between genome assemblies

Main Workflow

The typical ChIPseeker workflow:

1. Read peak files using readPeakFile

2. Annotate peaks using annotatePeak to get nearest genes, genomic features, and distances

3. Visualize results using plotAnnoBar, plotDistToTSS, etc.

4. (Optional) Compare with other datasets using enrichPeakOverlap or download from GEO

5. (Optional) Map regions to genes using seq2gene for functional enrichment analysis

Key Classes

• csAnno-class: Container class for annotated peaks with metadata and statistics

Citation

If you use ChIPseeker in published research, please cite:

• Q Wang, M Li, T Wu, L Zhan, L Li, M Chen, W Xie, Z Xie, E Hu, S Xu, G Yu. Exploring epigenomic datasets by ChIPseeker. Current Protocols, 2022, 2(10): e585.

• G Yu, LG Wang, QY He. ChIPseeker: an R/Bioconductor package for ChIP peak annotation, comparison and visualization. Bioinformatics, 2015, 31(14):2382-2383.

Author(s)

Maintainer: Guangchuang Yu [email protected]

Contributors: Ming Li, Qianwen Wang, Yun Yan, Hervé Pagès, Michael Kluge, Thomas Schwarzl, Zhougeng Xu, Chun-Hui Gao

See Also

Useful links:

• https://yulab-smu.top/contribution-knowledge-mining/

• Report bugs at https://github.com/YuLab-SMU/ChIPseeker/issues

• Bioconductor page: https://bioconductor.org/packages/ChIPseeker

Description

capture name of variable

Usage

.(..., .env = parent.frame())

Arguments

Value

expression

Examples

x <- 1
eval(.(x)[[1]])

Description

The function initializes and maintains a cache for TxDb objects and their associated genomic features. It checks if the cached TxDb matches the provided one, and updates the cache if they differ or if forced to update.

Usage

.ChIPseekerEnv(TxDb, item = "ChIPseekerEnv", force = FALSE)

Arguments

Details

This function manages the caching system for TxDb objects and related genomic features to improve performance by avoiding redundant computations.

The function performs the following:

1. Retrieves or creates a cache item

2. If no TxDb is cached, stores the provided TxDb

3. If a TxDb exists in cache, compares metadata to check if it matches

4. Updates cache if TxDb differs or if force=TRUE

5. Prints the genome version being used

This caching mechanism allows the package to reuse computed features (exons, introns, transcripts, etc.) across multiple function calls when using the same TxDb object.

Value

Invisibly returns NULL. Prints messages about genome version usage

Description

This function annotates ChIP-seq peaks with genomic features including nearest genes, genomic annotation (promoter, exon, intron, etc.), distance to TSS, and optional gene annotation from annotation databases. It can also identify flanking genes within a specified distance from peaks.

Usage

annotatePeak(
  peak,
  tssRegion = c(-3000, 3000),
  TxDb = NULL,
  level = "transcript",
  assignGenomicAnnotation = TRUE,
  genomicAnnotationPriority = c("Promoter", "5UTR", "3UTR", "Exon", "Intron",
    "Downstream", "Intergenic"),
  annoDb = NULL,
  addFlankGeneInfo = FALSE,
  flankDistance = 5000,
  sameStrand = FALSE,
  ignoreOverlap = FALSE,
  ignoreUpstream = FALSE,
  ignoreDownstream = FALSE,
  overlap = "TSS",
  verbose = TRUE,
  columns = c("ENTREZID", "ENSEMBL", "SYMBOL", "GENENAME")
)

Arguments

Details

The function performs comprehensive peak annotation through several steps:

1. **Feature extraction**: Extracts gene or transcript features from the provided TxDb or EnsDb annotation object, or uses user-defined GRanges.

2. **Nearest feature identification**: Finds the nearest gene/transcript to each peak using getNearestFeatureIndicesAndDistances, considering strand specificity and overlap options. The overlap parameter controls whether to consider overlaps with the entire gene body ("all") or only TSS regions ("TSS").

3. **Distance calculation**: Computes the distance from each peak to the transcription start site (TSS) of the nearest feature, with positive values indicating downstream and negative values indicating upstream.

4. **Genomic annotation**: Assigns genomic feature categories (Promoter-TSS, 5' UTR, 3' UTR, Exon, Intron, Downstream, Intergenic) based on the peak's location relative to gene structure. The priority order can be customized via genomicAnnotationPriority.

5. **Gene annotation**: Optionally adds gene identifiers (ENSEMBL, SYMBOL, GENENAME, ENTREZID) from annotation databases using the annoDb parameter.

6. **Flanking gene information**: Optionally identifies all genes within a specified flanking distance from each peak, providing comprehensive information about nearby genes.

The function returns a csAnno object containing the annotated peaks with all metadata columns. When TxDb is provided as a GRanges object, some features (genomic annotation, gene annotation, flanking genes) are disabled, and the function works with user-defined genomic features.

Value

A csAnno object containing the annotated peaks. The main annotation data is stored in the anno slot (a GRanges object) with the following metadata columns:

• All original columns from the input peak file/GRanges object

• annotation: Genomic feature category of the peak. Possible values are Promoter-TSS, 5' UTR, 3' UTR, Exon, Intron, Downstream, and Intergenic. Only present if assignGenomicAnnotation=TRUE

• geneChr: Chromosome of the nearest gene/transcript

• geneStart: Start position of the nearest gene/transcript

• geneEnd: End position of the nearest gene/transcript

• geneLength: Length of the nearest gene/transcript

• geneStrand: Strand of the nearest gene/transcript ("+" or "-")

• geneId: Gene identifier (Entrez ID for TxDb, or gene_id for EnsDb)

• transcriptId: Transcript identifier (only when level="transcript")

• distanceToTSS: Distance from peak to the transcription start site (TSS) of the nearest gene. Positive values indicate downstream, negative values indicate upstream. Distance is 0 for overlapping peaks

• ENSEMBL: Ensembl gene ID (only if annoDb is provided)

• SYMBOL: Gene symbol (only if annoDb is provided)

• GENENAME: Full gene name (only if annoDb is provided)

• ENTREZID: Entrez gene ID (only if annoDb is provided and requested in columns)

• flank_geneIds: Semicolon-separated list of all flanking gene IDs within the specified distance (only if addFlankGeneInfo=TRUE)

• flank_gene_distances: Semicolon-separated list of distances from the peak to each flanking gene. A distance of 0 means that the peak overlaps the feature range; at level="transcript" the feature is the whole transcript, so peaks inside a transcript body get 0 even when their distance to the TSS is not 0. For non-overlapping peaks the signed distance to the feature's TSS is reported (positive = downstream, negative = upstream)

• flank_txIds: Semicolon-separated list of all flanking transcript IDs (only if addFlankGeneInfo=TRUE and level="transcript")

The csAnno object also contains slots for:

• tssRegion: The TSS region used for annotation

• level: The annotation level ("transcript" or "gene")

• hasGenomicAnnotation: Whether genomic annotation was assigned

• detailGenomicAnnotation: Detailed annotation matrix (if available)

• annoStat: Annotation statistics

• peakNum: Total number of peaks

Author(s)

G Yu

See Also

plotAnnoBar plotAnnoPie plotDistToTSS

Examples

## Not run: 
require(TxDb.Hsapiens.UCSC.hg19.knownGene)
txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene
peakfile <- system.file("extdata", "sample_peaks.txt", package="ChIPseeker")
peakAnno <- annotatePeak(peakfile, tssRegion=c(-3000, 3000), TxDb=txdb)
peakAnno

## End(Not run)

Description

The function sorts GRanges objects by converting them to a data.frame, applying the dplyr arrange operation, and converting back to GRanges. This allows sorting by any metadata column or standard GRanges columns (seqnames, start, end, width, strand).

Usage

## S3 method for class 'GRanges'
arrange(.data, ..., .by_group = FALSE)

Arguments

Details

This function extends dplyr::arrange() to work with GRanges objects, allowing users to sort genomic ranges by any column using familiar dplyr syntax while preserving the GRanges structure.

The function performs the following steps:

1. Converts GRanges to data.frame using as.data.frame()

2. Applies dplyr::arrange() with the specified sorting columns

3. Converts back to GRanges using makeGRangesFromDataFrame() with keep.extra.columns=TRUE

All genomic range information and metadata columns are preserved. Sorting is stable (preserves original order for ties). Multiple sorting columns are applied in order (first column is primary sort key).

Value

GRanges object with ranges sorted by the specified columns. All metadata columns are preserved. The sort order is stable (ties preserve original order)

Examples

## Not run: 
## Sort by chromosome and start position (genomic order)
peak.gr <- peak.gr %>% arrange(seqnames, start)

## Sort by distance (descending - closest to TSS first)
peak.gr <- peak.gr %>% arrange(desc(abs(distanceToTSS)))

## Sort by annotation, then by distance
peak.gr <- peak.gr %>% arrange(annotation, distanceToTSS)

## Sort by score (descending), then by chromosome
peak.gr <- peak.gr %>% arrange(desc(score), seqnames)

## Complex sorting with multiple criteria
peak.gr <- peak.gr %>%
  arrange(
    annotation,
    desc(score),
    abs(distanceToTSS)
  )

## End(Not run)

Description

The function converts the anno slot (GRanges object) to a data.frame, preserving all metadata columns. This is useful for exporting data, performing data.frame operations, or using with functions that require data.frame input.

Usage

## S3 method for class 'csAnno'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Details

This function converts a csAnno object to a data.frame by extracting and converting the GRanges object containing annotated peaks.

Value

A data.frame containing all peak information with columns:

• Standard GRanges columns: seqnames, start, end, width, strand

• All metadata columns: annotation, geneId, distanceToTSS, geneChr, geneStart, geneEnd, etc.

Author(s)

Guangchuang Yu https://guangchuangyu.github.io

See Also

as.GRanges for converting to GRanges object

Examples

## Not run: 
peak.df <- as.data.frame(peakAnno)
## Export to CSV
write.csv(peak.df, "annotated_peaks.csv")

## End(Not run)

Description

The function returns the anno slot from the csAnno object, which contains all annotated peaks as a GRanges object with metadata columns (annotation, geneId, distanceToTSS, etc.).

Usage

as.GRanges(x)

Arguments

Details

This function extracts the GRanges object containing annotated peaks from a csAnno object.

Value

GRanges object containing all annotated peaks with their metadata columns. This is the same as accessing x@anno directly

Author(s)

Guangchuang Yu https://guangchuangyu.github.io

Examples

## Not run: 
peak.gr <- as.GRanges(peakAnno)
## Equivalent to: peak.gr <- peakAnno@anno

## End(Not run)

Description

The function merges multiple csAnno objects that were created with the same annotation parameters (TSS region, level, genomic annotation status). It combines all peaks, merges annotation statistics, and creates a unified summary. This is useful for comparing or combining results from multiple ChIP-seq experiments.

Usage

combine_csAnno(x, ...)

Arguments

Details

This function combines two or more csAnno objects into a single object, merging their peaks and aggregating annotation statistics.

The function performs the following operations:

1. Validates that all objects are csAnno instances

2. Checks that all objects have the same tssRegion, level, and hasGenomicAnnotation values

3. Combines all GRanges objects from the anno slots

4. Merges detailGenomicAnnotation data frames by row binding

5. Aggregates annotation statistics by merging and summing frequencies across all objects

6. Sums the total peak counts

The resulting object contains all peaks from all input objects with combined annotation statistics showing the overall distribution across genomic features.

Value

A new csAnno object containing:

• All peaks from all input objects combined

• Merged annotation statistics with aggregated frequencies

• Combined detail genomic annotations

• Sum of peak counts from all objects

The tssRegion, level, and hasGenomicAnnotation are inherited from the first object (all must be identical)

Author(s)

Guangchuang Yu https://guangchuangyu.github.io

References

https://github.com/YuLab-SMU/ChIPseeker/issues/157

See Also

annotatePeak for creating csAnno objects

Examples

## Not run: 
## Combine two peak annotation results
combined <- combine_csAnno(peakAnno1, peakAnno2, peakAnno3)

## Visualize combined statistics
plotAnnoBar(combined)

## End(Not run)

Description

The function creates a coverage plot showing where peaks are located across chromosomes. It calculates coverage by counting overlapping peaks at each genomic position, and displays the results as a bar/rectangular plot with one panel per chromosome.

Usage

covplot(
  peak,
  weightCol = NULL,
  xlab = "Chromosome Size (bp)",
  ylab = "",
  title = "ChIP Peaks over Chromosomes",
  chrs = NULL,
  xlim = NULL,
  lower = 1,
  fill_color = "black"
)

Arguments

Details

This function visualizes the coverage of ChIP-seq peaks across chromosomes, showing the density and distribution of peaks along the genome.

The function performs the following steps:

1. Loads peaks from file or uses provided GRanges object

2. Calculates coverage using coverage() function, optionally weighted by a metadata column

3. Filters coverage by the lower threshold to remove low signals

4. Aggregates coverage into contiguous regions

5. Creates a ggplot2 visualization with:

   • One facet per chromosome (if multiple chromosomes)

   • Rectangular bars showing coverage regions

   • Color coding for multiple peak sets (if input is a list)

For multiple peak sets (list input), the function automatically assigns colors and creates a grouped plot showing all sets together.

Value

A ggplot2 object that can be further customized or printed. The plot shows peak coverage as rectangular bars, with one panel per chromosome when multiple chromosomes are present

Author(s)

G Yu

Description

The csAnno class is the main output object from annotatePeak(). It stores annotated peaks as a GRanges object along with metadata about the annotation process and summary statistics. This object can be used for visualization, further analysis, and conversion to other formats.

Details

This class represents the output of ChIPseeker peak annotation. It contains annotated peaks along with their genomic annotations, nearest gene information, and annotation statistics.

The class contains the following slots:

• anno: GRanges object containing all annotated peaks with metadata columns (annotation, geneId, distanceToTSS, etc.)

• tssRegion: numeric vector of length 2 specifying the TSS region used for promoter annotation (e.g., c(-3000, 3000))

• level: character, annotation level - either "transcript" or "gene"

• hasGenomicAnnotation: logical, whether genomic feature annotations (Promoter, Exon, UTR, etc.) were assigned

• detailGenomicAnnotation: data.frame with logical columns indicating which genomic features each peak overlaps

• annoStat: data.frame containing annotation statistics showing the percentage of peaks in each genomic feature category

• peakNum: numeric, total number of peaks that were annotated

Slots

anno

GRanges object containing annotated peaks with all metadata

tssRegion

numeric vector of length 2, TSS region for promoter annotation

level

character, annotation level ("transcript" or "gene")

hasGenomicAnnotation

logical, whether genomic annotations were assigned

detailGenomicAnnotation

data.frame, detailed genomic annotation matrix

annoStat

data.frame, annotation statistics summary

peakNum

numeric, total number of annotated peaks

Author(s)

Guangchuang Yu https://guangchuangyu.github.io

See Also

annotatePeak

Description

download all BED files of a particular genome version

Usage

downloadGEObedFiles(genome, destDir = getwd())

Arguments

Author(s)

G Yu

Description

download BED supplementary files of a list of GSM accession numbers

Usage

downloadGSMbedFiles(GSM, destDir = getwd())

Arguments

Author(s)

G Yu

Description

dropAnno

Usage

dropAnno(csAnno, distanceToTSS_cutoff = 10000)

Arguments

Details

drop annotation exceeding distanceToTSS_cutoff

Value

csAnno object

Author(s)

Guangchuang Yu

Description

The function compares the overlap of genes associated with query and target ChIP-seq peaks. It uses a hypergeometric test to determine if the number of overlapping genes is significantly higher than expected by chance, suggesting biological similarity between the experiments.

Usage

enrichAnnoOverlap(
  queryPeak,
  targetPeak,
  TxDb = NULL,
  pAdjustMethod = "BH",
  chainFile = NULL,
  distanceToTSS_cutoff = NULL
)

Arguments

Details

This function tests whether two ChIP-seq experiments share significantly more genes than expected by chance, based on the genes nearest to their peaks.

The function performs the following steps:

1. Annotates both query and target peaks to find their nearest genes

2. Optionally filters peaks by distance to TSS using distanceToTSS_cutoff

3. Counts the number of overlapping genes between query and target

4. Performs a hypergeometric test to calculate p-values

5. Adjusts p-values for multiple testing

The hypergeometric test parameters:

• White balls (m): number of unique genes in query peaks

• Black balls (n): total genes minus query genes

• Drawn (k): number of unique genes in target peaks

• Overlap (q): number of overlapping genes

Value

A data.frame with one row per target peak comparison, containing:

• qSample: name of the query sample

• tSample: name of the target sample(s)

• qLen: number of unique genes in query peaks

• tLen: number of unique genes in target peaks

• N_OL: number of overlapping genes. Note that this counts genes, not peaks, so it can be larger than the number of input peaks: one peak is annotated to its nearest gene, but the same gene is reported once per peak and a peak region may overlap several target genes (see issue #84)

• pvalue: p-value from hypergeometric test

• p.adjust: adjusted p-value

Author(s)

G Yu

Description

The function compares the genomic overlap between query and target ChIP-seq peaks. It uses a permutation test approach: randomly shuffling target peaks across the genome and comparing the observed overlap to the distribution of overlaps from shuffled data. This provides a p-value indicating whether the observed overlap is significantly higher than expected by chance.

Usage

enrichPeakOverlap(
  queryPeak,
  targetPeak,
  TxDb = NULL,
  pAdjustMethod = "BH",
  nShuffle = 1000,
  chainFile = NULL,
  pool = TRUE,
  mc.cores = detectCores() - 1,
  verbose = TRUE,
  symmetric = FALSE
)

Arguments

Details

This function tests whether two ChIP-seq experiments have significantly more overlapping peaks than expected by chance, using permutation testing with shuffled peak positions.

The function performs the following steps:

1. Loads query and target peaks (supports BED files or GRanges objects)

2. Optionally converts target peaks to query genome using liftOver (if chainFile is provided)

3. If pool=TRUE, pools all target peaks and tests overlap with the pooled set

4. If pool=FALSE, tests overlap with each target peak set separately

5. For permutation testing:

   • Calculates the observed overlap ratio (overlapping peaks / total target peaks)

   • Randomly shuffles target peaks nShuffle times across the genome (preserving chromosome and peak width)

   • Calculates overlap ratio for each shuffled set

   • Computes p-value as (number of shuffled ratios >= observed ratio + 1) / (nShuffle + 1)

6. Adjusts p-values for multiple testing

Direction of the test. The observed quantity is the fraction of target peaks covered by the query peaks, N_OL / length(targetPeak), and the null distribution is generated by shuffling the target peaks. The test therefore answers "are the query peaks enriched within the target peaks?". N_OL itself is symmetric (it is the same number in both directions), but the p-value is not: exchanging queryPeak and targetPeak asks the mirrored question and normalises by the other peak set, so the p-values can differ substantially when the two peak sets differ in size. Even for equally sized sets the two null distributions are sampled independently, which leaves small Monte-Carlo differences (see issue #84). Compare N_OL directly if a direction-free measure is needed, increase nShuffle to reduce the Monte-Carlo part, or use symmetric=TRUE for a direction-free p-value (the mirrored direction is then computed as well and combined as min(1, 2*min(p, p_rev)), which doubles the number of permutations and raises the smallest reportable p-value to 2/(nShuffle+1)).

Value

A data.frame with one row per target peak comparison, containing:

• qSample: name of the query sample

• tSample: name of the target sample(s)

• qLen: number of peaks in query

• tLen: number of peaks in target (or pooled target if pool=TRUE)

• N_OL: number of overlapping peaks

• pvalue: p-value from permutation test (NA if nShuffle=0)

• p.adjust: adjusted p-value

Author(s)

G Yu

Description

The function filters GRanges objects by converting them to a data.frame, applying the dplyr filter operation, and converting back to GRanges. This allows filtering based on any metadata column or standard GRanges columns (seqnames, start, end, width, strand).

Usage

## S3 method for class 'GRanges'
filter(.data, ..., .by = NULL, .preserve = FALSE)

Arguments

Details

This function extends dplyr::filter() to work with GRanges objects, allowing users to filter genomic ranges using familiar dplyr syntax while preserving the GRanges structure and all metadata columns.

The function performs the following steps:

1. Converts GRanges to data.frame using as.data.frame()

2. Applies dplyr::filter() with the provided conditions

3. Removes unused factor levels using droplevels()

4. Converts back to GRanges using makeGRangesFromDataFrame() with keep.extra.columns=TRUE

All metadata columns are preserved in the output. The function supports all standard dplyr filter operations including logical operators, comparisons, and functions like is.na(), between(), etc.

Value

GRanges object containing only the filtered ranges that satisfy the conditions. All metadata columns are preserved, and unused factor levels are dropped

Examples

## Not run: 
## Filter peaks by annotation
filtered_peaks <- peak.gr %>% filter(annotation == "Promoter")

## Filter by distance to TSS
near_peaks <- peak.gr %>% filter(abs(distanceToTSS) < 5000)

## Multiple conditions (AND logic)
specific_peaks <- peak.gr %>%
  filter(annotation == "Promoter", abs(distanceToTSS) < 3000)

## Filter by chromosome
chr1_peaks <- peak.gr %>% filter(seqnames == "chr1")

## Complex conditions
complex_filter <- peak.gr %>%
  filter(annotation %in% c("Promoter", "5' UTR"),
         !is.na(geneId),
         width > 200)

## End(Not run)

Description

The function returns the annoStat slot, which contains a summary of how peaks are distributed across different genomic feature categories (Promoter, Exon, Intron, UTR, Intergenic, etc.) with percentages.

Usage

getAnnoStat(x)

Arguments

Details

This function extracts the annotation statistics data frame from a csAnno object.

Value

A data.frame with columns:

• Feature: genomic feature category (Promoter, 5' UTR, 3' UTR, Exon, Intron, Downstream, Intergenic, etc.)

• Frequency: percentage of peaks in each category

Only available if hasGenomicAnnotation=TRUE

Author(s)

Guangchuang Yu https://guangchuangyu.github.io

See Also

plotAnnoBar for visualizing these statistics

Examples

## Not run: 
stats <- getAnnoStat(peakAnno)
## View annotation distribution
print(stats)

## End(Not run)

Description

The function extracts genomic regions based on feature type and region type. It supports three region types:

• start_site: Region around the transcription start site (TSS). For a transcript at chr1:1000-1400, with upstream=100 and downstream=100, this extracts chr1:900-1100 (TSS +/- 100bp)

• end_site: Region around the transcription termination site (TTS). For a transcript at chr1:1000-1400, with upstream=100 and downstream=100, this extracts chr1:1300-1500 (TTS +/- 100bp)

• body: The full feature body. For a transcript at chr1:1000-1400, this extracts chr1:1000-1400 (the entire transcript)

Usage

getBioRegion(
  TxDb = NULL,
  upstream = 1000,
  downstream = 1000,
  by = "gene",
  type = "start_site"
)

Arguments

Details

This function extracts biological regions (promoters, gene bodies, UTRs, etc.) from a TxDb or EnsDb annotation object. It provides a unified interface for extracting different types of genomic regions.

The function supports multiple feature types:

• gene: Gene-level regions

• transcript: Transcript-level regions

• exon: Exon regions

• intron: Intron regions

• 3UTR, 5UTR, UTR: UTR regions

For start_site and end_site types, the function creates regions extending upstream and downstream from the site. For body type, it returns the full feature body. The function handles strand information correctly (upstream/downstream are relative to the feature's strand).

Value

GRanges object containing the extracted regions with attributes:

• type: The region type ("start_site", "end_site", or "body")

• by: The feature type used

• label: Generated label for the regions

• upstream: Upstream distance (for start_site/end_site)

• downstream: Downstream distance (for start_site/end_site)

Author(s)

Guangchuang Yu, Ming L

See Also

getPromoters for a convenience function to get promoters, makeBioRegionFromGranges for creating regions from custom GRanges

Description

The function queries an annotation database to retrieve gene information such as gene symbols, full gene names, Ensembl IDs, and other identifiers. It handles both Entrez Gene IDs and Ensembl Gene IDs, and returns a data frame with the requested annotation columns.

Usage

getGeneAnno(annoDb, geneID, type, columns)

Arguments

Details

This function retrieves gene annotations (symbol, gene name, etc.) from annotation databases (e.g., org.Hs.eg.db) based on gene IDs.

The function performs the following steps:

1. Validates and converts the gene ID type to the appropriate keytype for the annotation database (ENTREZID or ENSEMBL)

2. Removes version numbers from Ensembl IDs (e.g., "ENSG00000123456.1" becomes "ENSG00000123456")

3. Queries the annotation database using AnnotationDbi::select()

4. Handles duplicate gene IDs by keeping only the first occurrence

5. Returns a data frame with rows matching the input gene IDs

Value

A data.frame with:

• Rows corresponding to the input gene IDs (in the same order)

• Columns as specified in the columns parameter, plus the keytype column (ENTREZID or ENSEMBL)

• NA values for gene IDs that could not be found in the database

Returns NA if the ID type is not supported or if the database query fails

Author(s)

G Yu

Description

get genome version statistics collecting from GEO ChIPseq data

Usage

getGEOgenomeVersion()

Value

data.frame

Author(s)

G Yu

Description

get subset of GEO information by genome version keyword

Usage

getGEOInfo(genome, simplify = TRUE)

Arguments

Value

data.frame

Author(s)

G Yu

Description

accessing species statistics collecting from GEO database

Usage

getGEOspecies()

Value

data.frame

Author(s)

G Yu

Description

The function finds the closest feature to each peak by considering both upstream and downstream directions. It calculates distances from both the peak start and peak end to the feature's TSS, then selects the feature with the minimum absolute distance. The function handles overlaps between peaks and features, with different behaviors depending on the overlap parameter.

Usage

getNearestFeatureIndicesAndDistances(
  peaks,
  features,
  sameStrand = FALSE,
  ignoreOverlap = FALSE,
  ignoreUpstream = FALSE,
  ignoreDownstream = FALSE,
  overlap = "TSS"
)

Arguments

Details

This function identifies the nearest gene/transcript feature to each peak and calculates the distance from the peak to the feature's transcription start site (TSS).

The function performs the following steps:

1. Resizes features to width=1 (TSS points) for efficient distance calculation

2. Finds nearest upstream features using follow() and nearest downstream features using precede()

3. Calculates distances from both peak start and peak end to each feature's TSS

4. Selects the feature with the minimum absolute distance (or enforces direction based on ignoreUpstream/ignoreDownstream)

5. If overlaps are allowed (ignoreOverlap=FALSE), identifies overlapping features and assigns them with distance=0 (for overlap="TSS") or calculates distance from the closer peak end (for overlap="all")

6. Returns indices, distances, and filtered peaks (excluding peaks with no nearest feature)

Distance calculation is strand-aware: positive values indicate downstream, negative values indicate upstream. Overlapping peaks get distance=0 if overlap is "TSS".

Value

A list with three components:

• index: Integer vector of feature indices (1-based) for the nearest feature to each peak. Length equals the number of peaks with valid nearest features

• distance: Numeric vector of distances from each peak to the TSS of its nearest feature. Positive values indicate downstream, negative values indicate upstream, and 0 indicates overlap. Length equals the number of peaks with valid nearest features

• peak: GRanges object containing only the peaks that have valid nearest features (peaks with no nearest feature in either direction are excluded)

Author(s)

G Yu

Description

The function extracts promoter regions defined as regions around transcription start sites (TSS). For each gene or transcript, it creates a region extending upstream and downstream from the TSS. The function calls getBioRegion() with type="start_site".

Usage

getPromoters(TxDb = NULL, upstream = 1000, downstream = 1000, by = "gene")

Arguments

Details

This function extracts promoter regions (TSS regions) from a TxDb or EnsDb annotation object. It is a convenience wrapper around getBioRegion() for extracting promoter regions.

Value

GRanges object containing promoter regions with attributes:

• type: "start_site"

• by: the value of the by parameter

• label: generated label for the regions

• upstream: upstream distance

• downstream: downstream distance

See Also

getBioRegion for more flexible region extraction

Description

The function scans the package's extdata directory for sample peak files and returns their paths. The files are named based on the protein/condition they represent (extracted from the filename).

Usage

getSampleFiles()

Details

This function returns a list of sample ChIP-seq peak files included in the package for demonstration and testing purposes.

Value

A named list of file paths. Names are extracted from filenames (typically protein/condition names), and values are full file paths to the sample BED files

Author(s)

G Yu

Description

The function computes peak coverage across a set of genomic regions (windows). It supports two methods:

• Direct method (when nbin=NULL): For regions of equal size (e.g., promoters), calculates coverage at each base pair position

• Binning method (when nbin is specified): For regions of variable size (e.g., gene bodies), divides each region into a fixed number of bins and calculates average coverage per bin

Usage

getTagMatrix(
  peak,
  upstream,
  downstream,
  windows,
  type,
  by,
  TxDb = NULL,
  weightCol = NULL,
  nbin = NULL,
  verbose = TRUE,
  ignore_strand = FALSE
)

Arguments

Details

This function calculates a tag matrix representing peak coverage across genomic regions (e.g., promoters, gene bodies). The matrix can be used for visualization with functions like plotPeakProf() or plotAvgProf().

The function can work in two modes:

1. With pre-made windows: Provide a windows GRanges object created by getPromoters(), getBioRegion(), or makeBioRegionFromGranges()

2. Without windows: Provide TxDb and region parameters (type, by, upstream, downstream), and the function will create windows automatically

For upstream and downstream parameters:

• If windows is provided: For type='body', these extend the flanks; for type='start_site'/'end_site', they are ignored (taken from window attributes)

• If windows is missing: These define the region size for type='start_site'/'end_site', or extend flanks for type='body'

The weightCol parameter allows weighting peaks by a metadata column (e.g., peak score or signal value), useful for signal-weighted coverage.

Value

A matrix (tagMatrix) with:

• Rows: One per region (window)

• Columns: One per position/bin

• Values: Peak coverage/signal at each position

The matrix has attributes:

• upstream: Upstream distance

• downstream: Downstream distance

• type: Region type

• label: Region label

• is.binning: Whether binning method was used

See Also

getPromoters, getBioRegion, makeBioRegionFromGranges for creating windows, plotPeakProf, plotAvgProf for visualization

Description

The function divides each region into a fixed number of bins and calculates average coverage per bin. This allows handling regions of variable size (e.g., gene bodies of different lengths) by normalizing them to the same number of bins. The approach is similar to deeptools computeMatrix (https://deeptools.readthedocs.io/en/develop/content/tools/computeMatrix.html).

Usage

getTagMatrix.binning.internal(
  peak,
  weightCol = NULL,
  windows,
  nbin = 800,
  upstream = NULL,
  downstream = NULL,
  ignore_strand = FALSE
)

Arguments

Details

This is an internal function that calculates peak coverage using a binning approach, inspired by deeptools computeMatrix. It is called by getTagMatrix() when nbin is specified.

The function performs the following steps:

1. Loads peaks and calculates coverage (optionally weighted)

2. Filters windows to those within chromosome boundaries

3. Optionally extends windows by upstream and downstream (can be relative values using rel())

4. For each window, divides it into nbin equal-sized bins

5. Calculates average coverage per bin

6. Creates a matrix with one row per window and one column per bin

7. Reverse-complements negative strand regions (if ignore_strand=FALSE)

8. Filters out windows shorter than the minimum required length

The binning method is essential for visualizing coverage across variable-length regions (e.g., gene bodies), as it normalizes all regions to the same number of data points.

Value

A matrix with:

• Rows: One per window (regions meeting minimum length requirement)

• Columns: One per bin (nbin columns)

• Values: Average coverage/signal per bin

Description

Pre-calculated datasets included in the ChIPseeker package:

• ucsc_release: UCSC genome version information

• gsminfo: GEO Sample (GSM) information for ChIP-seq datasets

• tagMatrixList: Pre-calculated tag matrices for example datasets

Description

The function extracts regions from a custom GRanges object, similar to getBioRegion() but working with user-defined features instead of TxDb annotations. This is useful for features like enhancers, insulators, or other regulatory elements that are not part of standard gene annotations.

Usage

makeBioRegionFromGranges(gr, by, type, upstream = 1000, downstream = 1000)

Arguments

Details

This function creates biological regions from a user-provided GRanges object, allowing extraction of regions around start sites, end sites, or full bodies for custom genomic features not available in TxDb objects (e.g., enhancers, insulators).

The function supports three region types:

• start_site: Region around the start of each range. For an enhancer at chr1:1000-1400 with upstream=100 and downstream=100, extracts chr1:900-1100 (start +/- 100bp, strand-aware)

• end_site: Region around the end of each range. For an enhancer at chr1:1000-1400 with upstream=100 and downstream=100, extracts chr1:1300-1500 (end +/- 100bp, strand-aware)

• body: The full range body. For an enhancer at chr1:1000-1400, extracts chr1:1000-1400. For this type, upstream and downstream can be NULL

The function handles strand information correctly: for negative strand features, "upstream" and "downstream" are reversed relative to the genomic coordinates.

Value

GRanges object containing the extracted regions with attributes:

• type: The region type

• by: The feature type label

• label: Generated label for the regions

• upstream: Upstream distance (for start_site/end_site)

• downstream: Downstream distance (for start_site/end_site)

See Also

getBioRegion for extracting regions from TxDb objects

Description

The function mutates GRanges objects by converting them to a data.frame, applying the dplyr mutate operation, and converting back to GRanges. This allows creating new columns or modifying existing metadata columns based on expressions involving other columns.

Usage

## S3 method for class 'GRanges'
mutate(
  .data,
  ...,
  .by = NULL,
  .keep = c("all", "used", "unused", "none"),
  .before = NULL,
  .after = NULL
)

Arguments

Details

This function extends dplyr::mutate() to work with GRanges objects, allowing users to add new metadata columns or modify existing ones using familiar dplyr syntax while preserving the GRanges structure.

The function performs the following steps:

1. Converts GRanges to data.frame using as.data.frame()

2. Validates that .before and .after are not both specified

3. Applies dplyr::mutate() with the provided expressions, handling column positioning if .before or .after is specified

4. Converts back to GRanges using makeGRangesFromDataFrame() with keep.extra.columns=TRUE

All genomic range information (seqnames, ranges, strand) is preserved. The function supports all standard dplyr mutate operations including arithmetic, logical operations, and functions.

Value

GRanges object with modified or new metadata columns. All genomic range information is preserved. The order and position of new columns follows the .before or .after specifications

Examples

## Not run: 
## Add a new column based on existing data
peak.gr <- peak.gr %>% mutate(logScore = log10(score))

## Modify existing column
peak.gr <- peak.gr %>% mutate(distance = abs(distanceToTSS))

## Create multiple columns
peak.gr <- peak.gr %>%
  mutate(
    distance_kb = abs(distanceToTSS) / 1000,
    is_promoter = annotation == "Promoter",
    category = ifelse(abs(distanceToTSS) < 3000, "near", "far")
  )

## Place new column before specific column
peak.gr <- peak.gr %>%
  mutate(new_col = 1, .before = annotation)

## Keep only used columns
peak.gr <- peak.gr %>%
  mutate(result = score * 2, .keep = "used")

## End(Not run)

Description

The function computes the number of elements in each possible intersection of the input sets. It handles all combinations of set intersections using an inclusion-exclusion principle approach.

Usage

overlap(Sets)

Arguments

Details

This function calculates the overlap matrix for multiple sets, which is useful for creating Venn diagrams and understanding set relationships.

The function:

1. Generates all possible combinations of set inclusion/exclusion

2. For each combination, calculates the intersection size

3. Uses inclusion-exclusion principle to handle overlapping intersections

4. Returns a data frame with binary indicators for each set and the intersection size

The function is generic and works with any objects that support intersect() and length() methods, including GRanges objects.

Value

A data.frame with:

• One column per set (named after the sets)

• Binary values (0 or 1) indicating which sets are included in each intersection

• A "Weight" column containing the number of elements in each intersection

Rows represent all possible combinations of set intersections

Author(s)

G Yu

Description

The function generates a two-panel figure:

• Top panel: Heatmap showing signal intensity for each feature (row) across genomic positions (columns)

• Bottom panel: Average profile line showing the mean signal across all features at each position

This combination allows users to see both individual feature patterns and the overall trend simultaneously.

Usage

peak_Profile_Heatmap(
  peak,
  weightCol = NULL,
  TxDb = NULL,
  upstream = 1000,
  downstream = 1000,
  xlab = "",
  ylab = "",
  title = NULL,
  palette = NULL,
  verbose = TRUE,
  by = "gene",
  type = "start_site",
  nbin = NULL,
  ignore_strand = FALSE,
  windows_name = NULL,
  ncol = NULL,
  nrow = NULL,
  facet_label_text_size = 12,
  conf,
  facet = "row",
  free_y = TRUE,
  height_proportion = 4
)

Arguments

Details

This function creates a combined visualization showing both a heatmap of individual features and an average profile line plot in a single figure, providing both detailed and summary views of peak distributions.

Description

The function generates tag matrices from peaks and visualizes them as heatmaps. It supports both absolute positioning and binning modes. Features are typically sorted by signal strength, allowing identification of features with strong peak enrichment.

Usage

peakHeatmap(
  peak,
  weightCol = NULL,
  TxDb = NULL,
  upstream = 1000,
  downstream = 1000,
  xlab = "",
  ylab = "",
  title = NULL,
  palette = NULL,
  verbose = TRUE,
  by = "gene",
  type = "start_site",
  nbin = NULL,
  ignore_strand = FALSE,
  windows,
  ncol = NULL,
  nrow = NULL
)

Arguments

Details

This function creates a heatmap showing the distribution of ChIP-seq peaks around genomic features (e.g., TSS, gene body). Each row represents a feature and each column represents a genomic position.

The function:

1. Generates tag matrices from peaks using getTagMatrix()

2. Optionally uses custom windows (if provided) or generates them from TxDb based on by and type

3. Creates heatmap visualization with color-coded signal intensities

4. Supports single or multiple peak sets (list input)

Value

A ggplot2 heatmap object showing peak signals across features and positions. For multiple peak sets, returns a grid of heatmaps

Author(s)

G Yu

Description

The function extends peakHeatmap() to support multiple window sets. It generates tag matrices for each window set and creates a faceted heatmap visualization, with each facet showing peaks aligned to a different set of regions. This is useful for comparing peak patterns across different feature types (e.g., promoters vs enhancers) or conditions.

Usage

peakHeatmap_multiple_Sets(
  peak,
  weightCol = NULL,
  TxDb = NULL,
  upstream = 1000,
  downstream = 1000,
  xlab = "",
  ylab = "",
  title = NULL,
  palette = NULL,
  verbose = TRUE,
  by = "gene",
  type = "start_site",
  nbin = NULL,
  ignore_strand = FALSE,
  windows_name = NULL,
  ncol = NULL,
  nrow = NULL,
  facet_label_text_size = 12
)

Arguments

Details

This function creates heatmaps showing peak distributions across multiple sets of genomic regions (windows), allowing comparison of peak patterns across different feature types or conditions.

The function:

1. Generates tag matrices for each window set (specified via by or custom TxDb GRanges)

2. Creates heatmaps for each window set

3. Arranges them in a grid with faceting

4. Supports both absolute positioning and binning modes

All windows must have the same type (start_site, end_site, or body) and the same upstream and downstream parameters.

Value

figure

Description

The function visualizes the percentage of peaks falling into each genomic annotation category. It creates a horizontal bar chart where each bar represents a category, and the bar length represents the percentage of peaks in that category. The function supports both single csAnno objects and lists of csAnno objects for comparing multiple datasets.

Usage

plotAnnoBar(
  x,
  xlab = "",
  ylab = "Percentage(%)",
  title = "Feature Distribution",
  ...
)

Arguments

Details

This generic function creates a bar plot showing the distribution of peaks across different genomic annotation categories (Promoter, Exon, Intron, etc.).

The function:

1. Extracts annotation statistics from the csAnno object(s)

2. Calculates percentages for each annotation category

3. Creates a horizontal bar chart with categories on the y-axis and percentages on the x-axis

4. Color-codes each annotation category

Common annotation categories include: Promoter, 5' UTR, 3' UTR, Exon, Intron, Downstream, and Intergenic.

Value

A ggplot2 bar plot object showing the distribution of peaks across genomic annotation categories. For lists of csAnno objects, the plot shows side-by-side bars for comparison

See Also

plotAnnoPie for pie chart visualization, annotatePeak for peak annotation

Description

plot feature distribution based on their chromosome region

Usage

plotAnnoBar.data.frame(
  anno.df,
  xlab = "",
  ylab = "Percentage(%)",
  title = "Feature Distribution",
  categoryColumn
)

Arguments

Details

plot chromosome region features

Value

bar plot that summarize genomic features of peaks

Author(s)

Guangchuang Yu https://yulab-smu.top

See Also

annotatePeak plotAnnoPie

Description

The function visualizes the percentage of peaks falling into each genomic annotation category using a pie chart. Each slice of the pie represents an annotation category, with the slice size proportional to the percentage of peaks in that category. Labels show the category name and percentage.

Usage

plotAnnoPie(
  x,
  ndigit = 2,
  cex = 0.9,
  col = NA,
  legend.position = "rightside",
  pie3D = FALSE,
  radius = 0.8,
  ...
)

Arguments

Details

This generic function creates a pie chart showing the distribution of peaks across different genomic annotation categories.

The function:

1. Extracts annotation statistics from the csAnno object

2. Calculates percentages for each annotation category

3. Creates a pie chart with color-coded slices

4. Adds labels showing category names and percentages (rounded to ndigit decimal places)

5. Optionally creates a 3D pie chart for enhanced visualization

Common annotation categories include: Promoter, 5' UTR, 3' UTR, Exon, Intron, Downstream, and Intergenic.

Value

A pie chart plot showing the distribution of peaks across genomic annotation categories. The plot includes labels with category names and percentages, and a legend

See Also

plotAnnoBar for bar chart visualization, vennpie for nested pie chart visualization, annotatePeak for peak annotation

Description

pieplot from peak genomic annotation

Usage

plotAnnoPie.csAnno(
  x,
  ndigit = 2,
  cex = 0.8,
  col = NA,
  legend.position = "rightside",
  pie3D = FALSE,
  radius = 0.8,
  ...
)

Arguments

Value

pie plot of peak genomic feature annotation

Author(s)

Guangchuang Yu https://yulab-smu.top

See Also

annotatePeak plotAnnoBar

Examples

## Not run: 
require(TxDb.Hsapiens.UCSC.hg19.knownGene)
txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene
peakfile <- system.file("extdata", "sample_peaks.txt", package="chipseeker")
peakAnno <- annotatePeak(peakfile, TxDb=txdb)
plotAnnoPie(peakAnno)

## End(Not run)

Description

The function creates a line plot showing the average signal intensity of peaks across genomic regions. It can plot single or multiple peak sets, with optional confidence intervals (error bars or ribbons) and faceting options for comparing datasets.

Usage

plotAvgProf(
  tagMatrix,
  xlim,
  xlab = "Genomic Region (5'->3')",
  ylab = "Peak Count Frequency",
  conf,
  facet = "none",
  free_y = TRUE,
  origin_label = "TSS",
  verbose = TRUE,
  ...
)

Arguments

Details

Plot average peak profile

This function plots the average profile of peaks around genomic features (e.g., TSS, gene body) as a line plot, optionally with confidence intervals.

The function:

1. Calculates average signal across all features for each position

2. Optionally calculates confidence intervals (if conf is provided)

3. Creates a line plot with optional ribbon for confidence intervals

4. Supports faceting for multiple datasets (row, column, or none)

5. Allows independent y-axis scaling per facet

For multiple datasets (list input), the function automatically creates separate facets or overlays them based on the facet parameter.

Value

A ggplot2 object showing the average peak profile as a line plot, with optional confidence intervals and faceting

Author(s)

G Yu; Y Yan

Description

plot the profile of peaks that align to flank sequences of TSS

Usage

plotAvgProf2(
  peak,
  weightCol = NULL,
  TxDb = NULL,
  upstream = 1000,
  downstream = 1000,
  xlab = "Genomic Region (5'->3')",
  ylab = "Peak Count Frequency",
  conf,
  facet = "none",
  free_y = TRUE,
  verbose = TRUE,
  ignore_strand = FALSE,
  ...
)

Arguments

Details

This function is the old function of plotPeakProf2. It can only plot the start site region of gene.

Value

ggplot object

Author(s)

G Yu, Ming L

Description

The function visualizes where ChIP-seq peaks are located relative to gene TSSs. It categorizes peaks into distance bins (e.g., 0-1kb, 1-3kb, etc.) and displays the percentage of peaks in each category, separately for upstream (5') and downstream (3') regions. The plot uses a diverging bar chart with TSS at the center (0).

Usage

plotDistToTSS(
  x,
  distanceColumn = "distanceToTSS",
  xlab = "",
  ylab = "Binding sites (%) (5'->3')",
  title = "Distribution of transcription factor-binding loci relative to TSS",
  ...
)

Arguments

Details

This generic function creates a bar plot showing the distribution of peaks relative to transcription start sites (TSS), categorizing peaks by their distance from the nearest gene's TSS.

The function:

1. Categorizes peaks into distance bins based on distanceBreaks

2. Separates upstream (negative distance) and downstream (positive distance) peaks

3. Calculates percentages for each distance category

4. Creates a diverging bar plot with upstream peaks on the left and downstream peaks on the right, with TSS at the center

Value

A ggplot2 bar plot object showing the distribution of peaks relative to TSS. The plot uses a diverging bar chart format with upstream (5') on the left and downstream (3') on the right, with TSS at the center

See Also

annotatePeak for peak annotation, plotAnnoBar for annotation distribution plots

Description

The function visualizes where ChIP-seq peaks are located relative to gene TSSs. It categorizes peaks into distance bins (e.g., 0-1kb, 1-3kb, etc.) and displays the percentage of peaks in each category, separately for upstream (5') and downstream (3') regions. The plot uses a diverging bar chart with TSS at the center (0).

Usage

plotDistToTSS.data.frame(
  peakDist,
  distanceColumn = "distanceToTSS",
  distanceBreaks = c(0, 1000, 3000, 5000, 10000, 1e+05),
  palette = NULL,
  xlab = "",
  ylab = "Binding sites (%) (5'->3')",
  title = "Distribution of transcription factor-binding loci relative to TSS",
  categoryColumn = ".id"
)

Arguments

Details

This function creates a bar plot showing the distribution of peaks relative to transcription start sites (TSS), categorizing peaks by their distance from the nearest gene's TSS.

The function performs the following steps:

1. Categorizes peaks into distance bins based on distanceBreaks

2. Separates upstream (negative distance) and downstream (positive distance) peaks

3. Calculates percentages for each distance category

4. Creates a diverging bar plot with:

   • Upstream peaks shown as negative bars (left side)

   • Downstream peaks shown as positive bars (right side)

   • TSS marked at the center (0)

   • Distance categories color-coded

5. Supports grouping by a category column for comparing multiple datasets

Value

A ggplot2 bar plot object showing the distribution of peaks relative to TSS. The plot uses a diverging bar chart format with upstream (5') on the left and downstream (3') on the right, with TSS at the center

Author(s)

Guangchuang Yu https://guangchuangyu.github.io

See Also

annotatePeak

Examples

## Not run: 
require(TxDb.Hsapiens.UCSC.hg19.knownGene)
txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene
peakfile <- system.file("extdata", "sample_peaks.txt", package="ChIPseeker")
peakAnno <- annotatePeak(peakfile, TxDb=txdb)
plotDistToTSS(peakAnno)

## End(Not run)

Description

The function is a flexible entry point for plotting peak profiles. It can work with either pre-computed tag matrices or raw peak files/GRanges objects. When provided with peaks, it automatically generates tag matrices and plots them. The function routes to different plotting functions based on the input type and parameters.

Usage

plotPeakProf(
  tagMatrix = NULL,
  peak,
  upstream,
  downstream,
  conf,
  by,
  type,
  windows_name = NULL,
  weightCol = NULL,
  TxDb = NULL,
  xlab = "Genomic Region (5'->3')",
  ylab = "Peak Count Frequency",
  facet = "row",
  free_y = TRUE,
  verbose = TRUE,
  nbin = NULL,
  ignore_strand = FALSE,
  ...
)

Arguments

Details

Plot peak profiles around genomic features

This function visualizes the distribution of ChIP-seq peaks around genomic features (e.g., TSS, gene body, exons) by plotting average peak profiles or heatmaps.

The function behavior depends on the input:

• If tagMatrix is provided: plots directly from the tag matrix (supports both normal and binning modes)

• If tagMatrix is NULL: generates tag matrix from peaks and routes to:

  • plotPeakProf2() if by has length 1

  • plotPeakProf_MultiWindows() if by has length > 1

The function supports:

• Single or multiple peak sets (list of peaks)

• Confidence intervals for average profiles

• Binning mode for large datasets

• Faceting options for comparing multiple datasets

TxDb parameter can accept txdb object. But many regions can not be obtained by txdb object. In this case, Users can provide self-made granges served the same role as txdb object and pass to TxDb object.

by the features of interest.

(1) if users use txdb, by can be one of 'gene', 'transcript', 'exon', 'intron' , '3UTR' , '5UTR', 'UTR'. These features can be obtained by functions from txdb object.

(2) if users use self-made granges object, by can be everything. Because this by will not pass to functions to get features, which is different from the case of using txdb object. This by is only used to made labels showed in picture.

type means the property of the region. one of the "start site", "end site" and "body".

upstream and downstream parameter have different usages:

(1) if type == 'body', upstream and downstream can use to extend the flank of body region.

(2) if type == 'start_site'/'end_site', upstream and downstream refer to the upstream and downstream of the start_site or the end_site.

weightCol refers to column in peak file. This column acts as a weight value. Details see https://github.com/YuLab-SMU/ChIPseeker/issues/15

nbin refers to the number of bins. getTagMatrix() provide a binning method to get the tag matrix.

There are two ways input a list of window.

(1) Users can input a list of self-made granges objects

(2) Users can input a list of by and only one type. In this way, plotPeakProf_MultiWindows() can made a list of window from txdb object based on by and type.

Warning:

(1) All of these window should be the same type. It means users can only compare a list of "start site"/"end site"/"body region" with the same upstream and downstream.

(2) So it will be only one type and several by.

(3) Users can make window by txdb object or self-made granges object. Users can only choose one of 'gene', 'transcript', 'exon', 'intron' , '3UTR' , '5UTR' or 'UTR' in the way of using txdb object. User can input any by in the way of using self-made granges object.

(4) Users can mingle the by designed for the two ways. plotPeakProf_MultiWindows can accpet the hybrid by. But the above rules should be followed.

https://github.com/YuLab-SMU/ChIPseeker/issues/189

Value

ggplot object

Description

plot the profile of peaks automatically

Usage

plotPeakProf2(
  peak,
  upstream,
  downstream,
  conf,
  by,
  type,
  weightCol = NULL,
  TxDb = NULL,
  xlab = "Genomic Region (5'->3')",
  ylab = "Peak Count Frequency",
  facet = "none",
  free_y = TRUE,
  verbose = TRUE,
  nbin = NULL,
  ignore_strand = FALSE,
  ...
)

Arguments

Details

peak stands for the peak file.

by the features of interest.

(1) if users use txdb, by can be one of 'gene', 'transcript', 'exon', 'intron' , '3UTR' , '5UTR', 'UTR'. These features can be obtained by functions from txdb object.

(2) if users use self-made granges object, by can be everything. Because this by will not pass to functions to get features, which is different from the case of using txdb object. This by is only used to made labels showed in picture.

type means the property of the region. one of the "start site", "end site" and "body".

upstream and downstream parameter have different usages:

(1) if type == 'body', upstream and downstream can use to extend the flank of body region.

(2) if type == 'start_site'/'end_site', upstream and downstream refer to the upstream and downstream of the start_site or the end_site.

weightCol refers to column in peak file. This column acts as a weight vaule. Details see https://github.com/YuLab-SMU/ChIPseeker/issues/15

nbin refers to the number of bins, providing a binning method to get the tag matrix.

TxDb parameter can accept txdb object. But many regions can not be obtained by txdb object. In this case, Users can provide self-made granges served the same role as txdb object and pass to TxDb object.

plotPeakProf2() is different from the plotPeakProf(). plotPeakProf2() do not need to provide window parameter, which means plotPeakProf2() will call relevent functions to make window automatically.

Value

ggplot object

Author(s)

G Yu, Ming Li

Description

The function reads tab-delimited peak files and converts them to the specified output format. It automatically detects BED format files based on file extension and handles the coordinate system conversion (BED files use 0-based start coordinates, which are converted to 1-based for R compatibility). Additional columns beyond chromosome, start, and end positions are preserved in the output.

Usage

readPeakFile(peakfile, as = "GRanges", ...)

Arguments

Details

This function reads peak files in various formats (BED, narrowPeak, broadPeak, etc.) and converts them to either a GRanges object or data.frame. The function automatically handles BED file coordinate conversion (0-based to 1-based).

The function performs the following steps:

1. Detects file format based on extension (BED files: .bed, .bed.gz, .narrowPeak, .broadPeak, .gappedPeak, .bedGraph.gz, or files ending with Peak.gz)

2. Reads the file using utils::read.delim() with appropriate header settings (BED files have no header, other formats may have headers)

3. Converts BED coordinates from 0-based to 1-based by adding 1 to the start position (BED end position is already exclusive, so no adjustment needed)

4. Converts to the requested output format (GRanges or data.frame)

5. Preserves all additional columns beyond the first three (chromosome, start, end) as metadata columns in GRanges or as additional columns in data.frame

Supported file formats include standard BED files, narrowPeak, broadPeak, gappedPeak, bedGraph, and other tab-delimited formats with chromosome, start, and end positions in the first three columns.

Value

Depending on the as parameter:

• If as="GRanges": A GRanges object with:

  • seqnames: Chromosome names (from column 1)

  • ranges: IRanges with start and end positions (from columns 2 and 3)

  • Additional metadata columns: All columns beyond the first three are preserved as metadata columns with their original names

• If as="data.frame": A data.frame with all columns from the original file, with BED coordinates converted to 1-based if applicable

Author(s)

G Yu

Examples

peakfile <- system.file("extdata", "sample_peaks.txt", package="ChIPseeker")
peak.gr <- readPeakFile(peakfile, as="GRanges")
peak.gr

## Read a BED file
## peak.gr <- readPeakFile("peaks.bed", as="GRanges")

## Read with custom parameters
## peak.df <- readPeakFile("peaks.txt", as="data.frame", sep="\t")

Description

The function renames metadata columns in GRanges objects by converting them to a data.frame, applying the dplyr rename operation, and converting back to GRanges. This allows renaming any metadata column while preserving all genomic range information.

Usage

## S3 method for class 'GRanges'
rename(x, ...)

Arguments

Details

This function extends dplyr::rename() to work with GRanges objects, allowing users to rename metadata columns using familiar dplyr syntax while preserving the GRanges structure.

The function performs the following steps:

1. Converts GRanges to data.frame using as.data.frame()

2. Applies dplyr::rename() with the provided name mappings

3. Converts back to GRanges using makeGRangesFromDataFrame() with keep.extra.columns=TRUE

All genomic range information (seqnames, ranges, strand) is preserved. Only metadata columns are renamed; standard GRanges columns (seqnames, start, end, width, strand) cannot be renamed through this function.

Value

GRanges object with renamed metadata columns. All genomic range information and other metadata columns are preserved unchanged

Examples

## Not run: 
## Rename a single column
peak.gr <- peak.gr %>% rename(geneSymbol = SYMBOL)

## Rename multiple columns
peak.gr <- peak.gr %>%
  rename(
    geneSymbol = SYMBOL,
    geneName = GENENAME,
    distance = distanceToTSS
  )

## Rename to remove spaces or special characters
peak.gr <- peak.gr %>% rename(gene_id = "gene Id")

## End(Not run)

Description

The function maps genomic regions to genes through three mechanisms:

1. Host genes: Regions that overlap with exons or introns of genes. These are genes that directly contain the genomic regions

2. Proximal genes: Regions located within the promoter region (TSS region) of genes. These are genes whose transcription start sites are near the genomic regions

3. Flanking genes: Regions located within a specified distance from genes but outside the promoter region. These are nearby genes that may be regulated via cis-regulatory mechanisms

The function returns a vector of unique gene IDs that can be used for downstream functional enrichment analysis (e.g., GO, KEGG, Reactome pathway analysis).

Usage

seq2gene(seq, tssRegion, flankDistance, TxDb, sameStrand = FALSE)

Arguments

Details

This function associates genomic regions (e.g., ChIP-seq peaks, enhancers, regulatory elements) with coding genes in a many-to-many mapping. It is designed to link both coding and non-coding genomic regions to coding genes to facilitate functional enrichment analysis.

The function performs the following steps:

1. Identifies host genes by finding overlaps with exons and introns using getGenomicAnnotation.internal()

2. Extracts gene IDs from overlapping exons and introns, converting transcript-based IDs to gene IDs

3. Finds the nearest gene to each region using getNearestFeatureIndicesAndDistances()

4. Categorizes nearest genes into:

   • Promoter genes: genes where the distance falls within tssRegion

   • Flanking genes: genes where the absolute distance is less than flankDistance but outside tssRegion

5. Combines all gene IDs (host, promoter, and flanking) and returns unique gene IDs

This many-to-many mapping allows a single genomic region to be associated with multiple genes (e.g., overlapping multiple genes or having multiple nearby genes), and a single gene can be associated with multiple genomic regions.

Value

Character vector of unique gene IDs. The vector contains gene IDs from:

• Host genes (regions overlapping exons/introns)

• Proximal genes (regions within TSS region)

• Flanking genes (regions within flankDistance but outside TSS region)

The gene IDs are typically Entrez IDs (for TxDb) or gene_id (for EnsDb), and can be used directly for functional enrichment analysis with packages like clusterProfiler, DOSE, or ReactomePA

Author(s)

Guangchuang Yu

See Also

annotatePeak for detailed peak annotation, getNearestFeatureIndicesAndDistances for finding nearest features

Examples

## Not run: 
library(TxDb.Hsapiens.UCSC.hg19.knownGene)
TxDb <- TxDb.Hsapiens.UCSC.hg19.knownGene
file <- getSampleFiles()[[1]] # a bed file
gr <- readPeakFile(file)
genes <- seq2gene(gr, tssRegion=c(-1000, 1000), flankDistance = 3000, TxDb)

## Use the gene IDs for enrichment analysis
## library(clusterProfiler)
## ego <- enrichGO(gene = genes, OrgDb = org.Hs.eg.db, ont = "BP")

## End(Not run)

Description

The function generates a null distribution for permutation testing by randomly repositioning peaks within their respective chromosomes. It maintains:

• The number of peaks per chromosome

• The width of each peak

• The chromosome assignment

Usage

shuffle(peak.gr, TxDb)

Arguments

Details

This function randomly shuffles peak positions across chromosomes while preserving the original peak widths and chromosome distribution.

The shuffling process:

1. Groups peaks by chromosome

2. For each chromosome, randomly samples new start positions from the valid range (1 to chromosome length - peak width)

3. Creates new GRanges with shuffled positions but original widths

4. Sets strand to "*" (unstranded)

This is used in permutation testing to generate null distributions for statistical significance testing.

Value

GRanges object with shuffled peak positions. Peaks are randomly repositioned within their chromosomes, maintaining original widths and chromosome distribution

Author(s)

G Yu

Description

The function allows subsetting of csAnno objects using the same syntax as subsetting GRanges objects. It filters the peaks in the anno slot and automatically updates:

• The detailGenomicAnnotation data frame to match the filtered peaks

• The annoStat annotation statistics

• The peakNum total peak count

Usage

## S3 method for class 'csAnno'
subset(x, ...)

Arguments

Details

This function subsets a csAnno object by filtering peaks based on logical conditions, and automatically updates the associated annotation statistics and detail annotations.

The function:

1. Creates an index based on chromosome, start, and end positions of all peaks

2. Subsets the GRanges object in the anno slot using the provided conditions

3. Filters the detailGenomicAnnotation data frame to keep only rows corresponding to the remaining peaks

4. Recalculates annotation statistics using getGenomicAnnoStat()

5. Updates the peak count

The tssRegion, level, and hasGenomicAnnotation slots remain unchanged.

Value

A csAnno object containing only the filtered peaks, with updated annotation statistics and detail annotations

Author(s)

G Yu

Examples

## Not run: 
## Subset peaks by annotation type
peakAnno_promoter <- subset(peakAnno, annotation == "Promoter")

## Subset peaks by distance to TSS
peakAnno_near <- subset(peakAnno, abs(distanceToTSS) < 5000)

## Subset by multiple conditions
peakAnno_filtered <- subset(peakAnno,
                             annotation == "Promoter" &
                             abs(distanceToTSS) < 3000)

## End(Not run)

Description

plot the heatmap of tagMatrix

Usage

tagHeatmap(
  tagMatrix,
  xlab = "",
  ylab = "",
  title = NULL,
  palette = "RdBu",
  nrow = NULL,
  ncol = NULL
)

Arguments

Value

figure

Author(s)

G Yu

Description

The function creates an UpSet plot (an alternative to Venn diagrams) that shows how peaks are distributed across different combinations of genomic annotations. It displays:

• The frequency of each annotation combination (intersection)

• Which annotations are present in each combination

• Optionally, a vennpie plot overlay showing the overall annotation distribution

Usage

upsetplot.csAnno(
  x,
  order_by = "freq",
  vennpie = FALSE,
  vp = list(x = 0.6, y = 0.7, width = 0.8, height = 0.8)
)

Arguments

Details

This function visualizes the combinations of genomic annotations (e.g., Promoter, Exon, Intron, UTR) that peaks can have, using an UpSet plot to show set intersections and their frequencies.

The function performs the following steps:

1. Extracts the detailGenomicAnnotation data frame from the csAnno object, which contains logical columns indicating which annotations each peak has

2. Converts the annotation matrix into a list format where each peak is represented by the set of annotations it has

3. Creates an UpSet plot using ggupset showing:

   • Left panel: bar chart of intersection sizes (frequencies)

   • Top panel: bar chart showing individual set sizes

   • Bottom panel: matrix showing which sets are included in each intersection

4. Optionally overlays a vennpie plot if vennpie=TRUE

UpSet plots are particularly useful when there are many annotation categories and peaks can have multiple annotations simultaneously (e.g., a peak can be both in a Promoter and overlap an Exon).

Value

A ggplot2 object (or combined plot if vennpie=TRUE) showing the UpSet visualization. The plot can be further customized using ggplot2 functions or printed directly

Author(s)

Guangchuang Yu

See Also

vennpie for the vennpie plot function, plotAnnoBar for bar plots of annotation distribution

Examples

## Not run: 
require(TxDb.Hsapiens.UCSC.hg19.knownGene)
txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene
peakfile <- system.file("extdata", "sample_peaks.txt", package="ChIPseeker")
peakAnno <- annotatePeak(peakfile, TxDb=txdb)

## Basic UpSet plot
upsetplot(peakAnno)

## UpSet plot with vennpie overlay
upsetplot(peakAnno, vennpie=TRUE)

## Order by degree instead of frequency
upsetplot(peakAnno, order_by="degree")

## End(Not run)

Description

The function visualizes the genomic annotation of peaks using a nested pie chart approach. It displays three concentric pie charts showing:

• Outer ring: Genic vs Intergenic distribution

• Middle ring: Breakdown of Genic (Intron, Exon) and Intergenic (Upstream, Downstream, Distal Intergenic) categories

• Inner ring: Further breakdown showing Exon and Downstream regions in detail

This visualization helps understand the overlap between different annotation categories, as peaks can be annotated with multiple features simultaneously.

Usage

vennpie(x, r = 0.2, cex = 1.2, ...)

Arguments

Details

This generic function creates a nested pie chart (venn diagram style) visualization showing the distribution of peaks across different genomic annotation categories, with hierarchical nesting to show overlapping annotations.

Value

A plot showing nested pie charts with genomic annotation distribution

See Also

plotAnnoBar plotAnnoPie for alternative visualization methods

Description

The function visualizes the genomic annotation of peaks using a nested pie chart approach. It displays three concentric pie charts showing:

• Outer ring: Genic vs Intergenic distribution

• Middle ring: Breakdown of Genic (Intron, Exon) and Intergenic (Upstream, Downstream, Distal Intergenic) categories

• Inner ring: Further breakdown showing Exon and Downstream regions in detail

This visualization helps understand the overlap between different annotation categories, as peaks can be annotated with multiple features simultaneously (e.g., a peak can be both in an Exon and in a Promoter region).

Usage

vennpie.csAnno(x, r = 0.2, cex = 1.2, col = NULL)

Arguments

Details

This function creates a nested pie chart (venn diagram style) visualization showing the distribution of peaks across different genomic annotation categories, with hierarchical nesting to show overlapping annotations.

The function performs the following steps:

1. Extracts detailed genomic annotation from the csAnno object

2. Calculates counts for each annotation category:

   • Genic: peaks overlapping exons or introns

   • Intergenic: peaks not in genic regions

   • Exon: peaks overlapping exons

   • Intron: peaks overlapping introns

   • Upstream: peaks in promoter regions with negative distance to TSS

   • Downstream: peaks downstream of genes

   • Distal Intergenic: intergenic peaks far from genes

3. Creates three nested floating pie charts using floating.pie() from the plotrix package

4. Adds a legend showing all annotation categories with their colors

The function uses pseudo-counts (+1) for each category to ensure proper visualization even when some categories have zero counts, preventing color mismatches in the pie charts.

Value

No return value. Creates a plot showing nested pie charts of genomic annotation distribution

Author(s)

G Yu

See Also

plotAnnoPie for a simple pie chart, plotAnnoBar for a bar chart visualization

Examples

## Not run: 
require(TxDb.Hsapiens.UCSC.hg19.knownGene)
txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene
peakfile <- system.file("extdata", "sample_peaks.txt", package="ChIPseeker")
peakAnno <- annotatePeak(peakfile, TxDb=txdb)

## Create venn pie chart
vennpie(peakAnno)

## Customize colors
vennpie(peakAnno, col=c(Exon="red", Intron="blue"))

## Adjust size and legend
vennpie(peakAnno, r=0.3, cex=1.5)

## End(Not run)

Description

The function calculates all possible intersections between sets using the overlap() function, then visualizes the results as a Venn diagram. It supports three plotting backends, each with different features:

• gplots: Default method, produces simple black-and-white Venn diagrams using the gplots package

• ggVennDiagram: Produces colorful, customizable Venn diagrams using ggplot2, allowing full control over colors, labels, and styling

• Vennerable: Alternative method using the Vennerable package (requires installation from R-Forge)

Usage

vennplot(Sets, by = "gplots", ...)

Arguments

Details

This function creates Venn diagrams to visualize overlaps between multiple sets of objects (e.g., peaks, genes, genomic regions). It supports three different plotting methods with different features and customization options.

The function performs the following steps:

1. Validates input: ensures the list is named (auto-generates names if missing, e.g., "Set1", "Set2", ...)

2. Calculates all possible intersections using overlap(), which handles both vectors and GRanges objects

3. Creates the Venn diagram using the specified method:

   • gplots: Uses plot.venn() with a matrix format

   • ggVennDiagram: Passes sets directly to ggVennDiagram::ggVennDiagram() with additional parameters

   • Vennerable: Creates a Venn object and plots it

For GRanges objects, the function uses set intersection to find overlapping genomic regions. For vectors, it uses standard set intersection.

Value

A Venn diagram plot. The return type depends on the by parameter:

• gplots: Base R plot (invisible return)

• ggVennDiagram: ggplot2 object that can be further customized

• Vennerable: Grid plot (invisible return)

Author(s)

G Yu

See Also

overlap for calculating set intersections, vennplot.peakfile for a convenience function for peak files

Examples

## Not run: 
require(TxDb.Hsapiens.UCSC.hg19.knownGene)
txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene
peakfiles <- getSampleFiles()
peakAnnoList <- lapply(peakfiles, annotatePeak, TxDb=txdb)
names(peakAnnoList) <- names(peakfiles)

## Compare genes from different peak files
genes <- lapply(peakAnnoList, function(i) as.data.frame(i)$geneId)
vennplot(genes)

## Use ggVennDiagram for customizable plot
vennplot(genes, by="ggVennDiagram", show_percentage=TRUE)

## Compare GRanges objects directly
peaks <- lapply(peakfiles, readPeakFile)
names(peaks) <- names(peakfiles)
vennplot(peaks)

## End(Not run)

Description

The function simplifies the workflow of comparing multiple peak files by automatically reading the files and setting up the Venn diagram. It loads each peak file using readPeakFile(), optionally labels them, and then calls vennplot() to create the visualization.

Usage

vennplot.peakfile(files, labels = NULL)

Arguments

Details

This is a convenience function that reads peak files and creates a Venn diagram showing the overlap of genomic regions between different peak sets.

The function:

1. Reads each peak file using readPeakFile() (converts to GRanges)

2. Generates labels from filenames if not provided (removes file extensions)

3. Names the peak list with the labels

4. Calls vennplot() to create the Venn diagram

This is particularly useful for quickly comparing multiple ChIP-seq peak files to see how many peaks are shared between experiments.

Value

A Venn diagram plot showing the overlap of peaks between different files. The plot is created using the default method (by="gplots"). See vennplot for details on the return type

Author(s)

G Yu

See Also

vennplot for the main plotting function, readPeakFile for reading peak files

Examples

## Not run: 
## Compare multiple peak files
peakfiles <- c("sample1.bed", "sample2.bed", "sample3.bed")
vennplot.peakfile(peakfiles)

## With custom labels
vennplot.peakfile(peakfiles, labels=c("Treatment", "Control", "Input"))

## Using getSampleFiles()
files <- getSampleFiles()
vennplot.peakfile(files)

## End(Not run)