calibR_R6: R6 Class representing a calibR_R6 calibration machine.

calibR_R6R Documentation

R6 Class representing a calibR_R6 calibration machine.

Description

An instance of this class is expected to calibrate a user-defined model and produce summary plots/tables.

Format

An R6::R6Class object.

Public fields

calibration_model

a Decision-Analytic model under calibration

calibration_model_args

arguments passed to the calibration model

calibration_parameters

calibration parameters' data

calibration_targets

calibration targets' data

calibration_results

calibration interim results

model_interventions

model interventions to run cost-effectiveness analysis

transform_parameters

logical for whether to back transform parameters

GOF_measure_plot

log likelihood values for plot

model_predictions

simulated outputs

prior_samples

samples from parameters' priors

maximum_a_posteriori

parameter set with maximum posterior probability

PSA_samples

calibration and un-calibration parameters samples

PSA_results

PSA results

PSA_summary

PSA results' summary

PSA_summary_tables

PSA results' summary tables

simulated_targets

PSA results

plots

summary plots

Methods

Public methods


Method new()

Sample prior distribution(s) using one or more sampling method. This function currently supports: LHS, FGS and RGS.

Usage
calibR_R6$new(.model, .args, .params, .targets, .transform, .intervs = NULL)
Arguments
.model

The decision analytic model under calibration

.args

Calibration model arguments

.params

Calibration parameters

.targets

Calibration targets

.transform

Logical for whether the model will use transformed parameters. This allows some functions to back transform the parameters to their original scale before using them.

.intervs

A list containing the information about the considered interventions built into the model.

Returns

Object of class CalibrateR_R6

Examples
\dontrun{
}

Method sampleR()

Sample prior distribution(s) using one or more sampling method. This function currently supports: LHS, FGS and RGS.

Usage
calibR_R6$sampleR(.n_samples = 1, .sampling_method, .ssed_no = NULL)
Arguments
.n_samples

An integer specifying the number of samples to be generated.

.sampling_method

The sampling method(s) to use. The function currently supports LHS, RGS, and FGS.

.ssed_no

random seed number

Returns

Executes the required sampling method and populates the "prior samples" internal object.

Examples
\dontrun{
}

Method calibrateR_random()

Calibrate the model using one or more random search method(s).

Usage
calibR_R6$calibrateR_random(
  .optim = FALSE,
  .maximise = TRUE,
  .weighted = NULL,
  .sample_method = "LHS",
  .calibration_method = "LLK",
  .calibration_function = NULL
)
Arguments
.optim

Logical for whether the function is used by an optimisation algorithm. Default is FALSE.

.maximise

Logical for whether the output of the function is used in a maximising optimisation function. Default is TRUE.

.weighted

Logical for whether the SSE was to be weighted, default is TRUE. The weight used by function is 1/(sd^2).

.sample_method

The method used to sample from the prior distribution.

.calibration_method

goodness-of-fit method name.

.calibration_function

goodness-of-fit function.

Returns

Executes the required calibration method and populates the samples internal object.

Examples
\dontrun{
}

Method calibrateR_directed()

Calibrate the model using one or more directed search method(s).

Usage
calibR_R6$calibrateR_directed(
  .gof = "LLK",
  .gof_func = NULL,
  .n_samples = 1,
  .max_iterations = 1000,
  temp = 10,
  trace = NULL,
  .calibration_method = "NM",
  .sample_method = "LHS",
  .maximise = TRUE
)
Arguments
.gof

Name of goodness-of-fit function, default is log-likelihood.

.gof_func

Goodness-of-fit function; if NULL (default) the supported function defined by .gof will be used

.n_samples

Number of Starting sets (gausses) to use.

.max_iterations

Maximum number of algorithm iterations.

temp

SANN algorithm tuning parameter.

trace

Non-negative integer. If positive, tracing information on the progress of the optimization is produced. Higher values may produce more tracing information.

.calibration_method

The calibration process.

.sample_method

The method used to sample from the prior distribution.

.maximise

Logical for whether the function is to maximise.

Returns

Executes the required calibration method and populates the samples internal object.

Examples
\dontrun{
}

Method calibrateR_bayesian()

Calibrate the model using one or more calibration method.

Usage
calibR_R6$calibrateR_bayesian(
  .b_methods = "SIR",
  .n_resample = 1000,
  .IMIS_iterations = 10,
  .IMIS_sample = 100,
  .MCMC_burnIn = 10000,
  .MCMC_samples = 50000,
  .MCMC_thin = 5,
  .MCMC_rerun = TRUE,
  .diag_ = FALSE
)
Arguments
.b_methods

Bayesian calibration method(s)

.n_resample

Desired number of draws from the posterior

.IMIS_iterations

Maximum number of IMIS iterations

.IMIS_sample

Positive integer for the IMIS sample size at each iteration.

.MCMC_burnIn

Positive integer for the MCMC burn-in sample.

.MCMC_samples

Positive integer for the total MCMC sample, including burn-in.

.MCMC_thin

Positive integer for the value by which MCMC results are to reduced. .MCMC_thin defines the number of samples from which the first will be retained while the rest are discarded.

.MCMC_rerun

Logical for whether to re-run MCMC using the proposal distribution covariance matrix from the first run.

.diag_

Logical for whether to print diagnostics.

Returns

Executes the required calibration method and populates the samples internal object.

Examples
\dontrun{
}

Method sample_PSA_values()

Sample PSA values for the calibration parameters

Usage
calibR_R6$sample_PSA_values(.calibration_methods, .PSA_samples)
Arguments
.calibration_methods

Bayesian calibration method(s)

.PSA_samples

Number of PSA sets to sample

Examples
\dontrun{
}

Method run_PSA()

Run PSA

Usage
calibR_R6$run_PSA(.PSA_unCalib_values_ = NULL)
Arguments
.PSA_unCalib_values_

PSA values for un-calibrated parameters

Examples
\dontrun{
}

Method summarise_PSA()

Summarise PSA results

Usage
calibR_R6$summarise_PSA()
Examples
\dontrun{
}

Method draw_plots()

Draw plots

Usage
calibR_R6$draw_plots(
  prior_sample_method = "LHS",
  print_pair_correlations = FALSE
)
Arguments
prior_sample_method

Sampling method used to generate prior samples.

print_pair_correlations

Print pair-wise correlations to console.

Examples
\dontrun{
}

Method draw_GOF_measure()

Plot Goodness of fit function(s)

Usage
calibR_R6$draw_GOF_measure(
  .engine_ = "plotly",
  .blank_contour_ = TRUE,
  .gof_ = "LLK",
  .percent_sampled_ = 10,
  .n_samples_ = 10000,
  .true_points_ = FALSE,
  .greys_ = FALSE,
  .scale_ = NULL,
  .coloring_ = "fill",
  .legend_ = FALSE,
  .zoom_ = FALSE,
  .x_axis_lb_ = NULL,
  .x_axis_ub_ = NULL,
  .y_axis_lb_ = NULL,
  .y_axis_ub_ = NULL,
  .save_ = FALSE,
  .saving_path_ = here::here(),
  .saving_image_dir_ = "/images/GOFs/",
  .saving_x_params_ = 1,
  .saving_image_scale_ = 2,
  .saving_image_width_ = 1000,
  .saving_image_height_ = 600
)
Arguments
.engine_

String naming the plotting engine, currently "plotly".

.blank_contour_

Logical for whether to only plot blank or empty GOF contour plots.

.gof_

Goodness of fit (GOF) measure - fitness function. Either "LLK" or "SEE" for the log-likelihood and sum-of-squared-errors GOF, respectively.

.percent_sampled_

.percent_sampled_ The fraction of LHS, RGS, or FGS samples to select.

.n_samples_

Number of Grid samples to plot log likelihood

.true_points_

Logical for whether to add "True set" to plots.

.greys_

Logical for whether to use a Grey scale in the plot.

.scale_

The colour bar colour-scale. Available options are Greys, YlGnBu, Greens, YlOrRd, Bluered, RdBu, Reds, Blues, Picnic, Rainbow, Portland, Jet, Hot, Blackbody, Earth, Electric, Viridis, Cividis.

.coloring_

Which contouring is required (default fill) and options are "fill" | "heatmap" | "lines" | "none"

.legend_

Logical for whether to show a legend (default is FALSE). This parameter also controls text labels in the opposite way.

.zoom_

Logical (default FALSE) for whether to limit the resulting plot to the min() and max() of the two dimensional contour plots.

.x_axis_lb_

Lower bound of the plot's x axis.

.x_axis_ub_

Upper bound of the plot's x axis.

.y_axis_lb_

Lower bound of the plot's y axis.

.y_axis_ub_

Upper bound of the plot's y axis.

.save_

Logical for whether to save plots.

.saving_path_

String defining the path for where to save the plots.

.saving_image_dir_

String defining the sub-folder in the path where to save the plots.

.saving_x_params_

Integer or vector of integers for the rank(s) of

.saving_image_scale_

Positive integer dictating the scale at which the image is saved. Default value is 5 for images with width of 1/3 an A4 paper.

.saving_image_width_

Positive integer setting the width of the saved version of the plot. The default (1,000 px) is appropriate for an image 1/3 of the width of A4 sheet.

.saving_image_height_

Positive integer setting the height of the saved version of the plot. The default (600 px) is appropriate for an image 1/3 of the width of A4 sheet. #'

Examples
\dontrun{
}

Method draw_targets_plots()

Plot Targets (with or without simulated targets)

Usage
calibR_R6$draw_targets_plots(
  .engine_ = "ggplot2",
  .sim_targets_ = FALSE,
  .calibration_methods_ = "all",
  .legend_pos_ = "none",
  .PSA_samples_ = NULL,
  .PSA_unCalib_values_ = NULL,
  .save_ = FALSE,
  .saving_path_ = here::here(),
  .saving_image_dir_ = "/images/Targets/",
  .saving_image_scale_ = 2,
  .saving_image_width_ = 1000,
  .saving_image_height_ = 600,
  .saving_image_units_ = "px"
)
Arguments
.engine_

String naming the plotting engine, currently "ggplot2".

.sim_targets_

Logical (default FALSE) for whether generate then plot simulated targets. The generation of simulated targets requires the package to run the model using the sampled or identified PSA values.

.calibration_methods_

String vector naming the calibration methods for which simulated targets are to be generated. Options is either "all" (the default) or any of c("random", "directed", "bayesian").

.legend_pos_

String declaring the preferred position for the legend. Default is "bottom".

.PSA_samples_

Integer defining the maximum number of PSA values to use in plotting/generating the simulated targets.

.PSA_unCalib_values_

Tibble/table/dataframe containing the PSA draws for the parameters that are not calibrated in the object

.save_

Logical for whether to save plots.

.saving_path_

String defining the path for where to save the plots.

.saving_image_dir_

String defining the sub-folder in the path where to save the plots.

.saving_image_scale_

Positive integer dictating the scale at which the image is saved. Default value is 5 for images with width of 1/3 an A4 paper.

.saving_image_width_

Positive integer setting the width of the saved version of the plot. The default (1,000 px) is appropriate for an image 1/3 of the width of A4 sheet.

.saving_image_height_

Positive integer setting the height of the saved version of the plot. The default (600 px) is appropriate for an image 1/3 of the width of A4 sheet.

.saving_image_units_

A string (default "px") defining the units in which the width and height are provided.

Examples
\dontrun{
}

Method draw_distributions_plots()

Plot prior and posterior distributions

Usage
calibR_R6$draw_distributions_plots(
  .engine_ = "ggplot2",
  .bins_ = 20,
  .legend_pos_ = "none",
  .log_scaled_ = FALSE,
  .save_ = FALSE,
  .saving_path_ = here::here(),
  .saving_image_dir_ = "/images/Prior-posterior/",
  .saving_image_scale_ = 2,
  .saving_image_width_ = 1000,
  .saving_image_height_ = 600,
  .saving_image_units_ = "px"
)
Arguments
.engine_

String naming plotting package currently only supports "ggplot2".

.bins_

Numeric specifying the number of bins in the histograms.

.legend_pos_

String (default bottom) setting legend position.

.log_scaled_

Logical for whether to use log scale in the x axis.

.save_

Logical for whether to save plots.

.saving_path_

String defining the path for where to save the plots.

.saving_image_dir_

String defining the sub-folder in the path where to save the plots.

.saving_image_scale_

Positive integer dictating the scale at which the image is saved. Default value is 5 for images with width of 1/3 an A4 paper.

.saving_image_width_

Positive integer setting the width of the saved version of the plot. The default (1,000 px) is appropriate for an image 1/3 of the width of A4 sheet.

.saving_image_height_

Positive integer setting the height of the saved version of the plot. The default (600 px) is appropriate for an image 1/3 of the width of A4 sheet.

.saving_image_units_

A string (default "px") defining the units in which the width and height are provided.

Examples
\dontrun{
}

Method draw_PSA_summary_tables()

Draw PSA summary tables:—-

Usage
calibR_R6$draw_PSA_summary_tables(
  .save_ = FALSE,
  .saving_path_ = here::here(),
  .saving_data_dir_ = "/data/PSA tables/"
)
Arguments
.save_

Logical for whether to save tables data.

.saving_path_

String defining the path for where to save the tables data.

.saving_data_dir_

String defining the sub-folder in the path where to save the tables data.

Examples
\dontrun{
}

Method clone()

The objects of this class are cloneable with this method.

Usage
calibR_R6$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Examples

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$new`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$sampleR`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$calibrateR_random`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$calibrateR_directed`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$calibrateR_bayesian`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$sample_PSA_values`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$run_PSA`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$summarise_PSA`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$draw_plots`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$draw_GOF_measure`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$draw_targets_plots`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$draw_distributions_plots`
## ------------------------------------------------

## Not run: 


## ------------------------------------------------
## Method `calibR_R6$draw_PSA_summary_tables`
## ------------------------------------------------

## Not run: 


W-Mohammed/calibrater documentation built on Oct. 14, 2023, 1:57 a.m.