Merge pull request #92 from tidymodels/RC0.1.0

Rc0.1.0

Author: EmilHvitfeldt

.Rbuildignore

@@ -10,3 +10,5 @@
 ^\.github$
 ^dev$
 ^vignettes/articles$
+^cran-comments\.md$
+^CRAN-SUBMISSION$

DESCRIPTION

@@ -1,14 +1,14 @@
 Package: tidyclust
 Title: A Common API to Clustering
-Version: 0.0.0.9000
+Version: 0.1.0
 Authors@R: c(
     person("Emil", "Hvitfeldt", , "emilhhvitfeldt@gmail.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0002-0679-1945")),
     person("Kelly", "Bodwin", , "kelly@bodwin.us", role = "aut"),
-    person("RStudio", role = c("cph", "fnd"))
+    person("Posit Software, PBC.", role = c("cph", "fnd"))
   )
 Description: A common interface to specifying clustering models, in the
-    same style as `parsnip`. Creates unified interface across different
+    same style as 'parsnip'. Creates unified interface across different
     functions and computational engines.
 License: MIT + file LICENSE
 URL: https://github.com/tidymodels/tidyclust
@@ -45,8 +45,6 @@ Suggests:
     rmarkdown,
     testthat (>= 3.0.0),
     workflows (>= 1.1.2)
-VignetteBuilder: 
-    knitr
 Config/Needs/website: pkgdown, tidymodels, tidyverse, palmerpenguins,
     patchwork, ggforce
 Config/testthat/edition: 3

NAMESPACE

@@ -49,13 +49,8 @@ S3method(tune_cluster,workflow)
 S3method(update,hier_clust)
 S3method(update,k_means)
 export("%>%")
-export(.convert_form_to_x_fit)
-export(.convert_form_to_x_new)
-export(.convert_x_to_form_fit)
-export(.convert_x_to_form_new)
 export(ClusterR_kmeans_fit)
 export(augment)
-export(check_empty_ellipse_tidyclust)
 export(cluster_metric_set)
 export(control_cluster)
 export(extract_centroids)

R/arguments.R

@@ -65,6 +65,10 @@ make_form_call <- function(object, env = NULL) {
   fit_call
 }
 
+#' Change arguments of a cluster specification
+#'
+#' @inheritParams parsnip::set_args
+#' @return An updated `cluster_spec` object.
 #' @export
 set_args.cluster_spec <- function(object, ...) {
   the_dots <- enquos(...)
@@ -90,6 +94,10 @@ set_args.cluster_spec <- function(object, ...) {
   )
 }
 
+#' Change mode of a cluster specification
+#'
+#' @inheritParams parsnip::set_mode
+#' @return An updated `cluster_spec` object.
 #' @export
 set_mode.cluster_spec <- function(object, mode) {
   cls <- class(object)[1]

R/augment.R

@@ -9,6 +9,8 @@
 #' @param new_data A data frame or matrix.
 #' @param ... Not currently used.
 #' @rdname augment
+#' @return A `tibble::tibble()` with containing `new_data` with columns added
+#'   depending on the mode of the model.
 #' @examples
 #' kmeans_spec <- k_means(num_clusters = 5) %>%
 #'   set_engine("stats")

R/cluster_spec.R

@@ -3,9 +3,10 @@
 #' These functions are helpful when creating new packages that will register new
 #' cluster specifications.
 #'
+#' @return A `cluster_spec` object made to work with tidyclust.
+#'
 #' @export
 #' @keywords internal
-#' @rdname add_on_exports
 new_cluster_spec <- function(cls, args, eng_args, mode, method, engine) {
   modelenv::check_spec_mode_engine_val(model = cls, mode = mode, eng = engine)
 

R/convert_data.R

@@ -30,7 +30,6 @@
 #' @inheritParams fit.cluster_spec
 #' @rdname convert_helpers
 #' @keywords internal
-#' @export
 .convert_form_to_x_fit <- function(formula,
                                    data,
                                    ...,
@@ -149,10 +148,8 @@ local_one_hot_contrasts <- function(frame = rlang::caller_env()) {
 #' @param weights A numeric vector containing the weights.
 #' @inheritParams fit.cluster_spec
 #' @inheritParams .convert_form_to_x_fit
-#'
 #' @rdname convert_helpers
 #' @keywords internal
-#' @export
 .convert_x_to_form_fit <- function(x,
                                    weights = NULL,
                                    remove_intercept = TRUE) {
@@ -210,7 +207,6 @@ make_formula <- function(x, short = TRUE) {
 #' @inheritParams predict.cluster_fit
 #' @rdname convert_helpers
 #' @keywords internal
-#' @export
 .convert_form_to_x_new <- function(object,
                                    new_data,
                                    na.action = stats::na.pass,
@@ -262,7 +258,6 @@ make_formula <- function(x, short = TRUE) {
 
 #' @rdname convert_helpers
 #' @keywords internal
-#' @export
 .convert_x_to_form_new <- function(object, new_data) {
   new_data <- new_data[, object$x_var, drop = FALSE]
   if (!is.data.frame(new_data)) {

R/engines.R

@@ -1,3 +1,7 @@
+#' Change engine of a cluster specification
+#'
+#' @inheritParams parsnip::set_engine
+#' @return An updated `cluster_spec` object.
 #' @export
 set_engine.cluster_spec <- function(object, engine, ...) {
   mod_type <- class(object)[1]

R/extract.R

@@ -1,3 +1,50 @@
+#' Extract elements of a tidyclust model object
+#'
+#' @description
+#' These functions extract various elements from a clustering object. If they do
+#' not exist yet, an error is thrown.
+#'
+#' - `extract_fit_engine()` returns the engine specific fit embedded within
+#'   a tidyclust model fit. For example, when using [tidyclust::k_means()]
+#'   with the `"lm"` engine, this returns the underlying `kmeans` object.
+#'
+#' - `extract_parameter_set_dials()` returns a set of dials parameter objects.
+#'
+#' @param x A `cluster_fit` object or a `cluster_spec` object.
+#' @param ... Not currently used.
+#' @details
+#' Extracting the underlying engine fit can be helpful for describing the
+#'  model (via `print()`, `summary()`, `plot()`, etc.) or for variable
+#'  importance/explainers.
+#'
+#'  However, users should not invoke the `predict()` method on an extracted
+#'  model. There may be preprocessing operations that `tidyclust` has executed
+#'  on the data prior to giving it to the model. Bypassing these can lead to
+#'  errors or silently generating incorrect predictions.
+#'
+#' **Good**:
+#' ```r
+#'    tidyclust_fit %>% predict(new_data)
+#' ```
+#'
+#' **Bad**:
+#' ```r
+#'    tidyclust_fit %>% extract_fit_engine() %>% predict(new_data)
+#' ```
+#' @return
+#' The extracted value from the tidyclust object, `x`, as described in the
+#' description section.
+#'
+#' @name extract-tidyclust
+#' @examples
+#' kmeans_spec <- k_means(num_clusters = 2)
+#' kmeans_fit <- fit(kmeans_spec, ~ ., data = mtcars)
+#'
+#' extract_fit_engine(kmeans_fit)
+NULL
+
+
+#' @rdname extract-tidyclust
 #' @export
 extract_fit_engine.cluster_fit <- function (x, ...) {
   if (any(names(x) == "fit")) {

R/extract_assignment.R

@@ -3,6 +3,8 @@
 #' @param object An cluster_spec object.
 #' @param ... Other arguments passed to methods.
 #'
+#' @return A `tibble::tibble()` with 1 column `.cluster`.
+#'
 #' @examples
 #' kmeans_spec <- k_means(num_clusters = 5) %>%
 #'   set_engine("stats")