Skip to contents

Easy Hi-C track visualization

Source: R/ez_hic.R
ez_hic.Rd

This function creates a Hi-C contact matrix visualization from various input types. It provides a high-level interface supporting both square heatmap and triangle (rotated) views commonly used in genome browsers.

Usage

ez_hic(
  data,
  region = NULL,
  gene = NULL,
  gene_db = NULL,
  org_db = NULL,
  extend = 0.1,
  extend_type = c("proportion", "bp"),
  resolution = 10000,
  style = c("triangle", "square"),
  palette = c("cooler", "ylgnbu", "viridis", "bwr"),
  transform = "identity",
  limits = NULL,
  max_distance = NULL,
  rasterize = FALSE,
  rasterize_dpi = 300,
  show_diagonal = TRUE,
  border = FALSE,
  label_chr = TRUE,
  ...
)

Arguments

data

Input data. Can be:

  • A matrix: Dense contact matrix

  • A data frame: Sparse format with (pos1, pos2, score) or (bin1, bin2, score)

  • A file path: Tab-delimited matrix file

region

Genomic region to display (e.g., "chr1:1000000-2000000"). Either region or gene (with gene_db) must be provided.

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".

resolution

Resolution of the Hi-C data in base pairs (default: 10000)

style

Visualization style: "triangle" (default, rotated view) or "square"

palette

Color palette: "cooler" (red, default), "ylgnbu", "viridis", or "bwr"

transform

Scale transformation: "identity" (linear), "log10" (default), "log2", "sqrt"

limits

Numeric vector of length 2 for color scale limits (default: NULL, auto)

max_distance

Maximum interaction distance to show in base pairs (default: NULL, show all). Only applies to triangle style.

rasterize

Logical. If TRUE and ggrastr package is available, rasterize the Hi-C layer for better performance with large matrices. Default: FALSE

rasterize_dpi

Resolution for rasterization in dots per inch. Default: 300

show_diagonal

Logical. If TRUE, show the diagonal (self-interactions). Default: TRUE

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_hic or geom_hic_triangle

Value

A ggplot2 object

Examples

if (FALSE) { # \dontrun{
# Create example data
mat <- matrix(runif(2500), nrow = 50)
mat <- mat + t(mat)  # Make symmetric
diag(mat) <- diag(mat) * 2  # Stronger diagonal

# Triangle view (default)
ez_hic(mat, "chr1:1000000-1500000", resolution = 10000)

# Square heatmap view
ez_hic(mat, "chr1:1000000-1500000", resolution = 10000, style = "square")

# With log10 transformation and custom palette
ez_hic(mat, "chr1:1000000-1500000",
  resolution = 10000,
  trans = "log10",
  palette = "ylgnbu"
)

# Limit maximum distance shown
ez_hic(mat, "chr1:1000000-1500000",
  resolution = 10000,
  max_distance = 200000
)

# With rasterization for large regions
ez_hic(mat, "chr1:1000000-1500000",
  resolution = 10000,
  rasterize = TRUE,
  rasterize_dpi = 300
)

# Using gene name for region lookup
library(TxDb.Hsapiens.UCSC.hg38.knownGene)
ez_hic(hic_data, gene = "PTPRC", gene_db = TxDb.Hsapiens.UCSC.hg38.knownGene)
} # }