create.hexbinplot: Make a hexagonally binned plot
In BoutrosLab.plotting.general: Functions to Create Publication-Quality Plots
View source: R/create.hexbinplot.R
create.hexbinplot R Documentation
Make a hexagonally binned plot
Description
Takes a data.frame and writes a hexagonally binned plot
Usage
create.hexbinplot(
formula,
data,
filename = NULL,
main = NULL,
main.just = 'center',
main.x = 0.5,
main.y = 0.5,
main.cex = 3,
aspect = 'xy',
trans = NULL,
inv = NULL,
colour.scheme = NULL,
colourkey = TRUE,
colourcut = seq(0, 1, length = 11),
mincnt = 1,
maxcnt = NULL,
xbins = 30,
legend.title = NULL,
xlab.label = tail(sub('~', '', formula[-2]), 1),
ylab.label = tail(sub('~', '', formula[-3]), 1),
xlab.cex = 2,
ylab.cex = 2,
xlab.col = 'black',
ylab.col = 'black',
xlab.top.label = NULL,
xlab.top.cex = 2,
xlab.top.col = 'black',
xlab.top.just = 'center',
xlab.top.x = 0.5,
xlab.top.y = 0,
xlimits = NULL,
ylimits = NULL,
xat = TRUE,
yat = TRUE,
xaxis.lab = NA,
yaxis.lab = NA,
xaxis.cex = 1.5,
yaxis.cex = 1.5,
xaxis.rot = 0,
yaxis.rot = 0,
xaxis.col = 'black',
yaxis.col = 'black',
xaxis.tck = 1,
yaxis.tck = 1,
xaxis.fontface = 'bold',
yaxis.fontface = 'bold',
layout = NULL,
as.table = FALSE,
x.relation = 'same',
y.relation = 'same',
x.spacing = 0,
y.spacing = 0,
strip.col = 'white',
strip.cex = 1,
strip.fontface = 'bold',
add.grid = FALSE,
abline.h = NULL,
abline.v = NULL,
abline.lty = NULL,
abline.lwd = NULL,
abline.col = 'black',
abline.front = FALSE,
add.xyline = FALSE,
xyline.col = 'black',
xyline.lwd = 1,
xyline.lty = 1,
add.curves = FALSE,
curves.exprs = NULL,
curves.from = min(data, na.rm = TRUE),
curves.to = max(data, na.rm = TRUE),
curves.col = 'black',
curves.lwd = 2,
curves.lty = 1,
add.text = FALSE,
text.labels = NULL,
text.x = NULL,
text.y = NULL,
text.col = 'black',
text.cex = 1,
text.fontface = 'bold',
add.axes = FALSE,
top.padding = 0.1,
bottom.padding = 0.7,
left.padding = 0.5,
right.padding = 0.1,
add.rectangle = FALSE,
xleft.rectangle = NULL,
ybottom.rectangle = NULL,
xright.rectangle = NULL,
ytop.rectangle = NULL,
col.rectangle = 'transparent',
alpha.rectangle = 1,
background.col = 'transparent',
key = NULL,
legend = NULL,
height = 6,
width = 6,
size.units = 'in',
resolution = 1600,
enable.warnings = FALSE,
description = 'Created with BoutrosLab.plotting.general',
style = 'BoutrosLab',
preload.default = 'custom',
use.legacy.settings = FALSE,
inside.legend.auto = FALSE
);
Arguments
formula
The formula used to extract the x & y components from the data-frame. Transforming data within formula is not compatible with automatic scaling with 'xat' or 'yat'.
data
The data-frame to plot
filename
Filename for tiff output, or if NULL (default value) returns the trellis object itself
main
The main title for the plot (space is reclaimed if NULL)
main.just
The justification of the main title for the plot, default is centered
main.x
The x location of the main title, deault is 0.5
main.y
The y location of the main title, default is 0.5
main.cex
Size of the main plot title
aspect
This argument controls the physical aspect ratio of the panels, defaults to “xy”
trans
function specifying a transformation for the counts such as log, defaults to NULL
inv
the inverse transformation of trans, defaults to NULL
colour.scheme
colour scheme to be used, default NULL gives LinGray colour scale
colourkey
logical whether a legend should be drawn, defaults to TRUE
colourcut
Vector of values covering [0, 1] that determine hexagon colour class boundaries and hexagon legend size boundaries. Alternatively, an integer (<= maxcnt) specifying the number of equispaced colourcut values in [0,1].
mincnt
Cells with fewer counts are ignored
maxcnt
Cells with more counts are ignored, defaults to auto-generation
xbins
Number of bins to use in x, defaults to 30
legend.title
character/expression to use in place of default legend title or a named list with elements: lab, x, y; defaults to NULL
xlab.label
X-axis label
ylab.label
Y-axis label
xlab.cex
Size of x-axis label
ylab.cex
Size of y-axis label
xlab.col
Colour of the x-axis label, defaults to “black”
ylab.col
Colour of the y-axis label, defaults to “black”
xlab.top.label
The label for the top x-axis
xlab.top.cex
Size of top x-axis label
xlab.top.col
Colour of the top x-axis label
xlab.top.just
Justification of the top x-axis label, defaults to centered
xlab.top.x
The x location of the top x-axis label
xlab.top.y
The y location of the top y-axis label
xlimits
Two-element vector giving the x-axis limits
ylimits
Two-element vector giving the y-axis limits
xat
Accepts a vector listing where x-axis ticks should be drawn or if automatic scaling is desired, one of three strings: “auto”, “auto.linear” or “auto.log”. Automatic scaling fixes x-axis tick locations, labels, and data values dependent given data. “auto” will determine whether linear or logarithmic scaling fits the given data best, “auto.linear” or “auto.log” will force data to be scaled linearly or logarithmically respectively. Defaults to lattice automatic (TRUE). For more details see 'auto.axis()'.
yat
Accepts a vector listing where y-axis ticks should be drawn or if automatic scaling is desired, one of three strings: “auto”, “auto.linear” or “auto.log”. Automatic scaling fixes y-axis tick locations, labels, and data values dependent given data. “auto” will determine whether linear or logarithmic scaling fits the given data best, “auto.linear” or “auto.log” will force data to be scaled linearly or logarithmically respectively. Defaults to lattice automatic (TRUE). For more details see 'auto.axis()'.
xaxis.lab
Vector listing x-axis tick labels, defaults to automatic (TRUE). Using automatic scaling with xat will overwrite user input. Set to NULL to remove x-axis labels.
yaxis.lab
Vector listing y-axis tick labels, defaults to automatic (TRUE). Using automatic scaling with yat will overwrite user input. Set to NULL to remove y-axis labels.
xaxis.cex
Size of x-axis scales, defaults to 2
yaxis.cex
Size of y-axis scales, defaults to 2
xaxis.rot
Rotation of x-axis tick labels; defaults to 0
yaxis.rot
Rotation of y-axis tick labels; defaults to 0
xaxis.col
Colour of the x-axis tick labels, defaults to “black”
yaxis.col
Colour of the y-axis tick labels, defaults to “black”
xaxis.tck
Specifies the length of the tick marks for x-axis, defaults to 1
yaxis.tck
Specifies the length of the tick marks for y-axis, defaults to 1
xaxis.fontface
Fontface for the x-axis scales
yaxis.fontface
Fontface for the y-axis scales
layout
A vector specifying the number of columns, rows (e.g., c(2,1). Default is NULL.
as.table
Specifies panel drawing order, default is FALSE which draws panels from bottom left corner, moving right then up. Set to TRUE to draw from top left corner, moving right then down
x.relation
Allows x-axis scales to vary if set to “free”, defaults to “same”
y.relation
Allows y-axis scales to vary if set to “free”, defaults to “same”
x.spacing
A number specifying the distance between panels along the x-axis, defaults to 0
y.spacing
A number specifying the distance between panels along the y-axis, defaults to 0
strip.col
Strip background colour, defaults to “white”
strip.cex
Strip title character expansion
strip.fontface
Strip title fontface, defaults to bold
add.grid
Allows grid lines to be turned on or off
abline.h
Specify the superimposed horizontal line(s)
abline.v
Specify the superimposed vertical line(s)
abline.lty
Specify the superimposed line type
abline.lwd
Specify the superimposed line width
abline.col
Specify the superimposed line colour (defaults to black)
abline.front
If an abline and/or a grid has been added, this controls whether they are drawn in front of the hexbins
add.xyline
Allow y=x line to be drawn, default is FALSE
xyline.col
y=x line colour, defaults to black
xyline.lwd
Specifies y=x line width, defaults to 1
xyline.lty
Specifies y=x line style, defaults to 1 (solid)
add.curves
Allow curves to drawn, default is FALSE
curves.exprs
A list of functions, expressions, or calls using “x” as a variable that specify the curves to be drawn
curves.from
Specifies the x co-ordinates at which the start of each curve should be drawn, defaults to drawing the curves to the left edge of the plotting region
curves.to
Specifies the x co-ordinates at which the end of each curve should be drawn, defaults to drawing the curves to the right edge of the plotting region
curves.col
Specifies colours of curves, default is black for each curve
curves.lwd
Specifies width of curves, default is 1 for each curve
curves.lty
Specifies type of curves, default is 1 (solid) for each curve
add.text
Allow additional text to be drawn, default is FALSE
text.labels
Labels for additional text
text.x
The x co-ordinates where additional text should be placed
text.y
The y co-ordinates where additional text should be placed
text.col
The colour of additional text
text.cex
The size of additional text
text.fontface
The fontface for additional text
add.axes
Allow axis lines to be turned on or off
top.padding
A number giving the top padding in multiples of the lattice default
bottom.padding
A number giving the bottom padding in multiples of the lattice default
left.padding
A number giving the left padding in multiples of the lattice default
right.padding
A number giving the right padding in multiples of the lattice default
add.rectangle
Allow a rectangle to be drawn, default is FALSE
xleft.rectangle
Specifies the left x coordinate of the rectangle to be drawn
ybottom.rectangle
Specifies the bottom y coordinate of the rectangle to be drawn
xright.rectangle
Specifies the right x coordinate of the rectangle to be drawn
ytop.rectangle
Specifies the top y coordinate of the rectangle to be drawn
col.rectangle
Specifies the colour to fill the rectangle's area
alpha.rectangle
Specifies the colour bias of the rectangle to be drawn
background.col
Specifies the colour for the background of the plot
key
Add a key to the plot. See xyplot.
legend
Add a legend to the plot. Helpful for adding multiple keys and adding keys to the margins of the plot. See xyplot.
height
Figure height, defaults to 6 inches
width
Figure width, defaults to 6 inches
size.units
Figure units, defaults to inches
resolution
Figure resolution in dpi, defaults to 1600
enable.warnings
Print warnings if set to TRUE, defaults to FALSE
description
Short description of image/plot; default NULL.
style
defaults to “BoutrosLab”, also accepts “Nature”, which changes parameters according to Nature formatting requirements
preload.default
ability to set multiple sets of diffrent defaults depending on publication needs
use.legacy.settings
boolean to set wheter or not to use legacy mode settings (font)
inside.legend.auto
boolean specifying whether or not to use the automatic inside legend function
Details
WARNING: this function uses highly unusual semantics, different from the rest of the BoutrosLab.plotting.general library. The underlying hexbinplot function uses an argument called maxcnt to specify the maximum number of counts per cell. The default behaviour is not sensibly encoded via a NULL or an NA, but instead by using the missing function. As a result, we need to use do.call semantics to handle this function. This can mess up anything using substitute including things that generate p-values!
Value
If filename is NULL then returns the trellis object, otherwise creates a plot and returns a 0/1 success code.
Warning
If this function is called without capturing the return value, or specifying a filename, it may crash while trying to draw the histogram. In particular, if a script that uses such a call of create histogram is called by reading the script in from the command line, it will fail badly, with an error message about unavailable fonts:
Error in grid.Call.graphics("L_text", as.graphicsAnnot(x$label), x$x, )
Invalid font type
Calls: print ... drawDetails.text -> grid.Call.graphics -> .Call.graphics
If 'maxcnt' is passed, make sure it is not smaller than the actual maximum count (value depends on nbins). Otherwise, some data may be lost. If you aren't sure what the actual max count is, run this function without specifying the 'maxcnt' parameter using the desired number of bins.
Author(s)
Maud HW Starmans
See Also
xyplot, lattice or the Lattice book for an overview of the package.
Examples
set.seed(12345);
simple.data <- data.frame(
x = rnorm(10000),
y = rnorm(10000)
);
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Simple', fileext = '.tiff'),
formula = y ~ x,
data = simple.data,
main = 'Simple',
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 50
);
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Simple_underlined_legend_title', fileext = '.tiff'),
formula = y ~ x,
data = simple.data,
legend.title = list(lab = expression(bold(underline('Counts'))), x = 1, y = 1.1),
right.padding = 4,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 50
);
# Set up data
hexbin.data <- data.frame(
x = microarray[,1],
y = microarray[,2]
);
# Minimal Input
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Minimal_Input', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Minimal input',
# formatting bins
colourcut = seq(0, 1, length = 11),
# this sets the maximum value plotted -- values greater than this will not appear
maxcnt = 50,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 100
);
# Axes & Labels
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Axes_Labels', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Axes & labels',
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Customize Axes and labels
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 100
);
# Log Scaled Axis
log.data <- data.frame(
x = microarray[,1],
y = 10 ** microarray[,2]
);
create.hexbinplot(
formula = y ~ x,
data = log.data,
main = 'Log Scaled',
# Log base 10 scale y-axis
yat = 'auto.log',
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 100
);
# Aspect Ratio
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Aspect_Ratio', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Aspect ratio',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Set the aspect ratio to control plot dimensions
aspect = 2,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Colour scheme
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Colour_Change', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Colour change',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Specify colour scheme
colour.scheme = colorRampPalette(c('dodgerblue','paleturquoise','chartreuse','yellow',
'orange','red')),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Bin sizes
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Bin_Sizes', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Bin sizes',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colour.scheme = colorRampPalette(c('dodgerblue','paleturquoise','chartreuse', 'yellow',
'orange','red')),
# Specify bin sizes
colourcut = seq(0,1,length = 6),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Correlation Key
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Correlation', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Correlation',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Correlation Key
legend = list(
inside = list(
fun = draw.key,
args = list(
key = get.corr.key(
x = hexbin.data$x,
y = hexbin.data$y,
label.items = c('beta1', 'spearman'),
alpha.background = 0
)
),
x = 0.05,
y = 0.95,
corner = c(0,1),
draw = FALSE
)
),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Grid lines and diagonal
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Gridlines', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Gridlines',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Grid & diagonal
add.grid = TRUE,
add.xyline = TRUE,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Large range
# Generate some fake data with both very low and very high values
set.seed(12345);
x <- c(rnorm(100000,0,0.1),rnorm(1000,0,0.5),rnorm(1000,0,sd=0.75));
y <- c(rnorm(100000,0,0.1),rnorm(1000,0,0.5),rnorm(1000,0,sd=0.75));
fake.data <- data.frame(
x = x,
y = y,
z = y + x*(x+1)/4
);
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Range', fileext = '.tiff'),
formula = z ~ x,
data = fake.data,
main = 'Range',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
aspect = 1,
# Use colourcut to divide the bins appropriately
colourcut = c(0,0.0002,0.0004,0.0008,0.0016,0.0032,0.0064,0.0128,0.0256,0.0512,0.1024,0.2048,
0.4096,0.8192,1),
# Change the colour scheme
colour.scheme = function(n){BTC(n, beg=1, end=256)},
background.col = 'grey',
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Outliers
# Generate data with upper bound outlier
set.seed(12345);
x <- c(rnorm(1000,0,0),rnorm(4000,0,0.5));
y <- c(rnorm(1000,0,0),rnorm(4000,0,0.5));
fake.data.outlier <- data.frame(
x = x,
y = y,
z = y + x*(x+1)/4
);
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Outlier', fileext = '.tiff'),
formula = z ~ x,
data = fake.data.outlier,
main = 'Outlier',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
aspect = 1,
# Use colourcut to divide the bins appropriately
colourcut = c(seq(0,0.01, length = 4),seq(0.0125,0.1,length=4), seq(0.125,1,length=4)),
xbins = 15,
mincnt = 0,
# Change the colour scheme
colour.scheme = function(n){BTC(n, beg=1, end=256)},
background.col = 'grey',
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Nature style
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Nature_style', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Nature style',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Grid & diagonal
add.grid = TRUE,
add.xyline = TRUE,
# set style to Nature
style = 'Nature',
# demonstrating how to italicize character variables
ylab.lab = expression(paste('italicized ', italic('a'))),
# demonstrating how to create en-dashes
xlab.lab = expression(paste('en dashs: 1','\u2013', '10'^'\u2013', ''^3)),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Multiplot different groups
set.seed(73);
# Randomly generate groups
simple.data$groups <- sample(1:2, 10000, replace = TRUE);
simple.data$group.labels <- as.factor(simple.data$groups);
create.hexbinplot(
formula = y ~ x | groups,
# filename = tempfile(
# pattern = 'stratified_hexbinplot_numeric_conditioning',
# fileext = '.tiff'
# ),
data = simple.data,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
strip.col = 'white',
strip.cex = 0.8,
strip.fontface = 'bold',
resolution = 200
);
create.hexbinplot(
formula = y ~ x | group.labels,
# filename = tempfile(
# pattern = 'stratified_hexbinplot_factor_conditioning',
# fileext = '.tiff'
# ),
data = simple.data,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
strip.col = 'white',
strip.cex = 0.8,
strip.fontface = 'bold',
resolution = 200
);
BoutrosLab.plotting.general documentation built on Nov. 2, 2023, 6:01 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/create.hexbinplot.R
| create.hexbinplot | R Documentation |
Make a hexagonally binned plot
Description
Takes a data.frame and writes a hexagonally binned plot
Usage
create.hexbinplot(
formula,
data,
filename = NULL,
main = NULL,
main.just = 'center',
main.x = 0.5,
main.y = 0.5,
main.cex = 3,
aspect = 'xy',
trans = NULL,
inv = NULL,
colour.scheme = NULL,
colourkey = TRUE,
colourcut = seq(0, 1, length = 11),
mincnt = 1,
maxcnt = NULL,
xbins = 30,
legend.title = NULL,
xlab.label = tail(sub('~', '', formula[-2]), 1),
ylab.label = tail(sub('~', '', formula[-3]), 1),
xlab.cex = 2,
ylab.cex = 2,
xlab.col = 'black',
ylab.col = 'black',
xlab.top.label = NULL,
xlab.top.cex = 2,
xlab.top.col = 'black',
xlab.top.just = 'center',
xlab.top.x = 0.5,
xlab.top.y = 0,
xlimits = NULL,
ylimits = NULL,
xat = TRUE,
yat = TRUE,
xaxis.lab = NA,
yaxis.lab = NA,
xaxis.cex = 1.5,
yaxis.cex = 1.5,
xaxis.rot = 0,
yaxis.rot = 0,
xaxis.col = 'black',
yaxis.col = 'black',
xaxis.tck = 1,
yaxis.tck = 1,
xaxis.fontface = 'bold',
yaxis.fontface = 'bold',
layout = NULL,
as.table = FALSE,
x.relation = 'same',
y.relation = 'same',
x.spacing = 0,
y.spacing = 0,
strip.col = 'white',
strip.cex = 1,
strip.fontface = 'bold',
add.grid = FALSE,
abline.h = NULL,
abline.v = NULL,
abline.lty = NULL,
abline.lwd = NULL,
abline.col = 'black',
abline.front = FALSE,
add.xyline = FALSE,
xyline.col = 'black',
xyline.lwd = 1,
xyline.lty = 1,
add.curves = FALSE,
curves.exprs = NULL,
curves.from = min(data, na.rm = TRUE),
curves.to = max(data, na.rm = TRUE),
curves.col = 'black',
curves.lwd = 2,
curves.lty = 1,
add.text = FALSE,
text.labels = NULL,
text.x = NULL,
text.y = NULL,
text.col = 'black',
text.cex = 1,
text.fontface = 'bold',
add.axes = FALSE,
top.padding = 0.1,
bottom.padding = 0.7,
left.padding = 0.5,
right.padding = 0.1,
add.rectangle = FALSE,
xleft.rectangle = NULL,
ybottom.rectangle = NULL,
xright.rectangle = NULL,
ytop.rectangle = NULL,
col.rectangle = 'transparent',
alpha.rectangle = 1,
background.col = 'transparent',
key = NULL,
legend = NULL,
height = 6,
width = 6,
size.units = 'in',
resolution = 1600,
enable.warnings = FALSE,
description = 'Created with BoutrosLab.plotting.general',
style = 'BoutrosLab',
preload.default = 'custom',
use.legacy.settings = FALSE,
inside.legend.auto = FALSE
);
Arguments
formula |
The formula used to extract the x & y components from the data-frame. Transforming data within formula is not compatible with automatic scaling with 'xat' or 'yat'. |
data |
The data-frame to plot |
filename |
Filename for tiff output, or if NULL (default value) returns the trellis object itself |
main |
The main title for the plot (space is reclaimed if NULL) |
main.just |
The justification of the main title for the plot, default is centered |
main.x |
The x location of the main title, deault is 0.5 |
main.y |
The y location of the main title, default is 0.5 |
main.cex |
Size of the main plot title |
aspect |
This argument controls the physical aspect ratio of the panels, defaults to “xy” |
trans |
function specifying a transformation for the counts such as log, defaults to NULL |
inv |
the inverse transformation of trans, defaults to NULL |
colour.scheme |
colour scheme to be used, default NULL gives LinGray colour scale |
colourkey |
logical whether a legend should be drawn, defaults to TRUE |
colourcut |
Vector of values covering [0, 1] that determine hexagon colour class boundaries and hexagon legend size boundaries. Alternatively, an integer (<= maxcnt) specifying the number of equispaced colourcut values in [0,1]. |
mincnt |
Cells with fewer counts are ignored |
maxcnt |
Cells with more counts are ignored, defaults to auto-generation |
xbins |
Number of bins to use in x, defaults to 30 |
legend.title |
character/expression to use in place of default legend title or a named list with elements: lab, x, y; defaults to NULL |
xlab.label |
X-axis label |
ylab.label |
Y-axis label |
xlab.cex |
Size of x-axis label |
ylab.cex |
Size of y-axis label |
xlab.col |
Colour of the x-axis label, defaults to “black” |
ylab.col |
Colour of the y-axis label, defaults to “black” |
xlab.top.label |
The label for the top x-axis |
xlab.top.cex |
Size of top x-axis label |
xlab.top.col |
Colour of the top x-axis label |
xlab.top.just |
Justification of the top x-axis label, defaults to centered |
xlab.top.x |
The x location of the top x-axis label |
xlab.top.y |
The y location of the top y-axis label |
xlimits |
Two-element vector giving the x-axis limits |
ylimits |
Two-element vector giving the y-axis limits |
xat |
Accepts a vector listing where x-axis ticks should be drawn or if automatic scaling is desired, one of three strings: “auto”, “auto.linear” or “auto.log”. Automatic scaling fixes x-axis tick locations, labels, and data values dependent given data. “auto” will determine whether linear or logarithmic scaling fits the given data best, “auto.linear” or “auto.log” will force data to be scaled linearly or logarithmically respectively. Defaults to lattice automatic (TRUE). For more details see 'auto.axis()'. |
yat |
Accepts a vector listing where y-axis ticks should be drawn or if automatic scaling is desired, one of three strings: “auto”, “auto.linear” or “auto.log”. Automatic scaling fixes y-axis tick locations, labels, and data values dependent given data. “auto” will determine whether linear or logarithmic scaling fits the given data best, “auto.linear” or “auto.log” will force data to be scaled linearly or logarithmically respectively. Defaults to lattice automatic (TRUE). For more details see 'auto.axis()'. |
xaxis.lab |
Vector listing x-axis tick labels, defaults to automatic (TRUE). Using automatic scaling with xat will overwrite user input. Set to NULL to remove x-axis labels. |
yaxis.lab |
Vector listing y-axis tick labels, defaults to automatic (TRUE). Using automatic scaling with yat will overwrite user input. Set to NULL to remove y-axis labels. |
xaxis.cex |
Size of x-axis scales, defaults to 2 |
yaxis.cex |
Size of y-axis scales, defaults to 2 |
xaxis.rot |
Rotation of x-axis tick labels; defaults to 0 |
yaxis.rot |
Rotation of y-axis tick labels; defaults to 0 |
xaxis.col |
Colour of the x-axis tick labels, defaults to “black” |
yaxis.col |
Colour of the y-axis tick labels, defaults to “black” |
xaxis.tck |
Specifies the length of the tick marks for x-axis, defaults to 1 |
yaxis.tck |
Specifies the length of the tick marks for y-axis, defaults to 1 |
xaxis.fontface |
Fontface for the x-axis scales |
yaxis.fontface |
Fontface for the y-axis scales |
layout |
A vector specifying the number of columns, rows (e.g., c(2,1). Default is NULL. |
as.table |
Specifies panel drawing order, default is FALSE which draws panels from bottom left corner, moving right then up. Set to TRUE to draw from top left corner, moving right then down |
x.relation |
Allows x-axis scales to vary if set to “free”, defaults to “same” |
y.relation |
Allows y-axis scales to vary if set to “free”, defaults to “same” |
x.spacing |
A number specifying the distance between panels along the x-axis, defaults to 0 |
y.spacing |
A number specifying the distance between panels along the y-axis, defaults to 0 |
strip.col |
Strip background colour, defaults to “white” |
strip.cex |
Strip title character expansion |
strip.fontface |
Strip title fontface, defaults to bold |
add.grid |
Allows grid lines to be turned on or off |
abline.h |
Specify the superimposed horizontal line(s) |
abline.v |
Specify the superimposed vertical line(s) |
abline.lty |
Specify the superimposed line type |
abline.lwd |
Specify the superimposed line width |
abline.col |
Specify the superimposed line colour (defaults to black) |
abline.front |
If an abline and/or a grid has been added, this controls whether they are drawn in front of the hexbins |
add.xyline |
Allow y=x line to be drawn, default is FALSE |
xyline.col |
y=x line colour, defaults to black |
xyline.lwd |
Specifies y=x line width, defaults to 1 |
xyline.lty |
Specifies y=x line style, defaults to 1 (solid) |
add.curves |
Allow curves to drawn, default is FALSE |
curves.exprs |
A list of functions, expressions, or calls using “x” as a variable that specify the curves to be drawn |
curves.from |
Specifies the x co-ordinates at which the start of each curve should be drawn, defaults to drawing the curves to the left edge of the plotting region |
curves.to |
Specifies the x co-ordinates at which the end of each curve should be drawn, defaults to drawing the curves to the right edge of the plotting region |
curves.col |
Specifies colours of curves, default is black for each curve |
curves.lwd |
Specifies width of curves, default is 1 for each curve |
curves.lty |
Specifies type of curves, default is 1 (solid) for each curve |
add.text |
Allow additional text to be drawn, default is FALSE |
text.labels |
Labels for additional text |
text.x |
The x co-ordinates where additional text should be placed |
text.y |
The y co-ordinates where additional text should be placed |
text.col |
The colour of additional text |
text.cex |
The size of additional text |
text.fontface |
The fontface for additional text |
add.axes |
Allow axis lines to be turned on or off |
top.padding |
A number giving the top padding in multiples of the lattice default |
bottom.padding |
A number giving the bottom padding in multiples of the lattice default |
left.padding |
A number giving the left padding in multiples of the lattice default |
right.padding |
A number giving the right padding in multiples of the lattice default |
add.rectangle |
Allow a rectangle to be drawn, default is FALSE |
xleft.rectangle |
Specifies the left x coordinate of the rectangle to be drawn |
ybottom.rectangle |
Specifies the bottom y coordinate of the rectangle to be drawn |
xright.rectangle |
Specifies the right x coordinate of the rectangle to be drawn |
ytop.rectangle |
Specifies the top y coordinate of the rectangle to be drawn |
col.rectangle |
Specifies the colour to fill the rectangle's area |
alpha.rectangle |
Specifies the colour bias of the rectangle to be drawn |
background.col |
Specifies the colour for the background of the plot |
key |
Add a key to the plot. See xyplot. |
legend |
Add a legend to the plot. Helpful for adding multiple keys and adding keys to the margins of the plot. See xyplot. |
height |
Figure height, defaults to 6 inches |
width |
Figure width, defaults to 6 inches |
size.units |
Figure units, defaults to inches |
resolution |
Figure resolution in dpi, defaults to 1600 |
enable.warnings |
Print warnings if set to TRUE, defaults to FALSE |
description |
Short description of image/plot; default NULL. |
style |
defaults to “BoutrosLab”, also accepts “Nature”, which changes parameters according to Nature formatting requirements |
preload.default |
ability to set multiple sets of diffrent defaults depending on publication needs |
use.legacy.settings |
boolean to set wheter or not to use legacy mode settings (font) |
inside.legend.auto |
boolean specifying whether or not to use the automatic inside legend function |
Details
WARNING: this function uses highly unusual semantics, different from the rest of the BoutrosLab.plotting.general library. The underlying hexbinplot function uses an argument called maxcnt to specify the maximum number of counts per cell. The default behaviour is not sensibly encoded via a NULL or an NA, but instead by using the missing function. As a result, we need to use do.call semantics to handle this function. This can mess up anything using substitute including things that generate p-values!
Value
If filename is NULL then returns the trellis object, otherwise creates a plot and returns a 0/1 success code.
Warning
If this function is called without capturing the return value, or specifying a filename, it may crash while trying to draw the histogram. In particular, if a script that uses such a call of create histogram is called by reading the script in from the command line, it will fail badly, with an error message about unavailable fonts:
Error in grid.Call.graphics("L_text", as.graphicsAnnot(x$label), x$x, )
Invalid font type
Calls: print ... drawDetails.text -> grid.Call.graphics -> .Call.graphics
If 'maxcnt' is passed, make sure it is not smaller than the actual maximum count (value depends on nbins). Otherwise, some data may be lost. If you aren't sure what the actual max count is, run this function without specifying the 'maxcnt' parameter using the desired number of bins.
Author(s)
Maud HW Starmans
See Also
xyplot, lattice or the Lattice book for an overview of the package.
Examples
set.seed(12345);
simple.data <- data.frame(
x = rnorm(10000),
y = rnorm(10000)
);
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Simple', fileext = '.tiff'),
formula = y ~ x,
data = simple.data,
main = 'Simple',
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 50
);
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Simple_underlined_legend_title', fileext = '.tiff'),
formula = y ~ x,
data = simple.data,
legend.title = list(lab = expression(bold(underline('Counts'))), x = 1, y = 1.1),
right.padding = 4,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 50
);
# Set up data
hexbin.data <- data.frame(
x = microarray[,1],
y = microarray[,2]
);
# Minimal Input
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Minimal_Input', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Minimal input',
# formatting bins
colourcut = seq(0, 1, length = 11),
# this sets the maximum value plotted -- values greater than this will not appear
maxcnt = 50,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 100
);
# Axes & Labels
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Axes_Labels', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Axes & labels',
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Customize Axes and labels
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 100
);
# Log Scaled Axis
log.data <- data.frame(
x = microarray[,1],
y = 10 ** microarray[,2]
);
create.hexbinplot(
formula = y ~ x,
data = log.data,
main = 'Log Scaled',
# Log base 10 scale y-axis
yat = 'auto.log',
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 100
);
# Aspect Ratio
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Aspect_Ratio', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Aspect ratio',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Set the aspect ratio to control plot dimensions
aspect = 2,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Colour scheme
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Colour_Change', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Colour change',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Specify colour scheme
colour.scheme = colorRampPalette(c('dodgerblue','paleturquoise','chartreuse','yellow',
'orange','red')),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Bin sizes
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Bin_Sizes', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Bin sizes',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colour.scheme = colorRampPalette(c('dodgerblue','paleturquoise','chartreuse', 'yellow',
'orange','red')),
# Specify bin sizes
colourcut = seq(0,1,length = 6),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Correlation Key
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Correlation', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Correlation',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Correlation Key
legend = list(
inside = list(
fun = draw.key,
args = list(
key = get.corr.key(
x = hexbin.data$x,
y = hexbin.data$y,
label.items = c('beta1', 'spearman'),
alpha.background = 0
)
),
x = 0.05,
y = 0.95,
corner = c(0,1),
draw = FALSE
)
),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Grid lines and diagonal
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Gridlines', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Gridlines',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Grid & diagonal
add.grid = TRUE,
add.xyline = TRUE,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Large range
# Generate some fake data with both very low and very high values
set.seed(12345);
x <- c(rnorm(100000,0,0.1),rnorm(1000,0,0.5),rnorm(1000,0,sd=0.75));
y <- c(rnorm(100000,0,0.1),rnorm(1000,0,0.5),rnorm(1000,0,sd=0.75));
fake.data <- data.frame(
x = x,
y = y,
z = y + x*(x+1)/4
);
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Range', fileext = '.tiff'),
formula = z ~ x,
data = fake.data,
main = 'Range',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
aspect = 1,
# Use colourcut to divide the bins appropriately
colourcut = c(0,0.0002,0.0004,0.0008,0.0016,0.0032,0.0064,0.0128,0.0256,0.0512,0.1024,0.2048,
0.4096,0.8192,1),
# Change the colour scheme
colour.scheme = function(n){BTC(n, beg=1, end=256)},
background.col = 'grey',
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Outliers
# Generate data with upper bound outlier
set.seed(12345);
x <- c(rnorm(1000,0,0),rnorm(4000,0,0.5));
y <- c(rnorm(1000,0,0),rnorm(4000,0,0.5));
fake.data.outlier <- data.frame(
x = x,
y = y,
z = y + x*(x+1)/4
);
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Outlier', fileext = '.tiff'),
formula = z ~ x,
data = fake.data.outlier,
main = 'Outlier',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlab.label = 'Sample 1',
ylab.label = 'Sample 2',
aspect = 1,
# Use colourcut to divide the bins appropriately
colourcut = c(seq(0,0.01, length = 4),seq(0.0125,0.1,length=4), seq(0.125,1,length=4)),
xbins = 15,
mincnt = 0,
# Change the colour scheme
colour.scheme = function(n){BTC(n, beg=1, end=256)},
background.col = 'grey',
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Nature style
create.hexbinplot(
# filename = tempfile(pattern = 'Hexbinplot_Nature_style', fileext = '.tiff'),
formula = y ~ x,
data = hexbin.data,
main = 'Nature style',
xaxis.cex = 1,
yaxis.cex = 1,
xaxis.fontface = 1,
yaxis.fontface = 1,
xlab.cex = 1.5,
ylab.cex = 1.5,
xlimits = c(0,16),
ylimits = c(0,16),
xat = seq(0,16,2),
yat = seq(0,16,2),
aspect = 1,
colourcut = seq(0, 1, length = 11),
maxcnt = 50,
# Grid & diagonal
add.grid = TRUE,
add.xyline = TRUE,
# set style to Nature
style = 'Nature',
# demonstrating how to italicize character variables
ylab.lab = expression(paste('italicized ', italic('a'))),
# demonstrating how to create en-dashes
xlab.lab = expression(paste('en dashs: 1','\u2013', '10'^'\u2013', ''^3)),
description = 'Hexbinplot created by BoutrosLab.plotting.general',
resolution = 200
);
# Multiplot different groups
set.seed(73);
# Randomly generate groups
simple.data$groups <- sample(1:2, 10000, replace = TRUE);
simple.data$group.labels <- as.factor(simple.data$groups);
create.hexbinplot(
formula = y ~ x | groups,
# filename = tempfile(
# pattern = 'stratified_hexbinplot_numeric_conditioning',
# fileext = '.tiff'
# ),
data = simple.data,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
strip.col = 'white',
strip.cex = 0.8,
strip.fontface = 'bold',
resolution = 200
);
create.hexbinplot(
formula = y ~ x | group.labels,
# filename = tempfile(
# pattern = 'stratified_hexbinplot_factor_conditioning',
# fileext = '.tiff'
# ),
data = simple.data,
description = 'Hexbinplot created by BoutrosLab.plotting.general',
strip.col = 'white',
strip.cex = 0.8,
strip.fontface = 'bold',
resolution = 200
);
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.