R/shg-rcpp-docs.R

In SmokingHistoryGenerator: R Package for the Smoking History Generator

# Roxygen blocks for Rcpp-exported methods (not regenerated by compileAttributes).

#' @name SHGInterface
#' @return An \code{SHGInterface} reference object (R6-style external pointer) wrapping the C++
#'   simulation engine. Configure fields, then call simulation methods such as
#'   \code{\link{runSimFromFixedValues}} or \code{\link{runSimFromDataFrame}}; use
#'   \code{\link{getConfig}} / \code{\link{useConfig}} for settings and
#'   \code{\link{shg_load_params}} (via \code{load_params()}) for parameter bundles.
NULL

#' @name Rcpp_SHGInterface
#' @return The exported reference class \code{SHGInterface} (see \code{\link{SHGInterface}}):
#'   an external pointer to the C++ engine used for all simulations.
NULL

#' @name get_data_shape
#' @return A named list describing loaded parameter tables: counts of races, sexes,
#'   and cohorts; age ranges for initiation, cessation, mortality, and CPD; mortality
#'   calendar years; CPD intensity groups; and CPD row load/skip counts. Intended for
#'   validation before running simulations.
NULL

#' @name runSimFromDataFrame
#' @return If \code{attach_run_info = FALSE}, a \code{data.frame} with one row per input
#'   individual (same order) and columns \code{smoking_initiation_age} (\code{-999} =
#'   never smoker), \code{smoking_cessation_age}, \code{age_at_death}, and
#'   \code{cigarettes_per_day}. Constant \code{race}, \code{sex}, or \code{birth_cohort}
#'   are omitted when uniform. If \code{attach_run_info = TRUE}, the same four-component
#'   bundle as \code{\link{shg_run}} (\code{results}, \code{original_config},
#'   \code{repro_config}, \code{run_info}); see that help page for definitions.
#' @examples
#' shg <- new(SHGInterface)
#' shg$input_data_folder <- system.file("extdata", "2018", package = "SmokingHistoryGenerator")
#' pop <- data.frame(race = 0, sex = 0, birth_cohort = 1950)
#' hist <- shg$runSimFromDataFrame(pop)
#' head(hist)
NULL

#' @name runSimFromFixedValues
#' @return If \code{attach_run_info = FALSE}, a \code{data.frame} of \code{repeat}
#'   simulated individuals with columns \code{smoking_initiation_age} (\code{-999} =
#'   never smoker), \code{smoking_cessation_age}, \code{age_at_death}, and
#'   \code{cigarettes_per_day}. If \code{attach_run_info = TRUE}, the same four-component
#'   bundle as \code{\link{shg_run}}; see that help page for definitions.
#' @examples
#' shg <- new(SHGInterface)
#' shg$input_data_folder <- system.file("extdata", "2018", package = "SmokingHistoryGenerator")
#' hist <- shg$runSimFromFixedValues(500, 0, 0, 1950)
#' head(hist)
NULL

#' @name LegacyRunWebVersion
#' @return No return value. Called for side effects: runs the CLI-style engine and writes
#'   semicolon-separated results to \code{OUTPUTFILE} and diagnostics to \code{ERRORFILE}
#'   as specified in the configuration file (properties on the R object are ignored).
NULL

#' @name getConfig
#' @examples
#' shg <- new(SHGInterface)
#' shg$input_data_folder <- system.file("extdata", "2018", package = "SmokingHistoryGenerator")
#' shg$rng_strategy <- "RngStream"
#' shg$number_of_segments <- 4
#' config <- shg$getConfig()
#' names(config)
NULL

#' @name getReproConfig
#' @examples
#' shg <- new(SHGInterface)
#' shg$input_data_folder <- system.file("extdata", "2018", package = "SmokingHistoryGenerator")
#' shg$runSimFromFixedValues(500, 0, 0, 1950)
#' repro <- shg$getReproConfig()
#' names(repro)
NULL

#' @name useConfig
#' @return No return value. Called for side effects: updates fields on the \code{SHGInterface}
#'   instance to match \code{config} (typically from \code{\link{getConfig}}).
#' @examples
#' shg1 <- new(SHGInterface)
#' shg1$input_data_folder <- system.file("extdata", "2018", package = "SmokingHistoryGenerator")
#' shg1$rng_strategy <- "RngStream"
#' shg1$number_of_segments <- 4
#' config <- shg1$getConfig()
#' shg2 <- new(SHGInterface)
#' shg2$useConfig(config)
#' shg2$rng_strategy
NULL