| Title: | Convex Optimal Experiment Design |
|---|---|
| Description: | Convex optimal experiment design across discrete candidate grids using open-source optimization solvers. Specifies and optimizes designs using an object-oriented interface (via 'R6') for linear models, generalized linear/additive models, nonlinear models, and random intercept linear mixed models. Optimization and augmentation of weighted, penalized and convex constrained approximate designs is supported using the Splitting Cone Solver (SCS). Optimal rounding to integer-valued designs is supported using point-exchange methods or mixed-integer programming with the 'HiGHS' solver. For details, see Chau et al. (2026) <doi:10.48550/arXiv.2610.14288>. |
| Authors: | Joris Chau [aut, cre, cph] |
| Maintainer: | Joris Chau <[email protected]> |
| License: | Apache License (>= 2.0) |
| Version: | 1.0.0 |
| Built: | 2026-11-19 13:42:01 UTC |
| Source: | https://github.com/cran/cvxoptdes |
This dataset reports 88 measurements from an experiment in which ethanol was burned in a single cylinder automobile test engine. The data originates from the SemiPar package, which is now archived.
ethanolethanol
A data.frame containing 88 measurements with columns:
numeric, concentration of nitric oxide (NO) and nitrogen dioxide (NO2) in engine exhaust, normalized by the work done by the engine
numeric, the compression ratio of the engine
numeric, the equivalence ratio at which the engine was run – a measure of the richness of the air/ethanol mix
data.frame
Brinkman, N.D. (1981). Ethanol fuel – a single-cylinder engine study of efficiency and exhaust emissions. SAE transactions Vol. 90, No 810345, 1410–1424.
Ruppert, D., Wand, M.P. and Carroll, R.J. (2003). Semiparametric Regression. Cambridge University Press.
ethanolethanol
This dataset reports the production of o-xylenyl adducts of Buckminster fullerenes. Three process conditions (temperature, reaction time and ratio of sultine to C60) are varied to maximize the mole fraction of the desired ' product.
fullerenesfullerenes
A data.frame containing 120 experiments with columns:
numeric, reaction time in flow reactor (min)
numeric, relative concentration of sultine to C60
numeric, temperature of the reaction (Celsius)
numeric, mole fraction of the desired product
data.frame
head(fullerenes)head(fullerenes)
An R6 class for managing penalized locally optimal experiment designs for generalized additive models. This class encapsulates the generalized additive model at a set of nominal parameter values, the discrete design grid, optimization of an approximate continuous design, augmentation of an existing design, and optimal rounding to exact integer designs.
R6-object of class gam_design if called with gam_design$new().
The following penalized optimization problem is solved by $optimize():
where,
is the vector of design weights.
is the cost assigned to each design weight with scaling/penalty parameter .
is a vector of fixed user weights.
is the information matrix depending only on the weights and , and the design matrix by default.
If a non-trivial distribution family is chosen, the information matrix also depends on the nominal parameter values ,
the chosen (exponential) distribution family and the link function .
is the chosen optimality criterion, generally a function of the information matrix.
By default, the error distribution family is Gaussian with identity link function . This implies that the information matrix
(conditional on the error variance) is independent of the model parameters and given by:
If is not Gaussian or Gaussian with a non-canonical link function , the information matrix is given by:
with weights depending on the parameter values . Here,
and , with is the cumulant function of the exponential family . See glm_design for the exact details.
Given a vector of initial design weights and associated contribution weight ,
the following augmented penalized optimization problem is solved by $augment():
using the augmented information matrix,
The $strata() method stratifies the design by requiring that individual strata
are represented proportionally with given weights , (). If stratification is applied,
the following optimization problem is solved by $optimize():
using the same notation as in the ‘Optimal design problem’ section above. This means that the total weight
assigned to the design points in stratum is equal to for each .
Similarly, if stratification is applied, $augment() solves the augmented optimization problem with stratification
constraints.
The $sparsify() method solves the penalized optimization problem with an extra sparseness penalty
in the objective to promote sparsity in the approximate design . See lm_design for the available penalty functions.
The optimality criteria supported by $optimize(), $augment() and $sparsify() are: D-,
A-, I-, G-, and alias-optimality, see lm_design for the definitions.
lm_design -> glm_design -> gam_design
formulaa GAM model defined as a one-sided formula.
thetaa named vector or list of nominal parameter values at which the information matrix is evaluated.
Only used if $family is not gaussian(link = "identity") (the default).
familya description of the model distribution family and link function. See family for details of family functions.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
costan optional numeric vector containing costs associated to each design point (row) in data.
design_weightsa numeric vector with optimal design weights populated after optimization with $optimize(), $augment(), or $sparsify().
The attribute criterion lists the used design criterion and the achieved optimal criterion value.
strataa list with elements strata and proportions imposing a partition of the design points into individual (disjoint) strata
with given weight proportions.
alphathe cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available.
lambdathe ridge penalty added to the diagonal of the information matrix in the optimization problem. The ridge penalty is not used
upperthe design weight upper limit. The default is 1, corresponding to no upper limit constraint on the design weights.
Xthe design matrix obtained via mgcv::gam(formula, data = data, fit = FALSE, ...) given the design points in data and the model formula.
gam_design$new()Constructor. Initializes the experimental design to optimize with a linear model formula, discrete design grid, and optionally a distribution family with link function (and nominal set of parameter values).
gam_design$new( formula, data, theta = NULL, family = NULL, weights = NULL, cost = NULL, contrasts = NULL, alpha = 1, lambda = 0, upper = 1, ... )
formuladataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
thetaa named or unnamed vector or list of nominal parameter values at which the information matrix is evaluated.
Only needed if $family is not NULL.
familya family function describing the error distribution and link function in the model. Defaults to the gaussian
family with "identity" link function.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
Also accepts a one-sided formula made up of column names present in data. If NULL,
the unweighted optimal design problem is solved.
costan optional numeric vector containing costs associated to each design point (row) in data.
Also accepts a one-sided formula made up of column names present in data. If NULL,
the standard (non-penalized) optimal design problem is solved.
contrastsoptional contrasts used when evaluating the linear model formula.
alphanumeric value, cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available. The default is 1.
lambdanumeric value, ridge penalty added to the diagonal of the information matrix in the penalized optimization problem. The default is 0.
uppernumeric value in (0, 1], design weight upper limit. The default is 1, corresponding to no constraint on the design weights.
...any additional arguments passed to mgcv::gam(formula, data = data, fit = FALSE, ...) to evaluate the design matrix.
gam_design R6-object
gam_design$update()Updates the fields of an existing object.
Inputs should be named formula, data, theta, family, weights, cost,
alpha, lambda and/or upper respectively.
gam_design$update(...)
...named arguments formula, data, theta, family, weights, cost,
alpha, lambda and/or upper.
none
gam_design$stratify()Stratify the design by requiring that individual strata are represented proportionally. Call with strata = NULL to
unset previously defined strata.
gam_design$stratify(strata, proportions = NULL)
strataa factor variable of the same length as the number of rows in data. The factor levels determine
the partition of the design points into individual (disjoint) strata. Also accepts a one-sided formula made up of
column names present in data, in which case the strata are defined by the interaction between terms in the
model.frame obtained from the formula.
proportionsan optional numeric vector containing the weight proportions of the individual strata. Must be of the same length
as the number of factor levels in strata. If NULL, each stratum is assigned the same weight proportion.
none
gam_design$augment()Optimizes the augmented penalized approximate design given a vector of initial design weights
gam_design$augment(
design_weights,
gamma = 0.5,
criterion = c("D", "A", "I", "G", "alias"),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE
)
design_weightsa numeric vector with initial design weights, must be the same length as the number of design points in data.
Also accepts a one-sided formula made up of parameters in theta and column names in data.
gammanumeric contribution weight of the initial design in the augmented design problem, see also ‘Augmented optimal design’ above. Defaults to 0.5.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
numeric vector if return_value = TRUE, otherwise none
gam_design$optimize()Optimizes the penalized approximate design based on the selected criterion.
gam_design$optimize(
criterion = c("D", "A", "I", "G", "alias"),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE
)
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
numeric vector if return_value = TRUE, otherwise none
gam_design$sparsify()Sparsify the penalized approximate design by iterative reweighting of the optimization problem.
gam_design$sparsify(
max_iter,
criterion = c("D", "A", "I", "G", "alias"),
reweight_fun = c("entropy", "log-sum", "power"),
eps = .Machine$double.eps,
tol = .Machine$double.eps^(1/4),
p = 0.5,
design_weights = NULL,
scs_control = scs_control_dflt(),
return_value = TRUE,
show_progress = TRUE
)
max_iterpositive integer, maximum number of reweighted optimizations/iterations to run.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
reweight_funcharacter reweighting function, one of "entropy", "log-sum", "power", see lm_design for the definitions.
epspositive numeric value to ensure finite weights in reweighting functions.
tolnumeric tolerance used as a threshold for mean absolute relative difference in design weights between iterations to stop early.
ppositive numeric power with . Only used if reweight_fun = "power".
design_weights(optional) vector of design weights used as initial approximate design.
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
show_progresslogical, display a progress bar during the iterative reweighting procedure. Defaults to TRUE.
The sparseness cost penalties are scaled by the same alpha tuning parameter as for a user-specific cost vector, see scs_control_dflt.
If a cost vector c_1,...,c_n associated to the design weights is already specified. The sparseness penalty costs are multiplied
by the existing cost vector.
numeric vector if return_value = TRUE, otherwise none
gam_design$round()Round penalized approximate design to an exact (integer) design.
By default, the approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
For method "optimal", ridge and cost penalties and upper limit constraints present in $lambda, $cost and $upper
(if specified) are included in the criterion optimized by the point-exchange algorithm.
To override the initial approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If design_weights is set to FALSE,
the initial design is generated by random sampling.
gam_design$round(
m,
method = c("optimal", "efficient", "dist-sum", "dist-min"),
max_iter = 100,
n_repeats = 10,
replicates = TRUE,
tol = .Machine$double.eps^(1/3),
seed = NULL,
design_weights = TRUE,
augment_design = NULL,
show_progress = TRUE,
...
)
minteger number of design points included in the exact design.
methodthe method used to calculate the exact design. The following choices are supported:
"optimal" optimality criterion point-exchange algorithm (default). |
"efficient" efficient rounding method of Pukelsheim & Reider (1992). |
"dist-sum" maximize total pairwise (Euclidean) distance between design points. |
"dist-min" maximize minimum pairwise (Euclidean) distance between design points.
|
max_iterinteger number of maximum iterations in point-exchange algorithm. Only used when
method = "optimal", method = "dist-sum" or method = "dist-min".
n_repeatsinteger number of (random) repeats of the rounding/exchange algorithm. The exact design with the highest criterion value is returned. Defaults to 10.
replicateslogical, allow replicate design points in the exact design, defaults to TRUE.
Can also be an integer number, limiting the maximum number of allowed replicates per design point.
This argument overrides the $upper value constraint if existing.
tolnumeric tolerance used as lower threshold to continue iterations in point-exchange algorithm.
seed(optional) random seed used to generate jitter to break ties in rounding the initial exact design.
design_weights(optional) vector of design weights used as initial approximate design, with length equal
to the number of available design points. If TRUE (default), the approximate design is initialized from the
design_weights field. If FALSE, the initial approximate design is generated by random sampling.
augment_design(optional) integer design to augment, with length equal to the number of available design points.
show_progresslogical, display a progress bar during the rounding procedure (only if
n_repeats > 1). Defaults to TRUE.
...additional arguments to tune algorithm settings:
criterion, character string specifying the optimality criterion for the rounding procedure in case
design_weights has no "criterion" attribute, or to override the criterion specified in the "criterion" attribute.
If specified, must be one of "D", "A", "I", "G" or "alias".
numeric vector
gam_design$crit()Evaluate optimality criterion of a penalized approximate or rounded (exact) design.
The approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
gam_design$crit(
design_weights = NULL,
criterion = c("D", "A", "I", "G", "alias"),
lambda = TRUE,
alpha = TRUE
)
design_weights(optional) vector of design weights for which to evaluate optimality criterion.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
lambdalogical, whether to include the ridge penalty in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if $lambda is positive.
alphalogical, whether to include cost penalties in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if cost penalties are present
in the $cost field.
numeric criterion value
gam_design$vcov()Calculates the variance-covariance matrix of the model parameters based on an approximate or rounded (exact) design according to:
where is with , and is
, with GLM weights
evaluated at the nominal parameter values.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
Use the m argument to evaluate the covariance matrix for a specific number of design points, in which case the sum of the design weights is scaled to m.
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If the vector of design weights is already an integer design, leave
m unspecified, in which case the design is not rescaled.
gam_design$vcov(m, design_weights = NULL, sigma2 = 1)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
sigma2numeric error variance used to scale the covariance matrix. Defaults to 1, returning the unscaled covariance matrix.
numeric matrix
gam_design$sep()Calculates the standard error of prediction or the square root prediction variance across the design grid based on an approximate or rounded (exact)
design according to:
where is the covariance matrix as returned by $vcov().
If type = "response", the standard errors of prediction are transformed to the response scale by an application of the Delta method:
Use the newdata argument to evaluate the standard error of prediction at design points not in the candidate design grid defined by $data.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
gam_design$sep(
m,
newdata,
design_weights = NULL,
type = c("link", "response"),
sigma2 = 1
)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
newdata(optional) data frame or matrix with design points (rows) at which to return the standard error of prediction and which
can be evaluated by $formula.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
typethe type of prediction required. The default choice "link" returns the standard error of prediction on the scale of the linear predictors,
whereas "response" returns the standard error of prediction on the scale of the response variable.
sigma2numeric error variance used to scale the standard errors. Defaults to 1, returning the standardized standard error of prediction.
numeric vector
gam_design$corr()Calculates the correlation matrix of the columns of the design matrix based on an approximate or rounded (exact) design according to:
where is with , and is the design matrix centered by the (weighted)
column means:
is , with the diagonal elements of .
If center = FALSE, the uncentered correlation matrix is returned, which corresponds to the scale-invariant (unit diagonal) version of the information matrix
.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
gam_design$corr(design_weights = NULL, center = TRUE)
design_weights(optional) vector of design weights for which to evaluate the information matrix.
centerlogical, whether to center the design columns when evaluating the correlation matrix, defaults to TRUE.
numeric matrix
gam_design$clone()The objects of this class are cloneable with this method.
gam_design$clone(deep = FALSE)
deepWhether to make a deep clone.
## Ethanol dataset ## initialize model design <- gam_design$new( formula = ~s(E) + C, data = ethanol ) ## approximate I-optimal design design$optimize(criterion = "I") ## integer optimal design w/ 11 design points (exact_design <- design$round(m = 11, method = "optimal", criterion = "I", seed = 1)) design$subset(replicates = exact_design) ## GAM fitted to integer design gam_fit <- mgcv::gam(NOx ~ s(E) + C, data = ethanol[exact_design > 0, ]) summary(gam_fit) ## Volcano height dataset ## pre-process data data(volcano) volcano <- volcano[c(TRUE, FALSE), c(TRUE, FALSE)] data <- expand.grid( x1 = seq_len(dim(volcano)[1]), x2 = seq_len(dim(volcano)[2]) ) data[["y"]] <- c(volcano) ## initialize model design <- gam_design$new( formula = ~s(x1, x2), data = data ) ## integer I-optimal design w/ 30 design points exact_design <- design$round( m = 30, method = "optimal", criterion = "I", design_weights = FALSE ) design$crit(exact_design, criterion = "I") ## GAM fitted to integer design gam_fit <- mgcv::gam(y ~ s(x1, x2), data = data[exact_design > 0, ]) summary(gam_fit)## Ethanol dataset ## initialize model design <- gam_design$new( formula = ~s(E) + C, data = ethanol ) ## approximate I-optimal design design$optimize(criterion = "I") ## integer optimal design w/ 11 design points (exact_design <- design$round(m = 11, method = "optimal", criterion = "I", seed = 1)) design$subset(replicates = exact_design) ## GAM fitted to integer design gam_fit <- mgcv::gam(NOx ~ s(E) + C, data = ethanol[exact_design > 0, ]) summary(gam_fit) ## Volcano height dataset ## pre-process data data(volcano) volcano <- volcano[c(TRUE, FALSE), c(TRUE, FALSE)] data <- expand.grid( x1 = seq_len(dim(volcano)[1]), x2 = seq_len(dim(volcano)[2]) ) data[["y"]] <- c(volcano) ## initialize model design <- gam_design$new( formula = ~s(x1, x2), data = data ) ## integer I-optimal design w/ 30 design points exact_design <- design$round( m = 30, method = "optimal", criterion = "I", design_weights = FALSE ) design$crit(exact_design, criterion = "I") ## GAM fitted to integer design gam_fit <- mgcv::gam(y ~ s(x1, x2), data = data[exact_design > 0, ]) summary(gam_fit)
An R6 class for managing penalized locally optimal experiment designs for generalized linear models. This class encapsulates the generalized linear model at a set of nominal parameter values, the discrete design grid, optimization of an approximate continuous design, augmentation of an existing design, and optimal rounding to exact integer designs.
R6-object of class glm_design if called with glm_design$new().
The following penalized optimization problem is solved by $optimize():
where,
is the vector of design weights.
is the cost assigned to each design weight with scaling/penalty parameter .
is a vector of fixed user weights.
is the information matrix depending on the weights and ,
the design matrix , the nominal parameter values , the chosen (exponential) distribution family and the link function
.
is the chosen optimality criterion, generally a function of the information matrix.
In standard canonical form, the probability density (or mass) function of the exponential family is:
The cumulant function admits and , the variance function expressed as a
function of the mean. Given the link function , the systematic component is .
The information matrix is given by:
with weights causing the information matrix to depend on the parameter values ,
unlike the information matrix for a standard linear model.
Given a vector of initial design weights and associated contribution weight ,
the following augmented penalized optimization problem is solved by $augment():
using the augmented information matrix,
The $strata() method stratifies the design by requiring that individual strata
are represented proportionally with given weights , (). If stratification is applied,
the following optimization problem is solved by $optimize():
using the same notation as in the ‘Optimal design problem’ section above. This means that the total weight
assigned to the design points in stratum is equal to for each .
Similarly, if stratification is applied, $augment() solves the augmented optimization problem with stratification
constraints.
The $sparsify() method solves the penalized optimization problem with an extra sparseness penalty
in the objective to promote sparsity in the approximate design . See lm_design for the available penalty functions.
The optimality criteria supported by $optimize(), $augment() and $sparsify() are: D-,
A-, I-, G-, and alias-optimality, see lm_design for the definitions.
lm_design -> glm_design
formulaa linear model defined as a one-sided formula.
thetaa named vector or list of nominal parameter values at which the information matrix is evaluated.
familya description of the model distribution family and link function. See family for details of family functions.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
costan optional numeric vector containing costs associated to each design point (row) in data.
design_weightsa numeric vector with optimal design weights populated after optimization with $optimize(), $augment(), or $sparsify().
The attribute criterion lists the used design criterion and the achieved optimal criterion value.
strataa list with elements strata and proportions imposing a partition of the design points into individual (disjoint) strata
with given weight proportions.
alphathe cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available.
lambdathe ridge penalty added to the diagonal of the information matrix in the optimization problem. The ridge penalty is not used
upperthe design weight upper limit. The default is 1, corresponding to no upper limit constraint on the design weights.
Xthe design matrix obtained from all design points in data and the model formula.
glm_design$new()Constructor. Initializes the experimental design to optimize with a linear model formula, discrete design grid, nominal parameter values and distribution family with link function.
glm_design$new( formula, data, theta, family = gaussian(), weights = NULL, cost = NULL, contrasts = NULL, alpha = 1, lambda = 0, upper = 1, ... )
formulaa linear model defined as a one-sided formula.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
thetaa named or unnamed vector or list of nominal parameter values at which the information matrix is evaluated.
familya family function describing the error distribution and link function in the model. Defaults to the gaussian
family with "identity" link function.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
Also accepts a one-sided formula made up of column names present in data. If NULL,
the unweighted optimal design problem is solved.
costan optional numeric vector containing costs associated to each design point (row) in data.
Also accepts a one-sided formula made up of column names present in data. If NULL,
the standard (non-penalized) optimal design problem is solved.
contrastsoptional contrasts used when evaluating the linear model formula.
alphanumeric value, cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available. The default is 1.
lambdanumeric value, ridge penalty added to the diagonal of the information matrix in the penalized optimization problem. The default is 0.
uppernumeric value in (0, 1], design weight upper limit. The default is 1, corresponding to no constraint on the design weights.
...any additional arguments passed to model.matrix.
glm_design R6-object
glm_design$update()Updates the fields of an existing object.
Inputs should be named formula, data, theta, family, weights, cost,
alpha, lambda and/or upper.
glm_design$update(...)
...named arguments formula, data, theta, family, weights, cost,
alpha, lambda and/or upper.
none
glm_design$stratify()Stratify the design by requiring that individual strata are represented proportionally. Call with strata = NULL to
unset previously defined strata.
glm_design$stratify(strata, proportions = NULL)
strataa factor variable of the same length as the number of rows in data. The factor levels determine
the partition of the design points into individual (disjoint) strata. Also accepts a one-sided formula made up of
column names present in data, in which case the strata are defined by the interaction between terms in the
model.frame obtained from the formula.
proportionsan optional numeric vector containing the weight proportions of the individual strata. Must be of the same length
as the number of factor levels in strata. If NULL, each stratum is assigned the same weight proportion.
none
glm_design$augment()Optimizes the augmented penalized approximate design given a vector of initial design weights
glm_design$augment(
design_weights,
gamma = 0.5,
criterion = c("D", "A", "I", "G", "alias"),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE
)
design_weightsa numeric vector with initial design weights, must be the same length as the number of design points in data.
Also accepts a one-sided formula made up of parameters in theta and column names in data.
gammanumeric contribution weight of the initial design in the augmented design problem, see also ‘Augmented optimal design’ above. Defaults to 0.5.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
numeric vector if return_value = TRUE, otherwise none
glm_design$optimize()Optimizes the penalized approximate design based on the selected criterion.
glm_design$optimize(
criterion = c("D", "A", "I", "G", "alias"),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE
)
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
numeric vector if return_value = TRUE, otherwise none
glm_design$sparsify()Sparsify the penalized approximate design by iterative reweighting of the optimization problem.
glm_design$sparsify(
max_iter,
criterion = c("D", "A", "I", "G", "alias"),
reweight_fun = c("entropy", "log-sum", "power"),
eps = .Machine$double.eps,
tol = .Machine$double.eps^(1/4),
p = 0.5,
design_weights = NULL,
scs_control = scs_control_dflt(),
return_value = TRUE,
show_progress = TRUE
)
max_iterpositive integer, maximum number of reweighted optimizations/iterations to run.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
reweight_funcharacter reweighting function, one of "entropy", "log-sum", "power", see lm_design for the definitions.
epspositive numeric value to ensure finite weights in reweighting functions.
tolnumeric tolerance used as a threshold for mean absolute relative difference in design weights between iterations to stop early.
ppositive numeric power with . Only used if reweight_fun = "power".
design_weights(optional) vector of design weights used as initial approximate design.
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
show_progresslogical, display a progress bar during the iterative reweighting procedure. Defaults to TRUE.
The sparseness cost penalties are scaled by the same alpha tuning parameter as for a user-specific cost vector, see scs_control_dflt.
If a cost vector c_1,...,c_n associated to the design weights is already specified. The sparseness penalty costs are multiplied
by the existing cost vector.
numeric vector if return_value = TRUE, otherwise none
glm_design$round()Round penalized approximate design to an exact (integer) design.
By default, the approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
For method "optimal", ridge and cost penalties and upper limit constraints present in $lambda, $cost and $upper
(if specified) are included in the criterion optimized by the point-exchange algorithm.
To override the initial approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If design_weights is set to FALSE,
the initial design is generated by random sampling.
glm_design$round(
m,
method = c("optimal", "efficient", "dist-sum", "dist-min"),
max_iter = 100,
n_repeats = 10,
replicates = TRUE,
tol = .Machine$double.eps^(1/3),
seed = NULL,
design_weights = TRUE,
augment_design = NULL,
show_progress = TRUE,
...
)
minteger number of design points included in the exact design.
methodthe method used to calculate the exact design. The following choices are supported:
"optimal" optimality criterion point-exchange algorithm (default). |
"efficient" efficient rounding method of Pukelsheim & Reider (1992). |
"dist-sum" maximize total pairwise (Euclidean) distance between design points. |
"dist-min" maximize minimum pairwise (Euclidean) distance between design points.
|
max_iterinteger number of maximum iterations in point-exchange algorithm. Only used when
method = "optimal", method = "dist-sum" or method = "dist-min".
n_repeatsinteger number of (random) repeats of the rounding/exchange algorithm. The exact design with the highest criterion value is returned. Defaults to 10.
replicateslogical, allow replicate design points in the exact design, defaults to TRUE.
Can also be an integer number, limiting the maximum number of allowed replicates per design point.
This argument overrides the $upper value constraint if existing.
tolnumeric tolerance used as lower threshold to continue iterations in point-exchange algorithm.
seed(optional) random seed used to generate jitter to break ties in rounding the initial exact design.
design_weights(optional) vector of design weights used as initial approximate design, with length equal
to the number of available design points. If TRUE (default), the approximate design is initialized from the
design_weights field. If FALSE, the initial approximate design is generated by random sampling.
augment_design(optional) integer design to augment, with length equal to the number of available design points.
show_progresslogical, display a progress bar during the rounding procedure (only if
n_repeats > 1). Defaults to TRUE.
...additional arguments to tune algorithm settings:
criterion, character string specifying the optimality criterion for the rounding procedure in case
design_weights has no "criterion" attribute, or to override the criterion specified in the "criterion" attribute.
If specified, must be one of "D", "A", "I", "G" or "alias".
numeric vector
glm_design$crit()Evaluate optimality criterion of a penalized approximate or rounded (exact) design.
The approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
glm_design$crit(
design_weights = NULL,
criterion = c("D", "A", "I", "G", "alias"),
lambda = TRUE,
alpha = TRUE
)
design_weights(optional) vector of design weights for which to evaluate optimality criterion.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
lambdalogical, whether to include the ridge penalty in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if $lambda is positive.
alphalogical, whether to include cost penalties in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if cost penalties are present
in the $cost field.
numeric criterion value
glm_design$vcov()Calculates the variance-covariance matrix of the model parameters based on an approximate or rounded (exact) design according to:
where is with , and is
, with GLM weights
evaluated at the nominal parameter values.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
Use the m argument to evaluate the covariance matrix for a specific number of design points, in which case the sum of the design weights is scaled to m.
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If the vector of design weights is already an integer design, leave
m unspecified, in which case the design is not rescaled.
glm_design$vcov(m, design_weights = NULL, sigma2 = 1)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
sigma2numeric error variance used to scale the covariance matrix. Defaults to 1, returning the unscaled covariance matrix.
numeric matrix
glm_design$sep()Calculates the standard error of prediction or the square root prediction variance across the design grid based on an approximate or rounded (exact)
design according to:
where is the covariance matrix as returned by $vcov().
If type = "response", the standard errors of prediction are transformed to the response scale by an application of the Delta method:
Use the newdata argument to evaluate the standard error of prediction at design points not in the candidate design grid defined by $data.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
glm_design$sep(
m,
newdata,
design_weights = NULL,
type = c("link", "response"),
sigma2 = 1
)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
newdata(optional) data frame or matrix with design points (rows) at which to return the standard error of prediction and which
can be evaluated by $formula.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
typethe type of prediction required. The default choice "link" returns the standard error of prediction on the scale of the linear predictors,
whereas "response" returns the standard error of prediction on the scale of the response variable.
sigma2numeric error variance used to scale the standard errors. Defaults to 1, returning the standardized standard error of prediction.
numeric vector
glm_design$corr()Calculates the correlation matrix of the columns of the design matrix based on an approximate or rounded (exact) design according to:
where is with , and is the design matrix centered by the (weighted)
column means:
is , with the diagonal elements of .
If center = FALSE, the uncentered correlation matrix is returned, which corresponds to the scale-invariant (unit diagonal) version of the information matrix
.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
glm_design$corr(design_weights = NULL, center = TRUE)
design_weights(optional) vector of design weights for which to evaluate the information matrix.
centerlogical, whether to center the design columns when evaluating the correlation matrix, defaults to TRUE.
numeric matrix
glm_design$clone()The objects of this class are cloneable with this method.
glm_design$clone(deep = FALSE)
deepWhether to make a deep clone.
Lewis, S. L., Montgomery D. C., and Myers R. H. 2001. Examples of Designed Experiments with Nonnormal Responses. Journal of Quality Technology 3 (33): 265–78.
## Non-conforming tiles experiment ## Example 3 from [Lewis et al. (2001)] ## design grid data <- expand.grid( x1 = c(-1, 1), x2 = c(-1, 1), x3 = c(-1, 1), x4 = c(-1, 1), x5 = c(-1, 1), x6 = c(-1, 1), x7 = c(-1, 1) ) ## initialize model, design grid, family and nominal parameters design <- glm_design$new( formula = ~x1 + x2 + x3 + x4 + x5 + x6 + x7, data = data, family = binomial(link = "logit"), theta = c(-1.419, -0.578, 0.109, 0.266, -0.262, 0.434, -0.633, 0.425) ) ## approximate D-optimal design design$optimize(criterion = "D") ## integer design w/ 8 design points (exact_design <- design$round(m = 8, method = "optimal", n_repeats = 25, seed = 1)) design$subset(replicates = exact_design) ## Defect semiconductor wafers ## Example 5 from [Lewis et al. (2001)] ## design grid data <- rbind( expand.grid(x1 = -1:1, x2 = -1:1, x3 = -1:1), data.frame( x1 = c(-1.732, 1.732, 0, 0, 0, 0), x2 = c(0, 0, -1.732, 1.732, 0, 0), x3 = c(0, 0, 0, 0, -1.732, 1.732) ) ) ## initialize model, design grid, family and nominal parameters design <- glm_design$new( formula = ~(x1 + x2 + x3)^2 + I(x1^2) + I(x2^2) + I(x3^2), data = data, family = poisson(link = "log"), theta = c(1.9293, 0.6103, 0.7028, -0.3531, 0, 0.2471, 0, -0.5209, 0, 0) ) ## approximate D-optimal design design$optimize(criterion = "D") ## integer design w/ 18 design points (exact_design <- design$round(m = 18, method = "optimal", seed = 1)) design$subset(replicates = exact_design)## Non-conforming tiles experiment ## Example 3 from [Lewis et al. (2001)] ## design grid data <- expand.grid( x1 = c(-1, 1), x2 = c(-1, 1), x3 = c(-1, 1), x4 = c(-1, 1), x5 = c(-1, 1), x6 = c(-1, 1), x7 = c(-1, 1) ) ## initialize model, design grid, family and nominal parameters design <- glm_design$new( formula = ~x1 + x2 + x3 + x4 + x5 + x6 + x7, data = data, family = binomial(link = "logit"), theta = c(-1.419, -0.578, 0.109, 0.266, -0.262, 0.434, -0.633, 0.425) ) ## approximate D-optimal design design$optimize(criterion = "D") ## integer design w/ 8 design points (exact_design <- design$round(m = 8, method = "optimal", n_repeats = 25, seed = 1)) design$subset(replicates = exact_design) ## Defect semiconductor wafers ## Example 5 from [Lewis et al. (2001)] ## design grid data <- rbind( expand.grid(x1 = -1:1, x2 = -1:1, x3 = -1:1), data.frame( x1 = c(-1.732, 1.732, 0, 0, 0, 0), x2 = c(0, 0, -1.732, 1.732, 0, 0), x3 = c(0, 0, 0, 0, -1.732, 1.732) ) ) ## initialize model, design grid, family and nominal parameters design <- glm_design$new( formula = ~(x1 + x2 + x3)^2 + I(x1^2) + I(x2^2) + I(x3^2), data = data, family = poisson(link = "log"), theta = c(1.9293, 0.6103, 0.7028, -0.3531, 0, 0.2471, 0, -0.5209, 0, 0) ) ## approximate D-optimal design design$optimize(criterion = "D") ## integer design w/ 18 design points (exact_design <- design$round(m = 18, method = "optimal", seed = 1)) design$subset(replicates = exact_design)
This dataset reports the yield of the desired product and the reaction cost in a direct arylation reaction of imidazoles. Two continuous process conditions (temperature, initial concentration) and three reaction molecules (base, ligand, solvent) are varied to maximize the yield of the desired product while minimizing the cost of the reaction.
imidazolesimidazoles
A data.frame containing 1728 experiments with columns:
numeric, experimental yield of the reaction (%)
numeric, cost of the reaction scaled to the unit interval
numeric, initial substrate concentration (M)
numeric, temperature of the reaction (Celsius)
character, common name of the reaction base molecule
character, SMILES string of the reaction base molecule
character, common name of the reaction solvent molecule
character, SMILES string of the reaction solvent molecule
character, common name of the reaction ligand molecule
character, SMILES string of the reaction ligand molecule
data.frame
doi:10.1038/s41586-021-03213-y
Shields B.J. et al. (2021) “Bayesian reaction optimization as a tool for chemical synthesis”, Nature, Vol. 590 (7844).
Torres J.A.G. et al. (2022) “A Multi-Objective Active Learning Platform and Web App for Reaction Optimization”, J. Am. Chem. Soc., Vol. 144 (43).
head(imidazoles)head(imidazoles)
An R6 class for managing penalized optimal experiment designs for linear models. This class encapsulates the linear model formula, the discrete design grid, optimization of an approximate continuous design, augmentation of an existing design, and optimal rounding to exact integer designs.
R6-object of class lm_design if called with lm_design$new().
The following penalized optimization problem is solved by $optimize():
where,
is the vector of design weights.
is the cost assigned to each design weight with scaling/penalty parameter .
is a vector of fixed user weights.
is the information matrix depending on the weights ,
the design matrix created by model.matrix, and in the case of weighted regression
the heterogeneous weights .
is a diagonal matrix to regularize the information matrix with ridge penalty parameter .
is the chosen optimality criterion, generally a function of the information matrix.
Given the linear model formula, the information matrix (conditional on the error variance) is:
Given a vector of initial design weights and associated contribution weight ,
the following augmented penalized optimization problem is solved by $augment():
using the augmented information matrix,
The $strata() method stratifies the design by requiring that individual strata
are represented proportionally with given weights , (). If stratification is applied,
the following optimization problem is solved by $optimize():
using the same notation as in the ‘Optimal design problem’ section above. This means that the total weight
assigned to the design points in stratum is equal to for each .
Similarly, if stratification is applied, $augment() solves the augmented optimization problem with stratification
constraints.
The $sparsify() method solves the penalized optimization problem using a custom penalty function
to promote sparsity in the approximate design . Because the sparse optimization problem is
not convex, a sequential convex approximation is used substituting the (concave) sparseness penalty by linearized (convex) costs
on the design weights similar to the cost penalties above. The following options are supported:
"entropy"-penaltyShannon entropy penalty, , with linearized costs (iteration ):
"log-sum"-penaltyLog-sum penalty, , with linearized costs (iteration ):
"power"-penaltyPower (bridge) penalty, , with linearized costs (iteration ):
The following optimality criteria are supported in $optimize(), $augment() and $sparsify():
"D"-optimalityMaximize the volume of the information matrix , or equivalently minimize the volume of
the confidence ellipsoid of the parameter estimates:
where is the number of columns in the design matrix .
With non-zero ridge/cost penalties, the (penalized) optimality criterion is calculated as:
"A"-optimalityMaximize the inverse trace of the inverse information , or equivalently minimize the
average variance of the parameter estimates:
With non-zero ridge/cost penalties, the (penalized) optimality criterion is calculated as:
"I"-optimalityMaximize the inverse of the average prediction variance across the design space, (equivalently minimize the average prediction variance):
With non-zero ridge/cost penalties, the (penalized) optimality criterion is calculated as:
"G"-optimalityMaximize the inverse of the maximum prediction variance across the design space, (equivalently minimize the maximum prediction variance):
With non-zero ridge/cost penalties, the (penalized) optimality criterion is calculated as:
"alias"-optimalityMaximize one minus the average absolute cosine similarity (also uncentered correlation or normalized dot product)
between columns of the design matrix :
where is the elementwise-product of and the -th design column .
If all columns in the design matrix are centered, this is equivalent to minimizing the average correlation between columns in .
With non-zero cost penalties, the (penalized) optimality criterion is calculated as:
formulaa linear model defined as a one-sided formula.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
costan optional numeric vector containing costs associated to each design point (row) in data.
design_weightsa numeric vector with optimal design weights populated after optimization with $optimize(), $augment(), or $sparsify().
The attribute criterion lists the used design criterion and the achieved optimal criterion value.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
strataa list with elements strata and proportions imposing a partition of the design points into individual (disjoint) strata
with given weight proportions.
alphathe cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available.
lambdathe ridge penalty added to the diagonal of the information matrix in the optimization problem. The ridge penalty is not used
for the alias optimality criterion.
upperthe design weight upper limit. The default is 1, corresponding to no upper limit constraint on the design weights.
Xthe design matrix obtained from all design points in data and the model formula.
orthogonalthe dot product (orthogonality) constraint matrix. This matrix contains all dot product (upper limit)
constraints between design columns parsed from the orthogonal formula(s) in $new(orthogonal = ...) or $update(orthogonal = ...).
For design columns with no dot product constraint, the matrix entry is Inf.
zerosthe proportion of zeros vector. This vector contains the required proportion of zeros for each column in the design matrix
parsed from the zeros formula(s) in $new(zeros = ...) or $update(zeros = ...).
For design columns with no constraint, the value is NA.
col_meansthe imposed column mean vector. This vector contains the imposed column mean constraints for each column in the design matrix
parsed from the col_means formula in $new(col_means = ...) or $update(col_means = ...).
For design columns with no mean constraint, the value is NA.
lm_design$new()Constructor. Initializes the experimental design to optimize with a linear model formula and discrete design grid.
lm_design$new( formula, data, orthogonal = NULL, weights = NULL, cost = NULL, zeros = NULL, col_means = NULL, contrasts = NULL, alpha = 1, lambda = 0, upper = 1, ... )
formulaa linear model defined as a one-sided formula.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
orthogonalan optional two- or three-part formula or list of formulas imposing dot product (orthogonality)
constraints between the columns of the design matrix. In the three-part formula x1 + x2 ~ y1 + y2 ~ 0,
dot products are constrained between all combinations of columns in the first part of the formula (x1, x2)
and the second part of the formula (y1, y2). The third part (0) specifies the
upper limit on the dot product(s). If the formula only has two parts, e.g. x1 + x2 ~ y1 + y2, zero
dot product constraints are imposed. Also accepts a list of formulas, in which case constraints are added in the
order in which they appear in the list.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
Also accepts a one-sided formula using the column names present in data. If NULL,
the unweighted optimal design problem is solved.
costan optional numeric vector containing costs associated to each design point (row) in data.
Also accepts a one-sided formula using the column names present in data. If NULL,
the standard (non-penalized) optimal design problem is solved.
zerosan optional two-part formula or list of formulas imposing constraints on the proportion of zero values
in the columns of the design matrix. In the two-part formula x1 + x2 ~ 1/3, the proportion of zeros in the
columns specified by the first part of the formula (x1, x2) is constrained to be equal to the
(nonnegative) numeric value in the second part of the formula (1/3). Note that imposing constraints on the proportion
of zeros in the optimized design is only relevant if the design grid actually contain zero entries. For a list of formulas,
zero constraints are added in the order in which they appear in the list, analogous to the orthogonal argument.
col_meansan optional two-part formula imposing constraints on the column means of the design matrix.
In the two-part formula x1 + x2 ~ 0, the means of the columns specified by the first part of the formula (x1, x2)
are constrained to be equal to the numeric value in the second part of the formula (0).
contrastsoptional contrasts used when evaluating the linear model formula.
alphanumeric value, cost scale parameter in the penalized optimization problem, only used if $cost is available. The default is 1.
lambdanumeric value, ridge penalty added to the diagonal of the information matrix in the penalized optimization problem. The default is 0.
uppernumeric value in (0, 1], design weight upper limit. The default is 1, corresponding to no constraint on the design weights.
...any additional arguments passed to model.matrix.
lm_design R6-object
lm_design$update()Updates the fields of an existing object.
Inputs should be named formula, data, weights, orthogonal, cost, zeros,
col_means, alpha, lambda and/or upper.
lm_design$update(...)
...named arguments formula, data, weigts, orthogonal, cost, zeros,
col_means, alpha, lambda and/or upper.
none
lm_design$stratify()Stratify the design by requiring that individual strata are represented proportionally. Call with strata = NULL to
unset previously defined strata.
lm_design$stratify(strata, proportions = NULL)
strataa factor variable of the same length as the number of rows in data. The factor levels determine
the partition of the design points into individual (disjoint) strata. Also accepts a one-sided formula using
column names present in data, in which case the strata are defined by the interaction between terms in the
model.frame obtained from the formula.
proportionsan optional numeric vector containing the weight proportions of the individual strata. Must be of the same length
as the number of factor levels in strata. If NULL, each stratum is assigned the same weight proportion.
none
lm_design$augment()Optimizes the augmented penalized approximate design given a vector of initial design weights
lm_design$augment(
design_weights,
gamma = 0.5,
criterion = c("D", "A", "I", "G", "alias"),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE
)
design_weightsa numeric vector with initial design weights, must be the same length as the number of design points in data.
Also accepts a one-sided formula made up of column names present in data.
gammanumeric contribution weight of the initial design in the augmented design problem, see also ‘Augmented optimal design’ above. Defaults to 0.5.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights can be obtained from the design_weights field.
numeric vector if return_value = TRUE, otherwise none
lm_design$optimize()Optimizes the penalized approximate design based on the selected criterion.
lm_design$optimize(
criterion = c("D", "A", "I", "G", "alias"),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE
)
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights can be obtained from the design_weights field.
numeric vector if return_value = TRUE, otherwise none
lm_design$sparsify()Sparsify the penalized approximate design by iterative reweighting of the optimization problem.
lm_design$sparsify(
max_iter,
criterion = c("D", "A", "I", "G", "alias"),
reweight_fun = c("entropy", "log-sum", "power"),
eps = .Machine$double.eps,
tol = .Machine$double.eps^(1/4),
p = 0.5,
design_weights = NULL,
recenter = FALSE,
scs_control = scs_control_dflt(),
return_value = TRUE,
show_progress = TRUE
)
max_iterpositive integer, maximum number of reweighted optimizations/iterations to run.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
reweight_funcharacter reweighting function, one of "entropy", "log-sum", "power", see ‘Details’ for the definitions.
epspositive numeric value to ensure finite weights in reweighting functions, see ‘Details’.
tolnumeric tolerance used as a threshold for mean absolute relative difference in design weights between iterations to stop early.
ppositive numeric power with . Only used if reweight_fun = "power".
design_weights(optional) vector of design weights used as initial approximate design.
recenterlogical, recenter design columns based on the current design weights after each iteration. Defaults to FALSE.
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
return_valuereturn the optimal design weights. If set to FALSE, the design weights can be obtained from the design_weights field.
show_progresslogical, display a progress bar during the iterative reweighting procedure. Defaults to TRUE.
The sparseness cost penalties are scaled by the same alpha tuning parameter as for a user-specific cost vector, see scs_control_dflt.
If a cost vector c_1,...,c_n associated to the design weights is already specified. The sparseness penalty costs are multiplied
by the existing cost vector.
numeric vector if return_value = TRUE, otherwise none
lm_design$round()Round penalized approximate design to an exact (integer) design.
By default, the approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
For method "optimal", ridge and cost penalties and upper limit constraints present in $lambda, $cost and $upper
(if specified) are included in the criterion optimized by the point-exchange algorithm.
To override the initial approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If design_weights is set to FALSE,
the initial design is generated by random sampling.
lm_design$round(
m,
method = c("optimal", "efficient", "dist-sum", "dist-min", "orthogonal"),
max_iter = 100,
n_repeats = 10,
replicates = TRUE,
tol = .Machine$double.eps^(1/3),
seed = NULL,
design_weights = TRUE,
augment_design = NULL,
show_progress = TRUE,
...
)
minteger number of design points included in the exact design.
methodthe method used to calculate the exact design. The following choices are supported:
"optimal" optimality criterion point-exchange algorithm (default). |
"efficient" efficient rounding method of Pukelsheim & Reider (1992). |
"dist-sum" maximize total pairwise (Euclidean) distance between design points. |
"dist-min" maximize minimum pairwise (Euclidean) distance between design points. |
"orthogonal" minimizes aliasing subject to orthogonality constraints, see ‘Details’.
|
max_iterinteger number of maximum iterations in point-exchange algorithm. Only used when
method = "optimal", method = "dist-sum" or method = "dist-min".
n_repeatsinteger number of (random) repeats of the rounding/exchange algorithm. The exact design
with the highest criterion value is returned. Not used for method = "orthogonal". Defaults to 10.
replicateslogical, allow replicate design points in the exact design, defaults to TRUE.
Can also be an integer number, limiting the maximum number of allowed replicates per design point.
This argument overrides the $upper value constraint if existing.
tolnumeric tolerance used as lower threshold to continue iterations in point-exchange algorithm.
Also used as threshold to ensure positive diagonal entries of when method = "orthogonal".
seed(optional) random seed used to generate jitter to break ties in rounding the initial exact design.
Not used in the case of (mirai) asynchronous evaluation, which requires the random seed to be set via the
seed argument in mirai::daemons.
design_weights(optional) vector of design weights used as initial approximate design, with length equal
to the number of available design points. If TRUE (default), the approximate design is initialized from the
design_weights field. If FALSE, the initial approximate design is generated by random sampling.
augment_design(optional) integer design to augment, with length equal to the number of available design points.
show_progresslogical, display a progress bar monitoring the repeats of the rounding/exchange algorithm.
Defaults to TRUE.
...additional arguments to tune algorithm/solver settings:
criterion, character string specifying the optimality criterion for the rounding procedure in case design_weights
has no "criterion" attribute, or to override the criterion specified in the "criterion" attribute.
If specified, must be one of "D", "A", "I", "G" or "alias".
highs_control, a named list with control arguments supported by the HiGHS solver, only used if method = "orthogonal".
Defaults to highs_control = list(time_limit = 180, log_to_console = TRUE).
highs_write_mps, .mps file path. If provided, the HiGHS MILP is exported in MPS (Mathematical Programming System)
format to the provided file path. Can also be TRUE, in which case a new .mps file is created in the current working directory.
Only used if method = "orthogonal".
The repeated rounding/exchange algorithms can be run in parallel using the mirai asynchronous evaluation framework.
The parallel background R processes are configured by the user outside of $round() with mirai::daemons.
If daemon connections are available, $round() automatically runs the repeated exchange algorithms in parallel
using the configured daemons. If the underlying BLAS/LAPACK libraries are already multi-threaded, this may
inhibit the use of additional threads by the mirai asynchronous evaluation. In this case, it is recommended to restrict
BLAS/LAPACK to a single thread with the OPENBLAS_NUM_THREADS, MKL_NUM_THREADS or OMP_NUM_THREADS
environment variables, depending on the BLAS library that is used. In addition, note that there is a small overhead in populating the
environments of the background R processes, which may result in increased runtime compared to sequential evaluation in the main R process,
especially when n_repeats is small or the rounding/exchange algorithm does not take much time to complete.
The "orthogonal" rounding procedure uses HiGHS to find an exact design subject to orthogonality constraints.
This requires either a local installation of the HiGHS solver or the highs package to be installed.
To point to a local HiGHS installation, the environment variable HIGHS_HOME must be set to the highs
root directory when installing cvxoptdes. If installation fails, verify that highs_c_api.h exists, typically
present in $HIGHS_HOME/include/highs/interfaces, which is required to compile the source code.
numeric vector
lm_design$crit()Evaluate optimality criterion of a penalized approximate or rounded (exact) design.
The approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
lm_design$crit(
design_weights = NULL,
criterion = c("D", "A", "I", "G", "alias"),
lambda = TRUE,
alpha = TRUE
)
design_weights(optional) vector of design weights for which to evaluate optimality criterion.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
lambdalogical, whether to include the ridge penalty in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if $lambda is positive.
alphalogical, whether to include cost penalties in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if cost penalties are present
in the $cost field.
numeric criterion value
lm_design$vcov()Calculates the variance-covariance matrix of the model coefficients based on an approximate or rounded (exact) design according to:
where is with .
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
Use the m argument to evaluate the covariance matrix for a specific number of design points, in which case the sum of the design weights is scaled to m.
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If the vector of design weights is already an integer design, leave
m unspecified.
lm_design$vcov(m, design_weights = NULL, sigma2 = 1)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
sigma2numeric error variance used to scale the covariance matrix. Defaults to 1, returning the unscaled covariance matrix.
numeric matrix
lm_design$sep()Calculates the standard error of prediction or the square root prediction variance across the design grid based on an approximate or rounded (exact)
design according to:
where is the covariance matrix as returned by $vcov().
Use the newdata argument to evaluate the standard error of prediction at design points not in the candidate design grid defined by $data.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
lm_design$sep(m, newdata, design_weights = NULL, sigma2 = 1)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
newdata(optional) data frame or matrix with design points (rows) at which to return the standard error of prediction and which
can be evaluated by $formula.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
sigma2numeric error variance used to scale the standard errors. Defaults to 1, returning the standardized standard error of prediction.
numeric vector
lm_design$corr()Calculates the correlation matrix of the columns of the design matrix based on an approximate or rounded (exact) design according to:
where is with , and is the design matrix centered by the (weighted)
column means:
is , with the diagonal elements of .
If center = FALSE, the uncentered correlation matrix is returned, which corresponds to the scale-invariant (unit diagonal) version of the information matrix .
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
lm_design$corr(design_weights = NULL, center = TRUE)
design_weights(optional) vector of design weights for which to evaluate the information matrix.
centerlogical, whether to center the design columns when evaluating the correlation matrix, defaults to TRUE.
numeric matrix
lm_design$subset()Subsets the design points associated to an exact design vector with integer replicates as returned by $round().
The vector must be the same length as the number of design points in data.
lm_design$subset(replicates)
replicatesinteger vector of design point replicates of the same length as the candidate grid in data
data.frame
lm_design$clone()The objects of this class are cloneable with this method.
lm_design$clone(deep = FALSE)
deepWhether to make a deep clone.
Pukelsheim, F., and Rieder S. (1992) "Efficient rounding of approximate designs", Biometrika.
https://ergo-code.github.io/HiGHS/dev/installation/
https://mirai.r-lib.org/
## Getting started ## 3 factors w/ 5, 5 and 3 levels data <- expand.grid( x1 = -2:2, x2 = -2:2, x3 = -1:1 ) design <- lm_design$new( formula = ~(x1 + x2 + x3)^2 + I(x1^2) + I(x2^2) + I(x3^2), ## full quadratic model data = data ## design points ) ## approximate D-optimal design design$optimize(criterion = "D") ## integer D-optimal design w/ 13 design points (exact_design <- design$round(m = 13, method = "optimal", seed = 1)) design$subset(replicates = exact_design) ## integer design covariance and correlation matrices design$vcov(design_weights = exact_design, sigma2 = 1) design$corr(design_weights = exact_design) ## Penalized optimal design ## assign cost c = 1 if x3 = 1, and c = 0 otherwise design$update( cost = ~pmax(x3, 0), alpha = 1 ) ## penalized approximate D-optimal design design$optimize(criterion = "D") ## assign v = 1 if x3 = 1, and v = 0.1 otherwise design$update( weights = ~pmax(x3, 0.1), cost = NULL ) ## penalized approximate D-optimal design design$optimize(criterion = "D") ## exact design w/ 15 design points design$round(m = 15, method = "optimal", seed = 1) ## drop weights term design$update(weights = NULL) ## Stratified optimal design ## add stratification constraints design$stratify( strata = ~x3, proportions = c(1/4, 1/2, 1/4) ) ## approximate D-optimal design w/ stratification design$optimize(criterion = "D") ## verify stratification tapply(design$design_weights, design$data$x3, sum) ## exact design w/ stratification design$round(m = 12, method = "optimal", seed = 1) ## drop stratification design$stratify(strata = NULL) ## Orthogonality constraints ## orthogonal main effects wrt all other columns design$update( orthogonal = x1 + x2 + x3 ~ . ~ 0, alpha = 0.075 ## sparseness penalty ) design$orthogonal ## approximate D-optimal design w/ orthogonality constraints design$optimize(criterion = "D") ## sparsify support by iterative entropy reweighting design$sparsify(max_iter = 5, criterion = "D", reweight_fun = "entropy") if(requireNamespace("highs", quietly = TRUE)) { ## integer design w/ orthogonality constraints (ortho_design <- design$round(m = 8, method = "orthogonal", seed = 1)) ## verify correlations design$corr(ortho_design) } ## Optimal design augmentation ## Example from [Goos & Jones (2011), Chapter 3] ## 6 factors w/ 2 levels each data <- expand.grid( x1 = c(-1, 1), x2 = c(-1, 1), x3 = c(-1, 1), x4 = c(-1, 1), x5 = c(-1, 1), x6 = c(-1, 1) ) ## linear model w/ main effects and selected interactions design <- lm_design$new( formula = ~1 + x1 + x2 + x3 + x4 + x5 + x6 + x2:x3 + x1:x6 + x2:x6 + x3:x6 + x4:x6 + x1:x4, data = data ) ## initial design of size n=12 init_design <- c(0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1) ## approximate optimal augmented design design$augment(design_weights = init_design, gamma = 0.4, criterion = "D") ## exact augmented design (augment_design <- design$round(m = 8, method = "optimal", seed = 1, augment_design = init_design)) ## proposed design points design$subset(replicates = augment_design - init_design) ## augmented design w/ orthogonality constraints design_ortho <- design$clone() design_ortho$update( orthogonal = list( x1 + x2 + x3 + x4 + x5 + x6 ~ x1 + x2 + x3 + x4 + x5 + x6 ~ 0 ## uncorrelated main effects ) ) ## approximate augmented design design_ortho$augment( design_weights = init_design, gamma = 0.4, criterion = "D", return_value = FALSE ) if(requireNamespace("highs", quietly = TRUE)) { ## integer design w/ orthogonality constraints ortho_augment_design <- design_ortho$round( m = 8, method = "orthogonal", augment_design = init_design ) ## verify correlations design_ortho$corr(ortho_augment_design) }## Getting started ## 3 factors w/ 5, 5 and 3 levels data <- expand.grid( x1 = -2:2, x2 = -2:2, x3 = -1:1 ) design <- lm_design$new( formula = ~(x1 + x2 + x3)^2 + I(x1^2) + I(x2^2) + I(x3^2), ## full quadratic model data = data ## design points ) ## approximate D-optimal design design$optimize(criterion = "D") ## integer D-optimal design w/ 13 design points (exact_design <- design$round(m = 13, method = "optimal", seed = 1)) design$subset(replicates = exact_design) ## integer design covariance and correlation matrices design$vcov(design_weights = exact_design, sigma2 = 1) design$corr(design_weights = exact_design) ## Penalized optimal design ## assign cost c = 1 if x3 = 1, and c = 0 otherwise design$update( cost = ~pmax(x3, 0), alpha = 1 ) ## penalized approximate D-optimal design design$optimize(criterion = "D") ## assign v = 1 if x3 = 1, and v = 0.1 otherwise design$update( weights = ~pmax(x3, 0.1), cost = NULL ) ## penalized approximate D-optimal design design$optimize(criterion = "D") ## exact design w/ 15 design points design$round(m = 15, method = "optimal", seed = 1) ## drop weights term design$update(weights = NULL) ## Stratified optimal design ## add stratification constraints design$stratify( strata = ~x3, proportions = c(1/4, 1/2, 1/4) ) ## approximate D-optimal design w/ stratification design$optimize(criterion = "D") ## verify stratification tapply(design$design_weights, design$data$x3, sum) ## exact design w/ stratification design$round(m = 12, method = "optimal", seed = 1) ## drop stratification design$stratify(strata = NULL) ## Orthogonality constraints ## orthogonal main effects wrt all other columns design$update( orthogonal = x1 + x2 + x3 ~ . ~ 0, alpha = 0.075 ## sparseness penalty ) design$orthogonal ## approximate D-optimal design w/ orthogonality constraints design$optimize(criterion = "D") ## sparsify support by iterative entropy reweighting design$sparsify(max_iter = 5, criterion = "D", reweight_fun = "entropy") if(requireNamespace("highs", quietly = TRUE)) { ## integer design w/ orthogonality constraints (ortho_design <- design$round(m = 8, method = "orthogonal", seed = 1)) ## verify correlations design$corr(ortho_design) } ## Optimal design augmentation ## Example from [Goos & Jones (2011), Chapter 3] ## 6 factors w/ 2 levels each data <- expand.grid( x1 = c(-1, 1), x2 = c(-1, 1), x3 = c(-1, 1), x4 = c(-1, 1), x5 = c(-1, 1), x6 = c(-1, 1) ) ## linear model w/ main effects and selected interactions design <- lm_design$new( formula = ~1 + x1 + x2 + x3 + x4 + x5 + x6 + x2:x3 + x1:x6 + x2:x6 + x3:x6 + x4:x6 + x1:x4, data = data ) ## initial design of size n=12 init_design <- c(0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1) ## approximate optimal augmented design design$augment(design_weights = init_design, gamma = 0.4, criterion = "D") ## exact augmented design (augment_design <- design$round(m = 8, method = "optimal", seed = 1, augment_design = init_design)) ## proposed design points design$subset(replicates = augment_design - init_design) ## augmented design w/ orthogonality constraints design_ortho <- design$clone() design_ortho$update( orthogonal = list( x1 + x2 + x3 + x4 + x5 + x6 ~ x1 + x2 + x3 + x4 + x5 + x6 ~ 0 ## uncorrelated main effects ) ) ## approximate augmented design design_ortho$augment( design_weights = init_design, gamma = 0.4, criterion = "D", return_value = FALSE ) if(requireNamespace("highs", quietly = TRUE)) { ## integer design w/ orthogonality constraints ortho_augment_design <- design_ortho$round( m = 8, method = "orthogonal", augment_design = init_design ) ## verify correlations design_ortho$corr(ortho_augment_design) }
An R6 class for managing penalized optimal experiment designs for random intercept linear mixed models. This class encapsulates a random intercept linear mixed model, the discrete design grid, optimization of an approximate continuous design, augmentation of an existing design, and optimal rounding to exact integer designs including split-plot designs.
R6-object of class lme_design if called with lme_design$new().
The following penalized optimization problem is solved by $optimize():
where,
is the vector of design weights.
is the cost assigned to each design weight with scaling/penalty parameter .
is a vector of fixed user weights.
is the information matrix depending on the weights ,
the fixed-effects design matrix , the random-effects design matrix , the variance component ratio
, and in the case of weighted regression the heterogeneous weights .
is the chosen optimality criterion, generally a function of the information matrix.
Given a random intercept linear mixed model () defined by formula, the information matrix
of the fixed-effects model parameters, conditional on the random effects covariance matrix and the error variance, is given by:
where is the diagonal matrix with on the diagonal, and
is the inverse of the block-diagonal covariance matrix . Partitioned into random effects levels ,
where group has observations, consists of the level-specific blocks:
Given a vector of initial design weights and associated contribution weight ,
the following augmented penalized optimization problem is solved by $augment():
using the augmented information matrix,
The $strata() method stratifies the design by requiring that individual strata
are represented proportionally with given weights , (). If stratification is applied,
the following optimization problem is solved by $optimize():
This means that the total weight assigned to the design points in stratum is equal to for each .
Similarly, if stratification is applied, $augment() solves the augmented optimization problem with stratification
constraints.
The $round_split_plot() method rounds an approximate design to an exact (integer) split-plot design.
The rounding procedure enforces fixed levels of hard-to-change variables within each individual whole plot,
where the whole plots are the blocks in the random effects factors (i.e. whole plot variables).
Mathematically, for an exact design , the split-plot rounding procedure solves:
and are the design matrices of the hard-to-change and random effects factors subject to .
is a matrix with rows selected from the levels of the hard-to-change variables, where is the
number of whole plots. The second constraint ensures that the number of design points at each whole plot level is
exactly , the whole plot size. The split-plot designs are only available in the form of exact designs, and not approximate designs
(as returned by e.g. $optimize()).
The optimality criteria supported by $optimize() and $augment() are: D-,
A-, I-, G-, and alias-optimality, see lm_design for the definitions.
lm_design -> lme_design
formulaa two-part formula of the form ~ fix.eff ~ ran.eff representing a random intercept linear mixed model,
where fix.eff is a linear model formula encoding the fixed effects design matrix and ran.eff is an expression
encoding the levels of the random effects factor.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
etanumeric variance component ratio , where is the
(single) variance component of the random effects and is the error variance.
costan optional numeric vector containing costs associated to each design point (row) in data.
design_weightsa numeric vector with optimal design weights populated after optimization with $optimize() or $augment().
The attribute criterion lists the used design criterion and the achieved optimal criterion value.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
strataa list with elements strata and proportions imposing a partition of the design points into individual (disjoint) strata
with given weight proportions.
alphathe cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available.
lambdathe ridge penalty added to the diagonal of the information matrix in the optimization problem. The ridge penalty is not used
for the alias optimality criterion.
upperthe design weight upper limit. The default is 1, corresponding to no upper limit constraint on the design weights.
Xthe fixed effects design matrix obtained from all design points in data and the model formula.
Zthe random effects design matrix obtained from all design points in data and the model formula.
lme_design$new()Constructor. Initializes the experimental design to optimize with a linear mixed model, discrete design grid, and fixed variance component ratio.
lme_design$new( formula, data, eta, weights = NULL, cost = NULL, contrasts = NULL, alpha = 1, lambda = 0, upper = 1, ... )
formulaa two-part formula of the form ~ fix.eff ~ ran.eff, where fix.eff is
a linear model formula encoding the fixed effects design matrix and ran.eff is an expression
encoding the random effects levels. ran.eff is evaluated as a factor, with the factor levels
determining the random effects groups.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
etanumeric variance component ratio , where is the
(single) variance component of the random effects and is the error variance.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
Also accepts a one-sided formula using the column names present in data. If NULL,
the unweighted optimal design problem is solved.
costan optional numeric vector containing costs associated to each design point (row) in data.
Also accepts a one-sided formula made up of column names present in data. If NULL,
the standard (non-penalized) optimal design problem is solved.
contrastsoptional contrasts used when evaluating the fixed effects formula fix.eff.
alphanumeric value, cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available. The default is 1.
lambdanumeric value, ridge penalty added to the diagonal of the information matrix in the penalized optimization problem. The default is 0.
uppernumeric value in (0, 1], design weight upper limit. The default is 1, corresponding to no constraint on the design weights.
...any additional arguments passed to model.matrix when evaluating the fixed effects formula fix.eff.
lme_design R6-object
lme_design$update()Updates the fields of an existing object.
Inputs should be named formula, data, eta, weights, cost, alpha, lambda and/or upper respectively.
lme_design$update(...)
...named arguments formula, data, eta, weights, cost, alpha, lambda and/or upper.
none
lme_design$stratify()Stratify the design by requiring that individual strata are represented proportionally. Call with strata = NULL to
unset previously defined strata.
lme_design$stratify(strata, proportions = NULL)
strataa factor variable of the same length as the number of rows in data. The factor levels determine
the partition of the design points into individual (disjoint) strata. Also accepts a one-sided formula made up of
column names present in data, in which case the strata are defined by the interaction between terms in the
model.frame obtained from the formula.
proportionsan optional numeric vector containing the weight proportions of the individual strata. Must be of the same length
as the number of factor levels in strata. If NULL, each stratum is assigned the same weight proportion.
none
lme_design$optimize()Optimizes the penalized approximate design based on the selected criterion by iterative
reweighting of a convex approximation of the optimization problem.
"alias"-optimality is included for completeness only, as the optimality criterion
does not vary with the variance component ratio .
lme_design$optimize(
criterion = c("D", "A", "I", "G", "alias"),
max_iter = 1,
tol = .Machine$double.eps^(1/4),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE,
show_progress = TRUE
)
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
max_iterinteger number of iterations sequential convex approximation. The default is 1,
which returns the approximate design corresponding to a variance component ratio .
tolnumeric tolerance used to scale the minimum improvement threshold in the backtracking line search to determine a new set of approximate design weights.
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
show_progresslogical, display a progress bar during the rounding procedure (only if
max_iter > 1). Defaults to TRUE.
numeric vector if return_value = TRUE, otherwise none
lme_design$augment()Optimizes the augmented penalized approximate design given a vector of initial design weights
by iterative reweighting of a convex approximation of the optimization problem.
"alias"-optimality is included for completeness only, as the optimality criterion
does not vary with the variance component ratio .
lme_design$augment(
design_weights,
max_iter = 1,
gamma = 0.5,
criterion = c("D", "A", "I", "G", "alias"),
tol = .Machine$double.eps^(1/4),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE,
show_progress = TRUE
)
design_weightsa numeric vector with initial design weights, must be the same length as the number of design points in data.
Also accepts a one-sided formula made up of column names present in data.
max_iterinteger number of iterations sequential convex approximation. The default is 1,
which returns the approximate design corresponding to a variance component ratio .
gammanumeric contribution weight of the initial design in the augmented design problem, see also ‘Augmented optimal design’ above. Defaults to 0.5.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
tolnumeric tolerance used to scale the minimum improvement threshold in the backtracking line search to determine a new set of approximate design weights.
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
show_progresslogical, display a progress bar during the rounding procedure (only if
max_iter > 1). Defaults to TRUE.
numeric vector if return_value = TRUE, otherwise none
lme_design$round()Round penalized approximate design to an exact (integer) design.
The approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
For method "optimal", cost penalties and upper limit constraints present in $cost and $upper
(if specified) are included in the criterion optimized by the point-exchange procedure.
To override the initial approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If design_weights is set to FALSE,
the initial design is generated by random sampling.
lme_design$round(
m,
method = c("optimal", "efficient"),
max_iter = 100,
n_repeats = 10,
replicates = TRUE,
tol = .Machine$double.eps^(1/3),
seed = NULL,
design_weights = TRUE,
augment_design = NULL,
show_progress = TRUE,
...
)
minteger number of design points included in the exact design.
methodthe method used to calculate the exact design. The following choices are supported:
"optimal" optimality criterion point-exchange algorithm (default). |
"efficient" efficient rounding method of Pukelsheim & Reider (1992).
|
max_iterinteger number of maximum iterations in point-exchange algorithms. Only used when
method = "optimal".
n_repeatsinteger number of (random) repeats of the rounding/exchange algorithm. The exact design with the highest criterion value is returned. Defaults to 10.
replicateslogical, allow replicate design points in the exact design, defaults to TRUE.
Can also be an integer number, limiting the maximum number of allowed replicates per design point.
This argument overrides the $upper value constraint if existing.
tolnumeric tolerance used as lower threshold to continue iterations in point-exchange algorithms.
seed(optional) random seed used to generate jitter to break ties in rounding the initial exact design.
Not used in the case of (mirai) asynchronous evaluation, which requires the random seed to be set via the
seed argument in mirai::daemons.
design_weights(optional) vector of design weights used as initial approximate design, with length equal
to the number of available design points. If TRUE (default), the approximate design is initialized from the
design_weights field. If FALSE, the initial approximate design is generated by random sampling.
augment_design(optional) integer design to augment, with length equal to the number of available design points.
show_progresslogical, display a progress bar during the rounding procedure (only if
n_repeats > 1). Defaults to TRUE.
...additional arguments to tune algorithm/solver settings:
criterion, character string specifying the optimality criterion for the rounding procedure in case
design_weights has no "criterion" attribute, or to override the criterion specified in the "criterion" attribute.
If specified, must be one of "D", "A", "I", "G" or "alias".
The repeated rounding/exchange algorithms can be run in parallel using the mirai asynchronous evaluation framework.
The parallel background R processes are configured by the user outside of $round() with mirai::daemons.
If daemon connections are available, $round() automatically runs the repeated exchange algorithms in parallel
using the configured daemons. If the underlying BLAS/LAPACK libraries are already multi-threaded, this may
inhibit the use of additional threads by the mirai asynchronous evaluation. In this case, it is recommended to restrict
BLAS/LAPACK to a single thread with the OPENBLAS_NUM_THREADS, MKL_NUM_THREADS or OMP_NUM_THREADS
environment variables, depending on the BLAS library that is used. In addition, note that there is a small overhead in populating the
environments of the background R processes, which may result in increased runtime compared to sequential evaluation in the main R process,
especially when n_repeats is small or the rounding/exchange algorithm does not take much time to complete.
numeric vector
lme_design$round_split_plot()Round penalized approximate design to an exact (integer) split-plot design.
This rounding procedure enforces fixed levels of the defined hard_to_change factors within each whole plot, where the whole plots
are determined by the random effects factors in the model $formula.
Stratification constraints imposed with $stratify() are not taken into account as these are overridden by the split-plot design constraints.
The approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the initial approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
lme_design$round_split_plot( m, hard_to_change, max_iter = 100, n_repeats = 10, replicates = TRUE, tol = .Machine$double.eps^(1/3), seed = NULL, design_weights = NULL, augment_design = NULL, show_progress = TRUE, ... )
minteger whole plot size(s). If a single integer, the number of design points per level of the whole plot factor(s) is set equal to m, i.e.
the total number of design points in the split-plot design is m times the number of whole plot levels.
If a vector, the length of m must be the same as the number of whole plot levels, with the elements of m specifying the sizes of the individual whole plots.
hard_to_changehard-to-change factor variable of the same length as the number of rows in data. Also accepts
a one-sided formula made up of column names present in data, in which case the factor levels are defined by the interaction
between terms in the model.frame obtained from the formula.
max_iterinteger number of maximum iterations in point-exchange algorithms.
n_repeatsinteger number of (random) repeats of the rounding/exchange algorithm. The exact design with the highest criterion value is returned. Defaults to 10.
replicateslogical, allow replicate design points in the exact design, defaults to TRUE.
Can also be an integer number, limiting the maximum number of allowed replicates per design point.
This argument overrides the $upper value constraint if existing.
tolnumeric tolerance used a lower threshold to continue iterations in point-exchange algorithms.
seed(optional) random seed used to generate jitter to break ties in rounding the initial exact design.
Not used in the case of (mirai) asynchronous evaluation, which requires the random seed to be set via the
seed argument in mirai::daemons.
design_weights(optional) vector of design weights used as initial approximate design.
augment_design(optional) integer design to augment, with length equal to the number of available design points.
show_progresslogical, display a progress bar monitoring the repeats of the rounding/exchange procedure. Defaults to TRUE.
...additional arguments to tune algorithm settings:
criterion, character string specifying the optimality criterion for the rounding procedure in case
design_weights has no "criterion" attribute, or to override the criterion specified in the "criterion" attribute.
If specified, must be one of "D", "A", "I", or "G".
The repeated rounding/exchange algorithms can be run in parallel using the mirai asynchronous evaluation framework.
The parallel background R processes are configured by the user outside of $round() with mirai::daemons.
If daemon connections are available, $round() automatically runs the repeated exchange algorithms in parallel
using the configured daemons. If the underlying BLAS/LAPACK libraries are already multi-threaded, this may
inhibit the use of additional threads by the mirai asynchronous evaluation. In this case, it is recommended to restrict
BLAS/LAPACK to a single thread with the OPENBLAS_NUM_THREADS, MKL_NUM_THREADS or OMP_NUM_THREADS
environment variables, depending on the BLAS library that is used. In addition, note that there is a small overhead in populating the
environments of the background R processes, which may result in increased runtime compared to sequential evaluation in the main R process,
especially when n_repeats is small or the rounding/exchange algorithm does not take much time to complete.
numeric vector
lme_design$crit()Evaluate optimality criterion of a penalized approximate or rounded (exact) design.
If cost penalties are present in the $cost field, the penalized optimality criterion as described in the ‘Optimality criteria’ section of
lm_design are returned.
The approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
lme_design$crit(
design_weights = NULL,
criterion = c("D", "A", "I", "G", "alias"),
lambda = TRUE,
alpha = TRUE
)
design_weights(optional) vector of design weights for which to evaluate optimality criterion.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
lambdalogical, whether to include the ridge penalty in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if $lambda is positive.
alphalogical, whether to include cost penalties in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if cost penalties are present
in the $cost field.
numeric criterion value
lme_design$vcov()Calculates the variance-covariance matrix of the model parameters based on an approximate or rounded (exact) design according to:
Here and is the inverse of the block-diagonal covariance matrix ,
consisting of the level-specific blocks ,
with is the number of observations for random effects level .
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
Use the m argument to evaluate the covariance matrix for a specific number of design points, in which case the sum of the design weights is scaled to m.
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If the vector of design weights is already an integer design, leave
m unspecified, in which case the design is not rescaled.
lme_design$vcov(m, design_weights = NULL, sigma2 = 1)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
sigma2numeric error variance used to scale the covariance matrix. Defaults to 1, returning the unscaled covariance matrix.
numeric matrix
lme_design$sep()Calculates the standard error of prediction or the square root prediction variance across the design grid based on an approximate or rounded (exact)
design according to:
where is the covariance matrix as returned by $vcov().
Use the newdata argument to evaluate the standard error of prediction at design points not in the candidate design grid defined by $data.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
lme_design$sep(m, newdata, design_weights = NULL, sigma2 = 1)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
newdata(optional) data frame or matrix with design points (rows) for which to return the standard error of prediction and which
can be evaluated by $formula.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
sigma2numeric error variance used to scale the standard errors. Defaults to 1, returning the standardized standard error of prediction.
numeric vector
lme_design$corr()Calculates the correlation matrix of the design matrix columns based on an approximate or rounded (exact) design according to:
where and is the inverse of the block-diagonal covariance matrix .
is the design matrix centered by the (weighted) column means:
is , with the diagonal elements of .
If center = FALSE, the uncentered correlation matrix is returned, which corresponds to the scale-invariant (unit diagonal) version of the information matrix .
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
lme_design$corr(design_weights = NULL, center = TRUE, unscaled = FALSE)
design_weights(optional) vector of design weights for which to evaluate the information matrix.
centerlogical, whether to center the design columns when evaluating the correlation matrix, defaults to TRUE.
unscaledlogical value, whether to include in the calculation of . If TRUE, the ordinary
correlation matrix (without random effects) is returned.
numeric matrix
lme_design$clone()The objects of this class are cloneable with this method.
lme_design$clone(deep = FALSE)
deepWhether to make a deep clone.
## Getting started ## unbalanced design grid data <- data.frame( Treatment = c(-1, -1, 0, 0, 1, 1, -1, 0, 0, 1, -1, 1), Block = factor(rep(c("B1", "B2", "B3", "B4", "B5", "B6"), each = 2)) ) ## fixed effects quadratic model in Treatment ~ random intercepts by Block design <- lme_design$new( formula = ~ Treatment + I(Treatment^2) ~ Block, eta = 10, ## variance component ratio data = data ) ## approximate D-optimal design design$optimize(criterion = "D", max_iter = 10) ## integer design w/ 18 design points (exact_design <- design$round(m = 6, method = "optimal", seed = 1)) design$subset(replicates = exact_design) ## Split-plot design data <- expand.grid( A = -1:1, B = -1:1, C = -1:1, week = factor(1:7, levels = 1:7) ) ## two-factor interaction model w/ random week effect design <- lme_design$new( formula = ~ (A + B + C)^2 ~ week, eta = 1, data = data ) ## initial D-optimal approximate design design$optimize(criterion = "D", max_iter = 5, return_value = FALSE) ## D-optimal split-plot design w/ 3 points per whole plot ## and hard-to-change factor A exact_design <- design$round_split_plot( m = 3, hard_to_change = ~A ) design$subset(replicates = exact_design) ## Penalized optimal design design$update( cost = ~A, ## increase cost of high levels alpha = 1 ## penalty scaling term ) ## initial D-optimal approximate design design$optimize(criterion = "D", max_iter = 5, return_value = FALSE) exact_design <- design$round_split_plot( m = 3, hard_to_change = ~A ) design$subset(replicates = exact_design)## Getting started ## unbalanced design grid data <- data.frame( Treatment = c(-1, -1, 0, 0, 1, 1, -1, 0, 0, 1, -1, 1), Block = factor(rep(c("B1", "B2", "B3", "B4", "B5", "B6"), each = 2)) ) ## fixed effects quadratic model in Treatment ~ random intercepts by Block design <- lme_design$new( formula = ~ Treatment + I(Treatment^2) ~ Block, eta = 10, ## variance component ratio data = data ) ## approximate D-optimal design design$optimize(criterion = "D", max_iter = 10) ## integer design w/ 18 design points (exact_design <- design$round(m = 6, method = "optimal", seed = 1)) design$subset(replicates = exact_design) ## Split-plot design data <- expand.grid( A = -1:1, B = -1:1, C = -1:1, week = factor(1:7, levels = 1:7) ) ## two-factor interaction model w/ random week effect design <- lme_design$new( formula = ~ (A + B + C)^2 ~ week, eta = 1, data = data ) ## initial D-optimal approximate design design$optimize(criterion = "D", max_iter = 5, return_value = FALSE) ## D-optimal split-plot design w/ 3 points per whole plot ## and hard-to-change factor A exact_design <- design$round_split_plot( m = 3, hard_to_change = ~A ) design$subset(replicates = exact_design) ## Penalized optimal design design$update( cost = ~A, ## increase cost of high levels alpha = 1 ## penalty scaling term ) ## initial D-optimal approximate design design$optimize(criterion = "D", max_iter = 5, return_value = FALSE) exact_design <- design$round_split_plot( m = 3, hard_to_change = ~A ) design$subset(replicates = exact_design)
An R6 class for managing penalized locally optimal experiment designs for nonlinear models. This class encapsulates the nonlinear model at a set of nominal parameter values, the discrete design grid, optimization of an approximate continuous design, augmentation of an existing design, and optimal rounding to exact integer designs.
R6-object of class nlm_design if called with nlm_design$new().
The following penalized optimization problem is solved by $optimize():
where,
is the vector of design weights.
is the cost assigned to each design weight with scaling/penalty parameter .
is a vector of fixed user weights.
is the information matrix depending on the weights and ,
the design matrix and the nominal parameter values .
is a diagonal matrix to regularize the information matrix with ridge penalty parameter .
is the chosen optimality criterion, generally a function of the information matrix.
Given the nonlinear model f and nominal parameter values theta, the information matrix (conditional on the error variance) is given by:
where is the gradient vector at , i.e. the -th row of the Jacobian matrix.
Given a vector of initial design weights and associated contribution weight ,
the following augmented penalized optimization problem is solved by $augment():
using the augmented information matrix,
The $strata() method stratifies the design by requiring that individual strata
are represented proportionally with given weights , (). If stratification is applied,
the following optimization problem is solved by $optimize():
using the same notation as in the ‘Optimal design problem’ section above. This means that the total weight
assigned to the design points in stratum is equal to for each .
Similarly, if stratification is applied, $augment() solves the augmented optimization problem with stratification
constraints.
The $sparsify() method solves the penalized optimization problem with an extra sparseness penalty
in the objective to promote sparsity in the approximate design . See lm_design for the available penalty functions.
The optimality criteria supported by $optimize(), $augment() and $sparsify() are: D-,
A-, I-, G-, and alias-optimality, see lm_design for the definitions.
lm_design -> nlm_design
formulaa nonlinear model defined as a one-sided formula.
thetaa named vector or list of nominal parameter values at which the information matrix is evaluated.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
costan optional numeric vector containing costs associated to each design point (row) in data.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
design_weightsa numeric vector with optimal design weights populated after optimization with $optimize(), $augment(), or $sparsify().
The attribute criterion lists the used design criterion and the achieved optimal criterion value.
strataa list with elements strata and proportions imposing a partition of the design points into individual (disjoint) strata
with given weight proportions.
alphathe cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available.
lambdathe ridge penalty added to the diagonal of the information matrix in the optimization problem. The ridge penalty is not used
for the alias optimality criterion.
upperthe design weight upper limit. The default is 1, corresponding to no upper limit constraint on the design weights.
Xthe Jacobian matrix obtained from all design points in data and the model formula.
nlm_design$new()Constructor. Initializes the experimental design to optimize with a nonlinear model formula and discrete design grid.
nlm_design$new( formula, data, theta, weights = NULL, cost = NULL, alpha = 1, lambda = 0, upper = 1 )
formulaa nonlinear model defined as a one-sided formula.
dataa data frame or matrix containing all design points (rows) at which formula can be evaluated.
thetaa named vector or list of nominal parameter values at which the information matrix is evaluated.
weightsan optional numeric vector containing fixed user weights associated to each design point (row) in data.
Also accepts a one-sided formula made up of column names present in data. If NULL,
the unweighted optimal design problem is solved.
costan optional numeric vector containing costs associated to each design point (row) in data.
Also accepts a one-sided formula made up of column names present in data. If NULL,
the standard (non-penalized) optimal design problem is solved.
alphanumeric value, cost scale/penalty parameter in the penalized optimization problem, only used if $cost is available. The default is 1.
lambdanumeric value, ridge penalty added to the diagonal of the information matrix in the penalized optimization problem. The default is 0.
uppernumeric value in (0, 1], design weight upper limit. The default is 1, corresponding to no constraint on the design weights.
nlm_design R6-object
nlm_design$update()Updates the fields of an existing object.
Inputs should be named formula, data, theta, weights, cost, alpha, lambda and/or upper.
nlm_design$update(...)
...named arguments formula, data, theta, weights, cost, alpha, lambda and/or upper.
none
nlm_design$stratify()Stratify the design by requiring that individual strata are represented proportionally. Call with strata = NULL to
unset previously defined strata.
nlm_design$stratify(strata, proportions = NULL)
strataa factor variable of the same length as the number of rows in data. The factor levels determine
the partition of the design points into individual (disjoint) strata. Also accepts a one-sided formula made up of
column names present in data, in which case the strata are defined by the interaction between terms in the
model.frame obtained from the formula.
proportionsan optional numeric vector containing the weight proportions of the individual strata. Must be of the same length
as the number of factor levels in strata. If NULL, each stratum is assigned the same weight proportion.
none
nlm_design$augment()Optimizes the augmented penalized approximate design given a vector of initial design weights
nlm_design$augment(
design_weights,
gamma = 0.5,
criterion = c("D", "A", "I", "G", "alias"),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE
)
design_weightsa numeric vector with initial design weights, must be the same length as the number of design points in data.
Also accepts a one-sided formula made up of parameters in theta and column names in data.
gammanumeric contribution weight of the initial design in the augmented design problem, see also ‘Augmented optimal design’ above. Defaults to 0.5.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
numeric vector if return_value = TRUE, otherwise none
nlm_design$optimize()Optimizes the penalized approximate design based on the selected criterion.
nlm_design$optimize(
criterion = c("D", "A", "I", "G", "alias"),
scs_control = scs_control_dflt(),
verbose = FALSE,
return_value = TRUE
)
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
verbosedisplay verbose messages printed by the scs solver. Defaults to FALSE.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
numeric vector if return_value = TRUE, otherwise none
nlm_design$sparsify()Sparsify the penalized approximate design by iterative reweighting of the optimization problem.
nlm_design$sparsify(
max_iter,
criterion = c("D", "A", "I", "G", "alias"),
reweight_fun = c("entropy", "log-sum", "power"),
eps = .Machine$double.eps,
tol = .Machine$double.eps^(1/4),
p = 0.5,
design_weights = NULL,
scs_control = scs_control_dflt(),
return_value = TRUE,
show_progress = TRUE
)
max_iterpositive integer, maximum number of reweighted optimizations/iterations to run.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
reweight_funcharacter reweighting function, one of "entropy", "log-sum", "power", see lm_design for the definitions.
epspositive numeric value to ensure finite weights in reweighting functions.
tolnumeric tolerance used as a threshold for mean absolute relative difference in design weights between iterations to stop early.
ppositive numeric power with . Only used if reweight_fun = "power".
design_weights(optional) vector of design weights used as initial approximate design.
scs_controlan optional list of control parameters to tune the SCS optimization. See scs_control_dflt
for the available control parameters and their default values.
return_valuereturn the optimal design weights. If set to FALSE, the design weights should be retrieved from the design_weights field.
show_progresslogical, display a progress bar during the iterative reweighting procedure. Defaults to TRUE.
The sparseness cost penalties are scaled by the same alpha tuning parameter as for a user-specific cost vector, see scs_control_dflt.
If a cost vector c_1,...,c_n associated to the design weights is already specified. The sparseness penalty costs are multiplied
by the existing cost vector.
numeric vector if return_value = TRUE, otherwise none
nlm_design$round()Round penalized approximate design to an exact (integer) design.
By default, the approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
For method "optimal", ridge and cost penalties and upper limit constraints present in $lambda, $cost and $upper
(if specified) are included in the criterion optimized by the point-exchange algorithm.
To override the initial approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If design_weights is set to FALSE,
the initial design is generated by random sampling.
nlm_design$round(
m,
method = c("optimal", "efficient", "dist-sum", "dist-min"),
max_iter = 100,
n_repeats = 10,
replicates = TRUE,
tol = .Machine$double.eps^(1/3),
seed = NULL,
design_weights = TRUE,
augment_design = NULL,
show_progress = TRUE,
...
)
minteger number of design points included in the exact design.
methodthe method used to calculate the exact design. The following choices are supported:
"optimal" optimality criterion point-exchange algorithm (default). |
"efficient" efficient rounding method of Pukelsheim & Reider (1992). |
"dist-sum" maximize total pairwise (Euclidean) distance between design points. |
"dist-min" maximize minimum pairwise (Euclidean) distance between design points.
|
max_iterinteger number of maximum iterations in point-exchange algorithm. Only used when
method = "optimal", method = "dist-sum" or method = "dist-min".
n_repeatsinteger number of (random) repeats of the rounding/exchange algorithm. The exact design with the highest criterion value is returned. Defaults to 10.
replicateslogical, allow replicate design points in the exact design, defaults to TRUE.
Can also be an integer number, limiting the maximum number of allowed replicates per design point.
This argument overrides the $upper value constraint if existing.
tolnumeric tolerance used as lower threshold to continue iterations in point-exchange algorithm.
seed(optional) random seed used to generate jitter to break ties in rounding the initial exact design.
design_weights(optional) vector of design weights used as initial approximate design, with length equal
to the number of available design points. If TRUE (default), the approximate design is initialized from the
design_weights field. If FALSE, the initial approximate design is generated by random sampling.
augment_design(optional) integer design to augment, with length equal to the number of available design points.
show_progresslogical, display a progress bar during the rounding procedure (only if
n_repeats > 1). Defaults to TRUE.
...additional arguments to tune algorithm settings:
criterion, character string specifying the optimality criterion for the rounding procedure in case
design_weights has no "criterion" attribute, or to override the criterion specified in the "criterion" attribute.
If specified, must be one of "A", "I", "D", "G" or "alias".
numeric vector
nlm_design$crit()Evaluate optimality criterion of a penalized approximate or rounded (exact) design.
The approximate design is initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design, a vector of design weights can be passed using the design_weights argument.
nlm_design$crit(
design_weights = NULL,
criterion = c("D", "A", "I", "G", "alias"),
lambda = TRUE,
alpha = TRUE
)
design_weights(optional) vector of design weights for which to evaluate optimality criterion.
criterioncharacter string specifying the optimality criterion to use, see also ‘Details’. The following choices are supported:
"D" D-optimality (default). |
"A" A-optimality. |
"I" I-optimality. |
"G" G-optimality. |
"alias" alias-optimality.
|
lambdalogical, whether to include the ridge penalty in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if $lambda is positive.
alphalogical, whether to include cost penalties in the calculated optimality criterion (see ‘Optimality criteria’). Only relevant if cost penalties are present
in the $cost field.
numeric criterion value
nlm_design$vcov()Calculates the variance-covariance matrix of the model parameters based on an approximate or rounded (exact) design according to:
where is with , and is the Jacobian matrix at the nominal parameter values.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
Use the m argument to evaluate the covariance matrix for a specific number of design points, in which case the sum of the design weights is scaled to m.
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data. If the vector of design weights is already an integer design, leave
m unspecified, in which case the design is not rescaled.
nlm_design$vcov(m, design_weights = NULL, sigma2 = 1)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
sigma2numeric error variance used to scale the covariance matrix. Defaults to 1, returning the unscaled covariance matrix.
numeric matrix
nlm_design$sep()Calculates the standard error of prediction or the square root prediction variance across the design grid based on an approximate or rounded (exact)
design according to:
where is the covariance matrix as returned by $vcov().
Use the newdata argument to evaluate the standard error of prediction at design points not in the candidate design grid defined by $data.
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
nlm_design$sep(m, newdata, design_weights = NULL, sigma2 = 1)
m(optional) integer number of design points at which to evaluate the estimated covariance matrix. If missing, the
design weights remain unscaled, which for the default approximate (optimal) design is equivalent to m = 1.
newdata(optional) data frame or matrix with design points (rows) at which to return the standard error of prediction and which
can be evaluated by $formula.
design_weights(optional) vector of design weights for which to evaluate the estimated covariance matrix.
sigma2numeric error variance used to scale the standard errors. Defaults to 1, returning the standardized standard error of prediction.
numeric vector
nlm_design$corr()Calculates the correlation matrix of the columns of the Jacobian matrix based on an approximate or rounded (exact) design according to:
where is with , and is the Jacobian matrix centered by the (weighted)
column means:
Furthermore, is , with the diagonal elements of .
If center = FALSE, the uncentered correlation matrix is returned, which corresponds to the scale-invariant (unit diagonal) version of the information matrix .
The design weights are initialized from the design_weights field, which is the optimal (approximate) design calculated by $optimize().
To override the default approximate (optimal) design weights, a vector of design weights can be passed using the design_weights argument.
The vector must be the same length as the number of design points in data.
nlm_design$corr(design_weights = NULL, center = TRUE)
design_weights(optional) vector of design weights for which to evaluate the information matrix.
centerlogical, whether to center the Jacobian columns when evaluating the correlation matrix, defaults to TRUE.
numeric matrix
nlm_design$clone()The objects of this class are cloneable with this method.
nlm_design$clone(deep = FALSE)
deepWhether to make a deep clone.
## Lubricant example from [Bates & Watts (1998), Appendix 1, A1.8] ## design grid data <- expand.grid( x1 = seq(from = 0, to = 100, by = 10), ## temp. (C) x2 = seq(from = 0, to = 7, by = 0.5) ## pressure (atm) ) ## initialize model, nominal parameters and design grid design <- nlm_design$new( formula = ~b1/(b2 + x1) + b3 * x2 + b4 * x2^2 + b5 * x2^3 + (b6 * x2 + b7 * x2^3) * exp(-x1/(b8 + b9 * x2^2)), theta = c(b1 = 1054.541, b2 = 206.546, b3 = 1.46, b4 = -0.26, b5 = 0.023, b6 = 0.401, b7 = 0.035, b8 = 57.405, b9 = -0.477), data = data ) ## approximate I-optimal design design$optimize(criterion = "I") ## integer design w/ 11 design points (exact_design <- design$round(m = 11, method = "optimal", seed = 1)) design$subset(replicates = exact_design) ## Penalized optimal design design$update( cost = ~abs(x1 - 25) / 100 + abs(x2 - 1) / 7, ## condition weights alpha = 0.1, upper = 0.1 ## max weight per point ) ## re-optimize design$optimize(criterion = "I") ## optimal rounding w/ penalization design$round(m = 14, method = "optimal", seed = 1) ## Stratified optimal design design$update( cost = NULL, ## drop cost penalties data = subset(data, x1 %in% c(0, 20, 40, 100)) ) ## partition design space by temperature conditions ## by default, equal weight proportions are assigned to each condition design$stratify( strata = ~x1 ) ## stratified optimal design design$optimize(criterion = "I") ## verify stratification tapply(design$design_weights, design$data$x1, sum) ## optimal rounding w/ stratification design$round(m = 12, method = "optimal", seed = 1)## Lubricant example from [Bates & Watts (1998), Appendix 1, A1.8] ## design grid data <- expand.grid( x1 = seq(from = 0, to = 100, by = 10), ## temp. (C) x2 = seq(from = 0, to = 7, by = 0.5) ## pressure (atm) ) ## initialize model, nominal parameters and design grid design <- nlm_design$new( formula = ~b1/(b2 + x1) + b3 * x2 + b4 * x2^2 + b5 * x2^3 + (b6 * x2 + b7 * x2^3) * exp(-x1/(b8 + b9 * x2^2)), theta = c(b1 = 1054.541, b2 = 206.546, b3 = 1.46, b4 = -0.26, b5 = 0.023, b6 = 0.401, b7 = 0.035, b8 = 57.405, b9 = -0.477), data = data ) ## approximate I-optimal design design$optimize(criterion = "I") ## integer design w/ 11 design points (exact_design <- design$round(m = 11, method = "optimal", seed = 1)) design$subset(replicates = exact_design) ## Penalized optimal design design$update( cost = ~abs(x1 - 25) / 100 + abs(x2 - 1) / 7, ## condition weights alpha = 0.1, upper = 0.1 ## max weight per point ) ## re-optimize design$optimize(criterion = "I") ## optimal rounding w/ penalization design$round(m = 14, method = "optimal", seed = 1) ## Stratified optimal design design$update( cost = NULL, ## drop cost penalties data = subset(data, x1 %in% c(0, 20, 40, 100)) ) ## partition design space by temperature conditions ## by default, equal weight proportions are assigned to each condition design$stratify( strata = ~x1 ) ## stratified optimal design design$optimize(criterion = "I") ## verify stratification tapply(design$design_weights, design$data$x1, sum) ## optimal rounding w/ stratification design$round(m = 12, method = "optimal", seed = 1)
Allow the user to tune the parameters of the SCS solver procedure.
scs_control_dflt( maxiter = 1e+05, eps_rel = 1e-05, eps_abs = 1e-05, eps_infeas = 1e-07, alpha_relax = 1.5, rho_x = 1e-06, scale = 0.1, normalize = TRUE, acceleration_lookback = 10, acceleration_interval = 5, adaptive_scale = TRUE, adaptive_diag_scale = TRUE, time_limit_secs = 60 )scs_control_dflt( maxiter = 1e+05, eps_rel = 1e-05, eps_abs = 1e-05, eps_infeas = 1e-07, alpha_relax = 1.5, rho_x = 1e-06, scale = 0.1, normalize = TRUE, acceleration_lookback = 10, acceleration_interval = 5, adaptive_scale = TRUE, adaptive_diag_scale = TRUE, time_limit_secs = 60 )
maxiter |
positive integer, maximum number of iterations to run. |
eps_rel |
positive numeric, relative feasibility tolerance. |
eps_abs |
positive numeric, absolute feasibility tolerance. |
eps_infeas |
positive numeric, infeasibility tolerance (primal and dual). |
alpha_relax |
numeric value in (0, 2), douglas-Rachford relaxation parameter. |
rho_x |
positive numeric, primal scale factor. |
scale |
positive numeric, initial dual scale factor, updated if |
normalize |
logical, whether to perform heuristic data rescaling. |
acceleration_lookback |
positive integer, relative amount of memory used for Anderson acceleration.
More memory requires more time to compute but can give more reliable steps. If |
acceleration_interval |
positive integer, run Anderson acceleration every |
adaptive_scale |
logical, whether to heuristically adapt dual scale through the solve. |
adaptive_diag_scale |
logical, whether to refine the metric R per row, using the primal residual profile. Requires |
time_limit_secs |
positive numeric, time limit for solve run in seconds (can be fractional). The value 0 is interpreted as no limit. The default is 60. |
A list with components:
maxiter
eps_rel
eps_abs
eps_infeas
alpha_relax
rho_x
scale
normalize
acceleration_lookback
acceleration_interval
adaptive_scale
adaptive_diag_scale
time_limit_secs
with meanings as explained under 'Arguments'.
https://www.cvxgrp.org/scs/api/settings
## default tuning parameters scs_control_dflt()## default tuning parameters scs_control_dflt()