Package {LAGOtrials}

LAGOtrials: Learn-as-You-Go Adaptive Trial Optimization

Description

Optimizes interventions for adaptive "Learn-As-you-GO" (LAGO) trials, in which the intervention package is updated between stages using accumulating data. Given data from completed stages, lago_optimization() fits the outcome model (via 'stats' generalized linear models or, for clustered designs, cluster-robust variance) and computes the cost-optimal recommended intervention for the next stage that is expected to reach a target mean outcome and/or a desired statistical power. get_confidence_set() constructs confidence sets for the optimal intervention, and visualize_cost() and lago_report() summarize the cost surface and results. Methods are described in Nevo, Lok and Spiegelman (2021) doi:10.1214/20-aos1978 and Bing, Spiegelman, Nevo and Lok (2025) doi:10.1093/biomtc/ujaf061.

Author(s)

Maintainer: Ante Bing abing@bu.edu

Authors:

• Ante Bing abing@bu.edu

• Minh Bui

• Jingyu Cui

Other contributors:

• Mike Bostock (Author of the bundled D3 v7 library, inst/js/d3.v7.min.js) [copyright holder]

See Also

Useful links:

• https://correspondmerchant.github.io/LAGO-R-Package/

• https://github.com/correspondMerchant/LAGO-R-Package

• Report bugs at https://github.com/correspondMerchant/LAGO-R-Package/issues

BetterBirth Data (for binary outcome analysis)

Description

This is the cleaned version of the BetterBirth dataset used in Nevo et al.

Usage

BB_data

Format

A data frame with 6124 rows and 21 variables:

coaching_updt

Number of coaching visits accrued (at time of birth)

data_flag

Indicator of original dataset

datafeedback

Data feedback loop

launch_duration

Duration of checklist launch

leadership_ITT

Leadership engagement, ITT

leadership_updt

Intensity of leadership engagement (at time of birth)

pre_post

Indicator for visits after initial coaching visit

pilot_phase

Phase of the pilot studies

site_name

Site name

always_checklist

Checklist was used in all phases

sometimes_checklist

Checklist was only in some phases

birth_volume

Estimated monthly birth volume

birth_volume_100

Estimated monthly birth volume (divided by 100)

distance

Estimated distance to nearby hospital (km)

distance_10

Estimated distance to nearby hospital (divided by 10)

staff_nurse

Number of ANM, staff nurses, and lady health visitors

pp2_hand_hygiene

fada_op2_handwashing

pp3_oxytocin_mother

fada_op3_oxytocin_administered

center_type

Phase of the pilot studies

coach5

Number of coaching vissts accrued divided by 5

coach3

Number of coaching vissts accrued divided by 3

Source

doi:10.1186/s13012-015-0309-y

doi:10.1056/NEJMoa1701075

Examples

data(BB_data)
head(BB_data)

BetterBirth Data (for continuous outcome analysis, using EBP proportions as a continuous outcome).

Description

This is the cleaned version of the BetterBirth dataset used in Bing et al.

Usage

BB_proportions

Format

A data frame with 7359 rows and 4 variables:

coaching_updt

Number of coaching visits accrued (at time of birth)

launch_duration

Duration of checklist launch

birth_volume_100

Estimated monthly birth volume (divided by 100)

EBP_proportions

Essential birth practices performed out of all possible birth practices measured. We consider this as a continuous outcome.

Source

https://arxiv.org/pdf/2307.06552

Examples

data(BB_proportions)
head(BB_proportions)

Non-fatal diagnostics for the fitted outcome model

Description

Checks the fitted glm for signs that the fit is unreliable and issues warnings (never errors) so LAGO optimization can continue. Covers three Tier-1 checks: 1. glm fit warnings captured during fitting (separation signal). 2. separation / near-non-identifiability, detected via extremely large coefficient standard errors relative to the estimates. 3. intervention-component effects that are not statistically significant, which make the corresponding part of the recommendation unreliable.

Usage

diagnose_model_fit(model, intervention_components, fit_warnings = character(0))

Arguments

Value

Invisibly NULL. Called for its side effect of issuing warnings.

get_confidence_set

Description

Internal function that calculates the confidence set for the recommended interventions

Usage

get_confidence_set(
  predictors_data,
  include_center_effects = FALSE,
  center_weights_for_outcome_goal = 1,
  include_time_effects = FALSE,
  time_effect_optimization_value = NULL,
  additional_covariates = NULL,
  intervention_components,
  include_interaction_terms = FALSE,
  main_components = NULL,
  outcome_data,
  fitted_model,
  link,
  outcome_goal,
  outcome_type,
  intervention_lower_bounds,
  intervention_upper_bounds,
  confidence_set_grid_step_size,
  center_characteristics = NULL,
  center_characteristics_optimization_values = 0,
  confidence_set_alpha = 0.05,
  cluster_id = NULL,
  cost_list_of_vectors,
  rec_int
)

Arguments

Details

Continuous covariance treats fitted prior weights as relative observation weights. Scaling all weights by the same positive constant leaves the covariance unchanged for a fixed fit. Zero weight rows contribute nothing, but fitted row and cluster validation still includes them. Singular weighted bread is refused without regularization.

For the identity link without clusters, the bread is the inverse of X^T W X. The residual scale is \sum_i w_i (y_i - \mu_i)^2 divided by the positive weight row count minus the design column count. This denominator must be positive. For a full rank Gaussian identity fit, this is the usual estimated dispersion covariance. With clusters, the score for each row is w_i x_i (y_i - \mu_i).

For the logit link, the existing Gauss Newton sandwich is retained. Set d_i = \mu_i (1 - \mu_i) x_i. The bread is the inverse of \sum_i w_i d_i d_i^T and the row score is w_i d_i (y_i - \mu_i). Without clusters the meat is the sum of row score outer products (HC0). With clusters, for either link, the meat is the sum of cluster score outer products (CR0). Two clustering dimensions use the first covariance plus the second minus the intersection covariance. No finite sample correction is added.

These formulas extend the existing continuous covariance definition. They are not a frequency weight or survey design variance. In particular, the existing continuous quasibinomial covariance does not use that family's variance function, so this weight extension does not make it a general GLM covariance. Binary outcomes continue to use stats::vcov(fitted_model). Center weights for the outcome goal are separate from observation weights.

Value

List( confidence_set_size_percentage = <number, the size of the confidence set as a fraction of the grid. Both the count of qualifying interventions and the size of the grid count grid interventions only, so rec_int is excluded from each>, rec_int_ci = <named numeric c(lower, upper) rounded to 3 decimal places, the confidence interval at rec_int. Computed whether or not it covers the outcome goal, so callers never have to look for rec_int inside cs. For a binary outcome on the logit link both bounds are confined to [0, 1], where the estimate is a probability by construction and the interval around it therefore belongs in that range; the interval is still the delta-method one and a bound at exactly 0 or 1 is one that has been truncated to the range. Not confined on the identity link, where the estimate is the linear predictor and is itself unbounded, so confining the interval would report one that excludes its own estimate. That estimate leaving [0, 1] is a defect in its own right and not this one; lago_optimization() now warns when it does, so it is flagged rather than silent, and the interval is still reported as computed for the same reason as before. Not confined for a continuous outcome either, whose range is not knowable here. NULL when that interval is not computable>, cs = <data.frame of the grid interventions whose confidence interval covers the outcome goal, with their interval bounds and cost. rec_int is never one of its rows, and need not be a grid intervention at all. NULL when no grid intervention qualifies> )

See Also

[lago_optimization()]

Other LAGO functions: lago_budget(), lago_optimization(), lago_report(), lago_sensitivity(), visualize_cost()

Examples

# Normally reached through lago_optimization(include_confidence_set = TRUE).
# Called directly it needs the fitted outcome model and the recommended
# intervention from the optimization step, so both are taken from a run of
# the optimizer rather than refitting the model by hand. get_confidence_set()
# binds its prediction matrix to the coefficient vector by name, so a
# hand-fitted model may list its terms in any order. It must be fitted on
# exactly the predictors passed here, though: the intercept, the fixed
# center effects, the fixed time effects, the intervention components, the
# additional covariates and the center characteristics. Any other set of
# coefficients is an error naming what did not match.
# The lower bounds start at 1 while the data also contains 0s, so the
# optimizer warns about that; the warning is expected here.
opt <- lago_optimization(
  data = BB_data,
  outcome_name = "pp3_oxytocin_mother",
  outcome_type = "binary",
  glm_family = "binomial",
  intervention_components = c("coaching_updt", "launch_duration"),
  center_characteristics = c("birth_volume_100"),
  center_characteristics_optimization_values = 1.75,
  intervention_lower_bounds = c(1, 1),
  intervention_upper_bounds = c(40, 5),
  cost_list_of_vectors = list(c(0, 1700), c(0, 8000)),
  outcome_goal = 0.85,
  outcome_goal_intention = "maximize",
  include_confidence_set = FALSE,
  quiet = TRUE
)

intervention_components <- c("coaching_updt", "launch_duration")
predictors <- c(intervention_components, "birth_volume_100")

cs <- get_confidence_set(
  predictors_data = BB_data[, predictors, drop = FALSE],
  intervention_components = intervention_components,
  outcome_data = BB_data$pp3_oxytocin_mother,
  fitted_model = opt$model,
  link = "logit",
  outcome_goal = 0.85,
  outcome_type = "binary",
  intervention_lower_bounds = c(1, 1),
  intervention_upper_bounds = c(40, 5),
  confidence_set_grid_step_size = c(1, 1),
  center_characteristics = "birth_volume_100",
  center_characteristics_optimization_values = 1.75,
  cost_list_of_vectors = list(c(0, 1700), c(0, 8000)),
  rec_int = opt$rec_int
)

# Fraction of the grid inside the 95% confidence set: 18 of the 200 grid
# interventions qualify here (40 coaching values by 5 launch durations), so
# 0.09. print() shows the same number as a percentage.
cs$confidence_set_size_percentage

# The confidence interval at the recommended intervention, reported in its
# own field as c(lower, upper). It is computed whether or not it covers the
# outcome goal, so it is available even when no grid intervention qualifies.
# lago_optimization() reports this interval as $est_outcome_ci.
cs$rec_int_ci

# rec_int need not be one of the grid interventions, and here it is not:
# its launch_duration is about 2.78 while the grid steps through whole
# days. It is never a row of cs either, which holds the 18 qualifying grid
# interventions and nothing else.
opt$rec_int
head(cs$cs)

get_recommended_interventions

Description

Internal function that calculates the LAGO recommended interventions based on an outcome goal and/or a power goal.

Usage

get_recommended_interventions(
  data,
  intervention_components_coeff,
  include_interaction_terms,
  main_components,
  intervention_components,
  all_center_lvl_effects,
  center_weights_for_outcome_goal,
  cost_list_of_vectors,
  intervention_lower_bounds,
  intervention_upper_bounds,
  outcome_goal,
  optimization_method,
  optimization_grid_search_step_size,
  center_cha_coeff_vec = 0,
  center_characteristics_optimization_values = 0,
  link = "identity",
  lower_outcome_goal = FALSE,
  prev_recommended_interventions,
  shrinkage_threshold,
  power_goal,
  power_goal_approach,
  num_centers_in_next_stage,
  patients_per_center_in_next_stage,
  outcome_name,
  icc = NULL,
  power_goal_cluster_id = NULL,
  aliased_coef_names = character(0)
)

Arguments

Value

List( est_rec_int = recommended interventions, rec_int_cost = associated cost of the recommended interventions, est_reachable_outcome = estimated outcome mean/probability for the intervention group in the next stage, shrinking_method_used = whether the shrinking method was applied, effective_outcome_goal = the outcome goal actually used for optimization, i.e. max(power-implied outcome, outcome_goal) )

Budget-constrained LAGO optimization

Description

Answers the reverse of the usual LAGO question. Instead of "what is the least costly intervention that reaches an outcome goal?" ([lago_optimization()]), 'lago_budget()' asks "given a fixed budget, what is the best outcome I can reach, and with which intervention?".

The best-outcome-within-budget intervention always lies on the same least-cost frontier that [lago_optimization()] traces out (for any target outcome, the cheapest way to reach it is what the optimizer already finds), so ‘lago_budget()' sweeps the outcome goal across the outcome’s range with [lago_sensitivity()], reads the recommended cost and estimated outcome at each goal, and returns the reachable goal whose recommended cost is highest without exceeding the budget (for 'outcome_goal_intention = "maximize"'; the lowest reachable outcome within budget for '"minimize"'). It does not touch the optimizer internals, so it inherits the same model, cost functions and bounds.

Usage

lago_budget(object = NULL, ..., budget, n_grid = 25L, quiet = TRUE)

Arguments

Details

The candidate outcome goals span the outcome's range: '(0, 1)' for a binary outcome, or the observed range of the outcome column (padded by half a span on each side) for a continuous one. Each goal is one [lago_optimization()] run with the confidence set off. A goal beyond the reachable range does not error: the optimizer's shrinking method returns a recommendation whose estimated outcome falls short of the goal, so such a goal is not counted as genuinely reached and does not become a candidate (only goals the recommendation actually delivers are considered). Among the reached goals whose recommended cost is at most 'budget', the one with the best estimated outcome is chosen (largest for '"maximize"', smallest for '"minimize"'). The grid is extended in the improving direction until goals stop being reached or affordable, and a refinement sweep is then run near the affordability boundary to tighten the estimate.

If no reachable goal is affordable (the budget is below the cost of even the cheapest reachable intervention), the result has 'feasible = FALSE' and 'NA' recommendation fields. If every reachable goal is affordable, the budget does not bind ('binding = FALSE') and the maximum reachable outcome is returned.

Value

An object of class '"lago_budget"', a list with:

budget

The supplied budget.

feasible

'TRUE' if at least one reachable intervention was affordable.

binding

'TRUE' if the budget constrained the choice: a strictly better outcome was reachable but cost more than the budget. 'FALSE' if the best reachable outcome was already affordable.

rec_int

The recommended intervention (one value per component), or 'NA' when not 'feasible'.

rec_int_cost

Its cost (at most 'budget'), or 'NA'.

est_outcome

Its estimated outcome, or 'NA'.

outcome_goal

The outcome goal that produced the recommendation (equal to 'est_outcome' up to the grid resolution), or 'NA'.

frontier

A 'data.frame' of the reachable goals searched (the cost/outcome tradeoff curve): 'outcome_goal', 'rec_int_cost', 'est_outcome', 'affordable', 'status'.

component_names

The intervention component names.

intention

The 'outcome_goal_intention' used.

See Also

[lago_optimization()], [lago_sensitivity()]

Other LAGO functions: get_confidence_set(), lago_optimization(), lago_report(), lago_sensitivity(), visualize_cost()

Examples

# How good an outcome can a budget of 100 buy? (mtcars, continuous.)
b <- lago_budget(
  data = mtcars,
  outcome_name = "mpg",
  outcome_type = "continuous",
  glm_family = "gaussian",
  link = "identity",
  intervention_components = c("gear", "qsec"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 350),
  cost_list_of_vectors = list(c(0, 4), c(4, 6)),
  outcome_goal_intention = "maximize",
  budget = 100
)
b
plot(b)

# Reuse a fitted result's call instead of retyping it.
opt <- lago_optimization(
  data = mtcars, outcome_name = "mpg", outcome_type = "continuous",
  glm_family = "gaussian", link = "identity",
  intervention_components = c("gear", "qsec"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 350),
  cost_list_of_vectors = list(c(0, 4), c(4, 6)),
  outcome_goal = 30, outcome_goal_intention = "maximize",
  include_confidence_set = FALSE, quiet = TRUE
)
lago_budget(opt, budget = 100)

Run a LAGO optimization

Description

Fits the outcome model, calculates the recommended interventions based on an outcome goal and/or a power goal, calculates the confidence set for the recommended interventions, and prints the output. This is the main entry point of the package.

Categorical predictors in the outcome model always use treatment contrasts. This includes factors, ordered factors, character columns and logical columns. This coding overrides global contrast options and contrast attributes supplied on the input columns, without changing the input data or global options. The reference is the first retained factor level, the first sorted character value, or FALSE for a logical column. Ordered covariates keep their level order but do not use polynomial contrasts. Numeric predictors keep their values.

Usage

lago_optimization(
  data,
  input_data_structure = "individual_level",
  outcome_name,
  outcome_type,
  intervention_components,
  intervention_lower_bounds,
  intervention_upper_bounds,
  outcome_goal = NULL,
  outcome_goal_intention = "maximize",
  power_goal = NULL,
  power_goal_approach = "unconditional",
  num_centers_in_next_stage = NULL,
  patients_per_center_in_next_stage = NULL,
  icc = NULL,
  power_goal_cluster_id = NULL,
  unit_costs = NULL,
  default_cost_fxn_type = "cubic",
  cost_list_of_vectors = NULL,
  glm_family = "default",
  link = "default",
  optimization_method = "numerical",
  confidence_set_alpha = 0.05,
  weights = NULL,
  center_characteristics = NULL,
  center_characteristics_optimization_values = NULL,
  main_components = NULL,
  time_effect_optimization_value = NULL,
  additional_covariates = NULL,
  center_weights_for_outcome_goal = NULL,
  optimization_grid_search_step_size = NULL,
  confidence_set_grid_step_size = NULL,
  include_confidence_set = TRUE,
  include_center_effects = FALSE,
  center_effects_optimization_values = NULL,
  include_time_effects = FALSE,
  include_interaction_terms = FALSE,
  prev_recommended_interventions = NULL,
  shrinkage_threshold = 0.25,
  quiet = FALSE
)

Arguments

Value

List( recommended interventions, associated cost for the interventions, estimated outcome mean/probability for the intervention group, 95% confidence set percentage, 95% confidence set, overall intervention test results (test_results), a list with the test statistic and p-value; NULL unless a valid 'group' column is supplied. The confidence set fields are only present when include_confidence_set = TRUE.) The result also carries its own call arguments in the attribute '"lago_call_args"' (not a '$'-accessible field), so it can be passed directly to [lago_sensitivity()] to sweep one input without retyping the call.

See Also

[get_confidence_set()], [visualize_cost()], [lago_report()]

Other LAGO functions: get_confidence_set(), lago_budget(), lago_report(), lago_sensitivity(), visualize_cost()

Examples

# Basic case showing how to carry out the optimization with
# a built-in data set. The confidence set is skipped here to keep this
# example fast; the \donttest examples below show a full run with one.
lago_optimization(
  data = infert,
  outcome_name = "case",
  outcome_type = "binary",
  glm_family = "binomial",
  intervention_components = c("age", "parity"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(50, 10),
  cost_list_of_vectors = list(c(0, 4), c(0, 1)),
  outcome_goal = 0.5,
  outcome_goal_intention = "maximize",
  include_confidence_set = FALSE
)

# Fuller examples, including the confidence-set grid search, which is
# inherently slower. Wrapped in \donttest{} so they are still checkable
# but do not run on every automated check.

lago_optimization(
  data = BB_data,
  outcome_name = "pp3_oxytocin_mother",
  outcome_type = "binary",
  glm_family = "binomial",
  intervention_components = c("coaching_updt", "launch_duration"),
  center_characteristics = c("birth_volume_100"),
  center_characteristics_optimization_values = 1.75,
  intervention_lower_bounds = c(1, 1),
  intervention_upper_bounds = c(40, 5),
  cost_list_of_vectors = list(c(0, 1700), c(0, 8000)),
  outcome_goal = 0.85,
  outcome_goal_intention = "maximize",
  confidence_set_grid_step_size = c(1, 1)
)

lago_optimization(
  data = BB_proportions,
  outcome_name = "EBP_proportions",
  outcome_type = "continuous",
  glm_family = "quasibinomial",
  link = "logit",
  intervention_components = c("coaching_updt", "launch_duration"),
  center_characteristics = c("birth_volume_100"),
  center_characteristics_optimization_values = 1.75,
  intervention_lower_bounds = c(1, 1),
  intervention_upper_bounds = c(40, 5),
  cost_list_of_vectors = list(c(0, 1700), c(0, 8000)),
  outcome_goal = 0.85,
  outcome_goal_intention = "maximize",
  confidence_set_grid_step_size = c(1, 1)
)

Generate an HTML report for a LAGO optimization result

Description

Renders a self-contained, interactive HTML report for the object returned by [lago_optimization()]. The report knits a bundled parameterized R Markdown template and lays out the same sections, in the same order and with the same labels, as the console methods ([print.lago()] / [summary.lago()]): the recommended intervention, its cost, the estimated outcome (with its 95% CI) and goal, the power goal (when present), the confidence set (size, cost IQR, and first rows), the overall intervention-effect test (when present), and the fitted outcome-model coefficient table. A 'sessionInfo()' footer records the environment the report was produced in.

No new statistics are computed; every value is taken verbatim from an existing field on 'x' and formatted exactly as the console output formats it.

Usage

lago_report(
  x,
  output_file = NULL,
  title = "LAGO optimization report",
  open = FALSE,
  ...
)

Arguments

Details

The report is interactive and drawn entirely client-side with the bundled D3 v7 library ('inst/js/d3.v7.min.js') plus 'inst/js/lago-report.js', both inlined into the HTML so the output is a single self-contained, offline file with no external asset references (no CDN, no Shiny, no additional widget frameworks). It adds two interactive views:

• an interactive confidence-set plot: a hover-enabled scatter for a two-component intervention (with the recommended intervention highlighted) or a one-dimensional strip for a single component. For 3+ components, or when the interactive view is not applicable, it falls back to the static [plot.lago()] figure; when no confidence set is available the section is omitted.

• interactive cost curves: for each intervention component, its total-cost curve and marginal (per-unit) cost curve, each with a hover read-out, drawn from the result's cost functions and bounds.

Rendering requires the rmarkdown, knitr, and jsonlite packages (all listed under Suggests). If they are not installed, an informative error is raised.

Value

The path to the rendered HTML file, invisibly.

See Also

[lago_optimization()]

Other LAGO functions: get_confidence_set(), lago_budget(), lago_optimization(), lago_sensitivity(), visualize_cost()

Examples

# lago_report() renders an HTML file with rmarkdown, so it is wrapped in
# \dontrun: it writes to disk and invokes pandoc, and running a document
# render inside an in-process documentation build (e.g. pkgdown) can deadlock.
## Not run: 
result <- lago_optimization(
  data = BB_data,
  outcome_name = "pp3_oxytocin_mother",
  outcome_type = "binary",
  glm_family = "binomial",
  intervention_components = c("coaching_updt", "launch_duration"),
  center_characteristics = c("birth_volume_100"),
  center_characteristics_optimization_values = 1.75,
  intervention_lower_bounds = c(1, 1),
  intervention_upper_bounds = c(40, 5),
  cost_list_of_vectors = list(c(0, 1700), c(0, 8000)),
  outcome_goal = 0.85,
  outcome_goal_intention = "maximize",
  confidence_set_grid_step_size = c(1, 1),
  quiet = TRUE
)
report_path <- lago_report(result)

## End(Not run)

Sensitivity analysis for a LAGO recommendation

Description

Trial designers often are unsure about some of the inputs to [lago_optimization()], chiefly the outcome goal and the assumed intervention costs. 'lago_sensitivity()' answers "how much does the recommendation move if that input is different?" by re-running [lago_optimization()] across a sweep of one input and reporting how the recommended intervention, its cost, and the estimated outcome change. This turns a single point recommendation into a robustness picture: a stringency curve for the outcome goal, or a straight line for a uniform cost rescaling.

The confidence set is the slow part of [lago_optimization()] and is not needed to see how a recommendation moves, so every run is forced to 'include_confidence_set = FALSE' for speed. A single run failing does not abort the sweep: its outputs are recorded as 'NA' and a single warning names the failed values afterwards.

Usage

lago_sensitivity(object = NULL, ..., parameter, values, quiet = TRUE)

Arguments

Details

Each run builds the modified argument list from '...', forces 'include_confidence_set = FALSE', sets 'quiet = quiet', and calls [lago_optimization()] inside 'tryCatch()'. A run that errors contributes a row of 'NA' outputs with a non-'"ok"' status instead of stopping the sweep.

Value

An object of class '"lago_sensitivity"', which is a 'data.frame' with one row per element of 'values' and columns:

value

The swept value for that run.

<component>

One numeric column per intervention component, named by the component, holding its recommended value for that run.

rec_int_cost

The cost of the recommended intervention.

est_outcome_goal

The estimated outcome at the recommendation.

status

'"ok"' for a successful run, otherwise '"error"'.

The object carries attributes 'parameter' (the swept string), 'component_names' (the component column names), 'baseline' (the full [lago_optimization()] result at the baseline value, i.e. multiplier 1 for '"cost_multiplier"' or the value supplied in '...' for a named parameter, or 'NULL' if not present), and, when any run failed, 'error_messages' (the error text named by the failed values).

See Also

[lago_optimization()]

Other LAGO functions: get_confidence_set(), lago_budget(), lago_optimization(), lago_report(), visualize_cost()

Examples

# Recommended flow: fit once, then sweep the fitted result. Passing the
# `lago` result reuses its call, so there is no need to retype the
# arguments. Each run is a separate optimization, so this is wrapped in
# \donttest to keep automated checks fast; the confidence set is off
# internally so the sweep still runs quickly.
opt <- lago_optimization(
  data = mtcars,
  outcome_name = "mpg",
  outcome_type = "continuous",
  glm_family = "gaussian",
  link = "identity",
  intervention_components = c("gear", "qsec"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 350),
  cost_list_of_vectors = list(c(0, 4), c(4, 6)),
  outcome_goal = 30,
  outcome_goal_intention = "maximize",
  include_confidence_set = FALSE,
  quiet = TRUE
)
sens <- lago_sensitivity(
  opt,
  parameter = "outcome_goal",
  values = c(30, 35, 40)
)
sens
plot(sens)

# The same sweep spelled out directly (no fitted object). This is the
# equivalent long form and gives the same result.
sens2 <- lago_sensitivity(
  data = mtcars,
  outcome_name = "mpg",
  outcome_type = "continuous",
  glm_family = "gaussian",
  link = "identity",
  intervention_components = c("gear", "qsec"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 350),
  cost_list_of_vectors = list(c(0, 4), c(4, 6)),
  outcome_goal_intention = "maximize",
  parameter = "outcome_goal",
  values = c(30, 35, 40)
)

# How sensitive is it to the assumed costs? A uniform rescaling never changes
# which intervention is cheapest, so the recommendation is unchanged and the
# cost scales linearly with the multiplier. `...` overrides on top of the
# fitted object are used here to switch the swept parameter.
cost_sens <- lago_sensitivity(
  opt,
  parameter = "cost_multiplier",
  values = c(0.8, 1, 1.2)
)
cost_sens

PULESA hypertension-care data (main model)

Description

Clinic-level data from the PULESA study, a cluster-randomized trial of a multi-component intervention to improve hypertension care. Each row is one clinic in one time period. This is the version used to fit the "main" LAGO outcome model, whose intervention components are access to blood-pressure machines, access to medicines, delivery mode, hypertension training, performance improvement, and remote monitoring.

Usage

main_pulesa_data

Format

A data frame with 192 rows and 15 variables:

Clinic

Clinic (cluster) identifier

Period

Study time period

AccessBPMachines

Intervention component: access to blood-pressure machines

AccessMedicines

Intervention component: access to medicines

DeliveryA

Intervention component: care delivery mode A

DeliveryB

Intervention component: care delivery mode B

HypertensionTraining

Intervention component: hypertension training

MI_DeliveryB

Interaction term involving delivery mode B

MI_PerformanceImprovement

Interaction term involving performance improvement

MI_RemoteMonitoring

Interaction term involving remote monitoring

PerformanceImprovement

Intervention component: performance improvement

Proportions

Outcome: proportion of successes at the clinic-period

RemoteMonitoring

Intervention component: remote monitoring

Success

Outcome: number of successes at the clinic-period

Total_visit

Number of visits at the clinic-period

Examples

data(main_pulesa_data)
head(main_pulesa_data)

PULESA hypertension-care data (new model)

Description

Clinic-level data from the PULESA study, a cluster-randomized trial of a multi-component intervention to improve hypertension care. Each row is one clinic in one time period. This is the version used to fit the "new" LAGO outcome model, which uses the same clinics and periods as main_pulesa_data but a different specification of the intervention (the W1–W8 components and their interaction terms).

Usage

new_pulesa_data

Format

A data frame with 192 rows and 22 variables:

Clinic

Clinic (cluster) identifier

Period

Study time period

AccessBPMachines

Intervention component: access to blood-pressure machines

AccessMedicines

Intervention component: access to medicines

DeliveryA

Intervention component: care delivery mode A

DeliveryB

Intervention component: care delivery mode B

HypertensionTraining

Intervention component: hypertension training

MI_W5

Interaction term involving component W5

MI_W7

Interaction term involving component W7

MI_W8

Interaction term involving component W8

PerformanceImprovement

Intervention component: performance improvement

RemoteMonitoring

Intervention component: remote monitoring

Success

Outcome: number of successes at the clinic-period

Total_visit

Number of visits at the clinic-period

W1

Intervention component W1

W2

Intervention component W2

W3

Intervention component W3

W4

Intervention component W4

W5

Intervention component W5

W6

Intervention component W6

W7

Intervention component W7

W8

Intervention component W8

Examples

data(new_pulesa_data)
head(new_pulesa_data)

Plot a LAGO optimization result

Description

Visualizes the 95% confidence set. For a two-component intervention it plots the grid points in the confidence set with the recommended intervention highlighted; for a single component it plots the confidence interval bounds against the dose. A non-empty confidence set is required. 'result$cs' can be NULL even with 'include_confidence_set = TRUE' (its default), when no confidence set was found for the outcome goal or the shrinking method was used, and then plot() returns invisibly with a message rather than erroring.

Usage

## S3 method for class 'lago'
plot(x, ...)

Arguments

Value

A ggplot object (invisibly) when a plot is produced, otherwise 'NULL' invisibly.

Examples

# A plot needs a non-empty confidence set: plot() returns invisibly with a
# message when result$cs is NULL, which can happen even with
# include_confidence_set = TRUE (its default) if no confidence set was found
# for the outcome goal, or if the shrinking method was used.
# The lower bounds start at 1 while the data also contains 0s, so the
# optimizer warns about that; the warning is expected here.
result <- lago_optimization(
  data = BB_data,
  outcome_name = "pp3_oxytocin_mother",
  outcome_type = "binary",
  glm_family = "binomial",
  intervention_components = c("coaching_updt", "launch_duration"),
  center_characteristics = c("birth_volume_100"),
  center_characteristics_optimization_values = 1.75,
  intervention_lower_bounds = c(1, 1),
  intervention_upper_bounds = c(40, 5),
  cost_list_of_vectors = list(c(0, 1700), c(0, 8000)),
  outcome_goal = 0.85,
  outcome_goal_intention = "maximize",
  include_confidence_set = TRUE,
  confidence_set_grid_step_size = c(1, 1),
  quiet = TRUE
)

# Two components: the confidence set grid with the recommended
# intervention marked.
plot(result)

Plot a budget-constrained LAGO result

Description

Draws the cost/outcome frontier the search traced out (estimated outcome against recommended cost across the swept goals), with a vertical line at the budget and the chosen recommendation highlighted.

Usage

## S3 method for class 'lago_budget'
plot(x, ...)

Arguments

Value

A [ggplot2][ggplot2::ggplot] object, or 'NULL' invisibly when there is nothing reachable to plot.

Examples

b <- lago_budget(
  data = mtcars, outcome_name = "mpg", outcome_type = "continuous",
  glm_family = "gaussian", link = "identity",
  intervention_components = c("gear", "qsec"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 350),
  cost_list_of_vectors = list(c(0, 4), c(4, 6)),
  outcome_goal_intention = "maximize", budget = 100
)
plot(b)

Plot a LAGO sensitivity analysis

Description

Draws the sensitivity curve with [ggplot2][ggplot2::ggplot]. By default ('show = "cost"') it plots the recommended cost against the swept value as a line with points: for an '"outcome_goal"' sweep this is the cost-of-stringency curve, and for a '"cost_multiplier"' sweep it is a straight line. With 'show = "components"' it instead plots the recommended value of each intervention component against the swept value, one coloured line per component. Rows with 'NA' outputs are dropped with a message.

Usage

## S3 method for class 'lago_sensitivity'
plot(x, show = c("cost", "components"), ...)

Arguments

Value

A [ggplot2][ggplot2::ggplot] object, or 'NULL' invisibly when 'show = "components"' and no components are recorded.

Examples

sens <- lago_sensitivity(
  data = mtcars, outcome_name = "mpg", outcome_type = "continuous",
  glm_family = "gaussian", link = "identity",
  intervention_components = c("gear", "qsec"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 350),
  cost_list_of_vectors = list(c(0, 4), c(4, 6)),
  outcome_goal_intention = "maximize",
  parameter = "outcome_goal", values = c(30, 35, 40)
)
plot(sens)
plot(sens, show = "components")

Print a LAGO optimization result

Description

Full console display of the object returned by [lago_optimization()], rendered with boxed, colour-accented [cli][cli::cli] sections: an inputs recap (data dimensions, outcome, intervention components, model family/link and fixed effects, goals, costs and bounds), the fitted outcome-model coefficient table, the overall intervention-effect test, the recommended intervention with its cost and the estimated outcome (and its 95% confidence interval), and the confidence set (size, cost IQR, and first rows). Everything is shown on the console so results can be read without further calls. [summary.lago()] renders the same output.

Usage

## S3 method for class 'lago'
print(x, ...)

Arguments

Value

'x', invisibly.

Examples

# lago_optimization() already prints the result, so quiet = TRUE avoids
# rendering it twice here. The lower bounds start at 1 while the data also
# contains 0s, so the optimizer warns about that; the warning is expected.
result <- lago_optimization(
  data = BB_data,
  outcome_name = "pp3_oxytocin_mother",
  outcome_type = "binary",
  glm_family = "binomial",
  intervention_components = c("coaching_updt", "launch_duration"),
  center_characteristics = c("birth_volume_100"),
  center_characteristics_optimization_values = 1.75,
  intervention_lower_bounds = c(1, 1),
  intervention_upper_bounds = c(40, 5),
  cost_list_of_vectors = list(c(0, 1700), c(0, 8000)),
  outcome_goal = 0.85,
  outcome_goal_intention = "maximize",
  include_confidence_set = TRUE,
  confidence_set_grid_step_size = c(1, 1),
  quiet = TRUE
)

print(result)

Print a budget-constrained LAGO result

Description

Prints a short header with the budget and whether it binds, then the recommended intervention, its cost and estimated outcome (or a note that no intervention fits the budget).

Usage

## S3 method for class 'lago_budget'
print(x, ...)

Arguments

Value

'x', invisibly.

Examples

b <- lago_budget(
  data = mtcars, outcome_name = "mpg", outcome_type = "continuous",
  glm_family = "gaussian", link = "identity",
  intervention_components = c("gear", "qsec"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 350),
  cost_list_of_vectors = list(c(0, 4), c(4, 6)),
  outcome_goal_intention = "maximize", budget = 100
)
print(b)

Print a LAGO sensitivity analysis

Description

Prints a short header naming the varied parameter, the number of runs and how many failed, then the sensitivity 'data.frame', then a one-line summary of how 'rec_int_cost' ranges over the sweep.

Usage

## S3 method for class 'lago_sensitivity'
print(x, ...)

Arguments

Value

'x', invisibly.

Examples

sens <- lago_sensitivity(
  data = mtcars, outcome_name = "mpg", outcome_type = "continuous",
  glm_family = "gaussian", link = "identity",
  intervention_components = c("gear", "qsec"),
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 350),
  cost_list_of_vectors = list(c(0, 4), c(4, 6)),
  outcome_goal_intention = "maximize",
  parameter = "outcome_goal", values = c(30, 35, 40)
)
print(sens)

select_restart_within_bounds

Description

Internal function that picks the recommended intervention out of the points a multi-start numerical optimizer converged to, and returns it together with the cost of the point being recommended.

Usage

select_restart_within_bounds(
  restart_points,
  costs,
  lower_bounds,
  upper_bounds,
  cost_fun
)

Arguments

Details

The filter, the fallback, the choice, the projection and the cost recomputation are one decision and are deliberately kept together: each step's correctness depends on the one before it.

costs holds the cost each restart converged to, so the best restart is the cheapest one. Every restart satisfies the outcome constraint, which NlcOptim::solnl() enforces through confun, so cost is the only thing to choose on among the ones that are actually implementable.

solnl() treats the box as a soft constraint and will step a little outside it to buy a lower objective, so the cheapest restart is systematically the one furthest outside the bounds: selecting on cost alone selects for the violation. Restarts that left the box are therefore dropped before the comparison. If every restart left it they are all kept, so a recommendation is still returned, and the survivor is brought back onto the box.

The chosen restart can still sit a solver tolerance outside the box, when every restart did. A recommendation has to be implementable, so it is projected onto the bounds and its cost recomputed at the value actually being recommended rather than reported from the point the solver stopped at. The recomputed cost can be either side of the one the solver reported, since projection moves a component up to a lower bound or down to an upper one, so the solver's cost is not a bound on the recommendation's cost in either direction.

Value

A list with: - int_components: the chosen intervention, projected onto the bounds. - rec_int_cost: cost_fun() evaluated at int_components.

Summarize a LAGO optimization result

Description

Renders the same full console display as [print.lago()]: the inputs recap, outcome-model coefficient table, overall intervention-effect test, recommended intervention (with cost and the estimated-outcome CI), and the confidence set. Provided so 'summary()' works as expected on a "lago" object.

Usage

## S3 method for class 'lago'
summary(object, ...)

Arguments

Value

'object', invisibly.

Examples

# summary() currently renders exactly the same output as print(). The lower
# bounds start at 1 while the data also contains 0s, so the optimizer warns
# about that; the warning is expected here.
result <- lago_optimization(
  data = BB_data,
  outcome_name = "pp3_oxytocin_mother",
  outcome_type = "binary",
  glm_family = "binomial",
  intervention_components = c("coaching_updt", "launch_duration"),
  center_characteristics = c("birth_volume_100"),
  center_characteristics_optimization_values = 1.75,
  intervention_lower_bounds = c(1, 1),
  intervention_upper_bounds = c(40, 5),
  cost_list_of_vectors = list(c(0, 1700), c(0, 8000)),
  outcome_goal = 0.85,
  outcome_goal_intention = "maximize",
  include_confidence_set = TRUE,
  confidence_set_grid_step_size = c(1, 1),
  quiet = TRUE
)

summary(result)

Visualize and choose intervention cost functions

Description

Visualize the cost functions for the intervention components. This function creates a Shiny app that allows the user to adjust the coefficients of the cost functions for each intervention component and visualize the resulting total cost function and its derivative. The initial coefficients are calculated based on the unit costs, the cost function type (linear or cubic), and the lower and upper bounds. A "Cost function form" toggle at the top switches all components between the linear (2 coefficients) and cubic (a degree-4 total cost, 5 coefficients) forms, resetting each to that form's initial coefficients. The user can adjust the coefficients using sliders and reset them to their initial values. Each slider has a default range scaled to its coefficient's magnitude (derived from the unit costs and bounds), and the user can set a custom range for any slider using its "Range min" / "Range max" inputs. The total cost curve can also be reshaped directly: it carries a draggable handle at each of several points along the curve, and dragging one refits the cost function through the new set of points and updates the sliders. The app also displays the current coefficient vector for each component. The user can copy the final coefficient list for use in the optimization function lago_optimization().

Usage

visualize_cost(
  component_names,
  unit_costs,
  default_cost_fxn_type,
  intervention_lower_bounds,
  intervention_upper_bounds
)

Arguments

Details

When the app is closed with the "Return list to R & close" button, the coefficient list is also stored in the lago_cost_list option (overwriting any existing value) and a message reports this, so the list is available even when the app was launched with a bare visualize_cost(...) call rather than cost_list <- visualize_cost(...). Retrieve it with getOption("lago_cost_list"). Closing the browser tab instead of using the button does not save the list.

Value

Invisibly, the cost-function coefficient list (a list of numeric vectors, one per intervention component) as it stood when the app was closed, suitable for passing to lago_optimization(cost_list_of_vectors = ...). The same list can be copied from within the app.

See Also

[lago_optimization()]

Other LAGO functions: get_confidence_set(), lago_budget(), lago_optimization(), lago_report(), lago_sensitivity()

Examples

## Not run: 
visualize_cost(
  component_names = c("Component 1", "Component 2"),
  unit_costs = c(0.5, 1),
  default_cost_fxn_type = "linear",
  intervention_lower_bounds = c(0, 0),
  intervention_upper_bounds = c(10, 10)
)

## End(Not run)