Skip to contents

Create a feature track from genomic regions

Source: R/ez_feature.R
ez_feature.Rd

This function creates a feature track visualization from genomic regions, such as peaks or other genomic annotations. It can read directly from BED files or work with data frames containing genomic coordinates.

Usage

ez_feature(
  input,
  region = NULL,
  gene = NULL,
  gene_db = NULL,
  org_db = NULL,
  extend = 0.1,
  extend_type = c("proportion", "bp"),
  color = "black",
  fill = "gray70",
  alpha = 0.7,
  height = 0.8,
  use_score = FALSE,
  border = FALSE,
  label_chr = TRUE,
  ...
)

Arguments

input

Either a file path to a BED file or a data frame containing genomic coordinates with columns for chromosome, start, and end positions.

region

Genomic region to display in the format "chr:start-end". Either region or gene (with gene_db) must be provided. Example: "chr1:1000000-2000000"

gene

Gene name/symbol to look up (e.g., "PTPRC", "TP53"). When provided, the region is automatically determined from the gene coordinates in gene_db. Either region or gene must be provided.

gene_db

TxDb object for gene coordinate lookup when using gene parameter.

org_db

Optional OrgDb object for gene symbol mapping. If NULL (default), auto-detects available OrgDb packages.

extend

Numeric. Amount to extend the region beyond the gene body when using gene parameter. Default: 0.1 (10% of gene length on each side).

extend_type

How to interpret extend: "proportion" (relative to gene length) or "bp" (absolute base pairs). Default: "proportion".

color

Border color of the features. Default: "black"

fill

Fill color of the features. When use_score = TRUE, this will be used as the high value in the color gradient. Default: "gray70"

alpha

Transparency level of the features (0 = transparent, 1 = opaque). Default: 0.7

height

Height of the feature rectangles (0 to 1). Default: 0.8

use_score

Logical indicating whether to use the 'score' column for fill color. If TRUE, a gradient from white to the specified fill color will be used. Default: FALSE

border

Logical. If TRUE, adds a black border around the plot panel. Default: FALSE

label_chr

Logical. If TRUE (default), labels the x-axis with the chromosome name (e.g., "Chr1"). Set to FALSE to suppress the x-axis label.

...

Additional arguments passed to geom_feature()

Value

A ggplot2 object representing the feature track.

Details

The function automatically handles both file paths and data frames as input. When a file path is provided, it reads the BED file and creates the track. When a data frame is provided, it should contain at least 'chrom', 'start', and 'end' columns. If 'score' column is present and use_score = TRUE, features will be colored by their score values.

Examples

# From a data frame with uniform coloring
features <- data.frame(
  seqnames = c("chr1", "chr1", "chr1"),
  start = c(1000, 3000, 5000),
  end = c(2000, 4000, 6000),
  name = c("peak1", "peak2", "peak3"),
  score = c(10, 30, 50)
)
track <- ez_feature(
  features,
  "chr1:1-10000",
  fill = "darkgreen",
  alpha = 0.8
)
#> Warning: Ignoring unknown parameters: `height`