feat: R6 documentation

DESCRIPTION

@@ -53,7 +53,7 @@ Suggests:
     prettydoc,
     ggthemes (>= 4.2.0),
     visNetwork (>= 2.0.0)
-Roxygen: list(markdown = TRUE, r6 = FALSE)
+Roxygen: list(markdown = TRUE, r6 = TRUE)
 RoxygenNote: 7.1.0
 StagedInstall: no
 VignetteBuilder: knitr

R/Entity.R

@@ -1,34 +1,14 @@
 #' @title Entity class
 #'
-#' @description
-#'
-#' The base class (first building block) for [Agent], [Asset] and [Environment].
-#'
-#' @usage NULL
 #' @include Generic.R
-#' @format [R6::R6Class] object.
 #'
-#' @section Construction:
-#'
-#' ```
-#' x <- Entity$new(databackend, .data, id_col)
-#' ```
-#'
-#' Stores `.data` as a DataBackend object inside the object's list of data (`private$.data`)
-#' and registers the `id_col` (`private$.id_col`).
+#' @description
 #'
-#' * `databackend` :: an [R6::R6Class] generator]\cr
-#'   An [R6::R6Class] generator that inherits from `DataBackend`.
+#' The base class (first building block) for [Agent], [Asset] and [Environment].
 #'
-#' * `.data` :: `data.frame()`\cr
-#'   A object that inherits from `data.frame`.
 #'
-#' * `id_col` :: `character()`\cr
-#'   The name of the id column of `.data` and all relation columns. The first
-#'   element will be checked as the main id column of the entity data, which
-#'   must be unique integers. The rest of the vector will be consider as relation
-#'   columns. For example, if `c("pid", "partner_id")` is given `pid` must contain
-#'   unique integers, while `partner_id` can be `NA` or non-unique integers.
+#' @template param_databackend
+#' @template param_data
 #'
 #' @section Active Fields (read-only):
 #'
@@ -132,6 +112,15 @@ Entity <-
     inherit = Generic,
     public = list(
 
+      #' @description
+      #'
+      #' Create a new instance of this [R6][R6::R6Class] class.
+      #'
+      #' @param id_col The name of the id column of `.data` and all relation columns. The first
+      #'   element will be checked as the main id column of the entity data, which
+      #'   must be unique integers. The rest of the vector will be consider as relation
+      #'   columns. For example, if `c("pid", "partner_id")` is given `pid` must contain
+      #'   unique integers, while `partner_id` can be `NA` or non-unique integers.
       initialize = function(databackend, .data, id_col) {
         # browser()
         checkmate::assert_character(id_col, null.ok = FALSE, min.len = 1, unique = T, any.missing = FALSE, names = "unnamed")

R/Model.R

@@ -12,14 +12,10 @@
 #' By doing so, you can assess those models from [World] as it is flowing down a
 #' microsimulation pipeline just like [Entities].
 #'
-#' @section Construction:
+#' @section S3 methods:
 #'
-#' ```
-#' x <- Model$new(x)
-#' ```
-#'
-#' * `x` :: ([caret::train] | [data.table::data.table] | named `list`)\cr
-#' A model object that compatible.
+#' * `summary(m)`\cr
+#'  Ruturns summary of the stored model object.
 #'
 #' @section Active field (read-only):
 #'
@@ -35,23 +31,14 @@
 #' the use of a [Model] object to the specific group of agents (e.g: age between
 #' `x` and `y`) that was used to estimate the model.
 #'
-#' @section Public Methods:
-#'
-#'  * `get()`\cr
-#'  () -> ([caret::train] | [data.table::data.table] | named `list`)\cr
-#'  Get a model object.
-#'
-#'  * `set(x)`\cr
-#'  ([caret::train] | [data.table::data.table] | named `list`)\cr
-#'  Get a model object.
-#'
-#'  * `modify()`\cr
-#'  An abstract method.
-#'
-#'  * `simulate()`\cr
-#'  An abstract method.
+#' @section Public fields:
 #'
-#'  * `print()`\cr
+#' * `preprocessing_fn`\cr
+#' Default as NULL, this is to store a preprocessing function which will be
+#' used to evaluate the entity data in [Trans] prior to simulating the
+#' transition. A situation where this is useful could be when you want to limit
+#' the use of a [Model] object to the specific group of agents (e.g: age between
+#' `x` and `y`) that was used to estimate the model.
 #'
 #' @aliases Models
 #'
@@ -86,27 +73,51 @@ Model <-
     classname = "Model",
     inherit = Generic,
     public = list(
+
+
+      #' @description
+      #' Creates a new instance of this [R6][R6::R6Class] class.
+      #'
+      #' @param x a model object that is of one of {`r paste(get_supported_models(), collapse = ", ")`}
+      #' @param preprocessing_fn a function.
       initialize = function(x, preprocessing_fn = NULL) {
         self$preprocessing_fn <- preprocessing_fn
         self$set(x)
       },
+
+      #' @description
+      #'
+      #' Returns a copy of the stored model object. This is to prevent returning
+      #' a reference of the data.table object that might be used as a model.
+      #'
+      #' @return a model object.
       get = function() {
-        private$.model
+        if (is.data.table(private$.model)) {
+          return(data.table::copy(private$.model))
+        }
+        return(private$.model)
       },
+
+      #' @description
+      #'
+      #' An abstract method.
+      #'
+      #' @return
       set = function(x) {
         assert_transition_supported_model(x)
         private$.model <- x
         return(self)
       },
-      modify = function() {
-        private$abstract()
-      },
-      simulate = function() {
-        private$abstract()
-      },
+
+      #' @description
+      #'
+      #' Returns the class of the stored model object.
+      #'
+      #' @return a character
       class = function() {
         class(private$.model)
       },
+
       print = function() {
         print(private$.model)
       },
@@ -125,11 +136,8 @@ Model <-
     )
   )
 
-#' @param object a [Model] object
-#' @param ... dots
-#'
+
 #' @export
-#' @rdname Model
 summary.Model <- function(object, ...) {
   if (object$class() == "WrappedModel") {
     summary(object$model$learner.model)

R/Population.R

@@ -112,9 +112,24 @@ Population <- R6Class(
   public = list(
     # public ------------------------------------------------------------------
 
+    #' @field ind the reference to the [Individual] object created by Population
     ind = NULL,
+    #' @field hh the reference to the [Household] object created by Population
     hh = NULL,
 
+    #' @description
+    #' Create a [Population] object.
+    #'
+    #' @param ind_data ([data.table::data.table]) Microdata of Individuals/Persons.
+    #' @param hh_data ([data.table::data.table]) Microdata of Households.
+    #' @param pid_col (`character(1)`) Individual/Person id column in `ind_data`.
+    #' @param hid_col (`character(1)`) Household id column in `hh_data`.
+    #'
+    #' @return An [R6::R6Class] object of the [Population] class.
+    #'
+    #' @examples
+    #'
+    #' Pop <- Population$new()
     initialize = function(ind_data, hh_data, pid_col = NULL, hid_col = NULL){
       checkmate::assert_data_table(ind_data, min.rows = 1)
       checkmate::assert_data_table(hh_data, min.rows = 1)

R/module.R

@@ -16,7 +16,7 @@ dymiumModulesRepo <- "dymium-org/dymiumModules"
 #' @param .basedir :: `character(1)`\cr
 #' The base directory that the downloaded module will be saved at. [here::here()] is
 #' used to provide the default value which is is the root folder of the active RStudio project.
-#' @template repo-arg
+#' @template param_modulerepo
 #'
 #' @return path to the module.
 #'
@@ -67,7 +67,7 @@ download_module <- function(name, repo = dymiumModulesRepo, version, force = FAL
 #' Check if a module exists in a remote repository
 #'
 #' @param name name of the module to check.
-#' @template repo-arg
+#' @template param_modulerepo
 #'
 #' @return a logical value.
 #' @export
@@ -88,7 +88,7 @@ check_module <- function(name, repo = dymiumModulesRepo) {
 #' @param version a character. For example, if you would like to check
 #' for version 0.1.0 type it as a character '0.1.0'.
 #'
-#' @template repo-arg
+#' @template param_modulerepo
 #'
 #' @return a logical value
 #' @export
@@ -128,7 +128,7 @@ extract_module_versions <- function(name, filenames) {
 #' Get all version numbers of a module
 #'
 #' @param name name of the module.
-#' @template repo-arg
+#' @template param_modulerepo
 #'
 #' @return a character vector.
 #' @export
@@ -158,7 +158,7 @@ get_module_versions <- function(name, repo = dymiumModulesRepo) {
 
 #' Get the names of available modules from a remote repository
 #'
-#' @template repo-arg
+#' @template param_modulerepo
 #'
 #' @return a character vector.
 #' @export
@@ -181,7 +181,7 @@ get_modules <- function(repo = dymiumModulesRepo) {
 #' Get all files from a module
 #'
 #' @param name name of the module.
-#' @template repo-arg
+#' @template param_modulerepo
 #'
 #' @return a character vector.
 #' @export
@@ -204,7 +204,7 @@ get_module_files <- function(name, repo = dymiumModulesRepo) {
 
 #' Get all files from all modules in a repository.
 #'
-#' @template repo-arg
+#' @template param_modulerepo
 #'
 #' @return a character vector.
 #' @export

man-roxygen/param_data.R

@@ -0,0 +1,2 @@
+#' @param .data (`data.frame()`|[data.table::data.table()])\cr
+#'   A `data.frame` containing `Entity` data.

man-roxygen/param_databackend.R

@@ -0,0 +1,3 @@
+#' @param databackend ([DataBackend])\cr
+#'   Either a [DataBackend], or any object that inherits its such as [DataBackendDataTable]
+#'   and [DataBackendSpatialFeature].