create.qqplot.fit: Make a quantile-quantile plot of a sample

In BoutrosLab.plotting.general: Functions to Create Publication-Quality Plots

Make a quantile-quantile plot of a sample

Description

Takes a sample and creates a qq plot against a theoretical distribution, possibly conditioned on other variables.

Usage

create.qqplot.fit(
	x,
	data = NA,
	filename = NULL,
	groups = NULL,
	confidence.bands = FALSE,
	conf = 0.95,
        confidence.method = 'both',
	reference.line.method = 'quartiles',
	distribution = qnorm,
	aspect = 'fill',
        prepanel = NULL,
	main = NULL,
	main.just = 'center',
	main.x = 0.5,
	main.y = 0.5,
	main.cex = 3,
        xlab.label = NULL,
	ylab.label = NULL,
	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.col = 'black',
	yaxis.col = 'black',
	xaxis.fontface = 'bold',
        yaxis.fontface = 'bold',
	xaxis.log = FALSE,
	yaxis.log = FALSE,
	xaxis.rot = 0,
	yaxis.rot = 0,
	xaxis.tck = 1,
        yaxis.tck = 1,
	add.grid = FALSE,
	xgrid.at = xat,
	ygrid.at = yat,
	type = 'p',
	cex = 0.75,
	pch = 19,
	col = 'black',
        col.line = 'grey',
	lwd = 2,
	lty = 1,
	axes.lwd = 2.25,
	key = list(text = list(lab = c(''))),
	legend = NULL,
        add.rectangle = FALSE,
	xleft.rectangle = NULL,
	ybottom.rectangle = NULL,
	xright.rectangle = NULL,
        ytop.rectangle = NULL,
	col.rectangle = 'transparent',
	alpha.rectangle = 1,
	top.padding = 3,
	bottom.padding = 0.7,
        left.padding = 0.5,
	right.padding = 0.1,
	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

x	A formula or a numeric vector
data	An optional data source if x is a formula
filename	Filename for tiff output, or if NULL returns the trellis object itself
groups	The grouping variable in the data-frame
confidence.bands	Add confidence bands or not, default to FALSE. Note that in this function, the confidence band can only be added to a single plot, not for multi-qq plot.
conf	Confidence level, default to 0.95
confidence.method	Methods used to draw confidence bands: “simultaneous”, “pointwise”, “both”, defaults to “both”.
reference.line.method	Methods used to draw reference line and must be one of “quartiles”(default), “diagonal”, “robust”. “quartiles” will draw a line across 1/4 and 3/4 quantiles, “diagonal” will draw a 0-1 line, “robust” will draw a best fit line basing on linear model. Note: for multi-panel plot, only the default one is applicable.
distribution	A quantile function that takes a vector of probabilities as argument and produces the corresponding quantiles from a theoretical distribution, defaults to “qnorm”, that is normal distribution.
aspect	This argument controls the physical aspect ratio of the panels, defaults to “fill”
prepanel	A function that takes the same arguments as the “panel”
main	The main plot title
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 overall plot title, defaults to 3
xlab.label	x-axis title
ylab.label	y-axis title
xlab.cex	Size of x-axis label, defaults to 2.5
ylab.cex	Size of y-axis label, defaults to 2.5
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, defaults to automatic
ylimits	Two-element vector giving the y-axis limits, defaults to automatic
xat	Vector listing where the x-axis labels should be drawn, defaults to automatic
yat	Vector listing where the y-axis labels should be drawn, defaults to automatic
xaxis.lab	Vector listing x-axis tick labels, defaults to automatic
yaxis.lab	Vector listing y-axis tick labels, defaults to automatic
xaxis.cex	Size of x-axis scales, defaults to 1.5
yaxis.cex	Size of y-axis scales, defaults to 1.5
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.fontface	Fontface for the x-axis scales
yaxis.fontface	Fontface for the y-axis scales
xaxis.log	Logical indicating whether x-variable should be in logarithmic scale (and what base if numeric)
yaxis.log	Logical indicating whether y-variable should be in logarithmic scale (and what base if numeric)
xaxis.rot	Counterclockwise rotation of text in x-axis scales in degrees, defaults to 0
yaxis.rot	Counterclockwise rotation of text in y-axis scales in degrees, defaults to 0
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
add.grid	Default manner of drawing grid lines
xgrid.at	Vector listing where the x-axis grid lines should be drawn, defaults to xat
ygrid.at	Vector listing where the y-axis grid lines should be drawn, defaults to yat
type	Plot type
cex	Character expansion for plotting symbol
pch	Plotting character
col	Point colour
col.line	QQ line colour, defaults to grey
lwd	Specifies line width, defaults to 2
lty	Specifies line style, defaults to 1 (solid)
axes.lwd	Thickness of width of axes lines
key	A list giving the key (legend). The default suppresses drawing
legend	Add a legend to the plot. Helpful for adding multiple keys and adding keys to the margins of the plot. See xyplot.
add.rectangle	Allow a rectangle to be drawn, default is FALSE
xleft.rectangle	Specifies the left x ooordinate 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
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
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

Value

If filename is NULL then returns the trellis object, otherwise creates a plot and returns a 0/1 success code.

Warning

Note that the confidence band only works for a single panel qq plot, not for grouped data and multi-qq plot. Why? What's missing?

Author(s)

Ying Wu

See Also

qqmath, lattice or the Lattice book for an overview of the package.

Examples

set.seed(12345);
create.qqplot.fit(
    # filename = tempfile(pattern = 'QQfit_Simple', fileext = '.tiff'),
    x = rnorm(300),
    # choosing to compare against a uniform distribution
    distribution = qunif,
    resolution = 100
    );

# Minimal Input
create.qqplot.fit(
    # filename = tempfile(pattern = 'QQfit_Minimal_Input', fileext = '.tiff'),
    x = microarray[1:500,1],
    # choosing to compare against a uniform distribution
    distribution = qunif,
    main = 'Minimal input',
    description = 'QQplot fit created by BoutrosLab.plotting.general',
    resolution = 100
    );

# Axes and Labels
create.qqplot.fit(
    # filename = tempfile(pattern = 'QQfit_Axes_Labels', fileext = '.tiff'),
    x = microarray[1:500,1],
    distribution = qunif,
    main = 'Axes & labels',
    # Adding axes labels
    xlab.label = 'qunif',
    ylab.label = 'sample values',
    xlab.cex = 1.5,
    ylab.cex = 1.5,
    xaxis.fontface = 1,
    yaxis.fontface = 1,
    xaxis.cex = 1,
    yaxis.cex = 1,
    add.grid = TRUE,
    description = 'QQplot fit created by BoutrosLab.plotting.general',
    resolution = 100
    );

# Confidence bands 
create.qqplot.fit(
    # filename = tempfile(pattern = 'QQfit_Confidence_Bands', fileext = '.tiff'),
    x = microarray[1:500,1],
    distribution = qunif,
    main = 'Confidence bands',
    xlab.label = 'qunif',
    ylab.label = 'sample values',
    xlab.cex = 1.5,
    ylab.cex = 1.5,
    xaxis.fontface = 1,
    yaxis.fontface = 1,
    xaxis.cex = 1,
    yaxis.cex = 1,
    add.grid = TRUE,
    # Adding confidence bands (auto-generates legend)
    confidence.bands = TRUE,
    confidence.method = 'both',
    description = 'QQplot fit created by BoutrosLab.plotting.general',
    resolution = 100
    );


# Multiple qq plot conditioned on a variable
# 'Formula' format of data
chr.locations <- microarray$Chr[1:500];
chr.locations <- replace(chr.locations, which(chr.locations == 1), 'Chromosome 1');
chr.locations <- replace(chr.locations, which(chr.locations == 2), 'Chromosome 2');

qqplot.data <- data.frame(
    value = microarray[1:500,1],
    chr = chr.locations
    );

create.qqplot.fit(
    # filename = tempfile(pattern = 'QQfit_Multiple', fileext = '.tiff'),
    x = ~ value | chr,
    data = qqplot.data,
    distribution = qunif,
    main = 'Multiple plots',
    xlab.label = 'qunif',
    ylab.label = 'sample values',
    xlab.cex = 1.5,
    ylab.cex = 1.5,
    xaxis.fontface = 1,
    yaxis.fontface = 1,
    xaxis.cex = 1,
    yaxis.cex = 1,
    add.grid = TRUE,
    confidence.bands = TRUE,
    confidence.method = 'simultaneous',
    description = 'QQplot fit created by BoutrosLab.plotting.general',
    resolution = 100
    );

# Grouped qq plot
create.qqplot.fit(
    # filename = tempfile(pattern = 'QQfit_Grouped', fileext = '.tiff'),
    x = ~ value,
    data = qqplot.data,
    # Adding groups
    groups = qqplot.data$chr,
    # Colouring groups
    col = default.colours(2),
    # Setting different plotting characters
    pch = c(15, 19),
    distribution = qunif,
    main = 'Grouped & legend',
    xlab.label = 'qunif',
    ylab.label = 'sample values',
    xlab.cex = 1.5,
    ylab.cex = 1.5,
    xaxis.fontface = 1,
    yaxis.fontface = 1,
    xaxis.cex = 1,
    yaxis.cex = 1,
    add.grid = TRUE,
    confidence.bands = TRUE,
    confidence.method = 'simultaneous',
    # Adding legend for groups
    key = list(
        text = list(
            lab = c('1','2'),
            cex = 1,
            col = 'black'
            ),
        points = list(
            pch = c(15, 19),
            col = default.colours(2),
            cex = 1
            ),
        x = 0.04,
        y = 0.95,
        padding.text = 2
        ),
    description = 'QQplot fit created by BoutrosLab.plotting.general',
    resolution = 100
    );

# Correlation Key
create.qqplot.fit(
    # filename = tempfile(pattern = 'QQfit_Correlation_Key', fileext = '.tiff'),
    x = ~ value,
    data = qqplot.data,
    groups = qqplot.data$chr,
    col = default.colours(2),
    pch = c(15, 19),
    distribution = qunif,
    main = 'Correlation key',
    xlab.label = 'qunif',
    ylab.label = 'sample values',
    xlab.cex = 1.5,
    ylab.cex = 1.5,
    xaxis.fontface = 1,
    yaxis.fontface = 1,
    xaxis.cex = 1,
    yaxis.cex = 1,
    add.grid = TRUE,
    confidence.bands = TRUE,
    confidence.method = 'simultaneous',
    # Adjusting legend to contain multiple keys
    legend = list(
        inside = list(
            fun = draw.key,
            args = list(
                key = list(
                        text = list(
                            lab = c('1','2'),
                            cex = 1,
                            col = 'black'
                            ),
                        points = list(
                            pch = c(15, 19),
                            col = default.colours(2),
                            cex = 1
                            ),
                        x = 0.14,
                        y = 0.80,
                        padding.text = 2
                    )
                )
            ),
        inside = list(
            fun = draw.key,
            args = list(
                key = get.corr.key(
                    x = runif(500),
                    y = qqplot.data$value,
                    label.items = c('spearman', 'kendall','beta1'),
                    alpha.background = 0,
                    key.cex = 1
                    )
                ),
            x = 0.75,
            y = 0.20,
            corner = c(0,1)
            )
        ),
    description = 'QQplot fit created by BoutrosLab.plotting.general',
    resolution = 100
    );

# Nature style
create.qqplot.fit(
    # filename = tempfile(pattern = 'QQfit_Nature_style', fileext = '.tiff'),
    x = microarray[1:500,1],
    distribution = qunif,
    main = 'Nature style',
    xlab.cex = 1.5,
    ylab.cex = 1.5,
    xaxis.fontface = 1,
    yaxis.fontface = 1,
    xaxis.cex = 1,
    yaxis.cex = 1,
    add.grid = TRUE,
    confidence.bands = TRUE,
    confidence.method = 'both',

    # set style to Nature 
    style = 'Nature',
    
    # demonstrating how to italicize character variables
    ylab.label = expression(paste('italicized ', italic('a'))),
  
    # demonstrating how to create en-dashes
    xlab.label = expression(paste('en dashs: 1','\u2013', '10'^'\u2013', ''^3)),

    description = 'QQplot fit created by BoutrosLab.plotting.general',
    resolution = 1200
    );

BoutrosLab.plotting.general documentation built on Nov. 2, 2023, 6:01 p.m.