opt_des: Calculates the optimal design for a specified criterion

In optedr: Calculating Optimal and D-Augmented Designs for Single- and Multi-Factor Models

Calculates the optimal design for a specified criterion

Description

The opt_des function calculates the optimal design for an optimality criterion and a model input from the user. Supports single-factor models (design variable named x) and multi-factor models (design variables named x1, x2, ..., detected automatically from the formula).

Usage

opt_des(
  criterion,
  model,
  parameters,
  par_values = c(1),
  design_space,
  init_design = NULL,
  join_thresh = -1,
  delete_thresh = 0.02,
  delta = 1/2,
  tol = 1e-05,
  tol2 = 1e-05,
  par_int = NULL,
  matB = NULL,
  reg_int = NULL,
  max_iter = 21L,
  distribution = NA,
  weight_fun = function(x) 1,
  compound = NULL,
  rival_model = NULL,
  rival_params = NULL,
  rival_pars = NULL,
  family = "Normal",
  phi = 1,
  rival_lower = NULL,
  rival_upper = NULL,
  kl_fun = NULL
)

Arguments

criterion	character variable with the chosen optimality criterion.
model	formula describing the model. For single-factor models use x as the design variable; for multi-factor models use x1, x2, etc.
parameters	character vector with the parameter names.
par_values	numeric vector with the nominal parameter values.
design_space	For single-factor models: numeric vector c(min, max). For multi-factor models: named list list(x1 = c(min, max), x2 = c(min, max), ...).
init_design	optional dataframe with the initial design. For single-factor models use columns Point and Weight; for multi-factor models use one column per design variable plus Weight.
join_thresh	optional numeric threshold for merging nearby design points.
delete_thresh	optional numeric minimum weight to keep a support point.
delta	optional numeric in (0, 1), damping parameter of the algorithm.
tol	optional numeric for convergence of the weight loop.
tol2	optional numeric for the outer stop condition.
par_int	optional numeric vector of parameter indices for Ds-optimality.
matB	optional k x k matrix for L-optimality.
reg_int	optional bounds for the I-optimality integration region. Single-factor: c(min, max). Multi-factor: named list matching design_space.
max_iter	optional integer maximum number of outer cocktail iterations.
distribution	character variable specifying the response distribution.
weight_fun	optional variance-structure weight function.
compound	optional list of criterion specifications for criterion = "Compound". Each element must be a named list with at least criterion (character) and weight (positive numeric). Additional fields per sub-criterion: par_int (Ds-Optimality), reg_int (I-Optimality), matB (L-Optimality). Weights are normalised to sum to 1. Example: list(list(criterion="D-Optimality", weight=0.7), list(criterion="I-Optimality", weight=0.3, reg_int=c(380,422))).
rival_model	optional formula for the rival model used with criterion = "KL-Optimality". Defaults to model (same structure, rival parameters explored by inner optimisation).
rival_params	optional character vector of rival model parameter names. Defaults to parameters.
rival_pars	optional numeric vector of initial rival parameter values for the inner optimisation. Defaults to par_values.
family	character; GLM family for criterion = "KL-Optimality". One of "Normal", "Poisson", "Binomial", "Gamma". Default "Normal".
phi	positive numeric dispersion parameter for KL-Optimality. Default 1.
rival_lower	optional numeric vector of lower bounds for rival parameters in the inner optimisation. Defaults to -Inf for each parameter.
rival_upper	optional numeric vector of upper bounds for rival parameters in the inner optimisation. Defaults to Inf for each parameter.
kl_fun	optional user-supplied function(x, beta2) giving the point KL divergence at design point x for rival parameters beta2, as built by make_kl_fun. When provided, bypasses the family/rival_model path entirely; rival_pars must still be supplied for the inner optimisation.

Value

a list of class optdes with components optdes, convergence, sens, criterion, crit_value, and atwood.

Examples

# Single-factor (backward compatible)
opt_des("D-Optimality", y ~ a * exp(-b / x), c("a", "b"), c(1, 1500), c(212, 422))


# Two-factor Michaelis-Menten bisubstrate model
opt_des("D-Optimality",
        y ~ Vmax * x1 * x2 / ((K1 + x1) * (K2 + x2)),
        c("Vmax", "K1", "K2"), c(1, 1, 1),
        list(x1 = c(0.1, 10), x2 = c(0.1, 10)))

# Compound D+I (70% D, 30% I) for Antoine equation
opt_des("Compound",
        y ~ 10^(a - b/(c + x)), c("a","b","c"),
        c(8.07131, 1730.63, 233.426), c(1, 100),
        compound = list(
          list(criterion = "D-Optimality", weight = 0.7),
          list(criterion = "I-Optimality", weight = 0.3, reg_int = c(60, 100))
        ))

# KL-Optimality: discriminate quadratic from linear mean model (Normal)
opt_des("KL-Optimality",
        model        = y ~ a * x^2,
        parameters   = c("a"),
        par_values   = c(1),
        design_space = c(1, 5),
        rival_model  = y ~ b * x,
        rival_params = c("b"),
        rival_pars   = c(3),
        family       = "Normal",
        phi          = 1)

optedr documentation built on June 23, 2026, 5:07 p.m.