Shading-generating functions for computing residual-based shadings for mosaic and association plots.

```
shading_hcl(observed, residuals = NULL, expected = NULL, df = NULL,
h = NULL, c = NULL, l = NULL, interpolate = c(2, 4), lty = 1,
eps = NULL, line_col = "black", p.value = NULL, level = 0.95, ...)
```shading_hsv(observed, residuals = NULL, expected = NULL, df = NULL,
h = c(2/3, 0), s = c(1, 0), v = c(1, 0.5),
interpolate = c(2, 4), lty = 1, eps = NULL, line_col = "black",
p.value = NULL, level = 0.95, ...)

shading_max(observed = NULL, residuals = NULL, expected = NULL, df = NULL,
h = NULL, c = NULL, l = NULL, lty = 1, eps = NULL, line_col = "black",
level = c(0.9, 0.99), n = 1000, ...)

shading_Friendly(observed = NULL, residuals = NULL, expected = NULL, df = NULL,
h = c(2/3, 0), lty = 1:2, interpolate = c(2, 4),
eps = 0.01, line_col = "black", ...)

shading_Friendly2(observed = NULL, residuals = NULL,
expected = NULL, df = NULL, lty = 1:2, interpolate = c(2, 4), eps =
0.01, line_col = "black", ...)

shading_sieve(observed = NULL, residuals = NULL, expected = NULL, df = NULL,
h = c(260, 0), lty = 1:2, interpolate = c(2, 4),
eps = 0.01, line_col = "black", ...)

shading_binary(observed = NULL, residuals = NULL, expected = NULL, df = NULL,
col = NULL)

shading_Marimekko(x, fill = NULL, byrow = FALSE)

shading_diagonal(x, fill = NULL)

hcl2hex(h = 0, c = 35, l = 85, fixup = TRUE)

A shading function which takes only a single argument, interpreted as a
vector/table of residuals, and returns a `"gpar"`

object with the
corresponding vector(s)/table(s) of graphical parameter(s).

- observed
contingency table of observed values

- residuals
contingency table of residuals

- expected
contingency table of expected values

- df
degrees of freedom of the associated independence model.

- h
hue value in the HCL or HSV color description, has to be in [0, 360] for HCL and in [0, 1] for HSV colors. The default is to use blue and red for positive and negative residuals respectively. In the HCL specification it is

`c(260, 0)`

by default and for HSV`c(2/3, 0)`

.- c
chroma value in the HCL color description. This controls the maximum chroma for significant and non-significant results respectively and defaults to

`c(100, 20)`

.- l
luminance value in the HCL color description. Defaults to

`c(90, 50)`

for small and large residuals respectively.- s
saturation value in the HSV color description. Defaults to

`c(1, 0)`

for large and small residuals respectively.- v
saturation value in the HSV color description. Defaults to

`c(1, 0.5)`

for significant and non-significant results respectively.- interpolate
a specification for mapping the absolute size of the residuals to a value in [0, 1]. This can be either a function or a numeric vector. In the latter case, a step function with steps of equal size going from 0 to 1 is used.

- lty
a vector of two line types for positive and negative residuals respectively. Recycled if necessary.

- eps
numeric tolerance value below which absolute residuals are considered to be zero, which is used for coding the border color and line type. If set to

`NULL`

(default), all borders have the default color specified by`line\_col`

. If set to a numeric value, all border colors corresponding to residuals with a larger absolute value are set to the full positive or negative color, respectively; borders corresponding to smaller residuals are are drawn with`line\_col`

and`lty[1]`

. This is used principally in `shading\_Friendly`

.

- line_col
default border color (for

`shading_sieve`

: default sieve color).- p.value
the \(p\) value associated with the independence model. By default, this is computed from a Chi-squared distribution with

`df`

degrees of freedom.`p.value`

can be either a scalar or a`function(observed, residuals, expected, df)`

that computes the \(p\) value from the data. If set to`NA`

no inference is performed.- level
confidence level of the test used. If

`p.value`

is smaller than`1 - level`

, bright colors are used, otherwise dark colors are employed. For`shading_max`

a vector of levels can be supplied. The corresponding critical values are then used as`interpolate`

cut-offs.- n
number of permutations used in the call to

`coindep_test`

.- col
a vector of two colors for positive and negative residuals respectively.

- fixup
logical. Should the color be corrected to a valid RGB value before correction?

- x
object of class

`table`

used to determine the dimension.- fill
Either a character vector of color codes, or a palette function that generates such a vector. Defaults to

`rainbow_hcl`

- byrow
logical; shall tiles be filled by row or by column?

- ...
Other arguments passed to

`hcl2hex`

or`hsv`

, respectively.

Achim Zeileis Achim.Zeileis@R-project.org

These shading-generating functions can be passed to `strucplot`

to generate
residual-based shadings for contingency tables. `strucplot`

calls these
functions with the arguments `observed`

, `residuals`

, `expected`

,
`df`

which give the observed values, residuals, expected values and associated
degrees of freedom for a particular contingency table and associated independence
model.

The shadings `shading_hcl`

and `shading_hsv`

do the same thing conceptually,
but use HCL or HSV colors respectively. The former is usually preferred because they
are perceptually based. Both shadings visualize the *sign* of the residuals of
an independence model using two hues (by default: blue and red). The *absolute size* of
the residuals is visualized by the colorfulness and the amount of grey, by default in three categories:
very colorful for large residuals (> 4), less colorful for medium sized residuals (< 4 and > 2),
grey/white for small residuals (< 2). More categories or a continuous scale can
be specified by setting `interpolate`

. Furthermore, the result of a significance
test can be visualized by the amount of grey in the colors. If significant, a colorful
palette is used, if not, the amount of color is reduced.
See Zeileis, Meyer, and Hornik (2007) and `diverge_hcl`

for more details.

The shading `shading_max`

is applicable in 2-way contingency tables and uses
a similar strategy as `shading_hcl`

. But instead of using the cut-offs 2 and 4,
it employs the critical values for the maximum statistic (by default at 90% and 99%).
Consequently, color in the plot signals a significant result at 90% or 99% significance
level, respectively. The test is carried out by calling `coindep_test`

.

The shading `shading_Friendly`

is very similar to `shading_hsv`

, but additionally
codes the sign of the residuals by different line types. See Friendly
(1994) for more details. `shading_Friendly2`

and
`shading_sieve`

are similar, but use HCL colors.

The shading `shading_binary`

just visualizes the sign of the residuals by using
two different colors (default: blue HCL(260, 50, 70) and red HCL(0, 50, 70)).

`shading_Marimekko`

is a simple generating function for
producing, in conjunction with `mosaic`

, so-called
*Marimekko-charts*, which paint the tiles of each columns of a
mosaic display in the same color to better display departures from
independence.

`shading_diagonal`

generates a color shading for basically square
matrices (or arrays having the first two dimensons of same length)
visualizing the diagonal cells, and the off-diagonal cells 1, 2, ...
steps removed.

The color implementations employed are `hsv`

from base R and `polarLUV`

from the colorspace
package, respectively. To transform the HCL coordinates to
a hexadecimal color string (as returned by `hsv`

), the function
`hex`

is employed. A convenience wrapper `hcl2hex`

is provided.

Friendly M. (1994),
Mosaic Displays for Multi-Way Contingency Tables.
*Journal of the American Statistical Association*,
**89**, 190--200.

Meyer D., Zeileis A., and Hornik K. (2006),
The Strucplot Framework: Visualizing Multi-Way Contingency Tables with vcd.
*Journal of Statistical Software*, **17**(3), 1--48.
tools:::Rd_expr_doi("10.18637/jss.v017.i03"). See also `vignette("strucplot", package = "vcd")`

.

Zeileis A., Meyer D., Hornik K. (2007), Residual-Based Shadings for Visualizing
(Conditional) Independence. *Journal of Computational and Graphical Statistics*,
**16**, 507--525.

Zeileis A., Hornik K. and Murrell P. (2008),
Escaping RGBland: Selecting Colors for Statistical Graphics.
*Computational Statistics & Data Analysis*, **53**, 3259--3270.
Preprint available from https://www.zeileis.org/papers/Zeileis+Hornik+Murrell-2009.pdf.

`hex`

,
`polarLUV`

,
`hsv`

,
`mosaic`

,
`assoc`

,
`strucplot`

,
`diverge_hcl`

```
## load Arthritis data
data("Arthritis")
art <- xtabs(~Treatment + Improved, data = Arthritis)
## plain mosaic display without shading
mosaic(art)
## with shading for independence model
mosaic(art, shade = TRUE)
## which uses the HCL shading
mosaic(art, gp = shading_hcl)
## the residuals are too small to have color,
## hence the cut-offs can be modified
mosaic(art, gp = shading_hcl, gp_args = list(interpolate = c(1, 1.8)))
## the same with the Friendly palette
## (without significance testing)
mosaic(art, gp = shading_Friendly, gp_args = list(interpolate = c(1, 1.8)))
## assess independence using the maximum statistic
## cut-offs are now critical values for the test statistic
mosaic(art, gp = shading_max)
## association plot with shading as in base R
assoc(art, gp = shading_binary(col = c(1, 2)))
## Marimekko Chart
hec <- margin.table(HairEyeColor, 1:2)
mosaic(hec, gp = shading_Marimekko(hec))
mosaic(HairEyeColor, gp = shading_Marimekko(HairEyeColor))
## Diagonal cells shading
ac <- xtabs(VisualAcuity)
mosaic(ac, gp = shading_diagonal(ac))
```

Run the code above in your browser using DataLab