Merge pull request #165 from tidymodels/engine-documentation

Author: EmilHvitfeldt

NAMESPACE

@@ -71,6 +71,7 @@ export(.k_means_fit_stats)
 export(augment)
 export(cluster_metric_set)
 export(control_cluster)
+export(cut_height)
 export(extract_centroids)
 export(extract_cluster_assignment)
 export(extract_fit_engine)
@@ -89,6 +90,9 @@ export(get_tidyclust_colors)
 export(glance)
 export(hier_clust)
 export(k_means)
+export(knit_engine_docs)
+export(linkage_method)
+export(list_md_problems)
 export(load_pkgs)
 export(make_classes_tidyclust)
 export(min_grid)
@@ -119,6 +123,7 @@ export(translate_tidyclust)
 export(translate_tidyclust.default)
 export(tune)
 export(tune_cluster)
+export(values_linkage_method)
 importFrom(dplyr,"%>%")
 importFrom(dplyr,bind_cols)
 importFrom(generics,augment)

NEWS.md

@@ -20,6 +20,8 @@
 
 * Cluster reordering is now done at the fitting time, not the extraction and prediction time. (#154)
 
+* Engine specific documentation has been added for all models and engines. (#159)
+
 # tidyclust 0.1.2
 
 * The cluster specification methods for `generics::tune_args()` and `generics::tunable()` are now registered unconditionally (#115).

R/aaa.R

@@ -13,6 +13,13 @@ utils::globalVariables(
   )
 )
 
+
+release_bullets <- function() {
+  c(
+    "Run `knit_engine_docs()` and `devtools::document()` to update docs"
+  )
+}
+
 # nocov end
 
 # ------------------------------------------------------------------------------

R/dials-params.R

@@ -0,0 +1,45 @@
+#' Cut Height
+#'
+#' Used in most `tidyclust::hier_clust()` models.
+#'
+#' @inheritParams dials::Laplace
+#' @examples
+#' cut_height()
+#' @export
+cut_height <- function(range = c(0, dials::unknown()), trans = NULL) {
+  dials::new_quant_param(
+    type = "integer",
+    range = range,
+    inclusive = c(TRUE, TRUE),
+    trans = trans,
+    label = c(cut_height = "Cut Height"),
+    finalize = NULL
+  )
+}
+
+#' The agglomeration Linkage method
+#'
+#' @param values A character string of possible values. See `linkage_methods`
+#'  in examples below.
+#'
+#' @details
+#' This parameter is used in `tidyclust` models for `hier_clust()`.
+#' @examples
+#' values_linkage_method
+#' linkage_method()
+#' @export
+linkage_method <- function(values = values_linkage_method) {
+  dials::new_qual_param(
+    type = "character",
+    values = values,
+    label = c(activation = "Linkage Method"),
+    finalize = NULL
+  )
+}
+
+#' @rdname linkage_method
+#' @export
+values_linkage_method <- c(
+  "ward.D", "ward.D2", "single", "complete", "average", "mcquitty", "median",
+  "centroid"
+)

R/engine_docs.R

@@ -0,0 +1,67 @@
+# https://github.com/tidymodels/parsnip/blob/main/R/engine_docs.R
+
+#' Knit engine-specific documentation
+#' @param pattern A regular expression to specify which files to knit. The
+#' default knits all engine documentation files.
+#' @param ... Options passed to [knitr::knit()].
+#' @return A tibble with column `file` for the file name and `result` (a
+#' character vector that echos the output file name or, when there is
+#' a failure, the error message).
+#' @keywords internal
+#' @export
+knit_engine_docs <- function(pattern = NULL) {
+  rmd_files <- list.files("man/rmd", pattern = "\\.Rmd", full.names = TRUE)
+
+  if (!is.null(pattern)) {
+    target_exists <- grepl(pattern, rmd_files)
+    files <- rmd_files[target_exists]
+  } else {
+    files <- rmd_files[!grepl("(template-)|(setup\\.)|(aaa\\.)", rmd_files)]
+  }
+  outputs <- gsub("Rmd$", "md", files)
+
+  res <- map2(files, outputs, ~ try(knitr::knit(.x, .y), silent = TRUE))
+  is_error <- map_lgl(res, ~ inherits(.x, "try-error"))
+
+  if (any(is_error)) {
+    # In some cases where there are issues, the md file is empty.
+    errors <- res[which(is_error)]
+    error_nms <- basename(files)[which(is_error)]
+    errors <-
+      map_chr(errors, ~ cli::ansi_strip(as.character(.x))) %>%
+      map2_chr(error_nms, ~ paste0(.y, ": ", .x)) %>%
+      map_chr(~ gsub("Error in .f(.x[[i]], ...) :", "", .x, fixed = TRUE))
+    cat("There were failures duing knitting:\n\n")
+    cat(errors)
+    cat("\n\n")
+  }
+
+  res <- map_chr(res, as.character)
+
+  issues <- list_md_problems()
+  if (nrow(issues) > 0) {
+    cat("There are some issues with the help files:\n")
+    print(issues)
+  }
+
+  invisible(tibble::tibble(file = basename(files), result = res))
+}
+
+#' Locate and show errors/warnings in engine-specific documentation
+#' @return A tibble with column `file` for the file name, `line` indicating
+#'   the line where the error/warning occurred, and `problem` showing the
+#'   error/warning message.
+#' @keywords internal
+#' @export
+list_md_problems <- function() {
+  md_files <- list.files("man/rmd", pattern = "\\.md", full.names = TRUE)
+
+  get_errors <- function(file) {
+    lines <- readLines(file)
+    line <- grep("## (Error|Warning)", lines)
+    problem <- lines[line]
+    tibble::tibble(basename(file), line, problem)
+  }
+
+  map(md_files, get_errors) %>% vctrs::vec_rbind()
+}

R/hier_clust.R

@@ -5,6 +5,12 @@
 #' `hier_clust()` defines a model that fits clusters based on a distance-based
 #' dendrogram
 #'
+#' There are different ways to fit this model, and the method of estimation is
+#' chosen by setting the model engine. The engine-specific pages for this model
+#' are listed below.
+#'
+#' - \link[=details_hier_clust_stats]{stats}
+#'
 #' @param mode A single character string for the type of model. The only
 #'   possible value for this model is "partition".
 #' @param engine A single character string specifying what computational engine
@@ -23,7 +29,8 @@
 #' ## What does it mean to predict?
 #'
 #' To predict the cluster assignment for a new observation, we find the closest
-#' cluster. How we measure “closeness” is dependent on the specified type of linkage in the model:
+#' cluster. How we measure “closeness” is dependent on the specified type of
+#' linkage in the model:
 #'
 #' - *single linkage*: The new observation is assigned to the same cluster as
 #'   its nearest observation from the training data.

R/hier_clust_stats.R

@@ -0,0 +1,11 @@
+#' Hierarchical (Agglomerative) Clustering via stats
+#'
+#' [hier_clust()] creates Hierarchical (Agglomerative) Clustering model.
+#'
+#' @includeRmd man/rmd/hier_clust_stats.md details
+#'
+#' @name details_hier_clust_stats
+#' @keywords internal
+NULL
+
+# See inst/README-DOCS.md for a description of how these files are processed

R/k_means.R

@@ -4,7 +4,16 @@
 #'
 #' `k_means()` defines a model that fits clusters based on distances to a number
 #' of centers. This definition doesn't just include K-means, but includes
-#' models like K-prototypes
+#' models like K-prototypes.
+#'
+#' There are different ways to fit this model, and the method of estimation is
+#' chosen by setting the model engine. The engine-specific pages for this model
+#' are listed below.
+#'
+#' - \link[=details_k_means_stats]{stats}: Classical K-means
+#' - \link[=details_k_means_ClusterR]{ClusterR}: Classical K-means
+#' - \link[=details_k_means_klaR]{klaR}: K-Modes
+#' - \link[=details_k_means_clustMixType]{clustMixType}: K-prototypes
 #'
 #' @param mode A single character string for the type of model. The only
 #'   possible value for this model is "partition".

R/k_means_ClusterR.R

@@ -0,0 +1,12 @@
+#' K-means via ClusterR
+#'
+#' [k_means()] creates K-means model. This engine uses the classical definition
+#' of a K-means model, which only takes numeric predictors.
+#'
+#' @includeRmd man/rmd/k_means_ClusterR.md details
+#'
+#' @name details_k_means_ClusterR
+#' @keywords internal
+NULL
+
+# See inst/README-DOCS.md for a description of how these files are processed

R/k_means_clustMixType.R

@@ -0,0 +1,15 @@
+#' K-means via clustMixType
+#'
+#' [k_means()] creates K-prototypes model. A K-prototypes is the middle ground
+#' between a K-means and K-modes model, in the sense that it can be used with
+#' data that contains both numeric and categorical predictors.
+#'
+#' Both numeric and categorical predictors are requires for this engine.
+#'
+#' @includeRmd man/rmd/k_means_clustMixType.md details
+#'
+#' @name details_k_means_clustMixType
+#' @keywords internal
+NULL
+
+# See inst/README-DOCS.md for a description of how these files are processed