work on color_table, knit_include, ...

Author: friendly

NEWS.md

@@ -1,6 +1,6 @@
 ## Version 0.9.3
 
-* Added tidy conversion functions: as_array(), as_caseform(), as_freqform, as_table() PR #22 [Thx: Gavin Klorfine]
+* Added tidy conversion functions: `as_array()`, `as_caseform()`, `as_freqform`, `as_table()` PR #22 [Thx: Gavin Klorfine]
 * Fixed bug in `mcaplot()` coming from `ca::cacoords(): "non-conformable arguments"
 
 ## Version 0.9.2

R/Crossings.R

@@ -4,10 +4,10 @@
 #' `Crossings` creates an n-1 column matrix corresponding to different
 #' degrees of difficulty in crossing from one level to the next, as described
 #' by Goodman (1972).
-#' 
-#' Instead of treating all mobility as equal, this model posits that the difficulty 
-#' of moving between categories increases with the number of boundaries (or "crossings") 
-#' that must be crossed, and that associations between categories decrease 
+#'
+#' Instead of treating all mobility as equal, this model posits that the difficulty
+#' of moving between categories increases with the number of boundaries (or "crossings")
+#' that must be crossed, and that associations between categories decrease
 #' with their separation.
 #'
 #'
@@ -45,11 +45,11 @@
 #' hauser.CRdiag <- update(hauser.indep,
 #'                         ~ . + Crossings(Father,Son) + Diag(Father,Son))
 #' LRstats(hauser.CRdiag)
-#' 
+#'
 #' # what does Crossings do?
-#' cr <-with(Hauser79, Crossings(Father, Son))
+#' cr <- with(Hauser79, Crossings(Father, Son))
 #' head(cr)
-#' Crossings levels
+#' # Show the codings for varying Crossings levels
 #' matrix(cr[,1], nrow=5)
 #' matrix(cr[,2], nrow=5)
 #' matrix(cr[,3], nrow=5)

R/color_table.R

@@ -50,31 +50,34 @@
 #         is confusing and ugly. Examples:
 #     color_table(PreSex,  formula = MaritalStatus + Gender ~ PremaritalSex + ExtramaritalSex)
 #     color_table(PreSex,  formula = Gender + PremaritalSex + ExtramaritalSex ~  MaritalStatus)
-#         This can e handled using column spanners: https://gt.rstudio.com/reference/tab_spanner.html
-#         
+#         This can be handled using column spanners: https://gt.rstudio.com/reference/tab_spanner.html
+#
 
 
-#' Display Frequency Table with Colored Cell Backgrounds
+#' Smart Display of Frequency Table with Colored Cell Backgrounds
 #'
-#' Creates a formatted, semi-graphic "heatmap" table display of frequency data with cell backgrounds
-#' colored according to observed frequencies or their residuals from a loglinear model.
-#' This is an S3 generic function with methods for different input types.
+#' `color_table()` creates a formatted, semi-graphic "heatmap" table display of frequency data with cell backgrounds
+#' colored according to observed frequencies or their residuals from a loglinear model. The goal is to provide a
+#' "smart" tabular display of cross-classified frequency data, with some abilities to highlight possibly interesting
+#' patterns or unusual cells.
+#' This is an S3 generic function, providing methods for different input types: `"table"`, `"xtabs"`, `"matrix"`, `"ftable"`, `"structable"` or `"data.frame"`.
 #'
 #' @param x A `"table"`, `"xtabs"`, `"matrix"`, `"ftable"`, `"structable"`, or `"data.frame"` object
 #' @param ... Additional arguments passed to methods
 #'
 #' @details
 #' This function provides a heatmap-style representation of a frequency table,
 #' where background coloring is used to visualize patterns and anomalies in the data.
-#' When shading by residuals (the default), cells with large positive residuals
+#' When shading by _residuals_ (the default), cells with large positive residuals
 #' (more observations than expected) are shaded red, while cells with large negative
 #' residuals (fewer than expected) are shaded blue. This makes it easy to identify
 #' cells that deviate substantially from what would be expected under a given model
 #' (by default, the independence model).
 #'
 #' For multi-way tables (3 or more dimensions), residuals are computed from the
-#' model of complete independence among all factors using \code{\link[MASS]{loglm}},
-#' unless you specify a model using the `model` or `expected` arguments.
+#' model of complete independence among all factors using \code{\link[MASS]{loglm}}.
+#' But you can specify a model using the `model` or `expected` arguments, in a way similar to that provided
+#' by `mosaic.glm()`.
 #' A message is printed showing the chi-squared statistic, degrees of freedom,
 #' and p-value for this test.
 #'

R/knit_include.R

@@ -1,22 +1,24 @@
 #' Include an HTML-renderable object in any knitr output format
 #'
-#' A pipe-friendly helper for objects that render natively in HTML output
-#' (RStudio Viewer, HTML documents) but need an image fallback for PDF, Word,
-#' and other non-HTML formats.
+#' A pipe-friendly helper in Rmarkdown, Quarto, and other documents for objects that render natively in HTML output
+#' (RStudio Viewer, HTML documents) but need a convenient image fallback for PDF, Word,
+#' and other non-HTML formats. It was designed to solve a problem in rendering the result of `color_table()`,
+#' and then generalized to provide for other similar cases.
 #'
-#' Supported classes:
-#'   - `gt_tbl`     (gt package)       -- saved via \code{\link[gt]{gtsave}}
-#'   - `htmlwidget` (htmlwidgets family: plotly, DT, leaflet, dygraphs, ...)
+#' Supported classes (handled internally) solve this problem by saving the image to a file and then inserting it in the document
+#' using `knitr::include_graphics()`:
+#'   - `"gt_tbl"`     (gt package)       -- saved via \code{\link[gt]{gtsave}}
+#'   - `"htmlwidget"` (htmlwidgets family: plotly, DT, leaflet, dygraphs, ...)
 #'                                     -- saved via
 #'                                        \code{\link[htmlwidgets]{saveWidget}}
 #'                                        + \code{\link[webshot2]{webshot}}
 #'
-#' Packages that handle cross-format output natively (flextable, kableExtra,
-#' huxtable) do NOT need this helper.
+#' Packages that handle cross-format output natively (\pkg{flextable}, \pkg{kableExtra},
+#' \pkg{huxtable}) do NOT need this helper.
 #'
 #' For any other class, \code{x} is returned as-is in all output formats and
 #' knitr's normal printing applies.  This means the function is safe to use in
-#' a pipe on any object: it only intervenes when it knows how to help.
+#' a pipe on any object: it only intervenes when it knows how to help!
 #'
 #' @param x       Any R object. Specialised handling for \code{gt_tbl} and
 #'                \code{htmlwidget}; all other classes are passed through

dev/test-pairs-diag.R

@@ -0,0 +1,17 @@
+# test diag pairs with cell labels
+#
+library(vcdExtra)
+Hoyt <- vcdExtra::Hoyt
+Hoyt2 <- collapse.table(Hoyt,
+                        Status = c("College", rep("Non-College", 3)),
+                        Occupation = c(rep("High", 3),
+                                       rep("Medium", 2),
+                                       rep("Low", 3)))
+
+pairs(
+  Hoyt2,
+  gp = shading_Friendly,
+  space = 0.4,
+  gp_args = list(interpolate = 1:4),
+  diag_panel_args = list(NULL)
+)

man/Crossings.Rd

@@ -21,18 +21,33 @@ library(vcdExtra)
 ## Overview
 
 `color_table()` produces a `gt` table object with cell backgrounds shaded by
-observed frequencies or Pearson residuals from an independence model.
-
-`gt` tables render natively in **HTML output** — just return the object from a
-chunk and knitr handles the rest via `gt`'s built-in `knit_print` method.
-For **PDF or Word output**, save the table as a `.png` image and include it with
-`knitr::include_graphics()` (see [PDF / Word output] below).
+observed frequencies or Pearson residuals from an independence (or user-supplied)
+model. The goal is a "smart" tabular display that makes patterns of association
+or unusual cells immediately visible.
+
+When used interactively in RStudio, the returned `gt` object renders directly
+in the **Viewer** panel — no extra steps needed. However, using `color_table()`
+in R Markdown (`.Rmd`) or Quarto (`.qmd`) documents requires some special
+consideration because `gt` tables render natively only in **HTML output**. For
+**PDF or Word output**, the table must be saved as a PNG image and included with
+`knitr::include_graphics()`.
+
+The `knit_include()` helper in this package handles that branching automatically.
+Piping a `gt` table through `knit_include()` returns it unchanged for HTML output,
+and saves a PNG fallback for all other formats — so the same chunk knits correctly
+regardless of the output format.
 
 ---
 
 ## HTML output — return the gt object directly
 
-No `filename` argument is needed for HTML output.
+For documents that are compiled to HTML, `color_table()` renders natively: just return the object
+from a chunk and `knitr` handles it via `gt`'s built-in `knitr::knit_print()` method.
+No `filename` argument or extra wrapper is needed.
+
+The first example shades cells by Pearson residuals from the independence model
+(the default), making over- and under-represented Hair×Eye combinations
+immediately visible.
 
 ```{r html-basic}
 data(HairEyeColor)
@@ -41,10 +56,18 @@ HEC <- margin.table(HairEyeColor, 1:2)   # collapse over Sex
 color_table(HEC, title = "Hair \u00d7 Eye Color (residual shading)")
 ```
 
+For comparison, shading by raw frequencies (rather than residuals) gives a
+different picture — it highlights which combinations are simply most common,
+not which ones deviate from independence.
+
 ```{r html-freq}
 color_table(HEC, shade = "freq", title = "Hair \u00d7 Eye Color (frequency shading)")
 ```
 
+For a three-way table, a `formula` argument controls the layout: variables on
+the left of `~` become row groups, those on the right become column spanners.
+The legend note reproduces the chi-squared summary printed to the console.
+
 ```{r html-3way}
 color_table(HairEyeColor,
             formula = Eye ~ Hair + Sex,
@@ -61,8 +84,8 @@ For non-HTML output, save the table as a PNG and include with
 `.rtf`, `.docx`. The `vwidth` and `vheight` arguments control the image
 viewport in pixels.
 
-The chunk below is shown for illustration (`eval=FALSE`); the HTML approach
-above is all that is needed when knitting to HTML.
+The chunk below is shown for illustration only (`eval=FALSE`); the HTML approach
+above is sufficient when knitting to HTML.
 
 ```{r pdf-basic, eval=FALSE}
 color_table(HEC,
@@ -76,57 +99,53 @@ knitr::include_graphics("color_table_hec.png")
 
 ---
 
-## Universal helper — works in any output format
-
-This small wrapper branches on `knitr::is_html_output()` so the same source
-knits correctly to HTML, PDF, or Word without changes.
-
-```{r helper}
-include_color_table <- function(x, ..., file = "color_table_tmp",
-                                width = 600, height = 400) {
-  gt_obj <- color_table(x, ...)
-  if (knitr::is_html_output()) {
-    gt_obj
-  } else {
-    img <- paste0(file, ".png")
-    gt::gtsave(gt_obj, filename = img, vwidth = width, vheight = height)
-    knitr::include_graphics(img)
-  }
-}
-```
+## Universal output — `knit_include()`
+
+`knit_include()` eliminates the need to branch on output format by hand.
+Pipe the `gt` object through it and the same chunk works correctly whether
+you are knitting to HTML, PDF, or Word.
 
 ```{r universal-demo}
-include_color_table(HEC,
-                    title  = "Hair \u00d7 Eye Color",
-                    file   = "color_table_universal",
-                    width  = 520,
-                    height = 300)
+color_table(HEC,
+            title = "Hair \u00d7 Eye Color") |>
+  knit_include(width = 520, height = 300)
 ```
 
+`knit_include()` also handles `htmlwidget` objects (plotly, DT, leaflet, …)
+the same way — HTML output gets the interactive widget, PDF/Word output gets
+a screenshot. Any other class is passed through unchanged, so it is safe to
+use in a pipe on any object.
+
 ---
 
 ## More examples
 
-### Display residual values in cells
+### Displaying residual values in cells
+
+Setting `values = "residuals"` replaces the cell frequencies with the
+Pearson residual values themselves. This is useful when the exact magnitude
+of each deviation matters, not just its direction. Row and column totals are
+suppressed automatically because residuals do not have meaningful marginal sums.
 
 ```{r residuals-display}
-include_color_table(HEC,
-                    values = "residuals",
-                    title  = "Hair \u00d7 Eye \u2014 Pearson residuals",
-                    file   = "color_table_resid",
-                    width  = 520,
-                    height = 280)
+color_table(HEC,
+            values = "residuals",
+            title  = "Hair \u00d7 Eye \u2014 Pearson residuals") |>
+  knit_include(width = 520, height = 280)
 ```
 
 ### Multi-way table: PreSex data
 
+The `PreSex` data cross-classifies four variables. Here `MaritalStatus` is
+placed on rows and the two sexual-attitude variables form nested column spanners,
+making the interaction structure easy to read. The legend note records the
+goodness-of-fit for the complete-independence model.
+
 ```{r presex}
 data(PreSex, package = "vcd")
-include_color_table(PreSex,
-                    formula = MaritalStatus ~ PremaritalSex + ExtramaritalSex,
-                    legend  = TRUE,
-                    title   = "Pre/Extra-marital Sex by Marital Status",
-                    file    = "color_table_presex",
-                    width   = 520,
-                    height  = 300)
+color_table(PreSex,
+            formula = MaritalStatus ~ PremaritalSex + ExtramaritalSex,
+            legend  = TRUE,
+            title   = "Pre/Extra-marital Sex by Marital Status") |>
+  knit_include(width = 520, height = 300)
 ```