plotPlaid: Construct a plaid plot of interactions
In diffHic: Differential Analyis of Hi-C Data

Description Usage Arguments Details Value Author(s) References See Also Examples

Plot interactions between two sequences in a plaid format with informative coloring.

plotPlaid(file, param, first.region, second.region=first.region, width=10000, 
    col="black", max.count=20, xlab=NULL, ylab=NULL, diag=TRUE, count=FALSE, 
    count.args=list(), ...)

rotPlaid(file, param, region, width=10000, col="black", max.count=20, 
    xlab=NULL, max.height=NULL, ylab="Gap", ...)

`file`	character string specifying the path to an index file produced by `preparePairs`
`param`	a `pairParam` object containing read extraction parameters
`first.region`	a `GRanges` object of length 1 specifying the first region
`second.region`	a `GRanges` object of length 1 specifying the second region
`region`	a `GRanges` object of length 1 specifying the region of interest
`width`	an integer scalar specifying the width of each bin in base pairs
`col`	any type of R color to describe the color of the plot elements
`max.count`	a numeric scalar specifying the count for which the darkest color is obtained
`xlab`	character string for the x-axis label on the plot, defaults to the chromosome name of `first.region`
`max.height`	a numeric scalar indicating the y-axis limit for `rotPlaid`
`ylab`	character string for the y-axis label on the plot, defaults to the chromosome name of `second.regeion` in `plotPlaid`
`diag`	a logical scalar specifying whether boxes should be shown above the diagonal for intra-chromosomal plots in `plotPlaid`
`count`	a logical scalar specifying whether the count for each bin should be plotted in `plotPlaid`
`count.args`	a named list of arguments to be passed to `text` for plotting of bin counts, if `count=TRUE`
`...`	other named arguments to be passed to `plot`

The plotPlaid function constructs a plaid plot on the current graphics device. The intervals of the first.region and second.region are represented by the x- and y-axes, respectively. Each region is partitioned into bins of size width. Each bin pair is represented by a box in the plotting space, where each side of the box represents a bin. The color of the box depends on the number of read pairs mapped between the corresponding bins.

The resolution of colors can be controlled by varying max.count. All boxes with counts above max.count will be assigned the maximum intensity. Other boxes will be assigned a color of intensity proportional to the size of the count, such that a count of zero results in white space. Smaller values of max.count will improve contrast at low counts at the cost of contrast at higher counts. Scaling max.count is recommended for valid comparisons between libraries of different sizes (e.g., larger max.count for larger libraries).

If count=TRUE, the number of read pairs will be shown on top of each bin. This will be slower to plot but can be useful in some cases, e.g., when more detail is required, or when the range of colors is not sufficient to capture the range of counts in the data. If diag=TRUE, boxes will also be plotted above the diagonal for intra-chromosomal plots. This is set as the default to avoid confusion when first.region is not set as the anchor range, i.e., it has a lower sorting order than second.region. However, this can also be turned off to reduce redundancy in visualization around the diagonal.

The rotPlaid function constructs a plaid plot that has been rotated by 45 degrees. This is useful for visualizing local interactions within a specified region. In a rotated plot, the x-coordinate of a box in the plotting space represents the midpoint between two interacting bins, while the y-coordinate represents the distance between bins. More simply, the interacting bins of a box can be identified by tracing diagonals from the edges of the box to the x-axis.

By default, max.height is chosen to include the interaction between the boundaries region in rotPlaid. This is equivalent to the width of region. Smaller values can be chosen to focus on interactions closer to the diagonal. Larger values can also be used, but this is less useful as the interacting bins cannot be easily traced (as they will lie outside the x-axis limits).

Note that the plotted boxes for the bin pairs may overwrite the bounding box of the plot. This can be fixed by running box() after each plotPlaid call.

A (rotated) plaid plot is produced on the current graphics device. For both functions, a function is invisibly returned that converts counts into colors. This is useful for coordinating the colors, e.g., when constructing a separate color bar.

Aaron Lun

Lieberman-Aiden E et al. (2009). Comprehensive Mapping of Long-Range Interactions Reveals Folding Principles of the Human Genome. Science 326, 289-293.

preparePairs

hic.file <- system.file("exdata", "hic_sort.bam", package="diffHic")
originals <- readRDS(system.file("exdata", "cuts.rds", package="diffHic"))
param <- pairParam(originals)

# Setting up parameters
fout <- tempfile(fileext=".h5")
invisible(preparePairs(hic.file, param, fout))

# Constructing intra-chromosomal plaid plots around various regions.
plotPlaid(fout, param, first.region=GRanges("chrA", IRanges(1, 100)), 
    second.region=GRanges("chrA", IRanges(1, 200)), width=50, diag=TRUE)
box()
xxx <- plotPlaid(fout, param, first.region=GRanges("chrA", IRanges(1, 100)), 
    second.region=GRanges("chrA", IRanges(1, 200)), width=50, diag=FALSE)

# Making colorbars.
xxx(1:2)
xxx(1:5)
xxx(1:10)

# Constructing inter-chromosomal plaid plots around various regions
plotPlaid(fout, param, first.region=GRanges("chrB", IRanges(1, 100)), 
    second.region=GRanges("chrA", IRanges(1, 200)), width=50)
plotPlaid(fout, param, first.region=GRanges("chrB", IRanges(1, 100)), 
    second.region=GRanges("chrA", IRanges(1, 200)), width=100)

# For a hypothetical second library which is half the size of the previous one:
plotPlaid(fout, param, first.region=GRanges("chrB", IRanges(1, 100)),
    second.region=GRanges("chrA", IRanges(1, 200)), width=100, max.count=20, count=TRUE)
plotPlaid(fout, param, first.region=GRanges("chrB", IRanges(1, 100)),
    second.region=GRanges("chrA", IRanges(1, 200)), width=100, max.count=40,
    count=TRUE, count.args=list(col="blue"))

# Rotated plot.
rotPlaid(fout, param, region=GRanges("chrA", IRanges(1, 200)), width=50)
rotPlaid(fout, param, region=GRanges("chrA", IRanges(1, 200)), width=100)