Skip to contents

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.

Author

Ying Wu

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?

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
    );
#> Warning: explicit 'data' specification ignored


# 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
    );
#> Warning: explicit 'data' specification ignored


# 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
    );
#> Warning: explicit 'data' specification ignored


# 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
    );
#> Warning: explicit 'data' specification ignored


# \donttest{
# 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
    );
#> Warning: Cannot compute exact p-value with ties


# 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
    );
#> Warning: explicit 'data' specification ignored
#> Warning: Nature also requires italicized single-letter variables and en-dashes
#> 			for ranges and negatives. See example in documentation for how to do this.
#> Warning: Avoid red-green colour schemes, create TIFF files, do not outline the figure or legend.

# }