Technical notes about the PACE-HRH package

Global configuration

The term global configuration refers to system-wide variables set up when the PACE-HRH package is started. The most important of these is the location of the input data spreadsheet - the Excel spreadsheet that defines experiment scenarios, baseline population data, clinical task descriptions, health-worker cadres, etc.

The file globalconfig.json contains declarations for global configuration variables. The package reads globalconfig.json from the R working directory (getwd()) when the package is initialized using any of the Initialize___ functions.

The package sets the variable GPE$globalConfigLoaded to TRUE once globalconfig.json has been read.

> pacehrh:::GPE$globalConfigLoaded
[1] TRUE

The default global configuration file

If the package can’t find a globalconfig.json it will use the following default values.

{
  "configDirectoryLocation" : "./config",
  "inputExcelFile" : "model_inputs.xlsx",
  "suiteRngSeed" : 12345,
  "startYear" : 2020,
  "endYear" : 2040
}

If you want to override these defaults by writing your own globalconfig.json file, we’ve provided a sample in the util directory of the GitHub repository.

Global configuration variables

  • configDirectoryLocation: The location of the directory where configuration data is to be found. The default is a config sub-directory of the working directory.
  • inputExcelFile: The name of the input data spreadsheet file. The default value is “model_inputs.xlsx”. The default setup directs the package to look for the input data spreadsheet file at “config/model_inputs.xlsx”.
  • suiteRngSeed: The PACE-HRH package makes extensive use of random number generation. Before each suite of stochastic trials, the system calls the R function set.seed() with a random number seed value. The system uses a seed value provided by the user in the seed = parameter of the RunExperiments() function, or this global configuration value.
  • startYear: Starting year for simulations. Default = 2020.
  • endYear: Ending year for simulations. Default = 2040. Note: Users can also use the SetGlobalStartEndYears() function to set start and end years.

Terminology

  • Trial: A single prediction of healthcare task impacts. PACE-HRH performs several stochasically varied trials to measure potential variation in the predictions.
  • Experiment: synonym for trial.
  • Suite: A set of stochastic trials based on a scenario.
  • Scenario: A set of configuration parameters for a suite. Scenarios are defined by entries in the Scenario sheet of the input data spreadsheet.

Environments

The PACE-HRH package uses three R environments.

pacehrh:::globalPackageEnvironment (alias pacehrh:::GPE) stores configuration information for the entire package.

pacehrh:::baseValuesEnvironment (alias pacehrh:::BVE) stores the base values for stochastic trials.

pacehrh:::experimentValuesEnvironment (alias pacehrh:::EXP) stores the actual values, after applying stochastic variation, used in each trial.

At the start of a suite of trials (RunExperiments()), baseline information is loaded into the BVE environment. For each trial in the suite, stochastic variations are applied to values in the BVE, and the new values are saved in the EXP environment. The trial is then run based on the values in the EXP environment.

You can view the current contents of any of the environments with R’s ls.str() command.

For more information on the RStudio working directory, see RStudio support.