Plot a Genomic Region showing HiC, Features, Genes and Coverage

Source: R/plotHFGC.R

Plot a region with showing HiC, Features, Genes and Coverage

plotHFGC(
  gr,
  hic,
  features,
  genes,
  coverage,
  annotation,
  zoom = 1,
  shift = 0,
  max = 1e+07,
  axistrack = TRUE,
  cytobands,
  covtype = c("l", "heatmap"),
  linecol = c(),
  gradient = grDevices::hcl.colors(101, "viridis"),
  hiccol = list(anchors = "lightblue", interactions = "red"),
  featcol,
  genecol,
  annotcol,
  highlight = "blue",
  hicsize = 1,
  featsize = 1,
  genesize = 1,
  covsize = 4,
  annotsize = 0.5,
  hicname = "HiC",
  featname = "Features",
  featstack = c("full", "hide", "dense", "squish", "pack"),
  collapseTranscripts = "auto",
  maxTrans = 12,
  ylim = NULL,
  ...,
  fontsize = 12,
  cex.title = 0.8,
  rotation.title = 0,
  col.title = "white",
  background.title = "lightgray",
  title.width = 1.5
)

Arguments

gr

The range(s) of interest. Must be on a single chromosome

hic

Any HiC interactions to be included as a GenomicInteractions object. If not supplied, no HiC track will be drawn.

features

A named GRangesList or list of GRangesList objects. Each GRangesList should contain features in each element which will drawn on the same track. If providing a list, each GRangesList within the list will drawn on a separate track. If this argument is not specified, no feature track will be drawn. Features will be drawn with colours provided in featcol.

genes

A GRanges object with exon structure for each transcript/gene. If not included, no track will be drawn for gene/transcript structure. The expected mcols in this object are type, gene, exon transcript and symbol. See data(ex_trans) for an example.

coverage

A named list of BigWigFileList objects containing the primary tracks to show coverage for. Each list element will be drawn on a separate track, with elements within each BigWigFileList shown on the same track. List names will become track names. Alternatively, a single BigWigFileList will plot all individual files on separate tracks. If not included, no coverage tracks will be drawn.

annotation

Annotations for the coverage track(s). A single GRangesList if coverage is a BigWigListList. If coverage is supplied as a list of BigWigFileLists, a named list of GRangesList objects for each coverage track being annotatated. Names must match those given for coverage.

zoom

Multiplicative factor for zooming in and out

shift

Shift the plot. Applied after zooming

max

The maximum width of the plotting region. Given that the width of the final plotting window will be determined by any HiC interactions, this argument excludes any interactions beyond this distance. Plotting can be somewhat slow if any long range interactions are included. Ignored if no HiC interactions are supplied.

axistrack

logical. Add an AxisTrack()

cytobands

Cytogenetic bands to be displayed on each chromosome. See data('grch37.cytobands') for the correct format. Only drawn if a cytobands data.frame is provided.

covtype

The plot type for coverage. Currently only lines ("l") and heatmaps ("heatmap") are supported

linecol

If passing a BigWigFileList to coverage, a vector of colours. If passing a list of BigWigFileList objects to coverage, a list of colours with structure that matches the object being passed to coverage, i.e. a named list of the same length, with elements who's length matches each BigWigFileList. Only used if covtype = "l".

gradient

Colour gradient for heatmaps

hiccol

list with names "anchors" and "interactions". Colours are passed to these elements

featcol

Named vector (or list) of colours for each feature. Must be provided if drawing features

genecol

Named vector (or list) of colours for each gene category

annotcol

Colours matching the coverage annotations

highlight

Outline colour for the highlight track. Setting this to NULL will remove the highlight

hicsize, featsize, genesize, covsize, annotsize

Relative sizes for each track (hic, features, genes, coverage & annotation)

hicname, featname

Names displayed in the LHS panel

featstack

Stacking for the fature track

collapseTranscripts

Passed to GeneRegionTrack for the genes track. Defaults to "auto" for automatic setting. If the number of transcripts to be plotted is > maxtrans, the argument will be automatically set to "meta", otherwise this will be passed as FALSE which will show all transcripts.

maxTrans

Only used if collapseTranscripts is set to "auto".

ylim

If a numeric vector, this will be passed to all coverage tracks. Alternatively, a named list of y-limits for each coverage track with names that match those in each element of the coverage list.

...

Passed to DataTrack for the coverage tracks only. Useful arguments may be things like legend

fontsize

Applied across all tracks

cex.title

Passed to all tracks

rotation.title

Passed to all tracks

col.title

Passed to all tracks

background.title

Passed to all tracks

title.width

Expansion factor passed to plotTracks, and used to widen the panels on the LHS of all tracks. Can have unpredictable effects on the font size of y-axis limits due to the algorithm applied by plotTracks

Value

A Gviz object

Details

Convenience function for plotting a common set of tracks. All tracks are optional. For more fine control, users are advised to simply use Gviz directly.

The primary tracks defined in this function are H (HiC), F (features), G (genes), and C (coverage). Axis and Ideogram tracks are an additional part of this visualisation, with the Ideogram also being optional

Use all tracks specific to this dataset to generate a simple visualisation. In descending order the tracks displayed will be:

  1. HiC Interactions (if supplied)

  2. Regulatory features

  3. Genes/genes

  4. Coverage tracks as supplied

All tracks are optional and will simply be omitted if no data is supplied. See individual sections below for a more detailed explanation of each track

If wanting a single track of genes, simply pass a GRanges object in the format specified for a GeneRegionTrack. Passing a GRangesList with the same format will yield an individual track for each list element, with each track shown by default as a separate colour. This can be used for showing Up/Down-regulated genes, or Detected/Undetected genes.

If passing a BigWigFileList for the coverage track, each file within the object will be drawn on a separate track. If specified, the same y-limits will be applied to each track If passing a list of BigWigFileList objects, each list element will be drawn as a single track with the individual files within each BigWigFileList overlaid within each track.

Cytogenetic band information must be in the structure required by IdeogramTrack, with data for both GRCh37 and GRCh38 provided in this package (grch37.cytobands, grch38.cytobands).

A highlight overlay over the GRanges provided as the gr argument will be added if a colour is provided. If set to NULL, no highlight will be added.

Displaying HiC Interactions

The available arguments for displaying HiC Interactions are defined below. If hic is supplied, a single InteractionTrack will be added displaying all interactions with an anchor within the range specified by gr. Only interactions with an anchor explicitly overlapping gr will be shown. If no interactions are found within gr, the track will not be displayed. The plotting range will expand to incorporate these interactions, with the paramater max providing an upper limit on the displayed range.

hic

This is the GInteractions object required for inclusion of a HiC track in the final output. Will be ignored if not supplied

hiccol

Determines the colours used for display of anchors and interactions

hicsize

Relative size of the track compared to others

hicname

The name to display on the LHS panel

max

The maximum width of the plotted region. If multiple long-range interactions are identified, this provides an upper limit for the display. This defaults to 10Mb.

Displaying Features

If wanting to add an AnnotationTrack with regions defined as 'features', the following arguments are highly relevant. All are ignored if features is not provided.

features

A named GRangesList. Each element will be considered as a separate feature and drawn as a block in a distinct colour. Any mcols data will be ignored.

featcol

A named vector (or list) providing a colour for each element of features

featname

The name to display on the LHS panel

featstack

Stacking to be applied to all supplied features

featsize

Relative size of the track compared to others

Displaying Genes And Transcripts

To display genes or transcripts, simply provide a single GRanges object if you wish to display all genes on a single track. The mcols element of this object should contain the columns feature, gene, exon, transcript and symbol as seen on the GeneRegionTrack help page.

Alternatively, a GRangesList can be provided to display genes on separate tracks based on their category. This can be useful for separating and colouring Up/Down regulated genes in a precise way. All elements should be as described above. Again, all parameters associated with this track-set will be ignored of no object is supplied to this argument.

genes

A GRanges or GRangesList object as described above

genecol

A single colour if supplying a GRanges object, or a named vector/list of colours matching the GRangesList

genesize

Relative size of the track compared to others

collapseTranscripts

Passed to all tracks. See the GeneRegionTrack section in settings for detail regarding possible arguments. If genes is a GRangesList, can be a named vector/list with names matching the names of the genes object.

Displaying Coverage Tracks

This section contains the most flexibility and can take two types of input. The first option is a BigWigFileList, which will lead to each BigWig file being plotted on it's own track. An alternative is a list of BigWigFileList objects. In this case, each list element will be plotted as a separate track, with all individual BigWig files within each list element overlaid within the relevant track.

In addition to the coverage tracks, annotations can be added to each BigWigFileList in the form of coloured ranges, indicating anything of the users choice. Common usage may be to indicate regions with binding of a ChIP target is found to be detected, unchanged, gained or lost.

coverage

A BigWigFileList or list of BigWigFileList objects. A single BigWigFileList will be displayed with each individual file on a separate track with independent y-axes. Each element of the BigWigFileList must be named and these names will be displayed on the LHS panels A list of BigWigFileList objects will be displayed with each list element as a separate track, with any BigWig files overlaid using the same y-axis. The list must be named with these names displayed on the LHS panel. Each internal BigWig within a BigWigFileList must also be named.

covtype

Currently only lines (covtype = "l") and heatmaps (covtype = "heatmap") are supported. Colours can be specified using the arguments below

linecol

Can be a single colour applied to all tracks, or a named vector (or list) of colours. If coverage is a single BigWigFileList, these names should match the names of this object exactly. If coverage is a list of BigWigFileList objects, linecol should be a list with matching names. Each element of this list should also be a named vector with names that exactly match those of each corresponding BigWigFileList.

gradient

A colour gradient applied to all heatmap tracks. No specific structure is required beyond a vector of colours.

covsize

Relative size of the tracks compared to others

ylim

Can be a vector of length 2 applied to all coverage tracks. Alternatively, if passing a list of BigWigFlieList objects to the coverage argument, this can be a named list of numeric vectors with names matching coverage

annotation

Each BigWigFileList needs annotations to be passed to this argument as a named GRangesList, with names being used to associate unique colours with that set of ranges. If coverage is a BigWigFileList a simple GRangesList would be supplied and a single 'annotation' track will appear at the top of the set of coverage tracks. If coverage is a list, then a named list of GRangesList objects should be supplied, with each being displayed above the corresponding track from the coverage object.

annotcol

A vector of colours corresponding to all names within all GRangesList elements supplied as annotation. It is assumed that the same colour scheme will be applied to all annotation tracks and, as such, the colours should not be provided as a list which matches the coverage tracks. Instead, every named element anywhere in the annotation GRanges, across all of the tracks must be included as a colour

annotsize

Relative size of the tracks compared to others

Examples

# \donttest{
library(rtracklayer)
## Make sure we have the cytobands active
data(grch37.cytobands)

## Prepare the HiC, promoter & transcript information
data(ex_hic, ex_trans, ex_prom)
ex_features <- GRangesList(Promoter = ex_prom)
featcol <- c(Promoter = "red")

## Prepare the coverage
fl <- system.file(
"extdata", "bigwig", c("ex1.bw", "ex2.bw"), package = "extraChIPs"
)
bwfl <- BigWigFileList(fl)
names(bwfl)  <- c("ex1", "ex2")
bw_col <- c(ex1 = "#4B0055", ex2 = "#007094")

## Define the plotting range
gr <- GRanges("chr10:103862000-103900000")

## Now create the basic plot
plotHFGC(
  gr,
  hic = ex_hic, features = ex_features, genes = ex_trans, coverage = bwfl,
  featcol = featcol, linecol = bw_col, cytobands = grch37.cytobands
)


plotHFGC(
  gr,
  hic = ex_hic, features = ex_features, genes = ex_trans, coverage = bwfl,
  featcol = featcol, linecol = bw_col, cytobands = grch37.cytobands,
  maxTrans = 1
)

# }