plotDI {diffHic} | R Documentation

## Construct a plaid plot of differential interactions

### Description

Plot differential interactions in a plaid format with informative coloring.

### Usage

    plotDI(data, fc, first.region, second.region=first.region, col.up="red",
        col.down="blue", background="grey70", zlim=NULL, xlab=NULL, ylab=NULL,
        diag=TRUE, ...)

    rotDI(data, fc, region, col.up="red", col.down="blue", background="grey70",
        zlim=NULL, xlab=NULL, max.height=NULL, ylab="Gap", ...)

### Arguments

`data` | an InteractionSet object
`fc` | a numeric vector of log-fold changes
`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
`col.up` | any type of R color to describe the maximum color for positive log-fold changes
`col.down` | any type of R color to describe the maximum color for negative log-fold changes
`background` | any type of R color, specifying the background color of the interaction space
`zlim` | a numeric scalar indicating the maximum absolute log-fold change
`xlab` | character string for the x-axis label on the plot, defaults to the first chromosome name
`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 second chromosome name in `plotDI`
`diag` | a logical scalar specifying whether boxes should be shown above the diagonal for intra-chromosomal plots in `plotDI`
`...` | other named arguments to be passed to `plot`

### Details

The `plotDI` function constructs a plaid plot on the current graphics device. The intervals of `first.region` and `second.region` are represented by the x- and y-axes, respectively. Each bin pair is represented by a box in the plotting space, where each side of the box represents a bin. Plotting space that is not covered by any bin pair is shown in `background`.

The color of the box depends on the magnitude and sign of the log-fold change in `fc`. Positive log-FCs will range from white to `col.up`, whereas negative log-FCs will range from white to `col.down`. The chosen color is proportional to the magnitude of the log-FC, and the most extreme colors are only obtained at the maximum absolute log-FC in `fc`. The maximum value can be capped at `zlim` for better resolution of small log-FCs.

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 `rotDI` function constructs a rotated plot of differential interactions, for visualization of local changes. See `rotPlaid` for more details.

### Value

A (rotated) plaid plot of differential interactions is produced on the current graphics device. A function is also invisibly returned that converts log-FCs into colors. This is useful for coordinating the colors, e.g., when constructing a separate color bar.

### Author(s)

Aaron Lun

### References

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

### See Also

`plotPlaid`, `rotPlaid`, `squareCounts`

### Examples

    # Setting up the objects.
    a <- 10
    b <- 20
    regions <- GRanges(rep(c("chrA", "chrB"), c(a, b)), IRanges(c(1:a, 1:b), c(1:a, 1:b)),
        seqinfo=Seqinfo(seqlengths=c(chrA=a, chrB=b), seqnames=c("chrA", "chrB")))

    set.seed(3423)
    all.anchor1 <- sample(length(regions), 500, replace=TRUE)
    all.anchor2 <- as.integer(runif(500, 1, all.anchor1+1))
    out <- InteractionSet(matrix(0, 500, 1), colData=DataFrame(lib.size=1000),
            GInteractions(anchor1=all.anchor1, anchor2=all.anchor2,
                regions=regions, mode="reverse"), metadata=List(width=1))
    fc <- runif(nrow(out), -2, 2)

    # Constructing intra-chromosomal DI plots around various regions
    plotDI(out, fc, first.region=GRanges("chrA", IRanges(1, 10)),
        second.region=GRanges("chrA", IRanges(1, 10)), diag=TRUE)
    plotDI(out, fc, first.region=GRanges("chrA", IRanges(1, 10)),
        second.region=GRanges("chrA", IRanges(1, 10)), diag=FALSE)

    # Constructing inter-chromosomal DI plots around various regions
    xxx <- plotDI(out, fc, first.region=GRanges("chrB", IRanges(1, 10)),
        second.region=GRanges("chrA", IRanges(1, 20)), diag=TRUE)
    plotDI(out, fc, first.region=GRanges("chrB", IRanges(1, 100)),
        second.region=GRanges("chrA", IRanges(1, 200)), diag=TRUE, zlim=5)

    # Making colorbars.
    xxx((-10):10/10)
    xxx((-20):20/20)

    # Rotated.
    rotDI(out, fc, region=GRanges("chrA", IRanges(1, 200)))
    rotDI(out, fc, region=GRanges("chrB", IRanges(1, 200)))

[Package diffHic version 1.20.0 Index]