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-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. (2013) A graphical goodness-of-fit test for dependence models in higher dimensions; Journal of Computational and Graphical Statistics, 23(3), 700–716.

### 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 0.999-15 Index]