Update internal documentation for new features

Author: humanfactors

R/FIPS_formula_interface.R

@@ -4,13 +4,29 @@ validate_formula <- function(.FIPS_sim, model_formula) {
   NULL
 }
 
+
+#' get_bmm_model_frame
+#'
+#' @param .FIPS_sim A FIPS_Simulation object
+#' @param model_formula A formula describing how the time-varying processes predictors should be calculated for the predicted output.
+#'
+#' @return Minimal dataframe with only requird columns for computation
 get_bmm_model_frame <- function(.FIPS_sim, model_formula) {
   validated_labs = attr(terms(model_formula), "term.labels")
   validated_labs = validated_labs[!grepl("I\\(", validated_labs)]
   model_frame = data.frame(.FIPS_sim[,c(validated_labs)])
   return(model_frame)
 }
 
+#' process_bmm_formula
+#'
+#' The pvec is required to ensure it is contained in the environment for expression evaluation.
+#'
+#' @param .FIPS_sim A FIPS_Simulation object
+#' @param model_formula A formula describing how the time-varying processes predictors should be calculated for the predicted output.
+#' @param pvec A required pvec argument for the .FIPS_sim
+#'
+#' @return Minimal dataframe with only requird columns for computation
 process_bmm_formula <- function(.FIPS_sim, model_formula, pvec) {
   validate_formula(.FIPS_sim, model_formula)
   # Get a reduced .FIPS_sim with only required columns
@@ -27,13 +43,15 @@ process_bmm_formula <- function(.FIPS_sim, model_formula, pvec) {
   return(.FIPS_sim)
 }
 
-# Used for adding vectors to .FIPS_sim
+# Used for adding vectors to .FIPS_sim object (i..e, column binding)
+# and ensures attributes as set.
 add_formula_vector <- function(.FIPS_sim, pred_vector, pred_name) {
   .FIPS_sim[,pred_name] = pred_vector
   attr(.FIPS_sim, "pred_cols") = c(attr(.FIPS_sim, "pred_cols"), pred_name)
   return(.FIPS_sim)
 }
 
+# Set the pred_stat object
 set_pred_stat <- function(.FIPS_sim, pred_stat_name) {
     attr(.FIPS_sim, "pred_stat") = pred_stat_name
     return(.FIPS_sim)

R/FIPS_simulate.R

@@ -4,12 +4,26 @@
 #' It will dispatch to the selected model simulation type and then return the df with
 #' the fitted model columns added on as a `FIPS_simulation` object.
 #'
+#' If the formula argument is omitted, then default prediction values will be returned:
+#' KSS and alertness for TPM, and fatigue (i.e., lapses) for unified.
+#'
 #'
 #' @param FIPS_df A valid FIPS_df series that has not already been modelled
 #' @param modeltype String: either `"TPM"` (Three Process Model) or `"unified"`.
 #' @param pvec Parameter vector (named list), see default pvecs for guidance.
-#' @param model_formula A formula describing how the time-varying processes predictors should be calculated for the predicted output. See details.
-#' 
+#' @param model_formula An optional formula describing how the time-varying processes predictors should be calculated for the predicted output. See details.
+#'
+#' @details
+#'
+#' ### Formula Argument
+#'
+#' - The formula argument takes the form of an R formula expression (e.g., `y ~ c + s`).
+#' - The term of the left-hand side (e.g., `y`) defines the variable name
+#' - The term(s) on the right-hand side define how the variable is computed
+#' - All variables must be defined in your enviornment or in the FIPS_simulation output (e.g., `s, c, l, w` for "TPM").
+#' - Parameter vector and other variable arguments must be placed in `I(expression)` format. For example,
+#' `fatigue ~ s + c + I(pvec[["KSS_beta"]])`.
+#'
 #' @md
 #' @return a FIPS_simulation object
 #' @export

R/simulation_threeprocessmodel.R

@@ -219,12 +219,10 @@ TPM_append_model_cols <- function(.FIPS_df) {
 
 #' TPM_add_KSS
 #'
-#' @param .FIPS_sim
+#' Adds the KSS to a TPM FIPS_simulation. Will return error if FIPS_simulation not a TPM.
 #'
-#' @return
-#' @export
+#' @param .FIPS_sim a FIPS_simulation on the TPM
 #'
-#' @examples
 TPM_get_KSS_vector <- function(.FIPS_sim) {
 
   # Make sure we are operating on a TPM model
@@ -248,6 +246,14 @@ TPM_get_KSS_vector <- function(.FIPS_sim) {
   return(KSS_vector)
 }
 
+#' TPM Simulation Dispatcher
+#'
+#' Constructor/dispatcher for TPM model simulations.
+#'
+#' @param dat input dataframe (ensure this is in FIPS format)
+#' @param pvec a vector of default parameters
+#' @param model_formula A formula expression object of desired model caluclation
+#'
 TPM_simulation_dispatch <- function(dat, pvec, model_formula) {
   # check pvec for any problems, and whether parameters are the default
   TPM_check_pvec(pvec)
@@ -256,12 +262,12 @@ TPM_simulation_dispatch <- function(dat, pvec, model_formula) {
   dat = TPM_append_model_cols(dat)
   # Run the unified main simulation loop on dat
   dat = TPM_simulate(pvec, dat)
-  # Assign as FIPS_simulation class 
+  # Assign as FIPS_simulation class
   dat = FIPS_simulation(dat, modeltype = "TPM", pvec = pvec, pred_stat = "alertness", pred_cols = TPM_cols, model_formula = model_formula)
   # Add any required formula calculations
   if (is.null(model_formula)) {
     dat = add_formula_vector(.FIPS_sim = dat, pred_vector = TPM_get_KSS_vector(dat), pred_name = "KSS")
-    dat = process_bmm_formula(dat, alertness ~ s + c + u, pvec)  
+    dat = process_bmm_formula(dat, alertness ~ s + c + u, pvec)
   }
   if (!is.null(model_formula)) {
     dat = process_bmm_formula(dat, model_formula, pvec)

R/simulation_unifiedfatiguemodel.R

@@ -158,18 +158,26 @@ unified_append_model_cols <- function(.FIPS_df) {
   return(.FIPS_df)
 }
 
+
+#' Unified Simulation Dispatcher
+#'
+#' Constructor/dispatcher for Unified model simulations.
+#'
+#' @param dat input dataframe (ensure this is a FIPS_df)
+#' @param pvec a vector of default parameters, see [unified_pvec]
+#' @param model_formula A formula expression object of desire model caluclation
 unified_simulation_dispatch <- function(dat, pvec, model_formula) {
   # check pvec
   unified_check_pvec(pvec)
   # Add the unified model columns
   dat = unified_append_model_cols(dat)
   # Run the unified main simulation loop on dat
   dat = unified_simulate(pvec, dat)
-  # Assign as FIPS_simulation class 
+  # Assign as FIPS_simulation class
   dat = FIPS_simulation(dat, modeltype = "unified", pvec = pvec, pred_stat = "fatigue", pred_cols = unified_cols)
   # Add any required formula calculations
     if (is.null(model_formula)) {
-    dat = process_bmm_formula(dat, fatigue ~ s + I(pvec["kappa"]) * c, pvec)  
+    dat = process_bmm_formula(dat, fatigue ~ s + I(pvec["kappa"]) * c, pvec)
   }
   if (!is.null(model_formula)) {
     dat = process_bmm_formula(dat, model_formula, pvec)
@@ -202,7 +210,7 @@ unified_simulation_dispatch <- function(dat, pvec, model_formula) {
 #' @return simulated dataset complete
 #' @export
 unified_simulate <- function(pvec, dat) {
-  
+
   # Initialise S and L
   if (dat$wake_status[1]) {
     s_at_wake = pvec["S0"]
@@ -242,5 +250,5 @@ unified_simulate <- function(pvec, dat) {
   }
 
   return(dat)
-  
+
 }