Chapter 3 Usage

The complete statistical modeling, including data checks, data imputation, covariate screening, model selection, predictions and model summaries are all wrapped into the ModelPoisson() function. Only a control script and dataset are required. All of the output from the modeling is saved into summary folders and endpoint specific folders.

3.1 Statistical Analysis: ModelPoisson()

rm(list = ls(all = TRUE))
folder.dir <- getwd() 
ModelPoisson(pathRunType = folder.dir,
             user.input = "user-input.r",
             clean = TRUE,
             save.name = "myEnvironment.RData)

  • pathRunType: The directory where the control scripts and data sets are. All the modeling results will be saved to this directory as well. Must be an absolute path. Default value is getwd().

  • user.input: The file path of the control script (user-input.r) to source. Default value is NULL. If user.input is NULL, user needs to run/source the control file first then run ModelPoisson() as

rm(list = ls(all = TRUE))
folder.dir <- getwd()
source("user-input.r")
ModelPoisson(pathRunType = folder.dir,
             user.input = NULL,
             clean = TRUE,
             save.name = "myEnvironment.RData")
  • clean: If TRUE, clean the folders under the directory pathRunType before running a new analysis. Default value of clean is TRUE.
  • save.name: The modeling results and user’s modeling options are saved as .RData with the provided name under the directory pathRunType. Default value is “myEnvironment.RData.”

If the analysis was conducted successfully, several folders will have been created.

  • “Demog-Sum” folder contains summary tables of events, exposures, and covariates.
  • “Cov-EDA” folder contains figures of covariates correlation, exposure summary, and event summary vs time.
  • A folder is created for each Endpoint has a folder with the user-specified endpoint name.

There will be subfolders within each of the endpoint folders containing:

  • a sub-dataset RData file which was used in modeling this endpoint;
  • “Models” folder containing the saved modeling R objects, the model summary tables, and backwards deletion log.
  • “OR” folder containing the saved Odds-Ratio tables and figures if the final model contains any proper covariates.

3.2 New Predictions PredictionPoisson()

The modeling results from ModelPoisson() can be used for predicting the incidence rate of new specific groups such as treatment groups, patient populations, Age groups etc to reflect the different incidence rates due to the different exposure levels. PoissonERM provides easy way to use base model (ignoring covariates) in predicting incidence rate for new simulated exposures and to compare it with the observed incidence rates grouped by exposure level.

If there is no significant exposure response relationship, the prediction output will only includes the summary of the observed incidence rates and the provided new simulated exposures i.e. no predicted incidence rate results.

folder.dir <- getwd()
PredictionPoisson(pathRunType = folder.dir,
                  prediction.input = "prediction-user-input-sim.R",
                  model.RData = "myEnvironment.RData",
                  save.name = "myEnvironment_new.RData")

PredictionPoisson() creates one folder “Prediction” under each endpoint folder which contains new exposure summary and incidence rate summary. The figures are saved in multiple sizes and can be used as needed.

  • pathRunType: The directory where the control scripts and data sets are. All the results will be saved to this directory as well. Must be an absolute path. Default value is getwd().

  • prediction.input: The file path of the control script (prediction-user-input-sim.r) to source. Default value is NULL. If prediction.input is NULL, user needs to run/source the control file first then run PredictionPoisson() as

folder.dir <- getwd()
source("prediction-user-input-sim.R")
PredictionPoisson(pathRunType = folder.dir,
             prediction.input = NULL,
             model.RData = "myEnvironment.RData",
             save.name = "myEnvironment_new.RData")

  • model.RData: The saved modeling result object from ModelPoisson(), must be located under directory pathRunType. Default value is “myEnvironment.RData,” which is the default save.name value in function ModelPoisson().

  • save.name: The modeling results and the prediction results are saved as .RData with the provided name under the directory pathRunType. Default value is model.RData, which will rewrite the previously saved modeling result.

3.3 Report Generation: ReportPoisson()

The modeling results from ModelPoisson() or PredictionPoisson()can be used to generate an automated .Rmd report.

Notice that the report cannot be generated using the modeling results from ModelPoisson() if there is a “Prediction” folder in each endpoint result folder. If the user wants to generate report without prediction results after running PredictionPoisson(), user may remove those “Prediction” folders manually or simply clean the R Environment and rerun ModelPoisson() with clean = TRUE.

folder.dir <- getwd()
ReportPoisson(pathRunType = folder.dir,
              model.RData = "myEnvironment.RData",
              file.name = "Report.Rmd")
  • pathRunType: The directory where the previously saved modeling results (folders and the saved .RData file) located. The generated .Rmd report will be saved to this directory. Must be an absolute path. Default value is getwd().
  • model.RData: The saved modeling result object from ModelPoisson() or from PredictionPoisson(), must be located under directory pathRunType. Default value is “myEnvironment.RData,” which is the default save.name value in function ModelPoisson().
  • file.name: The file name for the generated report. The default value is “NULL.” If file.name is NULL or if file.name is not ended with “.Rmd,” the default file name will be “Poisson-Regression-Date&Time.Rmd.”

The saved .Rmd file can compile .html report via Knit without any further modification. It could be used as an initial draft of a comprehensive report.