Markov Models for Health Economic Evaluations

Description

An implementation of the modelling and reporting features described in reference textbooks and guidelines: deterministic and probabilistic sensitivity analysis, heterogeneity analysis, time dependency on state-time and model-time (semi-Markov and non-homogeneous Markov models), etc.

Author(s)

Maintainer: Kevin Zarca kevin.zarca@gmail.com

Authors:

• Antoine Filipovic-Pierucci

Other contributors:

• Matthew Wiener [contributor]

• Zdenek Kabat [contributor]

• Vojtech Filipec [contributor]

• Jordan Amdahl [contributor]

• Yonatan Carranza Alarcon [contributor]

• Vince Daniels [contributor]

See Also

Useful links:

• https://aphp.github.io/heemod/

• Report bugs at https://github.com/aphp/heemod/issues

Acceptability Curve from Probabilistic Analysis

Description

Acceptability Curve from Probabilistic Analysis

Usage

acceptability_curve(x, wtp_thresholds)

Arguments

Value

A data frame with columns .ceac (the cost-effectiveness acceptability threshold), .model (treatments or models), .n (the number of cases in which the treatment was most cost-effective), and .p (the proportion of cases where the treatment was most effective).

Add Hazards

Description

Get a survival distribution reflecting the independent hazards from two or more survival distributions.

Usage

add_hazards(...)

add_hazards_(dots)

Arguments

Value

A surv_add_haz object.

Examples

dist1 <- define_surv_dist(distribution = "exp", rate = .125)
dist2 <- define_surv_dist(distribution = "weibull", shape = 1.2, scale = 50)
combined_dist <- add_hazards(dist1, dist2)

Apply an Acceleration Factor

Description

Proportionally increase or reduce the time to event of a survival distribution.

Usage

apply_af(dist, af, log_af = FALSE)

Arguments

Value

A surv_aft object.

Examples

dist1 <- define_surv_dist(distribution = "exp", rate = .25)
aft_dist <- apply_af(dist1, 1.5)

Apply a Hazard Ratio

Description

Proportional reduce or increase the hazard rate of a distribution.

Usage

apply_hr(dist, hr, log_hr = FALSE)

Arguments

Value

A surv_ph object.

Examples

dist1 <- define_surv_dist(distribution = "exp", rate = .25)
ph_dist <- apply_hr(dist1, 0.5)

Apply an Odds Ratio

Description

Proportionally increase or reduce the odds of an event of a survival distribution.

Usage

apply_or(dist, or, log_or = FALSE)

Arguments

Value

A surv_po object.

Examples

dist1 <- define_surv_dist(distribution = "exp", rate = .25)
po_dist <- apply_or(dist1, 1.2)

Apply a time shift to a survival distribution

Description

Apply a time shift to a survival distribution

Usage

apply_shift(dist, shift)

Arguments

Details

A positive shift moves the fit backwards in time. That is, a shift of 4 will cause time 5 to be evaluated as time 1, and so on. If shift == 0, dist is returned unchanged.

Value

A surv_shift object.

Examples

dist1 <- define_surv_dist(distribution = "gamma", rate = 0.25, shape = 3)
shift_dist <- apply_shift(dist1, 4)
compute_surv(dist1, 1:10)
compute_surv(shift_dist, 1:10)

Convert Lazy Dots to Expression List

Description

This function is used by interpolate().

Usage

as_expr_list(.dots)

Arguments

Value

A list of expression.

Calculate Probability of Event

Description

Calculates the per-cycle event probabilities from a vector of survival probabilities.

Usage

calc_prob_from_surv(x)

Arguments

Value

The per-cycle event probabilities.

Calculate Probability of Survival

Description

Calculates the probability of survival from a vector of event probabilities

Usage

calc_surv_from_prob(x)

Arguments

Value

The survival probabilities.

Calibrate Model Parameters

Description

Search for the appropriate value of unknown parameters to obtain specific model results.

Usage

calibrate_model(
  x,
  parameter_names,
  fn_values,
  target_values,
  initial_values = NULL,
  method = c("Nelder-Mead", "BFGS", "L-BFGS-B"),
  ...
)

Arguments

Details

Parameters not being optimized are unchanged from the values in the model run. If initial_values is NULL, the initial parameter values will also be taken from the model run.

initial_values can be a vector or a table. In the second case each row corresponds to a set of initial parameter values: the calibration will be run once per set.

Passing in multiple initial values allows (among other things) the user to check whether the calibration gets the same results from different starting points.

Multi-dimensional problems are optimized with optimx::optimx(), 1-dimensional problems with stats::optimise() (except when a method is given). convcode is always NA with stats::optimise().

Running calibrate_model() does not change the model parameters; the user must create a new model and run it if desired.

See also vignette("k-calibration").

Value

A data frame in which each row has the calibrated values of parameters given in parameter_names, for the corresponding row of initial_values, along with the convergence code for each run.

Examples

param <- define_parameters(p = 0.8)

mat <- define_transition(
  p, C,
  0, 1
)
mod <- define_strategy(
  transition = mat,
  A = define_state(cost=10, effect = 0.5), 
  B = define_state(cost = 5, effect = 0.8)
)

res_mod <- run_model(
  mod = mod,
  parameters = param,
  init = c(1000L, 0L),
  cycles = 10,
  cost = cost,
  effect = effect,
  method = "end"
)

f <- function(x) {
  dplyr::filter(
    get_counts(x),
    state_names == "A" & model_time == 10
  )$count
}
f(res_mod)

#'\dontrun{
#'calibrate_model(
#'  res_mod,
#'  parameter_names = "p",
#'  fn_values = f,
#'  target_values = 130,
#'  initial_values = data.frame(p = c(0.5, 0.9)),
#'  lower = 0, upper = 1
#')
#'}

Check Cycle and Time Inputs

Description

Performs checks on the cycle and time inputs to eval_surv().

Usage

check_cycle_inputs(cycle, cycle_length)

Arguments

Check Markov Model Transition Matrix

Description

Check whether a matrix fulfills the conditions to be a transition matrix.

Usage

check_matrix(x)

Arguments

Details

This function is called by eval_transition() and should not be used directly.

Checks whether all rows sum to 1 and all probabilities are between 0 and 1.

Value

NULL

Check Names

Description

Throws an error if any of the names are reserved.

Usage

check_names(x)

Arguments

Details

Reserved names are model_time and anything starting with ..

Value

Nothing, just throws an error if a reserved name is encountered.

Check Model States for Consistency

Description

For internal use.

Usage

check_states(x)

Arguments

Details

All states should have the same value names.

Value

NULL

Check Strategy Index

Description

Check Strategy Index

Usage

check_strategy_index(x, i, allow_multiple = FALSE)

Arguments

Value

Strategy names.

Convert Data Frame Factor Variables to Character

Description

Convert Data Frame Factor Variables to Character

Usage

clean_factors(x)

Arguments

Value

A data frame.

Run heemod on a Cluster

Description

These functions create or delete a cluster for heemod. When the cluster is created it is automagically used by heemod functions.

Usage

use_cluster(num_cores, cluster = NULL, close = TRUE)

status_cluster(verbose = TRUE)

close_cluster()

Arguments

Details

The usual workflow is to create the cluster with use_cluster, then run functions such as run_psa() that make use of the cluster. To stop using the cluster run close_cluster().

The cluster status is given by status_cluster.

A custom cluster can be passed to use_cluster with the cluster argument. This custom cluster needs to work with parallel::parLapply().

Value

use_cluster and close_cluster return TRUE invisibly in case of success. status_cluster returns TRUE if a cluster is defined, FALSE otherwise.

Combine Multiple Models

Description

Given a set of models run with different parameters, return aggregated results to estimate population-level values.

Usage

combine_models(newmodels, weights, oldmodel)

Arguments

Value

A combined_models object, mostly similar to a result from run_model(). plot and summary methods are available.

Combine Probabilities

Description

Given several independent probabilities of an event, return the final probability of the event.

Usage

combine_probs(...)

Arguments

Details

This function is only correct if the probabilities are independent!

Value

A probability vector.

Examples

(p1 <- runif(5))
(p2 <- runif(5))
combine_probs(p1, p2)

Compute Count of Individual in Each State per Cycle

Description

Given an initial number of individual and an evaluated transition matrix, returns the number of individual per state per cycle.

Usage

## S3 method for class 'eval_part_surv'
compute_counts(x, init, inflow, ...)

compute_counts(x, ...)

## S3 method for class 'eval_matrix'
compute_counts(x, init, inflow, ...)

Arguments

Details

Use the method argument to specify if transitions are supposed to happen at the beginning or the end of each cycle. Alternatively linear interpolation between cycles can be performed.

Value

A cycle_counts object.

Compute ICER

Description

Compute ICER for Markov models.

Usage

compute_icer(x, strategy_order = order(x$.effect), threshold = 30000)

Arguments

Details

Models are ordered by effectiveness and ICER are computed sequentially.

Value

A data.frame with computed ICER.

Evaluate Survival Distributions

Description

Generate either survival probabilities or conditional probabilities of event for each model cycle.

Usage

compute_surv(x, time, cycle_length = 1, type = c("prob", "survival"), ...)

Arguments

Value

Returns either the survival probabilities or conditional probabilities of event for each cycle.

Compute State Values per Cycle

Description

Given states and counts, computes the total state values per cycle.

Usage

compute_values(states, count_list, strategy_starting_values)

Arguments

Value

A data.frame of state values, one column per state value and one row per cycle.

construct a survival object from tabular specification

Description

construct a survival object from tabular specification

Usage

construct_part_surv_tib(surv_def, ref, state_names, env = new.env())

Arguments

Details

This function is meant to be used only from within tabular_input.R. It won't work well otherwise, in that the environment is unlikely to have what you need.

columns of surv_def: .strategy, .type, .subset, dist, until where dist can be either the name of a distribution along with parameters, or a reference to a fit for example: fit('exp') or exp(rate = 0.5)

Value

a list with one element for each strategy. Each element is in turn a part_surv object, a list with two elements, pfs and os. And those elements are survival objects of various kinds, with the commonality that they can be used in compute_surv().

Read a Demographic Table

Description

This function mostly checks whether the parameters are correct.

Usage

create_demographic_table(newdata, params)

Arguments

Details

An optional .weights column can exist in the file.

Value

A data frame.

Load Data From a Folder Into an Environment

Description

Reads files containing data frames (in tabular format) from a directory, and loads them in an environment to be available during an analysis.

Usage

create_df_from_tabular(df_dir, df_envir)

Arguments

Details

The files must be in .csv, .xls, or .xlsx format. A file my_df.csv (or my_df.xls, or my_df.xlsx) will be loaded as a data frame my_df.

Value

The environment with the data frames.

Create a Transition Matrix From Tabular Input

Description

Transforms tabular input defining a transition matrix into an heemod object.

Usage

create_matrix_from_tabular(trans_probs, state_names, df_env = globalenv())

Arguments

Details

The data frame trans_probs should have columns from, to, and prob, where prob is the probability of a transition from the from state to the to state. Prob can be defined in terms of parameters, just as when using define_transition at the keyboard. Probabilities of 0 need not be specified - they will be automatically inserted.

All state names must be used in the from column of the transition matrix (otherwise you can just get rid of the state). Absorbing states should have a transition from and to themselves with probability 1.

Value

A transition matrix.

Create a heemod Model From Tabular Files Info

Description

Calls create_states_from_tabular() and create_matrix_from_tabular().

Usage

create_model_from_tabular(state_info, tm_info, df_env = globalenv())

Arguments

Value

A heemod model as returned by define_strategy().

Read Models Specified by Files

Description

Read Models Specified by Files

Usage

create_model_list_from_tabular(ref, df_env = globalenv())

Arguments

Value

A list of unevaluated models.

Create Model Options From a Tabular Input

Description

Create Model Options From a Tabular Input

Usage

create_options_from_tabular(opt)

Arguments

Value

A list of model options.

Create a Parameter Definition From Tabular Input

Description

If specified in the tabular file, DSA and PSA can also be created.

Usage

create_parameters_from_tabular(param_defs, df_env = globalenv())

Arguments

Details

The tabular parameter definition file can have the following columns: parameter (the parameter name, required), value (required), low and high (if both are present, a deterministic sensitivity analysis will be performed), and psa (a definition of a distribution to use in a probabilistic sensitivity analysis. Other columns will be ignored.

Value

The parameter definition.

Create State Definitions From Tabular Input

Description

Transforms tabular input defining states into an heemod object.

Usage

create_states_from_tabular(state_info, df_env = globalenv())

Arguments

Details

Columns of state_info besides .model and state include costs and utilities we want to keep track of, with appropriate values (these may include parameters). For any cost or utility that should be discounted, an additional column with the name ".discount.\<cost\>" or ".discount.\<effect\>", for the appropriate cost or effect, can be included. If no discounting is desired for a particular cost or effect, the corresponding column can be omitted.

A discount column can contain only a single value - a cost or benefit must be discounted by the same amount in each state. Discounts can be numbers or parameters (which will then need to be defined like any other).

The input data frame is expected to contain state information for all the models you will use in an analysis. For more information see the vignette: vignette("file-input", package = "heemod").

Value

A state list.

Define Calibration Function

Description

Define a function to be passed to the fn_values argument of calibrate_model().

Usage

define_calibration_fn(
  type,
  strategy_names,
  element_names,
  cycles,
  groups = NULL,
  aggreg_fn = sum
)

Arguments

Value

A numeric vector.

Examples

example("run_model")

f <- define_calibration_fn(
  type = c("count", "count", "value"),
  strategy_names = c("I", "I", "II"),
  element_names = c("A", "B", "ly"),
  cycles = c(3, 5, 9),
  groups = c(1, 1, 2),
  aggreg_fn = mean
)

Define a Correlation Structure for Probabilistic Uncertainty Analysis

Description

Not all correlation need to be specified for all variable combinations, unspecified correlations are assumed to be 0.

Usage

define_correlation(...)

define_correlation_(.dots)

Arguments

Value

An object of class correlation_matrix.

Examples

cm <- define_correlation(
    var1, var2, .4,
    var1, var3, -.2,
    var2, var3, .1
  )

Define a Sensitivity Analysis

Description

Define parameter variations for a Markov model sensitivity analysis.

Usage

define_dsa(...)

define_dsa_(par_names, low_dots, high_dots)

Arguments

Value

A sensitivity object.

Examples

define_dsa(
  a, 10, 45,
  b, .5, 1.5
)

Define Inflow for a BIA

Description

Define Inflow for a BIA

Usage

define_inflow(...)

define_inflow_(.dots)

Arguments

Value

An object similar to the return value of define_parameters().

Define Initial Counts

Description

Define Initial Counts

Usage

define_init(...)

define_init_(.dots)

Arguments

Value

An object similar to the return value of define_parameters().

Define Markov Model Parameters

Description

Define parameters called to compute the transition matrix or state values for a Markov model. Parameters can be time dependent by using the model_time parameter.

Usage

define_parameters(...)

define_parameters_(.dots)

## S3 method for class 'uneval_parameters'
modify(.OBJECT, ...)

Arguments

Details

Parameters are defined sequentially, parameters defined earlier can be called in later expressions.

Vector length should not be explicitly set, but should instead be stated relatively to model_time (whose length depends on the number of simulation cycles). Alternatively, dplyr functions such as dplyr::n() can be used.

This function relies heavily on the dplyr package. Parameter definitions should thus mimic the use of functions such as dplyr::mutate().

Variable names are searched first in the parameter definition (only parameters defined earlier are visible) then in the environment where define_parameters was called.

For the modify function, existing parameters are modified, but no new parameter can be added. Parameter order matters since only parameters defined earlier can be referenced in later expressions.

Value

An object of class uneval_parameters (actually a named list of quosures).

Examples

# parameter 'age' depends on time:
# simulating a cohort starting at 60 yo

define_parameters(
  age_start = 60,
  age = age_start + model_time
)

# other uses of model_time are possible

define_parameters(
  top_time = ifelse(model_time < 10, 1, 0)
)

# more elaborate: risk function

define_parameters(
  rate = 1 - exp(- model_time * .5)
)

# dont explicitly state lengths
# define_parameters(
#   var = seq(1, 15, 2)
# )


# instead rely on model_time or dplyr 
# functions such as n() or row_number()

define_parameters(
  var = seq(from = 1, length.out = n(), by = 3),
  var2 = seq(1, length(model_time), 2)
)

param <- define_parameters(
  age_start = 60,
  age = age_start + model_time
)

# modify existing parameters

modify(
  param,
  age_start = 40
)

# cannot add new parameters

# modify(
#   param,
#   const = 4.4,
#   age_2 = age ^ 2
# )

Define Partitioned Survival

Description

Define a partitioned survival model with progression-free survival and overall survival.

Usage

define_part_surv(
  pfs,
  os,
  state_names,
  terminal_state = FALSE,
  cycle_length = 1
)

define_part_surv_(pfs, os, state_names, cycle_length = 1)

Arguments

Value

A part_surv object.

Examples

dist_pfs <- define_surv_dist("exp", rate = 1)
dist_os <- define_surv_dist("exp", rate = .5)

define_part_surv(
  pfs = dist_pfs,
  os = dist_os,
  state_names = c(
    progression_free = "A",
    progression = "B",
    terminal = "C",
    death = "D"
  )
)
# identical to:
define_part_surv(
  pfs = dist_pfs,
  os = dist_os,
  terminal_state = TRUE
)

Define Parameters Distribution for Probabilistic Analysis

Description

Define the properties of parameter distributions and their correlation structure for probabilistic uncertainty analysis of Markov models.

Usage

define_psa(..., correlation)

define_psa_(.dots = list(), correlation)

Arguments

Details

The distributions must be defined within heemod (see distributions), or defined with define_distribution().

If no correlation matrix is specified parameters are assumed to be independant.

The correlation matrix need only be specified for correlated parameters.

Value

An object of class resamp_definition. Contains list_qdist, a list of quantile functions and correlation a correlation matrix.

Examples

mc <- define_correlation(
  age_init, cost_init, .4
)

define_psa(
    age_init ~ normal(60, 10),
    cost_init ~ normal(1000, 100),
    correlation = mc
)

# example with multinomial parameters

define_psa(
  rate1 + rate2 + rate3 ~ multinomial(10, 50, 40),
  a + b ~ multinomial(15, 30)
)

Define Starting State Values

Description

This function is meant to be used inside define_strategy() and define_state().

Usage

define_starting_values(...)

define_starting_values_(.dots)

Arguments

Details

The behaviour is different following the function using define_starting_values() as an argument.

• When used inside define_strategy(), the state values are modified for the first cycle in each state

• When used inside define_state(), the state values are modified for counts entering the state

Value

An object similar to the return value of define_parameters().

Define a Markov Model State

Description

Define the values characterising a Markov Model state for 1 cycle.

Usage

define_state(..., starting_values = define_starting_values())

define_state_(x)

## S3 method for class 'state'
modify(.OBJECT, ...)

Arguments

Details

As with define_parameters(), state values are defined sequentially. Later state definition can thus only refer to values defined earlier.

For the modify function, existing values are modified, no new values can be added. Values order matters since only values defined earlier can be referenced in later expressions.

Value

An object of class state (actually a named list of quosures).

Examples

st <- define_state(
  cost = 6453,
  utility = .876
)
st

Define Markov Model State List

Description

Define the states of a Markov model by combining state objects.

Usage

define_state_list(...)

define_state_list_(.dots)

## S3 method for class 'uneval_state_list'
modify(.OBJECT, ...)

Arguments

Details

State names have to correspond to those specified through define_transition().

All states should have the same value names.

The modify function can modify existing states or add new ones.

Value

An object of class uneval_state_list (a list of state objects).

Examples

## Not run: 
s1 <- define_state(cost = 1, util = 1)
s2 <- define_state(cost = 3, util = .4)

states_mod <- define_state_list(
  healthy = s1,
  sick = s2
)

states_mod

s1_bis <- define_state(cost = 0, util = 1)
s3 <- define_state(cost = 10, util = .1)

modify(
  states_mod,
  healthy = s1_bis,
  sicker = s3
)

## End(Not run)
  

Define a Markov Model

Description

Combine information on parameters, transition matrix and states defined through define_parameters(), define_transition() and define_state() respectively.

Usage

define_strategy(
  ...,
  transition = define_transition(),
  starting_values = define_starting_values()
)

define_strategy_(transition, states, starting_values)

Arguments

Details

This function checks whether the objects are compatible in the same model (same state names...).

State values and transition probabilities referencing state_time are automatically expanded to implicit tunnel states.

Value

An object of class uneval_model (a list containing the unevaluated parameters, matrix and states).

Examples

mat <- define_transition(
  state_names = c("s1", "s2"),
  1 / c, 1 - 1/ c,
  0, 1
)

s1 <- define_state(
  cost = 234,
  utility = 1
  )
s2 <- define_state(
  cost = 421,
  utility = .5
  )

define_strategy(
  transition = mat,
  s1 = s1,
  s2 = s2
)

Define a Survival Distribution

Description

Define a parametric survival distribution.

Usage

define_surv_dist(
  distribution = c("exp", "weibull", "weibullPH", "lnorm", "llogis", "gamma", "gompertz",
    "gengamma", "gengamma.orig", "genf", "genf.orig"),
  ...
)

Arguments

Value

A surv_dist object.

Examples

define_surv_dist(distribution = "exp", rate = .5)
define_surv_dist(distribution = "gompertz", rate = .5, shape = 1)

Define a Fitted Survival Model

Description

Define a fitted survival models with a Kaplan-Meier estimator or parametric distributions

Usage

define_surv_fit(x)

Arguments

Value

A surv_object object.

Examples

library(survival)

define_surv_fit(
  survfit(Surv(time, status) ~ 1, data = colon)
)

define_surv_fit(
  flexsurv::flexsurvreg(Surv(time, status) ~ 1, data = colon, dist = "exp")
)

Define a Restricted Cubic Spline Survival Distribution

Description

Define a restricted cubic spline parametric survival distribution.

Usage

define_surv_spline(scale = c("hazard", "odds", "normal"), ...)

Arguments

Value

A surv_dist object.

Examples

define_surv_spline(
  scale = "hazard", 
  gamma = c(-18.3122, 2.7511, 0.2292), 
  knots=c(4.276666, 6.470800, 7.806289)
)
define_surv_spline(
  scale = "odds", 
  gamma = c(-18.5809, 2.7973, 0.2035), 
  knots=c(4.276666, 6.470800, 7.806289)
)

Define a survival distribution based on explicit survival probabilities

Description

Define a survival distribution based on explicit survival probabilities

Usage

define_surv_table(x)

## S3 method for class 'data.frame'
define_surv_table(x)

## S3 method for class 'character'
define_surv_table(x)

Arguments

Value

a surv_table object, which can be used with compute_surv().

Examples

 x <- data.frame(time = c(0, 1, 5, 10), survival = c(1, 0.9, 0.7, 0.5))
 define_surv_table(x)
 

Define Transition Matrix for Markov Model

Description

Define a matrix of transition probabilities. Probability can depend on parameters defined with define_parameters(), and can thus be time-dependent.

Usage

define_transition(..., state_names)

define_transition_(.dots, state_names)

## S3 method for class 'uneval_matrix'
modify(.OBJECT, ...)

## S3 method for class 'uneval_matrix'
plot(x, relsize = 0.75, shadow.size = 0, latex = TRUE, ...)

Arguments

Details

Matric cells are listed by row.

Parameters names are searched first in a parameter object defined with define_parameters() and linked with the matrix through define_strategy(); then in the environment where the matrix was defined.

The complementary probability of all other row probabilities can be conveniently referred to as C.

The matrix code can be re-indented for readability with reindent_transition().

Only matrix size is checked during this step (the matrix must be square). Other conditions (such as row sums being equal to 1) are tested later, during model evaluation.

For the modify function, existing matrix cells are replaced with the new expression. Cells are referenced by name. Cell naming follows the cell_x_y convention, with x being the row number and y the column number.

Value

An object of class uneval_matrix (actually a named list of quosures expressions).

Examples

# simple 3x3 transition matrix

mat_1 <- define_transition(
  .2, 0, .8,
  0, .1, .9,
  0, 0, 1
)
mat_1

plot(mat_1)

# referencing parameters
# rr must be present in a parameter object
# that must later be linked with define_strategy

mat_2 <- define_transition(
  .5 - rr, rr,
  .4, .6
)
mat_2

reindent_transition(mat_2)

# can also use C

define_transition(
  C, rr,
  .4, .6
)

# updating cells from mat_1

modify(
  mat_1,
  cell_2_1 = .2,
  cell_2_3 = .7
)

# only matrix size is check, it is thus possible
# to define an incorrect matrix

# this matrix will generate an error later,
# during model evaluation

define_transition(
  .5, 3,
  -1, 2
)

Discount a Quantity Over Time. Should be a scalar if time is specified, a vector otherwise

Description

Discount a Quantity Over Time. Should be a scalar if time is specified, a vector otherwise

Usage

discount(x, r, first = FALSE, period = 1, linear = FALSE, time)

Arguments

Details

If the unit of discount rate is the year and a cycle duration is 1 month, period should be 12.

Value

A numeric vector of the same length as x.

Examples

discount(rep(10, 5), .02)
discount(rep(10, 5), .02, first = FALSE)
 
discount(1000, .05, time = 10)
discount(1000, .05, period = 2, time = 1:10)
discount(1000, .05, period = 2, time = 1:10, linear = TRUE)

Hack to Work Around a Discounting Issue

Description

This function is a hack to avoid a problem with discounting when the argument is a constant.

Usage

discount_hack(.dots)

Arguments

Details

The hack consists in replacing calls to discount(x) by discount(x * rep(1, dplyr::n())) to ensure x is recycled to the correct length.

Value

A modified state object.

Dispatch Values According to Strategy

Description

Returns different values depending on the strategy.

Usage

dispatch_strategy(.strategy, ...)

Arguments

Value

A vector of values.

Examples

define_parameters(
  val = 456,
  x = dispatch_strategy(
    strat_1 = 1234,
    strat_2 = 9876,
    strat_3 = val * 2 + model_time
  )
)

Hack to Automate Use of Strategy Name

Description

This function is a hack to automate the definition of the argument .strategy in dispatch_strategy().

Usage

dispatch_strategy_hack(.dots)

Arguments

Details

The hack consists in replacing calls to dispatch_strategy(...) by dispatch_strategy(.strategy = strategy, ...) if .strategy_name is not already defined.

Value

A modified quosures object.

Probability Density Functions for Probabilistic Uncertainty Analysis

Description

Define a distribution for PSA parameters.

Usage

normal(mean, sd)

lognormal(mean, sd, meanlog, sdlog)

gamma(mean, sd)

binomial(prob, size)

multinomial(...)

logitnormal(mu, sigma)

beta(shape1, shape2)

triangle(lower, upper, peak = (lower + upper)/2)

poisson(mean)

define_distribution(x)

beta(shape1, shape2)

triangle(lower, upper, peak = (lower + upper)/2)

use_distribution(distribution, smooth = TRUE)

Arguments

Details

These functions are not exported, but only used in define_psa(). To specify a user-made function use define_distribution().

use_distribution() uses gaussian kernel smoothing with a bandwidth parameter calculated by stats::density(). Values for unobserved quantiles are calculated by linear interpolation.

define_distribution() takes as argument a function with a single argument, x, corresponding to a vector of quantiles. It returns the distribution values for the given quantiles. See examples.

Examples

define_distribution(
  function(x) stats::qexp(p = x, rate = 0.5)
)

# a mixture of 2 gaussians
x <- c(rnorm(100), rnorm(100, 6))
plot(density(x))

use_distribution(x)

Evaluate Models From a Tabular Source

Description

Execute a full set of analyses, possibly including discrete sensitivity analysis, probabilistic sensitivity analysis, and analyses across demographics.

Usage

eval_models_from_tabular(
  inputs,
  run_dsa = TRUE,
  run_psa = TRUE,
  run_demo = TRUE
)

Arguments

Value

a list

• models (always) unevaluated model.

• model_runs (always) evaluated models

• dsa (deterministic sensitivity analysis) - if appropriate parameters provided

• psa (probabilistic sensitivity analysis) - if appropriate parameters provided

• demographics results across different demographic groups - if appropriate parameters provided

Evaluate Markov model parameters

Description

Evaluate parameters specified through define_parameters, for a given number of cycles.

Usage

eval_parameters(x, cycles = 1, strategy_name = NA)

Arguments

Value

An object of class eval_parameters (actually a data.frame with one column per parameter and one row per cycle).

Examples

param <- define_parameters(
  age_start = 60,
  age = age_start + model_time
)

heemod:::eval_parameters(param, cycles = 15)

Evaluate Resampling Definition

Description

Evaluate Resampling Definition

Usage

eval_resample(psa, N)

Arguments

Value

A data.frame of resampled values with on column per parameter and N rows.

Evaluate Markov Model States

Description

Evaluate Markov Model States

Usage

eval_state_list(x, parameters)

Arguments

Value

An eval_states object, a list with one data.frame per state containing a column per state value and a line per cycle.

Evaluate Strategy

Description

Given an unevaluated strategy, an initial number of individual and a number of cycle to compute, returns the evaluated version of the objects and the count of individual per state per model cycle.

Usage

eval_strategy(
  strategy,
  parameters,
  cycles,
  init,
  method,
  expand_limit,
  inflow,
  strategy_name
)

Arguments

Details

init need not be integer. E.g. c(A = 1, B = 0.5, C = 0.1, ...).

Value

An eval_strategy object (actually a list of evaluated parameters, matrix, states and cycles counts).

Examples

param <- define_parameters(
  a = model_time + 1 * 2
)

mat <- define_transition(
  1-1/a, 1/a,
  .1,    .9
)

mod <- define_strategy(
  transition = mat,
  A = define_state(cost = 10),
  B = define_state(cost = 2)
)

heemod:::eval_strategy(
  strategy = mod,
  parameters = param,
  init = define_init(A = 10, B = 5),
  cycles = 5,
  method = "end",
  inflow = define_inflow(A = 0, B = 0),
  strategy_name = "A",
  expand_limit = c(A = 5, B = 5)
)

Iteratively Evaluate a Markov Model With New Parameter Values

Description

Given a data.frame with on set of new parameters values per row, iteratively evaluate the model over the set of new values.

Usage

eval_strategy_newdata(x, strategy = 1, newdata)

Arguments

Details

New parameters with a missing value (NA) do not replace existing parameters.

Value

A data.frame containing the values of newdata and each Markov Model evaluation in res.

Examples

par1 <- define_parameters(
  a = 1,
  b = 1 / (model_time + a)
)

mat1 <- define_transition(
  1-b, b,
  0, 1
)
mod1 <- define_strategy(
  transition = mat1,
  define_state(var = a),
  define_state(var = a * model_time)
)

res1 <- run_model(
  mod1,
  parameters = par1,
  cycles = 5,
  init = 1:0,
  method = "end"
)

new_tab <- data.frame(
  a = 1:10
)

heemod:::eval_strategy_newdata(
  res1,
  newdata = new_tab
)

Evaluate Survival Distributions

Description

Generate either survival probabilities or conditional probabilities of event for each model cycle.

Usage

eval_surv(x, time, ...)

compute_surv_(x, time, cycle_length = 1, type = c("prob", "survival"), ...)

## S3 method for class 'surv_fit'
eval_surv(x, time, ...)

## Default S3 method:
eval_surv(x, ...)

## S3 method for class 'survfit'
eval_surv(x, time, ...)

## S3 method for class 'flexsurvreg'
eval_surv(x, time, ...)

## S3 method for class 'surv_model'
eval_surv(x, time, ...)

## S3 method for class 'surv_projection'
eval_surv(x, time, ...)

## S3 method for class 'surv_pooled'
eval_surv(x, time, ...)

## S3 method for class 'surv_ph'
eval_surv(x, time, ...)

## S3 method for class 'surv_shift'
eval_surv(x, time, ...)

## S3 method for class 'surv_aft'
eval_surv(x, time, ...)

## S3 method for class 'surv_po'
eval_surv(x, time, ...)

## S3 method for class 'surv_add_haz'
eval_surv(x, time, ...)

## S3 method for class 'surv_dist'
eval_surv(x, time, ...)

## S3 method for class 'surv_table'
eval_surv(x, time, ...)

Arguments

Value

Returns either the survival probabilities or conditional probabilities of event for each cycle.

Evaluate Markov Model Transition Matrix

Description

Evaluate a transition matrix using evaluated parameters.

Usage

eval_transition(x, parameters)

Arguments

Details

Runs checks on the transition matrix during evaluation.

This functions has been heavily optimized, and thus can be difficult to read. Good luck...

Value

An eval_matrix object (actually a list of transition matrices, one per cycle).

Expand States and Transition

Description

Given an unevaluated strategy, an initial number of individual and a number of cycle to compute, returns the evaluated version of the objects and the count of individual per state per model cycle.

Usage

expand_if_necessary(
  strategy,
  parameters,
  cycles,
  init,
  method,
  expand_limit,
  inflow,
  strategy_name
)

Arguments

Details

init need not be integer. E.g. c(A = 1, B = 0.5, C = 0.1, ...).

Value

Expanded states, transitions, input and inflow (if they require expansion; otherwise return inputs unchanged).

Examples

param <- define_parameters(
  a = model_time + 1 * 2
)

mat <- define_transition(
  1-1/a, 1/a,
  .1,    .9
)

mod <- define_strategy(
  transition = mat,
  A = define_state(cost = 10),
  B = define_state(cost = 2)
)

heemod:::eval_strategy(
  strategy = mod,
  parameters = param,
  init = define_init(A = 10, B = 5),
  cycles = 5,
  method = "end",
  inflow = define_inflow(A = 0, B = 0),
  strategy_name = "A",
  expand_limit = c(A = 5, B = 5)
)

Expand Time-Dependent States into Tunnel States

Description

This function for transition matrices and state values expands states relying on state_time in a series of tunnels states.

Usage

expand_state(x, ...)

## S3 method for class 'uneval_matrix'
expand_state(x, state_pos, state_name, cycles, n = 1, ...)

## S3 method for class 'uneval_state_list'
expand_state(x, state_name, cycles, ...)

## S3 method for class 'uneval_inflow'
expand_state(x, ...)

## S3 method for class 'uneval_init'
expand_state(x, state_name, cycles, ...)

Arguments

Value

The same object type as the input.

Export PSA Results for SAVI

Description

Export the result of a PSA in a format compatible with Sheffield Accelerated Value of Information software.

Usage

export_savi(x, folder = ".")

Arguments

Details

This function saves 3 files at the path given by folder: param.csv, the parameter values, cost.csv and effect.csv the cost and effect results.

The official SAVI website can be found at this URL: https://savi.shef.ac.uk/SAVI/

Value

Nothing. Creates 3 files.

Extract Evaluated Parameters

Description

Extracts the covariate-adjusted parameters from a flexsurv::flexsurvreg() object.

Usage

extract_params(obj, data = NULL)

Arguments

Value

A tidy data frame of curve parameters for each covariate level.

Extract Product-Limit Tables

Description

Extracts the product-limit table from a survfit object for all strata. Only survfit and unstratified survfit.coxph objects are supported.

Usage

extract_strata(sf)

Arguments

Value

A tidy data.frame of the product-limit tables for all strata.

Extract Product-Limit Table for a Stratum

Description

Extracts the product-limit table from a survfit object for a given stratum. Only survival::survfit() objects are supported.

Usage

extract_stratum(sf, index)

Arguments

Value

A data frame of the product-limit table for the given stratum.

Remove Blank Rows From Table

Description

Remove rows were all values are NA.

Usage

filter_blanks(x)

Arguments

Details

Some rows can be left blanks in the input table for readability, this function ensures those rows are removed.

Value

A data.frame without blank rows.

Gather Information for Running a Model From Tabular Data

Description

Gather Information for Running a Model From Tabular Data

Usage

gather_model_info(base_dir, ref_file)

Arguments

Value

A list with elements:

• models (of type uneval_model, created by create_model_list_from_tabular())

• param_info

• output_dir where to store output files, if specified

• demographic_file a table for demographic analysis

• model_options a list of model options.

Get State Membership Counts

Description

Given a result from run_model(), return state membership counts for a specific strategy.

Usage

## S3 method for class 'updated_model'
get_counts(x, ...)

## S3 method for class 'combined_model'
get_counts(x, ...)

get_counts(x, ...)

## S3 method for class 'run_model'
get_counts(x, ...)

## S3 method for class 'eval_strategy'
get_counts(x, ...)

## S3 method for class 'list'
get_counts(x, ...)

Arguments

Value

A data frame of counts per state.

Get count matrix and difference between two cycles

Description

Get count matrix and difference between two cycles

Usage

get_counts_diff(x, init, inflow)

Arguments

Value

A length 2 list of matrix : the count matrix for each cycle and the diff matrix showing the difference of counts between two cycles.

Return Efficiency Frontier

Description

Return Efficiency Frontier

Usage

get_frontier(x)

Arguments

Value

A vector of model names on the efficiency frontier.

Get count number

Description

Get count number

Usage

get_mat_total(x, init)

Arguments

Value

A count matrix

Return Markov Model Transition Matrix Order

Description

A generic that works both with uneval_matrix and eval_matrix.

Usage

get_matrix_order(x)

Arguments

Details

For internal use.

Value

An integer: matrix order.

Return parameters names

Description

Extract parameters names.

Usage

get_parameter_names(x)

Arguments

Value

A character vector of parameter names.

Get State Names

Description

Retrieve state names from an object containing states.

Usage

get_state_names(x, ...)

Arguments

Value

A character vector of state names.

Return Number of State

Description

For internal use.

Usage

get_state_number(x)

Arguments

Details

Work with both uneval_states and eval_states.

Value

An integer: number of states.

Return Names of State Values

Description

Return Names of State Values

Usage

get_state_value_names(x)

Arguments

Value

A character vector of state value names.

Get Markov Model Transition Matrix

Description

Works on both unevaluated and evaluated models.

Usage

get_transition(x)

Arguments

Value

An uneval_matrix or uneval_matrix object.

Get Strategy Values

Description

Given a result from run_model(), return cost and effect values for a specific strategy.

Usage

## S3 method for class 'updated_model'
get_values(x, ...)

## S3 method for class 'combined_model'
get_values(x, ...)

get_values(x, ...)

## S3 method for class 'run_model'
get_values(x, ...)

## S3 method for class 'eval_strategy'
get_values(x, ...)

## S3 method for class 'list'
get_values(x, ...)

Arguments

Value

A data frame of values per state.

Insert Elements in Vector

Description

Insert a vector in another vector.

Usage

insert(x, pos, what)

Arguments

Details

To insert an element at the beginning use a pos value of 0.

Duplicated positions are not allowed.

Value

A vector.

Examples

heemod:::insert(letters, c(0, 5, 26), c("xxx", "yyy"))

Interpolate Quosures

Description

Sequentially interpolates quosures, optionally using external references.

Usage

interpolate(x, ...)

## Default S3 method:
interpolate(x, more = NULL, ...)

## S3 method for class 'uneval_matrix'
interpolate(x, ...)

## S3 method for class 'state'
interpolate(x, ...)

## S3 method for class 'part_surv'
interpolate(x, ...)

## S3 method for class 'uneval_state_list'
interpolate(x, ...)

Arguments

Details

The interpolation is sequential: the second dot is interpolated using the first, the third using the interpolated first two, and so on.

Value

An interpolated quosures object.

Check whole Numbers

Description

Check whole Numbers

Usage

is.wholenumber(x, tol = .Machine$double.eps^0.5)

Arguments

Value

A logical scalar.

Check File Type

Description

Check File Type

Usage

is_csv(x)

is_xlsx(x)

is_xls(x)

Arguments

Value

Whether the file is (respectively) csv, xlsx, or xls.

Project Beyond a Survival Distribution with Another

Description

Project survival from a survival distribution using one or more survival distributions using the specified cut points.

Usage

join(..., at)

join_(dots, at)

Arguments

Value

A surv_projection object.

Examples

dist1 <- define_surv_dist(distribution = "exp", rate = .5)
dist2 <- define_surv_dist(distribution = "gompertz", rate = .5, shape = 1)
join_dist <- join(dist1, dist2, at=20)

Check if All the Elements of a List Are the Same

Description

Check if All the Elements of a List Are the Same

Usage

list_all_same(x)

Arguments

Value

A logical scalar.

Load a set of survival fits

Description

Load a set of survival fits

Usage

load_surv_models(location, survival_specs, use_envir)

Arguments

Value

A list with two elements:

• best_models, a list with the fits for each data file passed in; and

• envir, an environment containing the models so they can be referenced to get probabilities.

Look Up Values in a Data Frame

Description

A convenience function to easily look for values in a data frame.

Usage

look_up(data, ..., bin = FALSE, value = "value")

Arguments

Details

This function is mostly used to extract population informations (such as mortality rates), given some individual characteristics.

If binning is activated, numeric individual characteristics are matched to the corresponding reference value that is directly inferior.

Value

A vector of values, same length as ....

Examples

tempdf <- expand.grid(arg1 = c("A", "B", "C"), arg2 = 1:4, arg3 = 1:5)
tempdf$value <- 1:60

look_up(
  data = tempdf,
  value = "value",
  arg1 = c("A", "B", "C", "B", "A"),
  arg2 = c(1, 1, 3.2, 3.0, 5), 
  arg3 = c(-1, 1, 1, 2, 3)
)

# binning doesnt catch values lesser than the smaller
# reference value
look_up(
  data = tempdf,
  value = "value",
  arg1 = c("A", "B", "C", "B", "A"),
  arg2 = c(1, 1, 3.2, 3.0, 5), 
  arg3 = c(-1, 1, 1, 2, 3),
  bin = TRUE
)
# bin can alos be given as a charater vector
# to avoid binning all numeric variables
look_up(
  data = tempdf,
  value = "value",
  arg1 = c("A", "B", "C", "B", "A"),
  arg2 = c(1, 1, 3.2, 3.0, 5), 
  arg3 = c(-1, 1, 1, 2, 3),
  bin = c("arg2")
)

age_related_df <- data.frame(age = 10 * 0:9, decade = 1:10)

look_up(age_related_df, age = c(0, 10, 20), value = "decade")

# binning might help in the situation
look_up(age_related_df, age = c(5, 15, 23.5), 
        value = "decade")
look_up(age_related_df, age = c(5, 15, 23.5), 
        value = "decade", bin = TRUE)

Make Syntactically Valid Names

Description

Compared to make.names() this function also converts characters to lower case and replaces . by ⁠_⁠.

Usage

make_names(x)

Arguments

Value

A character vector.

Mix Two or More Survival Distributions

Description

Mix a set of survival distributions using the specified weights.

Usage

mix(..., weights = 1)

mix_(dots, weights = 1)

Arguments

Value

A surv_pooled object.

Examples

dist1 <- define_surv_dist(distribution = "exp", rate = .5)
dist2 <- define_surv_dist(distribution = "gompertz", rate = .5, shape = 1)
pooled_dist <- mix(dist1, dist2, weights = c(0.25, 0.75))

Modify Object

Description

This generic function allows the modification of various objects such as parameters, transitions matrix or states.

Usage

modify(.OBJECT, ...)

Arguments

Details

More details are available on the respective help page of each object definition.

Value

Same class as x.

Specify Inputs for Multiple Models From a Single File

Description

Parse a data.frame containing specifications for multiple models into a list of inputs required for each model.

Usage

parse_multi_spec(multi_spec, split_on = ".model", group_vars)

Arguments

Details

Each combination of values of the columns specified by group_vars should either be unique in the file (in which case it will be replicated for all values of split_on), or must be repeated as many times as unique values of split_on.

split_on is usually the model name.

group_var can be the state names, or from and to lines for a matrix definition...

Value

A list of data frames, one for each value of split_on.

Convert saved fits to partitioned survival objects

Description

Convert saved fits to partitioned survival objects

Usage

part_survs_from_surv_inputs(surv_inputs, state_names)

Arguments

Details

surv_inputs is a tibble with columns type (PFS or OS, not case sensitive), treatment, set_name (for data subsets), dist (for survival distribution assumptions), fit (for the fitted survival object) and set_def (how the subset of data was defined, just to keep it around)

Value

a tibble of partitioned survival objects, similar to the original tibble of survival fits, with all the columns except type and fit, and a new column part_surv.

Plot Sensitivity Analysis

Description

Plot the results of a sensitivity analysis as a tornado plot.

Usage

## S3 method for class 'dsa'
plot(
  x,
  type = c("simple", "difference"),
  result = c("cost", "effect", "icer"),
  strategy = NULL,
  widest_on_top = TRUE,
  limits_by_bars = TRUE,
  resolve_labels = FALSE,
  shorten_labels = FALSE,
  remove_ns = FALSE,
  bw = FALSE,
  ...
)

Arguments

Details

Plot type simple plots variations of single strategy values, while difference plots incremental values.

Value

A ggplot2 object.

Plot Results of Probabilistic Analysis

Description

Various plots for Markov models probabilistic analysis.

Usage

## S3 method for class 'psa'
plot(
  x,
  type = c("ce", "ac", "cov", "evpi"),
  max_wtp = 1e+05,
  n = 100,
  log_scale = TRUE,
  diff = FALSE,
  threshold,
  bw = FALSE,
  ...
)

Arguments

Details

type = "ac" plots cost-effectiveness acceptability curves, type = "ce" plots results on the cost-efficiency plane, type = "cov" to perform covariance analysis on the results, type = "evpi" for expected value of perfect information.

Value

A ggplot2 object.

Plot Results of a Markov Model

Description

Various plots for Markov models.

Usage

## S3 method for class 'run_model'
plot(
  x,
  type = c("counts", "ce", "values"),
  panels = c("by_strategy", "by_state", "by_value"),
  values = NULL,
  strategy = NULL,
  states = NULL,
  free_y = FALSE,
  bw = FALSE,
  ...
)

Arguments

Value

A ggplot2 object.

Examples

## These examples require \code{res_mod} from the hip replacement model discussed in
## `vignette("non-homogeneous", package = "heemod")`.

## Not run: 
  plot(res_mod)

  plot(res_mod, model = "all")
  plot(res_mod, model = "all", panels = "by_state")

  plot(res_mod, model = "all", include_states = c("RevisionTHR", "SuccessR"))
  plot(res_mod, model = "all", panels = "by_state", include_states = c("RevisionTHR", "SuccessR"))
 
  plot(res_mod, model = 2, panel = "by_state", include_states = c("RevisionTHR", "SuccessR"))
  

## End(Not run)

Plot general survival models

Description

Plot general survival models

Usage

## S3 method for class 'surv_object'
plot(
  x,
  times = seq.int(0, 30),
  type = c("surv", "prob"),
  psa,
  Nrep = 100,
  join_opts = list(join_col = "red", join_pch = 20, join_size = 3),
  ...
)

Arguments

Details

The function currently only highlights join points that are at the top level; that is, for objects with class surv_projection. To avoid plotting the join points, set join_size to a negative number.

Value

a ggplot2::ggplot() object.

Examples

## Evaluation of the variability of the survival distribution

surv1 <- define_surv_dist("exp", rate = 0.1)
psa <- define_psa(surv1 ~ resample_surv(n = 100))
plot(surv1, psa=psa)

## plot surv_projection object
surv2 <- define_surv_dist("exp", rate = 0.5)
plot(join(surv1, surv2, at = 2), psa = psa, Nrep = 50)

## surv_fit object
library(survival)
km <- define_surv_fit(survfit(formula = Surv(time, status) ~ 1, data = aml))
fs <- flexsurv::flexsurvreg(formula = Surv(time, status) ~ 1, 
                        data = aml, 
                        dist = "weibull") |>
  define_surv_fit()

psa2 <- define_psa(km ~ resample_surv(),
                   fs ~ resample_surv(),
                   surv1 ~ resample_surv(100))
plot(km, psa = psa2)

plot(join(km, surv1, at = 6), psa = psa2)
plot(join(fs, surv1, at = 6), psa = psa2)

Returns "s" if x > 1

Description

Returns "s" if x > 1

Usage

plur(x)

plur_y(x)

Arguments

Value

"s" or "".

Convenience Functions to Compute Probabilities

Description

These convenience functions make it easier to compute transition probabilities from incidence rates, OR, RR, or probabilities estimated on a different timeframe.

Usage

rescale_prob(p, to = 1, from = 1)

prob_to_prob(...)

rate_to_prob(r, to = 1, per = 1)

or_to_prob(or, p)

rr_to_prob(rr, p)

Arguments

Value

A probability.

Examples

# convert 5-year probability 
# to 1-year probability
rescale_prob(p = .65, from = 5)

# convert 1-year probability 
# to 1-month probability
rescale_prob(p = .5, to = 1/12)

# convert rate per 1000 PY
# to 5-year probability
rate_to_prob(r = 162, per = 1000, to = 5)

# convert OR to probability
or_to_prob(or = 1.9, p = .51)

# convert RR to probability
rr_to_prob(rr = 1.9, p = .51)

Project Beyond a Survival Distribution with Another (pairwise)

Description

Project survival from a survival distribution using another survival distribution at the specified cutpoint. Used by project to reduce the list of distributions.

Usage

project_fn(dist1, dist2_list)

Arguments

Value

A surv_projection object.

Read the accepted file formats for tabular input

Description

Columns starting with '.comment' are ignored.

Usage

read_file(file_name)

Arguments

Value

A data.frame.

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

dplyr

%>%

Reindent Transition Matrix

Description

Reindent Transition Matrix

Usage

reindent_transition(x, print = TRUE)

Arguments

Value

The reindented matrix as a text string, invisibly.

Resample survival distribution

Description

Resample survival distribution

Usage

resample_surv(n)

resample_surv_boot(x)

resample_surv_dist(x, n)

r_resample_surv_dist(distribution, type, args)

r_boot_survfit(x)

Arguments

Rescale Discount Rate

Description

Rescale a discount rate between two time frames.

Usage

rescale_discount_rate(x, from, to)

Arguments

Details

Continuous discounting is assumed, i.e. when converting a long-term discount rate into a short-term rate, we assume that a partial gain from one short term is multiplicatively discounted in all following short terms. At the same time, we assume the short-term rate is time-invariant.

Value

Rate rescaled under the assumption of compound discounting.

Examples

  ## 1% monthly interest rate to annual
  rescale_discount_rate(0.01, 1, 12)
  ## 3% annual discount rate to (approximately) weekly 
  rescale_discount_rate(0.03, 52, 1)

Use the BCEA package

Description

Interfaces the output of run_psa() into the BCEA package.

Usage

run_bcea(x, ...)

Arguments

Details

The BCEA package is needed for this function to work.

Value

A BCEA analysis.

Run Sensitivity Analysis

Description

Run Sensitivity Analysis

Usage

run_dsa(model, dsa)

Arguments

Value

A data.frame with one row per model and parameter value.

Examples

param <- define_parameters(
  p1 = .5,
  p2 = .2,
  r = .05
)
mod1 <- define_strategy(
  transition = define_transition(
    C, p1,
    p2, C
  ),
  define_state(
    cost = discount(543, r),
    ly = 1
  ),
  define_state(
    cost = discount(432, r),
    ly = .5
  )
)

mod2 <- define_strategy(
  transition = define_transition(
    C, p1,
    p2, C
  ),
  define_state(
    cost = 789,
    ly = 1
  ),
  define_state(
    cost = 456,
    ly = .8
  )
)

res2 <- run_model(
  mod1, mod2,
  parameters = param,
  init = c(100, 0),
  cycles = 10,
  cost = cost,
  effect = ly
)

ds <- define_dsa(
  p1, .1, .9,
  p2, .1, .3,
  r, .05, .1
)
print(ds)



#'\dontrun{
#'x <- run_dsa(res2, ds)
#'plot(x, value = "cost")
#'}
#'
#'
# can be specified as a function of other parameters


ds2 <- define_dsa(
  p2, p1 - .1, p1 + .1
)

#'\dontrun{
#'run_dsa(res2, ds2)
#'}

Run Markov Model

Description

Runs one or more strategy. When more than one strategy is provided, all strategies should have the same states and state value names.

Usage

run_model(
  ...,
  parameters = define_parameters(),
  init = c(1000L, rep(0L, get_state_number(get_states(list(...)[[1]])) - 1)),
  cycles = 1,
  method = c("life-table", "beginning", "end"),
  cost = NULL,
  effect = NULL,
  state_time_limit = NULL,
  central_strategy = NULL,
  inflow = rep(0L, get_state_number(get_states(list(...)[[1]])))
)

run_model_(
  uneval_strategy_list,
  parameters,
  init,
  cycles,
  method,
  cost,
  effect,
  state_time_limit,
  central_strategy,
  inflow
)

Arguments

Details

In order to compute comparisons strategies must be similar (same states and state value names). Thus strategies can only differ through transition matrix cell values and values attached to states (but not state value names).

The initial number of individuals in each state and the number of cycle will be the same for all strategies

state_time_limit can be specified in 3 different ways:

1. As a single value: the limit is applied to all states in all strategies. 2. As a named vector (where names are state names): the limits are applied to the given state names, for all strategies. 3. As a named list of named vectors: the limits are applied to the given state names for the given strategies.

Counting method represents where the transition should occur, based on https://journals.sagepub.com/doi/10.1177/0272989X09340585: "beginning" overestimates costs and "end" underestimates costs.

Value

A list of evaluated models with computed values.

Examples

# running a single model

mod1 <-
  define_strategy(
    transition = define_transition(
      .5, .5,
      .1, .9
    ),
    define_state(
      cost = 543,
      ly = 1
    ),
    define_state(
      cost = 432,
      ly = 1
    )
  )


res <- run_model(
  mod1,
  init = c(100, 0),
  cycles = 2,
  cost = cost,
  effect = ly
)

# running several models
mod2 <-
  define_strategy(
    transition = define_transition(
      .5, .5,
      .1, .9
    ),
    define_state(
      cost = 789,
      ly = 1
    ),
    define_state(
      cost = 456,
      ly = 1
    )
    
  )


res2 <- run_model(
  mod1, mod2,
  init = c(100, 0),
  cycles = 10,
  cost = cost,
  effect = ly
)

Run Analyses From Files

Description

This function runs a model from tabular input.

Usage

run_model_tabular(
  location,
  reference = "REFERENCE.csv",
  run_dsa = TRUE,
  run_psa = TRUE,
  run_demo = TRUE,
  save = FALSE,
  overwrite = FALSE
)

Arguments

Details

The reference file should have two columns. data can be added, having value TRUE where an absolute file path is provided. data values must include state, tm, and parameters, and can also include options, demographics and data. The corresponding values in the file column give the names of the files (located in base_dir) that contain the corresponding information - or, in the case of data, the directory containing the tables to be loaded.

Value

A list of evaluated models (always), and, if appropriate input is provided, dsa (deterministic sensitivity analysis), psa (probabilistic sensitivity analysis) and demographics (results across different demographic groups).

Run Probabilistic Uncertainty Analysis

Description

Run Probabilistic Uncertainty Analysis

Usage

run_psa(model, psa, N, keep = FALSE)

Arguments

Value

A list with the following elements

• psa: a data.frame with one row per model.

• run_model: a data.frame with mean cost and utility for each strategy

• model: the initial model object

• N: the number of simulations ran

• resamp_par: the resampled parameters

• full: if keep is TRUE, a list of each model objects created at each iteration

Examples

# example for run_psa

mod1 <- define_strategy(
  transition = define_transition(
    .5, .5,
    .1, .9
  ),
  define_state(
    cost = cost_init + age * 5,
    ly = 1
  ),
  define_state(
    cost = cost_init + age,
    ly = 0
  )
)

mod2 <- define_strategy(
  transition = define_transition(
    p_trans, C,
    .1, .9
  ),
  define_state(
    cost = 789 * age / 10,
    ly = 1
  ),
  define_state(
    cost = 456 * age / 10,
    ly = 0
  )
  
)

res2 <- run_model(
  mod1, mod2,
  parameters = define_parameters(
    age_init = 60,
    cost_init = 1000,
    age = age_init + model_time,
    p_trans = .7
  ),
  init = 1:0,
  cycles = 10,
  cost = cost,
  effect = ly
)

rsp <- define_psa(
  age_init ~ normal(60, 10),
  cost_init ~ normal(1000, 100),
  p_trans ~ binomial(.7, 100),
  correlation = matrix(c(
    1,  .4, 0,
    .4, 1,  0,
    0,  0,  1
  ), byrow = TRUE, ncol = 3)
)


# with run_model result
# (only 10 resample for speed)
ndt1 <- run_psa(res2, psa = rsp, N = 10)

Safely Convert From Characters to Numbers

Description

These function return an error if a conversion fails.

Usage

safe_convert(x, f)

as_numeric_safe(x)

as_integer_safe(x)

Arguments

Value

A converted vector.

Save Model Outputs

Description

Save Model Outputs

Usage

save_outputs(outputs, output_dir, overwrite)

Arguments

Value

NULL. Used for its side effect of creating files in the output directory.

Normalize Cost and Effect

Description

Normalize cost and effect values taking base model as a reference.

Usage

## S3 method for class 'combined_model'
scale(x, center = TRUE, scale = TRUE)

## S3 method for class 'psa'
scale(x, center = TRUE, scale = TRUE)

## S3 method for class 'run_model'
scale(x, center = TRUE, scale = TRUE)

## S3 method for class 'dsa'
scale(x, center = TRUE, scale = TRUE)

Arguments

Value

Input with normalized .cost and .effect, ordered by .effect.

Set Covariates of a Survival Distribution

Description

Set the covariate levels of a survival model to be represented in survival projections.

Usage

set_covariates(dist, ..., data = NULL)

set_covariates_(dist, covariates, data = NULL)

Arguments

Value

A surv_model object.

Examples

fs1 <- flexsurv::flexsurvreg(
  survival::Surv(rectime, censrec)~group,
  data=flexsurv::bc,
  dist = "llogis"
)
good_model <- set_covariates(fs1, group = "Good")
cohort <- data.frame(group=c("Good", "Good", "Medium", "Poor"))
mixed_model <- set_covariates(fs1, data = cohort)

Summarise Markov Model Results

Description

Summarise Markov Model Results

Usage

## S3 method for class 'run_model'
summary(object, threshold = NULL, ...)

Arguments

Value

A summary_run_model object.

Summarize surv_shift objects

Description

Summarize surv_shift objects

Usage

## S3 method for class 'surv_shift'
summary(object, summary_type = c("plot", "standard"), ...)

Arguments

Value

A summary.

Run Model on New Data

Description

Given a table of new parameter values with a new parameter set per line, runs iteratively Markov models over these sets.

Usage

## S3 method for class 'run_model'
update(object, newdata, ...)

## S3 method for class 'updated_model'
plot(
  x,
  type = c("simple", "difference", "counts", "ce", "values"),
  result = c("cost", "effect", "icer"),
  strategy = NULL,
  ...
)

Arguments

Details

newdata must be a data.frame with the following properties: the column names must be parameter names used in define_parameters(); and an optional column .weights can give the respective weight of each row in the target population.

Weights are automatically scaled. If no weights are provided equal weights are used for each strata.

For the plotting function, the type argument can take the following values: "cost", "effect" or "icer" to plot the heterogeneity of the respective values. Furthermore "ce" and "count" can produce from the combined model plots similar to those of run_model().

Value

A data.frame with one row per model/value.

Warning

Histograms do not account for weights. On the other hand summary results do.

Examples

mod1 <-
  define_strategy(
    transition = define_transition(
      .5, .5,
      .1, .9
    ),
    define_state(
      cost = 543 + age * 5,
      ly = 1
    ),
    define_state(
      cost = 432 + age,
      ly = 1 * age / 100
    )
  )

mod2 <-
  define_strategy(
    transition = define_transition(
      .5, .5,
      .1, .9
    ),
    define_state(
      cost = 789 * age / 10,
      ly = 1
    ),
    define_state(
      cost = 456 * age / 10,
      ly = 1 * age / 200
    )
  )

res <- run_model(
  mod1, mod2,
  parameters = define_parameters(
    age_init = 60,
    age = age_init + model_time
  ),
  init = 1:0,
  cycles = 10,
  cost = cost,
  effect = ly
)

# generating table with new parameter sets
new_tab <- data.frame(
  age_init = 40:45
)

# with run_model result
ndt <- update(res, newdata = new_tab)

summary(ndt)

# using weights

new_tab2 <- data.frame(
  age_init = 40:45,
  .weights = runif(6)
)

#'\dontrun{
#'ndt2 <- update(res, newdata = new_tab2)
#'
#'summary(ndt2)
#'}

Use WHO Mortality Rate

Description

Returns age and sex-specific mortality probabilities for a given region

Usage

get_who_mr(age, sex = NULL, region = NULL, year = "latest")

Arguments

Details

Only locally cached data are available. For memory space reasons local data is only available for WHO high-income countries (pooled), and only for the latest year.

Value

This function should be used within define_transition() or define_parameters().

Examples

define_transition(
  C, get_who_mr(age = 50 + model_time, sex = "FMLE", region = "EUR"),
  0, 1
)

Weighted Summary

Description

Compute a weighted summary of a numeric vector.

Usage

wtd_summary(x, weights = NULL)

Arguments

Details

If weights is NULL an unweighted summary is returned.

Value

A vector with values Min., 1st Qu., Median, Mean, 3rd Qu., Max..