Merge pull request #66 from wjakethompson/object-conversion

Add functionality for converting objects to `measrdcm` objects

Author: wjakethompson

.lintr

@@ -6,9 +6,6 @@ exclusions: list(
     "R/stanmodels.R",
     "R/import-standalone-obj-type.R",
     "R/import-standalone-types-check.R",
-    "R/zzz-class-dcm-estimate.R" = list(
-      line_length_linter = Inf
-    ),
     "R/dep-fit-dcm.R" = list(
       line_length_linter = Inf
     ),

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: measr
 Title: Bayesian Psychometric Measurement Using 'Stan'
-Version: 1.0.0.9000
+Version: 1.0.0.9001
 Authors@R: c(
     person("W. Jake", "Thompson", , "wjakethompson@gmail.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0001-7339-0300")),

NAMESPACE

@@ -19,6 +19,7 @@ export(as_label)
 export(as_name)
 export(bic)
 export(cdi)
+export(cmdstanr)
 export(create_profiles)
 export(crum)
 export(dcm_estimate)
@@ -31,17 +32,22 @@ export(enquos)
 export(fit_m2)
 export(fit_ppmc)
 export(get_parameters)
+export(gqs)
 export(hdcm)
 export(independent)
 export(lcdm)
 export(loglik_array)
 export(loo)
 export(loo_compare)
+export(mcmc)
 export(measr_dcm)
 export(measr_examples)
 export(measr_extract)
+export(measrdcm)
+export(optim)
 export(prior)
 export(reliability)
+export(rstan)
 export(rvar_mad)
 export(rvar_max)
 export(rvar_mean)

R/zxx-class-stan-classes.R

@@ -1,13 +1,71 @@
-# Define classes for estimation methods ----------------------------------------
-stanmethod <- S7::new_class("stanmethod", package = "measr")
-
-mcmc <- S7::new_class("mcmc", parent = stanmethod, package = "measr")
-optim <- S7::new_class("optim", parent = stanmethod, package = "measr")
-gqs <- S7::new_class("gqs", parent = stanmethod, package = "measr")
-
+#' S7 classes for estimation specifications
+#'
+#' The constructors for Stan back-ends and methods are exported to support
+#' extensions to measr, for example converting other models to `measrfit`
+#' objects. We do not expect or recommend calling these functions directly
+#' unless you are converting objects, or creating new methods for measrfit
+#' objects.
+#'
+#' @details
+#' ## Back-end classes
+#'
+#' There are two classes for estimation backends, which define the package that
+#' should be used, or was used, to estimate a model.
+#' The `rstan()` class indicates use of `{rstan}`, whereas `cmdstanr()`
+#' indicates use of `{cmdstanr}`.
+#' Both classes inherit from `measr::stanbackend`.
+#'
+#' ## Method classes
+#'
+#' The method classes define which estimation method should be used, or was
+#' used, for a model.
+#' The `mcmc()` class indicates the use of Markov chain Monte Carlo via
+#' [rstan::sampling()] when using `{rstan}` or the
+#' [`$sample()`][cmdstanr::sample()] method of the
+#' [CmdStanModel][cmdstanr::CmdStanModel] class when using `{cmdstanr}`.
+#' The `optim()` class indicates the use maximum-likelihood via
+#' [rstan::optimizing()] when using `{rstan}` or the
+#' [`$optimize()`][cmdstanr::optimize()] method of the
+#' [CmdStanModel][cmdstanr::CmdStanModel] class when using `{cmdstanr}`.
+#' Finally, there is a `gqs()` class for use when a model has previously been
+#' estimated and were are interested in calculating generated quantities (e.g.,
+#' [score()], [loglik_array()]).
+#' The `gqs()` class indicates the use of [rstan::gqs()] when using `{rstan}`
+#' and the [`$generate_quantities()`][cmdstanr::generate_quantities()] method of
+#' the [CmdStanModel][cmdstanr::CmdStanModel] class when using `{cmdstanr}`.
+#' All method classes inherit from `measr::stanmethod`.
+#'
+#' @return An [S7 object][S7_object()] with the corresponding class.
+#' @rdname stan-classes
+#' @name stan-classes
+#' @examples
+#' rstan()
+#'
+#' mcmc()
+NULL
 
 # Define classes for backends --------------------------------------------------
 stanbackend <- S7::new_class("stanbackend", package = "measr")
 
+#' @export
+#' @rdname stan-classes
 rstan <- S7::new_class("rstan", parent = stanbackend, package = "measr")
+
+#' @export
+#' @rdname stan-classes
 cmdstanr <- S7::new_class("cmdstanr", parent = stanbackend, package = "measr")
+
+# Define classes for estimation methods ----------------------------------------
+stanmethod <- S7::new_class("stanmethod", package = "measr")
+
+#' @export
+#' @rdname stan-classes
+mcmc <- S7::new_class("mcmc", parent = stanmethod, package = "measr")
+
+#' @export
+#' @rdname stan-classes
+optim <- S7::new_class("optim", parent = stanmethod, package = "measr")
+
+#' @export
+#' @rdname stan-classes
+gqs <- S7::new_class("gqs", parent = stanmethod, package = "measr")

R/zzz-class-dcm-estimate.R

@@ -41,16 +41,15 @@
 #'   * For `backend = "rstan"`, arguments are passed to [rstan::sampling()]
 #'     or [rstan::optimizing()].
 #'   * For `backend = "cmdstanr"`, arguments are passed to the
-#'     [`$sample()`](https://mc-stan.org/cmdstanr/reference/model-method-sample.html)
-#'     or
-#'     [`$optimize()`](https://mc-stan.org/cmdstanr/reference/model-method-optimize.html)
-#'     methods of the
-#'     [CmdStanModel](https://mc-stan.org/cmdstanr/reference/CmdStanModel.html)
-#'     class.
+#'     [`$sample()`][cmdstanr::sample()] or
+#'     [`$optimize()`][cmdstanr::optimize()] methods of the
+#'     [CmdStanModel][cmdstanr::CmdStanModel] class.
 #'
 #' @concept Bayesian
 #' @concept DCM
 #' @concept Stan
+#' @concept Cmd
+#' @concept Model
 #'
 #' @returns A `measrdcm` object.
 #' @export
@@ -173,8 +172,8 @@ dcm_estimate <- function(dcm_spec, data, missing = NA, identifier = NULL,
 #' @param backend The name of the backend used to fit the model.
 #' @param model The fitted Stan model. This will object of class
 #'   [rstan::stanfit-class] if `backend = "rstan"` and
-#'   [`CmdStanMCMC`](https://mc-stan.org/cmdstanr/reference/CmdStanMCMC.html)
-#'   if `backend = "cmdstanr"` was specified when fitting the model.
+#'   [`CmdStanMCMC`][cmdstanr::CmdStanMCMC] if `backend = "cmdstanr"` was
+#'   specified when fitting the model.
 #' @param respondent_estimates An empty list for adding estimated person
 #'   parameters after fitting the model.
 #' @param fit An empty list for adding model fit information after fitting the
@@ -194,7 +193,7 @@ dcm_estimate <- function(dcm_spec, data, missing = NA, identifier = NULL,
 measrfit <- S7::new_class("measrfit", package = "measr",
   properties = list(
     model_spec = S7::new_property(
-      class = S7::S7_object,
+      class = S7::class_any,
       setter = function(self, value) {
         if (!is.null(self@model_spec)) {
           stop("@model_spec is read-only", call. = FALSE)
@@ -214,8 +213,7 @@ measrfit <- S7::new_class("measrfit", package = "measr",
       }
     ),
     stancode = S7::new_property(
-      class = S7::new_S3_class(class = c("glue", "character")),
-      default = glue::glue(),
+      class = S7::class_character,
       setter = function(self, value) {
         if (!is.null(self@stancode)) {
           stop("@stancode is read-only", call. = FALSE)
@@ -226,7 +224,7 @@ measrfit <- S7::new_class("measrfit", package = "measr",
     ),
     method = S7::new_property(
       class = stanmethod,
-      default = optim(),
+      default = NULL,
       setter = function(self, value) {
         if (!is.null(self@method)) {
           stop("@method is read-only", call. = FALSE)
@@ -247,7 +245,7 @@ measrfit <- S7::new_class("measrfit", package = "measr",
     ),
     backend = S7::new_property(
       class = stanbackend,
-      default = rstan(),
+      default = NULL,
       setter = function(self, value) {
         if (!is.null(self@backend)) {
           stop("@backend is read-only", call. = FALSE)
@@ -325,8 +323,59 @@ measrfit <- S7::new_class("measrfit", package = "measr",
   }
 )
 
+#' S7 class for measrdcm objects
+#'
+#' The `measrdcm` constructor is exported to facilitate the conversion of other
+#' model objects (e.g., `stanfit`) to `measrdcm` objects. We do not expect or
+#' recommend calling this function directly, unless you are creating a method
+#' for converting to `measrdcm`. Rather, to create a `measrdcm` object, one
+#' should use [dcm_estimate()].
+#'
+#' @param model_spec The model specification used to estimate the model.
+#' @param data The data used to estimate the model.
+#' @param stancode The model code in *Stan* language.
+#' @param method The method used to fit the model.
+#' @param algorithm The name of the algorithm used to fit the model.
+#' @param backend The name of the backend used to fit the model.
+#' @param model The fitted Stan model. This will object of class
+#'   [rstan::stanfit-class] if `backend = "rstan"` and
+#'   [`CmdStanMCMC`][cmdstanr::CmdStanMCMC] if `backend = "cmdstanr"` was
+#'   specified when fitting the model.
+#' @param respondent_estimates An empty list for adding estimated person
+#'   parameters after fitting the model.
+#' @param fit An empty list for adding model fit information after fitting the
+#'   model.
+#' @param criteria An empty list for adding information criteria after fitting
+#'   the model.
+#' @param reliability An empty list for adding reliability information after
+#'   fitting the model.
+#' @param file Optional name of a file which the model objects was saved to
+#'   or loaded from.
+#' @param version The versions of measr, *Stan*, and rstan or cmdstanr that were
+#'   used to fit the model.
+#'
+#' @concept Stan
+#'
+#' @returns A `measrdcm` object.
+#' @seealso [dcm_estimate()].
+#' @export
+#'
+#' @examples
+#' qmatrix <- tibble::tibble(
+#'   att1 = sample(0:1, size = 15, replace = TRUE),
+#'   att2 = sample(0:1, size = 15, replace = TRUE),
+#'   att3 = sample(0:1, size = 15, replace = TRUE),
+#'   att4 = sample(0:1, size = 15, replace = TRUE)
+#' )
+#'
+#' spec <- dcm_specify(qmatrix = qmatrix)
+#'
+#' measrdcm(spec)
 measrdcm <- S7::new_class("measrdcm", parent = measrfit, package = "measr",
   properties = list(
-    model_spec = S7::new_property(class = dcmstan::dcm_specification)
+    model_spec = S7::new_property(
+      class = dcmstan::dcm_specification,
+      default = NULL
+    )
   )
 )

_pkgdown.yml

@@ -83,6 +83,8 @@ reference:
 - title: internal
   contents:
   - measr_examples
+  - measrdcm
+  - stan-classes
 
 articles:
 - title: Get started

inst/WORDLIST

@@ -4,6 +4,7 @@ CDM
 CDMs
 CMD
 Cai
+Cmd
 CmdStan
 CmdStanModel
 CmdStanR
@@ -18,12 +19,16 @@ Gabry
 Gelman
 Gierl
 Kiado
+Kreiner
 Kruskal's
 Kullback
 LCDM
 Leibler
 Liu
+Makransky
+Marais
 Maydeu
+Mesbah
 Metaprogramming
 Mplus
 Netlify
@@ -34,13 +39,15 @@ PPMCs
 Petrov
 RMSEA
 RStan
+Rasch
 Roussos
 Rtools
 Rupp
 SRMSR
 Schwarz
 Sinharay
 Templin
+Thissen
 Tian
 Vehtari
 WAIC