Skip to contents

gghic

Source: R/gghic.R
gghic.Rd

A ggplot2 wrapper of geom_hic(), geom_ideogram(), geom_annotation(), geom_track(), geom_tad(), and geom_loop() for easy visualisation of Hi-C/-like data.

Usage

gghic(
  data = NULL,
  score_column = "balanced",
  scale_method = log10,
  ideogram = FALSE,
  ideogram_width_ratio = 1/30,
  ideogram_fontsize = 10,
  ideogram_colour = "red",
  ideogram_fill = "#FFE3E680",
  annotation = FALSE,
  annotation_width_ratio = 1/50,
  annotation_spacing_ratio = 1/3,
  annotation_fontsize = 10,
  annotation_colour = "#48CFCB",
  annotation_fill = "#48CFCB",
  track = FALSE,
  track_width_ratio = 1/20,
  track_spacing_ratio = 1/2,
  track_fill = "black",
  track_fontsize = 5,
  tad = FALSE,
  tad_is_0based = FALSE,
  tad_colour = "grey",
  loop = FALSE,
  loop_is_0based = FALSE,
  loop_colour = "black",
  loop_fill = NA,
  concatemer = FALSE,
  concatemer_width_ratio = 1/100,
  concatemer_spacing_ratio = 1/5,
  expand_xaxis = FALSE,
  expand_left = NULL,
  expand_right = NULL,
  ...
)

Arguments

data

Either a HiCExperiment object, or a GInteractions object, or a tibble/data.frame.

score_column

The column name of which the score is calculated. Default is "balanced".

scale_method

The function to scale the score. Default is log10.

ideogram

Whether to add ideogram or not. Default is FALSE.

ideogram_width_ratio

The width ratio of the ideogram. Default is 1/30.

ideogram_fontsize

The font size of the ideogram. Default is 10.

ideogram_colour

The color of the ideogram. Default is "red".

ideogram_fill

The fill color of the highlighted region on the ideogram. Default is "#FFE3E680".

annotation

Whether to add annotation or not. Default is FALSE.

annotation_width_ratio

The width ratio of the annotation. Default is 1/50.

annotation_spacing_ratio

The spacing ratio of the annotation. Default is 1/3.

annotation_fontsize

The font size of the annotation. Default is 10.

annotation_colour

The color of the annotation. Default is "#48CFCB".

annotation_fill

The fill color of the annotation. Default is "#48CFCB".

track

Whether to add track or not. Default is FALSE.

track_width_ratio

The width ratio of the track. Default is 1/20.

track_spacing_ratio

The spacing ratio of the track. Default is 1/2.

track_fill

The fill color of the track. Default is "black".

track_fontsize

The font size of the track. Default is 5.

tad

Whether to add TAD or not. Default is FALSE.

tad_is_0based

Whether the TAD coordinates are 0-based or not. Default is FALSE.

tad_colour

The color of the TAD. Default is "grey".

loop

Whether to add loop or not. Default is FALSE.

loop_is_0based

Whether the loop coordinates are 0-based or not. Default is FALSE.

loop_colour

The color of the loop. Default is "black".

loop_fill

The fill color of the loop. Default is NA.

concatemer

Whether to add concatemer or not. Default is FALSE.

concatemer_width_ratio

The width ratio of the concatemer. Default is 1/100.

concatemer_spacing_ratio

The spacing ratio of the concatemer. Default is 1/5.

expand_xaxis

Whether to expand the x-axis or not. Default is FALSE.

expand_left

The left expansion of the x-axis. Default is NULL.

expand_right

The right expansion of the x-axis. Default is NULL.

...

Arguments passed on to geom_tad, geom_loop, geom_hic, geom_ideogram, geom_annotation, geom_track, geom_tad, geom_loop

tad_path

A path to the TAD file. Default is NULL.

tad_gis

An InteractionSet object of TADs. Default is NULL.

is_0based

Whether the TAD file is 0-based or not. Default is FALSE.

colour

The color of the TADs. Default is grey.

mapping

Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.

stat

The statistical transformation to use on the data for this layer. When using a geom_*() function to construct a layer, the stat argument can be used the override the default coupling between geoms and stats. The stat argument accepts the following:

  • A Stat ggproto subclass, for example StatCount.

  • A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count".

  • For more information and other ways to specify the stat, see the layer stat documentation.

position

A position adjustment to use on the data for this layer. This can be used in various ways, including to prevent overplotting and improving the display. The position argument accepts the following:

  • The result of calling a position function, such as position_jitter(). This method allows for passing extra arguments to the position.

  • A string naming the position adjustment. To give the position as a string, strip the function name of the position_ prefix. For example, to use position_jitter(), give the position as "jitter".

  • For more information and other ways to specify the position, see the layer position documentation.

na.rm

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.

show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.

inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().

loop_path

A path to the loop file. Default is NULL.

loop_gis

An InteractionSet object of loops. Default is NULL.

shape

The shape of the loops. Default is 21.

fill

The fill color of the loops. Default is NA.

size

The size of the loops. Default is NULL. If NULL, the size is grid::unit(1 / 80, "native").

linewidth

The line width of the loops. Default is 1.

rasterize

Whether to rasterize the plot or not. Default is FALSE.

dpi

The resolution of the rasterised plot. Default is 300.

dev

The device to rasterise the plot. Default is "cairo".

scale

The scale of the rasterised plot. Default is 1.

draw_boundary

Whether to draw the boundary line or not when plotting multiple chromosomes. Default is TRUE.

boundary_colour

The color of the boundary line. Default is "black".

linetype

The line type of the boundary line. Default is "dashed".

genome

The genome name. Default is "hg19".

chrom_prefix

Whether the input data has chromosome names with prefix 'chr' or not. Default is TRUE.

highlight

Whether to highlight the boundary of the chromosome. Default is TRUE.

length_ratio

The ratio of the length of each chromosome ideogram relative to the width of the Hi-C plot. Default is 0.8.

txdb

The TxDb object. Default is NULL.

tx2gene

An optional data frame or tibble that maps transcript information to gene information. It should include the following columns:

  • chrom: Chromosome number or name.

  • gene_id: Entrez gene ID.

  • gene_symbol: Common symbol or name of the gene.

  • tx_id: Entrez transcript ID.

  • tx_name: Name of the transcript.

  • gene_type: Type or classification of the gene.

  • tx_type: Type or classification of the transcript.

gtf_path

The path to the GTF file, which is used to generate txdb and tx2gene. Generated files are saved in the cache directory. Default is NULL.

maxgap

The maximum gap between genes to be drawn in the same line. Default is -1.

include_ncrna

Whether to include ncRNA or not. Default is TRUE.

style

The style of the gene model track, which can be "basic" or "arrow". Default is "basic".

gene_symbols

A character vector of gene symbols to be included only. Default is NULL.

fontsize

The font size of the gene symbols. Default is 10.

data_paths

The paths to the sequencing data files. Default is NULL.

data_granges

The GRanges object of the sequencing data. Default is NULL.

data_range

The range of the x axis. It can be "auto", "maximum", or a number (vector). Default is "auto".

Value

A ggplot object.

Examples

if (FALSE) { # \dontrun{
library(gghic)
library(dplyr)
library(HiCExperiment)
library(InteractionSet)
library(scales)
library(scales)

dir_cache_gghic <- user_cache_dir(appname = "gghic")
url_file <- paste0(
  "https://raw.githubusercontent.com/mhjiang97/gghic-data/refs/heads/",
  "master/cooler/chr4_11-5kb.cool"
)
path_file <- file.path(dir_cache_gghic, "chr4_11-5kb.cool")
download.file(url_file, path_file)

hic <- path_file |>
  CoolFile() |>
  import()

gis <- interactions(hic)
gis$score <- log10(gis$balanced)
x <- as_tibble(gis)
scores <- x$score[pairdist(gis) != 0 & !is.na(pairdist(gis) != 0)]
scores <- scores[!is.na(scores) & !is.infinite(scores)]
x$score <- oob_squish(x$score, c(min(scores), max(scores)))

url_file <- paste0(
  "https://raw.githubusercontent.com/mhjiang97/gghic-data/refs/heads/",
  "master/gtf/gencode-chr4_11.gtf.gz"
)
path_gtf <- glue("{dir_cache_gghic}/gencode-chr4_11.gtf.gz")
download.file(url_file, path_gtf)

x |>
  filter(
    center1 > 10000000 & center1 < 11000000 &
      center2 > 10000000 & center2 < 11000000
  ) |>
  gghic(
    draw_boundary = TRUE,

    ideogram = TRUE, genome = "hg19", highlight = TRUE,
    ideogram_fontsize = 7, ideogram_width_ratio = 0.08,

    annotation = TRUE, include_ncrna = FALSE, gtf_path = path_gtf,
    style = "arrow", maxgap = 100000, annotation_fontsize = 5,
    annotation_width_ratio = 0.05,

    expand_xaxis = TRUE
  )
} # }