diff --git a/DESCRIPTION b/DESCRIPTION index 2d4f8a94..54505bb3 100644 --- a/DESCRIPTION +++ b/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 diff --git a/R/Entity.R b/R/Entity.R index 594576f2..72249159 100644 --- a/R/Entity.R +++ b/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") diff --git a/R/Model.R b/R/Model.R index 8d22081d..bfb4343a 100644 --- a/R/Model.R +++ b/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) diff --git a/R/Population.R b/R/Population.R index 08ff369e..aa66853f 100644 --- a/R/Population.R +++ b/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) diff --git a/R/module.R b/R/module.R index f7e4f7e4..f580553c 100644 --- a/R/module.R +++ b/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 diff --git a/man-roxygen/param_data.R b/man-roxygen/param_data.R new file mode 100644 index 00000000..2cc9ed24 --- /dev/null +++ b/man-roxygen/param_data.R @@ -0,0 +1,2 @@ +#' @param .data (`data.frame()`|[data.table::data.table()])\cr +#' A `data.frame` containing `Entity` data. diff --git a/man-roxygen/param_databackend.R b/man-roxygen/param_databackend.R new file mode 100644 index 00000000..4d5ea94d --- /dev/null +++ b/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]. diff --git a/man-roxygen/repo-arg.R b/man-roxygen/param_modulerepo.R similarity index 100% rename from man-roxygen/repo-arg.R rename to man-roxygen/param_modulerepo.R