R: Plot gene and genome maps

plot_gene_map {genoPlotR}

R Documentation

Plot gene and genome maps

Description

This plotting function represents linearly DNA segments and their comparisons. It will plot one line per DNA segment, eventually separated by the comparisons. In addition, a tree can be plotted on the left of the plot, and annotations on the top row. Since this is a grid plot, it can be placed into other graphics, or modified subsequently.

Usage

plot_gene_map(dna_segs,
              comparisons = NULL,
              tree = NULL,
              tree_width = NULL,
              tree_branch_labels_cex = NULL,
              tree_scale = FALSE,
              legend = NULL, 
              annotations = NULL, 
              annotation_height = 1, 
              annotation_cex = 0.8, 
              seg_plots=NULL,    # user-defined plots
              seg_plot_height=3, # height of plots (in lines)
              seg_plot_height_unit="lines", # unit of preceding
              seg_plot_yaxis=3, # if non-null or non false, ticks
              seg_plot_yaxis_cex=scale_cex,
              xlims = NULL,
              offsets = NULL,
              minimum_gap_size = 0.05,
              fixed_gap_length = FALSE,
              limit_to_longest_dna_seg = TRUE,
              main = NULL, 
              main_pos = "centre", 
              dna_seg_labels = NULL, 
              dna_seg_label_cex=1,
              dna_seg_label_col="black",
              gene_type = NULL,
              arrow_head_len = 200,
              dna_seg_line = TRUE,
              scale = TRUE, 
              dna_seg_scale = !scale,
              n_scale_ticks=7,
              scale_cex=0.6,
              global_color_scheme = c("auto", "auto", "blue_red", 0.5),
              override_color_schemes = FALSE,
              plot_new=TRUE,
              debug = 0,
              ...)

Arguments

`dna_segs`	A list of `dna_seg` objects. Mandatory.
`comparisons`	A list of `comparison` objects. Optional.
`tree`	A tree, under the form of a `phylog` object. If specified, takes place at the left of the tags. See details below for more information.
`tree_width`	Numeric. The width of the tree area in the plot, in inches. By default, takes 20 percent of the total plot.
`tree_branch_labels_cex`	Numeric or `NULL` (default). If the tree provided contains node annotations, they will be displayed with this `cex`. If equal to 0, node annotations are not displayed.
`tree_scale`	Logical. Plot a scale for the tree? Default is FALSE.
`legend`	Yet unimplemented.
`annotations`	An `annotation` object or a list of annotation objects. See details. Optional.
`annotation_height`	Numeric. The height, in lines, of the annotation line. One by default, if `annotation is defined`.
`annotation_cex`	Numeric. The `cex` (i.e. the character expansion) of the annotation line.
`seg_plots`	A list of `seg_plot` objects of the length as `dna_segs`, a single `seg_plot` or `NULL` (default). To draw plots associated to a `dna_seg`. See `seg_plot` for more information and some examples.
`seg_plot_height`	The height of the `seg_plot` regions. By default, equals to 3 (lines, see next argument).
`seg_plot_height_unit`	The unit of the height of the `seg_plot` regions. Should be a valid `unit`. See the `grid` documentation for more information. If equals to "null", then the height will be calculated as a proportion of the comparison region (i.e. 0.5 means the `seg_plot` region will be half the size of the `comparison`.
`seg_plot_yaxis`	Can be `NULL`, `FALSE` or a numercic. In the first two cases, no y-axis is drawn for the `seg_plot`s. If numeric, a axis is drawn with approximately that number of ticks.
`seg_plot_yaxis_cex`	The character expansion of the `seg_plot_yaxis` labels. Equals to `scale_cex` by default.
`xlims`	A list with as many elements as there are `dna_seg`s, or `NULL`. If `NULL`, the whole segment will be represented. If a list, each element of the list is a numeric vector, representing pairs of left and right limits for each subsegment. See details.
`offsets`	A list or a vector with as many elements as there are `dna_seg`s, or `NULL`. If is a numeric vector, gives the offset of the first subsegment. If is a list, each element should have the same length as there are subsegments (see `xlims`). Gives then the length of each gap. If `NULL`, the size of the gaps is optimized to minimize the lengths of the comparisons. See details.
`minimum_gap_size`	A numeric. How much of the plotting region should a gap be, at least. Default is 0.05 (20% of the plotting region).
`fixed_gap_length`	Should the gaps have a fixed length? Otherwise, the gap length will be optimized to minimize the size of comparisons. `FALSE` by default.
`limit_to_longest_dna_seg`	A logical. Should the plot be restricted to the longest `dna_seg`? If no, the other segments can be extended to better fit comparisons.
`main`	A character. Main title of the plot.
`main_pos`	Position of the main title. One of `centre`, `left` or `right`.
`dna_seg_labels`	A character, same length as `dna_segs`. The names of the segments. If `NULL`, the names of `dna_segs` will be used, if available. Else, no name are plotted. If a `tree` is given, names must exist either in `dna_seg_labels` or in the names of `dna_segs`.
`dna_seg_label_cex`	A numeric. The character size for the DNA segments labels, or tree labels. Default is 1.
`dna_seg_label_col`	A color, of length 1 or of the same length as `dna_segs`. Gives the color of the labels. Default is black.
`gene_type`	A character. Describes the type of representation of genes or `dna_seg` elements. See details.
`arrow_head_len`	A numeric. Gives the length of arrow heads for gene type "arrows". The arrow head extends at maximum at half of the gene. Set to `Inf` to have all arrow heads covering the half of the gene. 200 by default.
`dna_seg_line`	A vector, either logical or giving colors, of length 1 or of same length as `dna_segs`. Should the line in the middle of the segments be drawn, and if yes, in what color. `TRUE` by default, which gives black lines. `FALSE` (logical, or as a string) results in no plotting.
`scale`	A logical. Should the scale be displayed on the plot. `TRUE` by default.
`dna_seg_scale`	A logical, of length one or of the same length as `dna_segs`. Should a scale be displayed below each or all dna segments, respectively. `!scale` by default.
`n_scale_ticks`	A integer. The (approximate) number of ticks on the longest segment. Default: 7.
`scale_cex`	A numeric. The character size for the scale labels. Default is 1.
`global_color_scheme`	A character of length 4. If no `col` column is present on any comparison or is `override_color_schemes` is set, apply a global color scheme over all comparions. See below for more details. `c("auto", "auto", "blue_red")` by default.
`override_color_schemes`	A logical. If `TRUE`, apply a global color scheme even if there are comparisons that have `col` columns. `FALSE` by default.
`plot_new`	Logical. Produce a new plot? If `TRUE`, uses `grid.newpage` before plotting.
`debug`	A numeric. If > 0, only that number of element will be plotted for each `dna_seg` and `comparison`.
`...`	Further arguments to be passed to user-defined graphical functions.

Details

One line is plotted per dna_seg. Eventually, the space between the lines will be filled with the comparisons. dna_segs can be annotated with annotations, and accompagnying data can be plotted using seg_plot.

A phylogenetic tree (a phylog object from package ade4) can be drawn at the left of the plot. The tree does not need to be ordered as the dna_seg_labels, but a permutation of the tree with that order should exist. If the tree is large, the number of permutations become too large, and the function will stop (>100000 permutations). The solution is then to provide segments that are ordered in the same manner as the tree labels (or vice-versa).

There is an (experimental) support for branch annotations. These are given in the Newick tree, directly after the parenthesis closing a node. They can be characters or integers, but so far newick2phylog doesn't support decimal values. Tags will be ignored if they start with "I", and trimmed if they start with "X".

The format of the elements of dna_segs is previously determined in the object or can be globally set by gene_type. See the function gene_types to return the available types. Gene type can also be user-defined, using a function returning a grob. See gene_types for more details.

xlims allow the user to plot subsegments of a dna_seg. xlims consists of a list composed of as many numeric vectors as there are segments. Each of these numeric vectors give pairs of left and right borders, and gives the direction. For example, c(1,2,6,4) will plot two subsegments, segment 1 to 2 which is plotted left to right and segment 4 to 6, plotted right to left. -Inf and Inf values are accepted. NULL values will result in plotting the whole segment.

offsets allows to user to define the placement of the subsegments. If a list is provided, each element of the list should have as many elements as there are subsegments. It will give the size of the gaps, including the first one from the border of the plot to the first subsegment.

A main title (main) can also be added at the top of the plot, at the position defined by main_pos. A general scale can be added at the bottom right of the plot (scale).

dna_seg_scale gives the ability to plot scales on one, some or every segment. c(TRUE, FALSE, TRUE) will add scales to the first and third segments.

The four elements of global_color_scheme are (i) which column serves as scale to apply the color scheme, or "auto" (default); (ii) if the scale is "increasing" or "decreasing" (see apply_color_scheme for more details), or "auto" (default); (iii) the color scheme to apply; (iv) the transparency to apply (0.5 by default).

Value

Nothing. A lattice graphic is plotted on the current device.

Note

This plotting function has been tested as far as possible, but given its complexity and that the package is young, bugs or strange behaviors are possible. Please report them to the author.

As of 10/3/2010, support for viewing exons/introns is only available using genbank and embl formats, not when importing ptt files.

Author(s)

Lionel Guy lionel.guy@ebc.uu.se, Jens Roat Kultima

Examples

old.par <- par(no.readonly=TRUE)
data("three_genes")

## Segments only
plot_gene_map(dna_segs=dna_segs) 

## With comparisons
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons) 

## Tree
names <- c("A_aaa", "B_bbb", "C_ccc")
names(dna_segs) <- names
tree <- newick2phylog("(((A_aaa:4.2,B_bbb:3.9):3.1,C_ccc:7.3):1);")
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              tree=tree)
## Increasing tree width
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              tree=tree, tree_width=3)
## Annotations on the tree
tree2 <- newick2phylog("(((A_aaa:4.2,B_bbb:3.9)97:3.1,C_ccc:7.3)78:1);")
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              tree=tree2, tree_width=3)
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              tree=tree2, tree_width=3, tree_branch_labels_cex=0.5)
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              tree=tree2, tree_width=3, tree_branch_labels_cex=0)

## Annotation
## Calculating middle positions
mid_pos <- middle(dna_segs[[1]])

# Create first annotation
annot1 <- annotation(x1=mid_pos, text=dna_segs[[1]]$name)
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons, annotations=annot1)

## Exploring options
annot2 <- annotation(x1=c(mid_pos[1], dna_segs[[1]]$end[2]),
                     x2=c(NA, dna_segs[[1]]$end[3]),
                     text=c(dna_segs[[1]]$name[1], "region1"),
                     rot=c(30, 0), col=c("grey", "black"))
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              annotations=annot2, annotation_height=1.3)

## xlims
## Just returning a segment
plot_gene_map(dna_segs, comparisons,
              xlims=list(NULL, NULL, c(Inf,-Inf)),
              dna_seg_scale=TRUE)
## Removing one gene
plot_gene_map(dna_segs, comparisons,
              xlims=list(NULL, NULL, c(-Inf,2800)),
              dna_seg_scale=TRUE)

## offsets
offsets <- c(0, 0, 0)  
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons, offsets=offsets)
offsets <- c(200, 400, 0)  
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons, offsets=offsets)

## main
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              main="Comparison of A, B and C")
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              main="Comparison of A, B and C", main_pos="left")

## dna_seg_labels
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              dna_seg_labels=c("Huey", "Dewey", "Louie"))

## dna_seg_labels size
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              dna_seg_labels=c("Huey", "Dewey", "Louie"),
              dna_seg_label_cex=2)

## dna_seg_line
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              dna_seg_line=c("FALSE", "red", grey(0.6)))

## gene_type
plot_gene_map(dna_segs=dna_segs, comparisons=comparisons,
              gene_type="side_blocks")

##
## From here on, using a bigger dataset from a 4-genome comparison
##
data("barto")
## Adding a tree
tree <- newick2phylog("(BB:2.5,(BG:1.8,(BH:1,BQ:0.8):1.9):3);")
## Showing only subsegments
xlims1 <- list(c(1380000, 1445000),
               c(10000, 83000),
               c(15000, 98000),
               c(5000, 82000))
## Reducing dataset size for speed purpose
for (i in 1:length(barto$dna_segs)){
    barto$dna_segs[[i]] <- trim(barto$dna_segs[[i]], xlim=xlims1[[i]])
    if (i < length(barto$dna_segs))
        barto$comparisons[[i]] <- trim(barto$comparisons[[i]],
                                      xlim1=xlims1[[i]], xlims1[[i+1]])   
}
plot_gene_map(barto$dna_segs, barto$comparisons, tree=tree,
              xlims=xlims1,
              dna_seg_scale=TRUE)
## Showing several subsegments per genome
xlims2 <- list(c(1445000, 1415000, 1380000, 1412000),
               c(  10000,   45000,   50000,   83000, 90000, 120000),
               c(  15000,   36000,   90000,  120000, 74000,  98000),
               c(   5000,    82000))

## dna_seg_scale, global_color_scheme, size, number, color of dna_seg_scale,
## size of dna_seg_scale labels
plot_gene_map(barto$dna_segs, barto$comparisons, tree=tree, xlims=xlims2,
              dna_seg_scale=c(TRUE, FALSE, FALSE, TRUE), scale=FALSE,
              dna_seg_label_cex=1.7,
              dna_seg_label_col=c("black", "grey", "blue", "red"),
              global_color_scheme=c("e_value", "auto", "grey", "0.7"),
              n_scale_ticks=3, scale_cex=1)

## Hand-made offsets: size of all gaps
offsets2 <- list(c(10000, 10000),
                 c(2000, 2000, 2000),
                 c(10000, 5000, 2000),
                 c(10000))
plot_gene_map(barto$dna_segs, barto$comparisons, tree=tree,
              #annotations=annots,
              xlims=xlims2,
              offsets=offsets2,
              dna_seg_scale=TRUE)
##
## Exploring and modifying a previously plotted gene map plot
##
## View viewports
current.vpTree()
## Go down to one of the viewports, add an xaxis, go back up to root viewport
downViewport("dna_seg_scale.3.2")
grid.rect()
upViewport(0)
## Get all the names of the objects
grobNames <- getNames()
grobNames
## Change the color ot the scale line
grid.edit("scale.lines", gp=gpar(col="grey"))
## Remove first dna_seg_lines
grid.remove("dna_seg_line.1.1")

##
## Plot genoPlotR logo
##
col <- c("#B2182B", "#D6604D", "#F4A582", "#FDDBC7",
         "#D1E5F0", "#92C5DE", "#4393C3", "#2166AC")
cex <- 2.3
## First segment 
start1 <- c(150, 390, 570)
end1   <- c(  1, 490, 690)
genoR <- c(270, 530)
## Second segment
start2 <- c(100, 520, 550)
end2   <- c(240, 420, 650)
Plot <- c(330)
## dna_segs
ds1 <- as.dna_seg(data.frame(name=c("", "", ""),
                             start=start1, end=end1, strand=rep(1, 3),
                             col=col[c(2, 6, 1)], stringsAsFactor=FALSE))
ds_genoR <- as.dna_seg(data.frame(name=c("geno", "R"),
                             start=genoR, end=genoR, strand=rep(1, 2),
                             col=c(col[8], "black"),
                             stringsAsFactor=FALSE), cex=cex, gene_type="text")
ds2 <- as.dna_seg(data.frame(name=c("", "", ""),
                             start=start2, end=end2, strand=rep(1, 3),
                             col=col[c(5, 3, 7)],
                             stringsAsFactor=FALSE))
ds_Plot <- as.dna_seg(data.frame(name="Plot",
                             start=Plot, end=Plot, strand=1,
                             col=col[c(1)],
                             stringsAsFactor=FALSE), cex=cex, gene_type="text")
## comparison
c1 <- as.comparison(data.frame(start1=start1, end1=end1,
                               start2=start2, end2=end2,
                               col=grey(c(0.6, 0.8, 0.5))))
## Generate genoPlotR logo
## Not run: 
pdf("logo.pdf", h=0.7, w=3)

## End(Not run)
par(fin=c(0.7, 3))
plot_gene_map(dna_segs=list(c(ds1, ds_genoR), c(ds2, ds_Plot)),
              comparisons=list(c1), scale=FALSE, dna_seg_scale=FALSE,
              dna_seg_line=grey(0.7), offsets=c(-20,160))
## Not run: 
dev.off()

## End(Not run)
par(old.par)

[Package genoPlotR version 0.8.11 Index]