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
)
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
data |
A data.frame. The input dataset containing the variables of
interest.
|
input_data_structure |
A character string. The data structure of the
input data. Must be either "individual_level" or "center_level".
Default value without user specification: "individual_level".
|
outcome_name |
A character string. The name of the column in the dataset
that represents the outcome of interest.
|
outcome_type |
A character string. Specifies the type of the outcome.
Must be either "continuous" for continuous outcomes or "binary" for binary
outcomes.
|
intervention_components |
A character vector. The names of the columns
in the dataset that represent the intervention components.
For example: c("component1", "component2").
|
intervention_lower_bounds |
A numeric vector. Specifies the lower bounds
of the intervention components.
For example: for a two-component intervention package, lower bounds could be
c(0,0).
|
intervention_upper_bounds |
A numeric vector. Specifies the upper bounds
of the intervention components.
For example: for a two-component intervention package, upper bounds could be
c(10,20).
|
outcome_goal |
A numeric value. Specifies the outcome goal, a desired
probability or mean value.
Default value without user specification: NULL.
At least one of outcome_goal or power_goal must be provided. If only a
power goal is provided, the optimization target is the outcome level needed
to achieve the power goal. If both are provided, the effective outcome goal
is the higher of the two (see power_goal).
|
outcome_goal_intention |
A character string. Specifies the direction in
which the interventions are expected to move the outcome, relative to the
outcome without any intervention. Must be either "maximize" or "minimize".
Set it to "maximize" when a larger outcome is desired and the interventions
are meant to increase the outcome up to the outcome goal (for example,
increasing the probability that a treatment is administered). Set it to
"minimize" when a smaller outcome is desired and the interventions are meant
to decrease the outcome down to the outcome goal (for example, reducing a
mortality rate). This argument only controls the optimization direction; the
outcome goal itself is always given as the target outcome value, regardless
of the intention.
Default value without user specification: "maximize".
Note: "minimize" cannot be combined with a power goal, because achieving a
power goal requires increasing the outcome.
|
power_goal |
A numeric value. Specifies the power goal, a desired power
value (between 0 and 1). Only supported for binary outcomes, and requires a
'group' column (values "treatment"/"control", with both arms present and at
least one observed outcome in each) along with
num_centers_in_next_stage and patients_per_center_in_next_stage.
At least one of outcome_goal or power_goal must be provided. The power goal
is converted into the outcome level needed to achieve that power; the
effective outcome goal used for optimization is
max(power-implied outcome, outcome_goal). When only a power goal is
provided, the power-implied outcome is used directly.
Default value without user specification: NULL.
|
power_goal_approach |
A character string. Specifies the approach to
achieve the power goal. Must be either "unconditional" or "conditional".
Default value without user specification: "unconditional".
|
num_centers_in_next_stage |
A numeric value. Specifies the number of
total centers (treatment + control) in the next stage of the trial.
Default value without user specification: NULL.
|
patients_per_center_in_next_stage |
A numeric value. Specifies
the number of patients per center in the next stage of the trial.
Default value without user specification: NULL.
|
icc |
A numeric value in [0, 1), or a length-2 numeric vector
c(control, treatment). Specifies the intra-cluster correlation used to
inflate the variance of the power-calculation test statistic by a design
effect, so that the power goal accounts for within-center clustering.
Only used when a power_goal is provided (ignored otherwise). When NULL, the
power calculation assumes independent observations (the original behavior);
icc = 0 gives the identical result. A larger icc raises the outcome level
needed to meet the power goal, so it recommends a stronger intervention. A
non-zero icc requires power_goal_cluster_id.
Default value without user specification: NULL.
|
power_goal_cluster_id |
A character string. The name of a column in the
data identifying the stage-1 centers (clusters), used to compute the stage-1
design effect for the power calculation. Required when icc is non-zero. The
stage-1 cluster size is the variance-appropriate (size-biased) mean
sum(m_i^2) / sum(m_i) over that arm's centers, where m_i counts the center's
rows with an observed outcome, and each arm must have at least two centers
with an observed outcome.
Default value without user specification: NULL.
|
unit_costs |
A numeric vector. Specifies the unit costs for each
intervention component.
Default value without user specification: NULL.
|
default_cost_fxn_type |
A character string. Specifies the shape of the
default cost function. Must be either "linear" or "cubic".
Default value without user specification: "cubic".
|
cost_list_of_vectors |
A list of numeric vectors. Specifies the cost
functions for each intervention component. Each numeric vector in the list
contains coefficients of the cost function for one intervention component.
For example:
list(c(1, 2, 3, 4), c(4, 6), c(5, 4, 3)) represents:
- First component: cost = 1 + 2x_1 + 3x_1^2 + 4x_1^3
- Second component: cost = 4 + 6x_2
- Third component: cost = 5 + 4x_3 + 3x_3^2
list(c(0, 2), c(0, 6), c(0, 4)) represents:
- First component: cost = 2x_1
- Second component: cost = 6x_2
- Third component: cost = 4x_3
Default value without user specification: NULL.
Please note that either the unit_costs or cost_list_of_vectors must be
specified. If both are specified, the cost_list_of_vectors will be used.
|
glm_family |
A character string. The family of the glm() outcome model.
Default value without user specification:
"gaussian" for continuous outcomes, "binomial" for binary outcomes.
|
link |
A character string. The link function of the glm() outcome model.
Must be either "logit" or "identity": those are the links whose inverse the
estimated outcome and the confidence set are computed with, so they are the
only ones that can be reported on the outcome scale the goal is stated on.
Default value without user specification:
"identity" for continuous outcomes, "logit" for binary outcomes.
|
optimization_method |
A character string. Specifies the method used for
LAGO optimization. Must be either "numerical" or "grid_search".
Default value without user specification: "numerical".
- Use "grid_search" if you want to exhaustively test every possible
intervention package compositions in LAGO optimization.
- Use "numerical" if you want to use gradient-based technique in LAGO
optimization.
Note: if optimization_grid_search_step_size is provided while this is
"numerical", it is automatically switched to "grid_search" (with a message).
|
confidence_set_alpha |
A numeric value. The type I error considered in
the confidence set calculations.
Default value without user specification: 0.05.
|
weights |
A numeric vector. The weights argument of the glm()
outcome model. Continuous confidence covariance uses the actual fitted
prior weights as relative observation weights, with zero weights excluded
from covariance contributions and the identity residual degrees of freedom.
See get_confidence_set() for the covariance formulas and family limits.
A data column named weights does not replace this argument.
|
center_characteristics |
A character vector. The names of the columns in
the dataset that represent the center characteristics.
Note, include_center_effects and center_characteristics cannot be used
together at the same time.
For example: c("characteristic1")
|
center_characteristics_optimization_values |
A numeric vector. The
fixed values of the center characteristics at which the recommended
intervention is computed. Because the outcome model can depend on center
characteristics, the recommendation is specific to a center with these
characteristic values, i.e. the optimization answers "what is the optimal
intervention for a center whose characteristics equal these values?". Must
be provided when center_characteristics is used, must be numeric, and must
have the same length and order as center_characteristics.
For a categorical characteristic with two levels, use 0 for the reference
level and 1 for the other level. For a logical characteristic, these values
select FALSE and TRUE. Categorical characteristics with more than two levels
are not supported. Recode them as separate numeric indicator columns.
For example, with center_characteristics = c("birth_volume_100"), setting
center_characteristics_optimization_values = c(1.75) computes the
recommended intervention for a center with birth_volume_100 = 1.75.
|
main_components |
A character vector. Specifies the main intervention
components in the presence of interaction terms.
For example: c("component1", "component2").
|
time_effect_optimization_value |
A numeric value. The value of the time
effect that will be used for LAGO optimization.
|
additional_covariates |
A character vector. The names of the columns in
the dataset that represent additional covariates that need to be included
in the outcome model. This includes interaction terms or any other additional
covariates. For recommendations and confidence output, numeric covariates
are held at 0 and categorical covariates are held at their reference level.
Set a factor's level order before calling this function to choose its
reference level. Categorical additional covariates can have more than two
levels.
For example: c("component2xcomponent4").
|
center_weights_for_outcome_goal |
A numeric vector. Specifies the
weights that will be used for calculating recommended interventions that
satisfy the outcome goal for an (weighted) average center.
The weights need to sum up to 1, and must all be non-negative and finite.
A weight of 0 is allowed and excludes that center from the average. A center
with no row where every model variable and the row's glm weight
(center_sample_size for center level data) are observed is left out of the
fit, so its weight must be 0. The weights follow the order of the centers:
the levels of a factor column once unused levels are dropped (an explicit NA
level included), and the sorted values otherwise.
Default value without user specification:
For each center the model fitted, calculate what percentage its sample size
(all of its rows, or its center_sample_size for center level data) is of the
total over those centers, and use that percentage as the center's weight. A
center the model could not fit is left out, with a warning. For center level
data, a center with no center_sample_size at all is refused instead.
|
optimization_grid_search_step_size |
A numeric vector. Specifies the
step size of the grid search algorithm used in LAGO optimization. This
argument is only used by the "grid_search" method; if it is provided while
optimization_method is "numerical", optimization_method is automatically
switched to "grid_search" (with a message).
Default value without user specification:
1/20 of the range for each intervention component.
|
confidence_set_grid_step_size |
A numeric vector. Specifies the step
size of the grid search algorithm used in the confidence set calculation.
Default value without user specification:
1/20 of the range for each intervention component.
|
include_confidence_set |
A boolean. Specifies whether the confidence set
should be calculated along with the recommended interventions.
Default value without user specification: TRUE.
|
include_center_effects |
A boolean. Specifies whether the fixed effects
should be included in the outcome model. If set to TRUE, please make sure
that the input data has a 'center' column to identify the centers. An
ordered factor is converted to an unordered one, so each center gets its own
effect, and at least two centers need a row the outcome model can use.
Note, include_center_effects and center_characteristics cannot be used
together at the same time.
Default value without user specification: FALSE for individual level data,
TRUE for center level data.
|
center_effects_optimization_values |
A character string. The name of
the center of interest (one of the values of the 'center' column) that will
be used for center-specific LAGO optimization. This is only used when
include_center_effects is set to TRUE. If not specified, the LAGO
optimization will be carried out for a weighted average of the centers the
model fitted (see center_weights_for_outcome_goal). The
center must have a row where every model variable and the row's glm weight
(center_sample_size for center level data) are observed.
|
include_time_effects |
A boolean. Specifies whether the fixed time
effects should be included in the outcome model. If set to TRUE, please
make sure that the input data has a 'period' column to identify the time
periods. An ordered factor is converted to an unordered one, so each period
gets its own effect, and at least two periods need a row the outcome model
can use.
Default value without user specification: FALSE.
|
include_interaction_terms |
A boolean. Specifies whether there are
interaction terms in the intervention components. Please make sure the
interaction terms are included in "intervention_components", and they
follow the correct naming scheme: "component1:component3".
Default value without user specification: FALSE.
|
prev_recommended_interventions |
A numeric vector. The recommended
interventions from a previous stage of the LAGO optimization. If provided,
this will be used in the shrinking method (see Section 5.1 of the
Supplementary material of Nevo et al. (2021) for details).
|
shrinkage_threshold |
A numeric value. The threshold for the shrinkage
method to kick in. This threshold represents the proportion of the distance
between the estimated outcome without intervention, and the outcome goal. If
the maximum reachable outcome is less than this value, the shrinkage method
from Section 5.1 of the Supplementary Materials of Nevo et al. (2021)
will be applied. If the maximum reachable outcome is greater than this value,
then the maximum reachable outcome will be used as the outcome goal, and the
shrinkage method will not be used.
Default value without user specification: 0.25.
|
quiet |
A boolean. If TRUE, suppresses the progress messages, the paced
delays between them, and the final printed output, which speeds up the call
substantially (the default paced output adds about two seconds of artificial
delay). The returned value is identical either way. Genuine warnings about
the data or model fit are still shown. Useful for programmatic or repeated
calls (for example, simulations).
Default value without user specification: FALSE.
|
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)
)
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
)
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)
)