HWTernaryPlot: Ternary plot with the Hardy-Weinberg acceptance region

View source: R/HWTernaryPlot.R

HWTernaryPlotR Documentation

Ternary plot with the Hardy-Weinberg acceptance region

Description

HWTernaryPlot is a routine that draws a ternary plot for three-way genotypic compositions (AA,AB,BB), and represents the acceptance region for different tests for Hardy-Weinberg equilibrium (HWE) in the plot. This allows for graphical testing of a large set of markers (e.g. SNPs) for HWE. The (non) significance of the test for HWE can be inferred from the position of the marker in the ternary plot. Different statistical tests for HWE can be done graphically with this routine: the ordinary chisquare test, the chisquare test with continuity correction and the Haldane's exact test.

Usage

HWTernaryPlot(X, n = NA, addmarkers = TRUE, newframe = TRUE, hwcurve = TRUE, 
vbounds = FALSE, mafbounds = FALSE, mafvalue = 0.05, axis = 0, region = 1, 
vertexlab = colnames(X), alpha = 0.05, vertex.cex = 1, pch = 19, cc = 0.5, 
markercol = "black", markerbgcol = "black", cex = 0.75, axislab = "", 
verbose = FALSE, markerlab = NULL, markerpos = NULL, mcex = 1, connect =
FALSE, curvecols = rep("black",5), signifcolour = TRUE, patternsigsymbol = 19,
curtyp = "solid", ssf = "max", pvaluetype = "selome", grid = FALSE,
gridlabels = TRUE, patternramp = FALSE, axisticklabels = FALSE, ...)

Arguments

X

a matrix of n genotypic compositions or counts. If it is a matrix of compositions, X should have (n rows that sum 1, and 3 columns, with the relative frequencies of AA, AB and BB respectively. Argument n should be supplied as well. If X is a matrix of raw genotypic counts, it should have 3 columns with the absolute counts of AA, AB and BB respectively. Argument n may be supplied and will be used for painting acceptance regions. If not supplied n is computed from the data in X.

n

the samples size (for a complete composition with no missing data).

addmarkers

represent markers by dots in the triangle (addmarkers=TRUE) or not
(addmarkers=FALSE).

newframe

allows for plotting additional markers in an already existing ternary plot. Overplotting is achieved by setting newframe to FALSE. Setting newframe = TRUE (default) will create a new ternary plot.

hwcurve

draw the HW parabola in the plot (hwcurve=TRUE) or not (hwcurve=FALSE).

vbounds

indicate the area corresponding to expected counts > 5 (vbounds=TRUE) or not (vbounds=FALSE).

mafbounds

indicate the area corresponding to MAF < mafvalue.

mafvalue

a critical value for the minor allele frequency (MAF).

axis

draw a vertex axis
0 = no axis is drawn
1 = draw the AA axis
2 = draw the AB axis
3 = draw the BB axis
4 = draw tick on the A-B axis

region

the type of acceptance region to be delimited in the triangle
0 = no acceptance region is drawn
1 = draw the acceptance region corresponding to a Chi-square test
2 = draw the acceptance region corresponding to a Chi-square test with continuity correction
3 = draw the acceptance region corresponding to a Chi-square test with continuity correction for D > 0
4 = draw the acceptance region corresponding to a Chi-square test with continuity correction for D < 0
5 = draw the acceptance regions for all preceding tests simultaneously
6 = draw the acceptance region corresponding to a Chi-square test with continuity correction with the upper limit for D > 0 and the lower limit for D < 0
7 = draw the acceptance region corresponding to a two-sided exact test

vertexlab

labels for the three vertices of the triangle

alpha

significance level (0.05 by default)

vertex.cex

character expansion factor for the labels of the vertices of the triangle.

pch

the plotting character used to represent the markers.

cc

value for the continuity correction parameter (0.5 by default).

markercol

vector with colours for the marker points in the triangle.

markerbgcol

vector with background colours for the marker points in the triangle.

cex

expansion factor for the marker points in the triangle.

axislab

a label to be put under the horizontal axis.

verbose

print information on the numerically found cut-points between curves of the acceptance region and the edges of the triangle.

markerlab

labels for the markers in the triangle.

markerpos

positions for the marker labels in the triangle (1,2,3 or 4).

mcex

character expansion factor for the labels of the markers in the ternary plot.

connect

connect the represented markers by a line in the ternary plot.

curvecols

a vector with four colour specifications for the different curves that can be used to delimit the HW acceptance region. E.g. curvecols=c("red", "green","blue","black","purple") will paint the Hardy-Weinberg curve red, the limits of the acceptance region for an ordinary chi-square test for HWE green, the limits of the acceptance region for a chi-square test with continuity correction when D > 0 blue and the limits of the acceptance region for a chi-square test with continuity correction when D < 0 black, and the limits of the exact acceptance region purple.

signifcolour

colour the marker points automatically according to the result of a signifance test (green markers non-siginficant, red markers significant). signifcolour only takes effect if region is set to 1, 2 or 7.

patternsigsymbol

plotting character used to represent significant makers when patternramp=TRUE

curtyp

style of the drawn curves ("dashed","solid","dotted",...)

ssf

sample size function ("max","min","mean","median",...). Indicates how the sample size for drawing acceptance regions is determined from the matrix of counts.

pvaluetype

method to compute p-values in an exact test ("dost" or "selome")

grid

draw a reference grid for genotype frequencies at (0.2,0.4,0.6,0.8)

gridlabels

if grid=TRUE plot labels at the grid

patternramp

paint a colour ramp for patterns of genotype frequencies. This will ignore signifcolour, and use colour to represent marker frequencies. The ramp is a green-red gradient for the relative frequency of the pattern.

axisticklabels

place numeric labels for allele frequencies on the A-B axis.

...

other arguments passed on to the plot function (e.g. main for a main title).

Details

HWTernaryPlot automatically colours significant markers in red, and non-significant markers in green if region is set to 1, 2 or 7.

Value

minp

minimum allele frequency above which testing for HWE is appropriate (expected counts exceeding 5).

maxp

maximum allele frequency below which testing for HWE is appropriate.

inrange

number of markers in the appropriate range.

percinrange

percentage of markers in the appropriate.

nsignif

number of significant markers (only if region equals 1,2 or 7.)

Author(s)

Jan Graffelman jan.graffelman@upc.edu

References

Graffelman, J. and Morales, J. (2008) Graphical Tests for Hardy-Weinberg Equilibrium Based on the Ternary Plot. Human Heredity 65(2):77-84.

Graffelman, J. (2015) Exploring Diallelic Genetic Markers: The HardyWeinberg Package. Journal of Statistical Software 64(3): 1-23. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.18637/jss.v064.i03")}.

See Also

HWChisq

Examples

#
# Ternary plot with 1000 SNPs and HWE curve
#

X <- HWData(nm=1000,n=100)
HWTernaryPlot(X,100,region=0,vertex.cex=2,pch=1)

#
# Genotype frequency pattern of simulated SNPs with uniform
# allele frequency distribution
#

X <- HWData(nm=1000,n=100)
HWTernaryPlot(X,patternramp = TRUE)

#
# Genotype frequency pattern of simulated SNPs with skewed 
# allele frequency distribution
#

X <- HWData(nm=1000,n=100,shape1=1,shape2=20)
HWTernaryPlot(X,patternramp = TRUE)

#
# Genotype frequency pattern of SNPs simulated under HWE with
# allele frequency of 0.50
#

X <- HWData(nm=1000,n=100,p=0.25)
HWTernaryPlot(X,patternramp = TRUE)

#
# Genotype frequency pattern of SNPs simulated under HWE with
# allele frequency of 0.25
#

X <- HWData(nm=1000,n=100,p=0.25)
HWTernaryPlot(X,patternramp = TRUE)

#
# Genotype frequency pattern of SNPs simulated under HWE with
# allele frequency of 0.25, using a triangle to mark siginficant markers
#

X <- HWData(nm=1000,n=100,p=0.25)
HWTernaryPlot(X,patternramp = TRUE, region=1, patternsigsymbol = 2)

#
# Ternary plot of 1000 SNPs simulated under HWE and uniform allele frequency, with
# acceptance region for a chi-square test and significant markers in red.
#

X <- HWData(nm=1000,n=100)
HWTernaryPlot(X)

#
# Ternary plot of 100 SNPs simulated under HWE and uniform allele frequency, with
# acceptance region for an exact test and significant markers in red.
#

X <- HWData(nm=100,n=100)
## Not run: HWTernaryPlot(X,region=7)

HardyWeinberg documentation built on May 29, 2024, 6:17 a.m.