R/RcppExports.R

In SmokingHistoryGenerator: R Package for the Smoking History Generator

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' SHGInterface Class
#' @name SHGInterface
#' @title SHGInterface
#' @aliases SHGInterface
#' @export
#' @description The SHG Interface class provides an Rcpp interface to the Smoking History Generator (SHG)
#' @field number_of_segments Number of segments to use for simulation. Use -1 for auto-calculation (default), 1 for single segment, or N > 1 for explicit segment count. Auto-calculation uses: min(cores * 10, repeat / 1000). Note: MersenneTwister RNG is restricted to 1 segment.
#' @field num_threads Thread count: -1 = auto (all cores, multi-threaded), 1 = single-threaded, N = use N threads. Default: -1. Note: MersenneTwister RNG requires num_threads = 1.
#' @field rng_strategy 'RngStream' for MRG32k3a (default) or 'MersenneTwister' for Mersenne Twister RNG. 'RngStream' is recommended for reproducibility especially with multi-threaded simulations. Note: MersenneTwister RNG is restricted to single-segment, non-parallel execution due to limitations in maintaining IID properties across segments.
#' @field input_data_folder Set or get the base folder for input data files
#' @field initiation_filename Set or get the initiation filename
#' @field cessation_filename Set or get the cessation filename
#' @field mortality_filename Set or get the mortality probabilities filename (e.g. acm.csv or ocm-excl-lung-cancer.csv)
#' @field smok_params_source URL or local path of the last load_params() smoking zip (empty if unset)
#' @field mort_params_source URL or local path of the last load_params() mortality zip (empty if unset)
#' @field mort_params_type Mortality table from last load_params(): acm or ocm (empty if unset)
#' @field params_cache_dir Read-only. Directory where load_params() stores extracted bundles (same as shg_params_cache_dir()). Delete this folder to clear the cache manually.
#' @field cpd_filename Set or get the cpd filename
#' @field immediate_cessation_year Set or get Immediate Cessation Year; If 0, no immediate cessation
#' @field mt_seeds Set or get MersenneTwister seeds. Must be a numeric vector of exactly 4 values (one for each stream: initiation, cessation, life table, individual). If not set, default seeds are used. Only used when rng_strategy is "MersenneTwister".
#' @field rngstream_seed Set or get RngStream seed. Must be a numeric vector of exactly 6 values (a single seed vector that generates 4 substreams, one for each stream: initiation, cessation, life table, individual). If not set, default seed is used. Only used when rng_strategy is "RngStream".
NULL

#' @name get_data_shape
#' @title get_data_shape method
#' @description Returns a list containing information about the shape/dimensions of the current input data files.
#'              It reads the configured parameter files directly and does not require running a simulation first.
#' @return A list with data shape information including races, sexes, cohorts, age ranges, cohort boundaries, and CPD statistics.
NULL

#' @name runSimFromDataFrame
#' @title runSimFromDataFrame method
#' @description runSimFromDataFrame offers a way to configure and run a simulation from an existing R dataframe. It returns a dataframe of simulated smoking histories with the same number of rows and order as the input dataframe.
#' @details On Windows, \code{output_file} (direct disk output) cannot be combined with
#'          multi-threaded execution (\code{num_threads} not equal to \code{1}). The call stops with an error
#'          before loading inputs or writing files. Use the default in-memory DataFrame return value, or set
#'          \code{num_threads <- 1} to write a file.
#' @param dfPopulation The input dataframe with named columns for race, sex, and birth_cohort
NULL

#' @name runSimFromFixedValues
#' @title runSimFromFixedValues method
#' @description runSimFromFixedValues offers a way to configure and run a simulation from fixed values for race, sex, and birth year cohort rather than passing a data frame. It returns a dataframe of simulated smoking histories for n individuals.
#' @param repeat The number of individuals to simulate
#' @param race (default = 0 and refers to all races combined)
#' @param sex (0 for male, 1, for female)
#' @param cohort_year (four digit birth cohort year)
NULL

#' @name LegacyRunWebVersion
#' @title LegacyRunWebVersion method
#' @description This method offers a way to configure and run a simulation from an input configuration file. Rather than return a R DataFrame, it produces results in an output file. It works in the same as calling the CLI version of the Smoking History Generator with a single input file parameter.
#' @param input_file_name Path to a Legacy web-style configuration file. Paths inside the file are resolved relative to the R process working directory (the \code{input_data_folder} property is ignored). Sample text configs live under \code{tests/testdata/legacy-web-examples/} in the package source; for installed use, build a config with absolute paths from \code{system.file("extdata", "2018", package = "SmokingHistoryGenerator")}.
#' @examples
#' shg <- new(SHGInterface)
#' d <- system.file("extdata", "2018", package = "SmokingHistoryGenerator")
#' tf <- tempfile(fileext = ".txt")
#' writeLines(c(
#'   "RNGSTRATEGY=RngStream",
#'   "RNGSTREAM_SEED=12345,12345,12345,12345,12345,12345",
#'   "RACE=0", "SEX=0", "YOB=1950", "CESSATION_YR=0", "REPEAT=100",
#'   paste0("INIT_PROB=", file.path(d, "smoking", "initiation.csv")),
#'   paste0("CESS_PROB=", file.path(d, "smoking", "cessation.csv")),
#'   paste0("MORTALITY_PROB=", file.path(d, "mortality", "acm.csv")),
#'   paste0("CPD_DATA=", file.path(d, "smoking", "cpd.csv")),
#'   paste0("OUTPUTFILE=", tempfile("out_", fileext = ".txt")),
#'   paste0("ERRORFILE=", tempfile("err_", fileext = ".txt"))
#' ), tf)
#' shg$LegacyRunWebVersion(tf)
NULL

#' Get current SHG configuration
#' @name getConfig
#' @title Get SHG Configuration
#' @description Returns the current configuration of the SHG instance as an R list. Can include debug information when debug=TRUE.
#' @param debug Logical. If TRUE, includes additional debug information such as RNG state fingerprint, package version, system info, and memory usage. If not provided, defaults to FALSE.
#' @return A list containing the current intent configuration including: config_version, rng_strategy, number_of_segments, num_threads, seeds, input file paths (including mortality_filename), smok_params_source, mort_params_source, and mort_params_type (from load_params, else NA), immediate_cessation_year, inferred cohort_year (single-cohort runs; otherwise NA), repeat/race/sex after runSimFromFixedValues (otherwise NA), and timestamp. This method returns currently applied values (including unresolved auto values such as -1 for segments/threads). Use \code{getReproConfig()} to export effective runtime values from the last completed simulation. seeds always returns concrete values (explicit user seeds or defaults). If debug=TRUE, also includes rng_state_fingerprint, package_version, package_source, r_version, platform, and memory_usage.
NULL

#' Get reproducibility-focused SHG configuration from last run
#' @name getReproConfig
#' @title Get Reproducibility Configuration
#' @description Returns a configuration list that captures effective runtime settings from the last completed simulation.
#' @param debug Logical. If TRUE, includes additional debug information such as RNG state fingerprint, package version, system info, and memory usage. If not provided, defaults to FALSE.
#' @return A list like \code{getConfig()} for the last completed simulation, but with
#' \code{number_of_segments} as the effective segment count used and \strong{without}
#' \code{num_threads} (thread count must not affect simulation outcomes for fixed seeds
#' and segment layout; consumers default to auto threads when reloading). Errors if no
#' simulation has completed on the instance.
#' @examples
#' shg <- new(SHGInterface)
#' shg$input_data_folder <- system.file("extdata", "2018", package = "SmokingHistoryGenerator")
#' shg$runSimFromFixedValues(500, 0, 0, 1950)
#' repro <- shg$getReproConfig()
NULL

#' Configure SHG instance from config object
#' @name useConfig
#' @title Use SHG Configuration
#' @description Configures an existing SHG instance from a configuration object (typically obtained from getConfig()).
#' @param config A list containing configuration parameters. Must include config_version. All parameters are validated.
#' @details This method validates the config_version and all parameters before setting them. Unknown fields are warned about but allowed for future compatibility. Missing optional fields use defaults. Fields are applied in an order suitable for round-trips from getConfig(): number_of_segments and num_threads are set before rng_strategy (so switching to Mersenne Twister does not message when the saved list already has single-threaded settings), then seeds, then paths and other options. If the list has deprecated \code{run_multi_threaded} but no \code{num_threads}, it is mapped: FALSE -> \code{num_threads = 1}, TRUE -> \code{num_threads = -1}. If both are present, \code{num_threads} wins. If the list updates local input paths (\code{input_data_folder} or any per-table filename) but omits \code{smok_params_source}, \code{mort_params_source}, and \code{mort_params_type}, any previously recorded bundle provenance is cleared for the omitted key(s) so metadata cannot refer to an older zip after retargeting inputs.
NULL

#' Rcpp SHG Interface Class
#' @name Rcpp_SHGInterface
#' @title Rcpp SHG Interface Class
#' @export
#' @description This module provides an Rcpp interface to the Smoking History Generator (SHG) application, including intent-oriented config methods (\code{getConfig}/\code{useConfig}) and reproducibility export (\code{getReproConfig}).
NULL