pairsRosenblatt {copula}R Documentation

Plots for Graphical GOF Test via Pairwise Rosenblatt Transforms

Description

pairsColList() creates a list containing information about colors for a given matrix of (approximate aka “pseudo”) p-values. These colors are used in pairsRosenblatt() for visualizing a graphical goodness-of-fit test based on pairwise Rosenblatt transformed data.

Usage

pairsRosenblatt(cu.u, pvalueMat=pviTest(pairwiseIndepTest(cu.u)),
                method = c("scatter", "QQchisq", "QQgamma",
                           "PPchisq", "PPgamma", "none"),
                g1, g2, col = "B&W.contrast",
                colList = pairsColList(pvalueMat, col=col),
                main=NULL,
                sub = gpviString(pvalueMat, name = "pp-values"),
		panel = NULL, do.qqline = TRUE,
                keyOpt = list(title="pp-value", rug.at=pvalueMat), ...)

pairsColList(P, pdiv = c(1e-04, 0.001, 0.01, 0.05, 0.1, 0.5),
             signif.P = 0.05, pmin0 = 1e-05, bucketCols = NULL,
             fgColMat = NULL, bgColMat = NULL, col = "B&W.contrast",
             BWcutoff = 170,
             bg.col = c("ETHCL", "zurich", "zurich.by.fog", "baby",
                        "heat", "greenish"),
             bg.ncol.gap = floor(length(pdiv)/3),
             bg.col.bottom = NULL, bg.col.top = NULL, ...)

Arguments

cu.u

(n,d,d)-array of pairwise Rosenblatt-transformed observations as returned by pairwiseCcop().

pvalueMat

(d,d)-matrix of p-values (or pp-values).

method

character indicating the plot method to be used. Currently possible are:

"scatter"

a simple scatter plot.

"QQchisq"

a Q-Q plot after a map to the \chi^2 distribution.

"QQgamma"

a Q-Q plot after a map to the gamma distribution.

"PPchisq"

a P-P plot after a map to the \chi^2 distribution.

"PPgamma"

a P-P plot after a map to the gamma distribution.

"none"

no points are plotted.

Note: These methods merely just set g1 and g2 correctly; see the code for more details.

g1

function from [0,1]^n\to[0,1]^n applied to "x" for plotting in one panel.

g2

function from [0,1]^{n\times 2}\to[0,1]^n applied to "y" for plotting in one panel.

colList

list of colors and information as returned by pairsColList().

main

title.

sub

sub-title with a smart default containing a global (p)p-value.

panel

a panel function as for pairs, or, by default, NULL, where the panel is set as points or “points + qqline” if the method is "QQ...." and do.qqline is true.

do.qqline

if method = "QQ....", specify if the plot panels should also draw a qqline().

keyOpt

argument passed to .pairsCond() for options for the key.

...

additional arguments passed to .pairsCond() (for pairsRosenblatt()) and to heat_hcl() (for pairsColList; used to generate the color palette), see Details.

P

d \times d matrix of p-values.

pdiv

numeric vector of strictly increasing p-values in (0,1) that determine the “buckets” for the background colors of .pairsCond() which creates the pairs-like goodness-of-fit plot.

signif.P

significance level (must be an element of pdiv).

pmin0

a numeric indicating the lower endpoint of the p-value buckets if pmin is zero. If set to 0, the lowest value of the p-value buckets will also be 0.

Note that pmin0 should be in (0, min(pdiv)) when using pairsColList() for .pairsCond().

bucketCols

vector of length as pdiv containing the colors for the buckets. If not specified, either bg.col.bottom and bg.col.top are used (if provided) or bg.col (if provided).

fgColMat

(d,d)-matrix with foreground colors (the default will be black if the background color is bright and white if it is dark; see also BWcutoff).

bgColMat

(d,d)-matrix of background colors; do not change this unless you know what you are doing.

col

foreground color (defaults to "B&W.contrast" which switches black/white according to BWcutoff), passed to .pairsCond(). If colList is not specified, this color is used to construct the points' color.

BWcutoff

number in (0, 255) for switching foreground color if col="B&W.contrast".

bg.col

color scheme for the background colors.

bg.ncol.gap

number of colors left out as "gap" for color buckets below/above signif.P (to make significance/non-significance more visible).

bg.col.bottom

vector of length 3 containing a HCL color specification. If bg.col.bottom is provided and bucketCols is not, bg.col.bottom is used as the color for the bucket of smallest p-values.

bg.col.top

vector of length 3 containing a HCL color specification. If bg.col.top is provided and bucketCols is not, bg.col.top is used as the color for the bucket of largest p-values.

Details

Extra arguments of pairsRosenblatt() are passed to .pairsCond(), these notably may include key, true by default, which draws a color key for the colors used as panel background encoding (pseudo) p-values.

pairsColList() is basically an auxiliary function to specify the colors used in the graphical goodness-of-fit test as conducted by pairsRosenblatt(). The latter is described in detail in Hofert and Mächler (2013). See also demo(gof_graph).

Value

pairsRosenblatt:

invisibly, the result of .pairsCond().

pairsColList:

a named list with components

fgColMat

matrix of foreground colors.

bgColMat

matrix of background colors (corresponding to P).

bucketCols

vector containing the colors corresponding to pvalueBuckets as described above.

pvalueBuckets

vector containing the endpoints of the p-value buckets.

References

Hofert, M. and Mächler, M. (2014) A graphical goodness-of-fit test for dependence models in higher dimensions; Journal of Computational and Graphical Statistics, 23(3), 700–716. doi:10.1080/10618600.2013.812518

See Also

pairwiseCcop() for the tools behind the scenes. demo(gof_graph) for examples.

Examples

## 2-dim example {d = 2} ===============
##
## "t" Copula with 22. degrees of freedom; and (pairwise) tau = 0.5
nu <- 2.2 # degrees of freedom
## Define the multivariate distribution
tCop <- ellipCopula("t", param=iTau(ellipCopula("t", df=nu), tau = 0.5),
                    dim=2, df=nu)
set.seed(19)
X <- qexp(rCopula(n = 400, tCop))

## H0 (wrongly): a Normal copula, with correct tau
copH0 <- ellipCopula("normal", param=iTau(ellipCopula("normal"), tau = 0.5))

## create array of pairwise copH0-transformed data columns
cu.u <- pairwiseCcop(pobs(X), copula = copH0)

## compute pairwise matrix of p-values and corresponding colors
pwIT <- pairwiseIndepTest(cu.u, N=200) # (d,d)-matrix of test results

round(pmat <- pviTest(pwIT), 3) # pick out p-values
## .286 and .077
pairsRosenblatt(cu.u, pvalueMat= pmat)



### A shortened version of   demo(gof_graph) -------------------------------

N <- 32 ## too small, for "testing"; realistically, use a larger one:
if(FALSE)
N <- 100

## 5d Gumbel copula ##########

n <- 250 # sample size
d <- 5 # dimension
family <- "Gumbel" # copula family
tau <- 0.5
set.seed(17)
## define and sample the copula (= H0 copula), build pseudo-observations
cop <- getAcop(family)
th <- cop@iTau(tau) # correct parameter value
copH0 <- onacopulaL(family, list(th, 1:d)) # define H0 copula
U. <- pobs(rCopula(n, cop=copH0))

## create array of pairwise copH0-transformed data columns
cu.u <- pairwiseCcop(U., copula = copH0)

## compute pairwise matrix of p-values and corresponding colors
pwIT <- pairwiseIndepTest(cu.u, N=N, verbose=interactive()) # (d,d)-matrix of test results
round(pmat <- pviTest(pwIT), 3) # pick out p-values
## Here (with seed=1):  no significant ones, smallest = 0.0603

## Plots ---------------------

## plain (too large plot symbols here)
pairsRosenblatt(cu.u, pvalueMat=pmat, pch=".")

## with title, no subtitle
pwRoto <- "Pairwise Rosenblatt transformed observations"
pairsRosenblatt(cu.u, pvalueMat=pmat, pch=".", main=pwRoto, sub=NULL)

## two-line title including expressions, and centered
title <- list(paste(pwRoto, "to test"),
              substitute(italic(H[0]:C~~bold("is Gumbel with"~~tau==tau.)),
                         list(tau.=tau)))
line.main <- c(4, 1.4)
pairsRosenblatt(cu.u, pvalueMat=pmat, pch=".",
                main=title, line.main=line.main, main.centered=TRUE)

## Q-Q plots -- can, in general, better detect outliers
pairsRosenblatt(cu.u, pvalueMat=pmat, method="QQchisq", cex=0.2)

[Package copula version 1.1-3 Index]