copula: pairsRosenblatt – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

pairsRosenblatt

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-square distribution. `"QQgamma"` a Q-Q plot after a map to the gamma distribution. `"PPchisq"` a P-P plot after a map to the chi-square 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 -> [0,1]^n applied to "x" for plotting in one panel.
`g2`	`function` from [0,1]^(n x 2) -> [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 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

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)

copula

Multivariate Dependence with Copulas

v1.0-1

GPL (>= 3) | file LICENCE

Authors

Marius Hofert [aut] (<https://orcid.org/0000-0001-8009-4665>), Ivan Kojadinovic [aut] (<https://orcid.org/0000-0002-2903-1543>), Martin Maechler [aut, cre] (<https://orcid.org/0000-0002-8685-9910>), Jun Yan [aut] (<https://orcid.org/0000-0003-4401-7296>), Johanna G. Nešlehová [ctb] (evTestK(), <https://orcid.org/0000-0001-9634-4796>), Rebecca Morger [ctb] (fitCopula.ml(): code for free mixCopula weight parameters)

Initial release

2020-12-07