bump pkg ver; extend datasets vignette

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: heplots
 Type: Package
 Title: Visualizing Hypothesis Tests in Multivariate Linear Models
-Version: 1.7.0
-Date: 2024-05-01
+Version: 1.7.1
+Date: 2024-05-03
 Authors@R: c(
             person(given = "Michael", 
                    family = "Friendly", 

NEWS.md

@@ -1,3 +1,7 @@
+## Version 1.7.1 (2024-05-03)
+
+* Extended the "datasets" vignette with further description of how this was done.
+
 ## Version 1.7.0 (2024-05-01)
 
 This is a semi-major release, primarily documenting all datasets in the package with `@concept` tags.

README.Rmd

@@ -41,7 +41,7 @@ stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://
 
 ## **Visualizing Hypothesis Tests in Multivariate Linear Models** 
 
-Version 1.7.0
+Version 1.7.1
 
 ## Description 
 
@@ -172,7 +172,8 @@ method tags. Their names are linked to their documentation with graphical output
 library(here)
 library(dplyr)
 library(tinytable)
-dsets <- read.csv(here::here("extra", "datasets.csv"))
+#dsets <- read.csv(here::here("extra", "datasets.csv"))
+dsets <- read.csv("https://raw.githubusercontent.com/friendly/heplots/master/extra/datasets.csv")
 dsets <- dsets |> dplyr::select(-X) |> arrange(tolower(dataset))
 
 # link dataset to pkgdown doc

vignettes/datasets.Rmd

@@ -14,7 +14,7 @@ bibliography: "HE-examples.bib"
 link-citations: yes
 csl: apa.csl
 vignette: >
-  %\VignetteIndexEntry{HE plot datasets}
+  %\VignetteIndexEntry{Data sets in the heplots package}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -43,11 +43,46 @@ library(ggplot2)
 library(dplyr)
 ```
 
-The `heplots` package provides a large collection of data sets illustrating a
-variety of multivariate linear models with some an analyses,
-and graphical displays. The table below classifies these with
-method tags (`@concept`). 
-The main methods are:
+## Documenting package datasets {-}
+Datasets used in package examples are such an important part of making a package understandable and usable, but is often overlooked.
+In developing the `heplots` package I collected a large collection of data sets illustrating a
+variety of multivariate linear models with some an analyses, and graphical displays. Each of these have much more than the
+usual stub examples, that often look like:
+
+```{r eval=FALSE}
+data(dataset)
+# str(dataset); plot(dataset)
+```
+
+But `.Rd`, and now `roxygen`, don't make it easy to work with numerous datasets in a package, or, more impportantly, to document what they illustrate. I'm showing the work to create this vignette, in case these ideas are useful to others.
+
+In this release, I started with a file generated by:
+
+```{r}
+vcdExtra::datasets("heplots") |> head(4)
+```
+
+Then, in the roxygen documentation, I added `@concept` tags to classify these datasets according to methods used. For example,
+the documentation for the `AddHealth` data contains these lines:
+
+```{r eval=FALSE}
+#' @name AddHealth
+#' @docType data
+ ...
+#' @keywords datasets
+#' @concept MANOVA
+#' @concept ordered
+```
+
+With standard
+processing, these concepts along with the keywords, appear in the **Index** section of the manual constructed by `devtools::build_manual()`. In the `pkgdown`
+site for this package, they are also searchable in the **search** box.
+
+With a bit of extra processing, I created a dataset [datasets.csv](https://raw.githubusercontent.com/friendly/heplots/master/extra/datasets.csv)
+used below.
+
+## Methods {-}
+The main methods used in the example datasets are shown in the table below:
 
 * **MANOVA**: Multivariate analysis of variance
 * **MANCOVA**: Multivariate of covariance
@@ -70,7 +105,7 @@ The dataset names are linked to the documentation with graphical output on the
 <!-- # fixed by deleting Probe2 from the list and renaming Probe1 -> Probe -->
 
 
-## Dataset table
+## Dataset table {-}
 
 ```{r datasets}
 library(here)
@@ -86,12 +121,11 @@ refurl <- "http://friendly.github.io/heplots/reference/"
 dsets <- dsets |>
   mutate(dataset = glue::glue("[{dataset}]({refurl}{dataset}.html)")) 
 
-#tinytable::tt(dsets)
-knitr::kable(dsets)
-
+#knitr::kable(dsets)
+tinytable::tt(dsets)  |> format_tt(markdown = TRUE)
 ```
 
-## Concept table
+## Concept table {-}
 
 This table can be inverted to list the datasets that illustrate each concept:
 
@@ -103,8 +137,8 @@ concepts <- dsets |>
   summarize(datasets = toString(dataset), .by = tags) |>
   rename(concept = tags)
 
-#tinytable::tt(concepts)
-knitr::kable(concepts)
+#knitr::kable(concepts)
+tinytable::tt(concepts) |> format_tt(markdown = TRUE)
 ```