shadings                 package:vcd                 R Documentation

_S_h_a_d_i_n_g-_g_e_n_e_r_a_t_i_n_g _F_u_n_c_t_i_o_n_s _f_o_r _R_e_s_i_d_u_a_l-_b_a_s_e_d _S_h_a_d_i_n_g_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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_binary(observed = NULL, residuals = NULL, expected = NULL, df = NULL,
       col = hcl(c(260, 0), 50, 70))

_A_r_g_u_m_e_n_t_s:

observed: contingecy table of observed values

residuals: contingecy table of residuals

expected: contingecy 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. 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.

line_col: default border 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.

     ...: Other arguments passed to 'hcl' or 'hsv', respectively.

_D_e_t_a_i_l_s:

     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 uniform. 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 (2005) 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.

     The shading 'shading_binary' just visualizes the sign of the
     residuals by using two different colors.

_V_a_l_u_e:

     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).

_A_u_t_h_o_r(_s):

     Achim Zeileis Achim.Zeileis@R-project.org

_R_e_f_e_r_e_n_c_e_s:

     Friendly, M. (1994) Mosaic displays for multi-way contingency
     tables. _Journal of the American Statistical Association_, *89*,
     190-200.

     Zeileis A., Meyer D., Hornik K. (2005), Residual-based Shadings
     for Visualizing (Conditional) Independence. Report 20, Department
     of Statistics and Mathematics, Wirtschaftsuniversitt Wien,
     Research Report Series, <URL: http://epub.wu-wien.ac.at/>.

_S_e_e _A_l_s_o:

     'hcl', 'hsv', 'mosaic', 'assoc', 'strucplot', 'diverge_hcl'

_E_x_a_m_p_l_e_s:

     ## 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 two 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)))

