From 6e3720691893873ceaae96aec8ea4169e839eb60 Mon Sep 17 00:00:00 2001
From: amarin <17020181+asiripanich@users.noreply.github.com>
Date: Tue, 10 Dec 2019 12:19:26 +1100
Subject: [PATCH 1/2] minor update Population doc
---
R/Population.R | 15 +++++++++++++++
man/Population.Rd | 44 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 59 insertions(+)
diff --git a/R/Population.R b/R/Population.R
index 38f29ea4..d9dc5611 100644
--- a/R/Population.R
+++ b/R/Population.R
@@ -114,9 +114,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){
self$add(Individual$new(), name = "Individual")
self$add(Household$new(), name = "Household")
diff --git a/man/Population.Rd b/man/Population.Rd
index 59f8ba94..ab0d90f2 100644
--- a/man/Population.Rd
+++ b/man/Population.Rd
@@ -94,9 +94,27 @@ their respective objects.
}
}
+\examples{
+
+## ------------------------------------------------
+## Method `Population$new`
+## ------------------------------------------------
+
+
+Pop <- Population$new()
+}
\section{Super classes}{
\code{\link[dymiumCore:Generic]{dymiumCore::Generic}} -> \code{\link[dymiumCore:ContainerGeneric]{dymiumCore::ContainerGeneric}} -> \code{\link[dymiumCore:Container]{dymiumCore::Container}} -> \code{Population}
}
+\section{Public fields}{
+\if{html}{\out{}}
+\describe{
+\item{\code{ind}}{the reference to the \link{Individual} object created by Population}
+
+\item{\code{hh}}{the reference to the \link{Household} object created by Population}
+}
+\if{html}{\out{
}}
+}
\section{Methods}{
\subsection{Public methods}{
\itemize{
@@ -147,10 +165,36 @@ their respective objects.
\if{html}{\out{
}}
\if{html}{\out{}}
\subsection{Method \code{new()}}{
+Create a \link{Population} object.
\subsection{Usage}{
\if{html}{\out{}}\preformatted{Population$new(ind_data, hh_data, pid_col = NULL, hid_col = NULL)}\if{html}{\out{
}}
}
+\subsection{Arguments}{
+\if{html}{\out{}}
+\describe{
+\item{\code{ind_data}}{(\link[data.table:data.table]{data.table::data.table}) Microdata of Individuals/Persons.}
+
+\item{\code{hh_data}}{(\link[data.table:data.table]{data.table::data.table}) Microdata of Households.}
+
+\item{\code{pid_col}}{(\code{character(1)}) Individual/Person id column in \code{ind_data}.}
+
+\item{\code{hid_col}}{(\code{character(1)}) Household id column in \code{hh_data}.}
+}
+\if{html}{\out{
}}
+}
+\subsection{Returns}{
+An \link[R6:R6Class]{R6::R6Class} object of the \link{Population} class.
+}
+\subsection{Examples}{
+\if{html}{\out{}}
+\preformatted{
+Pop <- Population$new()
+}
+\if{html}{\out{
}}
+
+}
+
}
\if{html}{\out{
}}
\if{html}{\out{}}
From 21b3fc26d923b1652d58d88a27414ea1bbc70c83 Mon Sep 17 00:00:00 2001
From: amarin <17020181+asiripanich@users.noreply.github.com>
Date: Wed, 1 Apr 2020 16:53:06 +1100
Subject: [PATCH 2/2] merged
---
DESCRIPTION | 16 +++-
R/Entity.R | 36 +++----
R/Model.R | 95 +++++++++++++------
R/module.R | 17 ++--
man-roxygen/param_data.R | 2 +
man-roxygen/param_databackend.R | 3 +
.../{repo-arg.R => param_modulerepo.R} | 0
7 files changed, 107 insertions(+), 62 deletions(-)
create mode 100644 man-roxygen/param_data.R
create mode 100644 man-roxygen/param_databackend.R
rename man-roxygen/{repo-arg.R => param_modulerepo.R} (100%)
diff --git a/DESCRIPTION b/DESCRIPTION
index edf19e26..bc5afe44 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -41,9 +41,19 @@ Suggests:
covr,
mapview,
knitr,
- rmarkdown
-Roxygen: list(markdown = TRUE, r6 = FALSE)
-RoxygenNote: 7.0.2
+ rmarkdown,
+ ggplot2 (>= 3.0.0),
+ DiagrammeR (>= 1.0.0),
+ randomForest,
+ reactable,
+ patchwork (>= 1.0.0),
+ scales (>= 1.1.0),
+ prettydoc,
+ ggthemes (>= 4.2.0),
+ visNetwork (>= 2.0.0)
+Roxygen: list(markdown = TRUE, r6 = TRUE)
+RoxygenNote: 7.1.0
+StagedInstall: no
VignetteBuilder: knitr
Collate:
'Generic.R'
diff --git a/R/Entity.R b/R/Entity.R
index a9b17e5f..c0db4822 100644
--- a/R/Entity.R
+++ b/R/Entity.R
@@ -1,30 +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(1)`\cr
-#' The id column of `.data`.
+#' @template param_databackend
+#' @template param_data
#'
#' @section Fields:
#'
@@ -118,9 +102,15 @@ Entity <-
inherit = Generic,
public = list(
-
- cont = NULL,
-
+ #' @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) {
checkmate::assert_string(id_col, na.ok = FALSE, null.ok = FALSE)
checkmate::assert_names(names(.data), must.include = id_col, type = 'strict')
diff --git a/R/Model.R b/R/Model.R
index e2547405..def614c0 100644
--- a/R/Model.R
+++ b/R/Model.R
@@ -8,32 +8,24 @@
#'
#' A container for the supported model objects (see [SupportedTransitionModels]).
#'
-#' @section Construction:
+#' @section S3 methods:
#'
-#' ```
-#' x <- Model$new(x)
-#' ```
+#' * `summary(m)`\cr
+#' Ruturns summary of the stored model object.
#'
-#' * `x` :: ([caret::train] | [data.table::data.table] | named `list`)\cr
-#' A model object that compatible.
+#' @section Active field (read-only):
#'
-#' @section Public Methods:
+#' * `model`\cr
+#' The stored model object in its original form.
#'
-#' * `get()`\cr
-#' () -> ([caret::train] | [data.table::data.table] | named `list`)\cr
-#' Get a model object.
+#' @section Public fields:
#'
-#' * `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.
-#'
-#' * `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
#'
@@ -55,28 +47,63 @@ Model <-
classname = "Model",
inherit = Generic,
public = list(
- initialize = function(x) {
+
+
+ #' @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) {
stopifnot(private$.check_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)
+ },
+
+ preprocessing_fn = NULL
+ ),
+ active = list(
+ model = function() {
+ if (is.data.table(private$.model)) {
+ return(data.table::copy(private$.model))
+ }
+ get(".model", envir = private)
}
),
private = list(
@@ -95,3 +122,13 @@ Model <-
}
)
)
+
+
+#' @export
+summary.Model <- function(object, ...) {
+ if (object$class() == "WrappedModel") {
+ summary(object$model$learner.model)
+ } else {
+ summary(object$model)
+ }
+}
diff --git a/R/module.R b/R/module.R
index 15a92aec..873f4930 100644
--- a/R/module.R
+++ b/R/module.R
@@ -13,7 +13,10 @@ dymiumModulesRepo <- "dymium-org/dymiumModules"
#' be downloaded.
#' @param force A logical value. force download even though the module already exists locally.
#' @param remove_download a logical value whether to delete the downloaded zip file or not.
-#' @template repo-arg
+#' @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 param_modulerepo
#'
#' @return path to the module.
#'
@@ -65,7 +68,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
@@ -86,7 +89,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
@@ -126,7 +129,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
@@ -156,7 +159,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
@@ -179,7 +182,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
@@ -202,7 +205,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