Package {OptOR}

OptOR: Optimal Hyperrectangular Operating Regions

Description

OptOR provides methods for computing optimal axis-aligned hyperrectangles in discrete binary arrays and continuous regions defined by quadratic response functions.

Details

The package includes methods for discrete optimization, grid classification, continuous refinement, and exact global extrema calculations.

Author(s)

Maintainer: Christian Palmes christian.palmes@bayer.com

Authors:

• Christian Palmes christian.palmes@bayer.com

Other contributors:

• Bayer AG [copyright holder]

• Raluca Ilinca Schmitt raluca_ilinca.schmitt@bayer.com [contributor]

• Adrian Funke adrian.funke@bayer.com [contributor]

Construct and Classify a Quadratic-Response Grid

Description

Constructs a regular grid over a continuous factor region and classifies either the grid points or the associated axis-aligned subboxes according to one or more quadratic response-surface models and their specified lower and upper response limits.

Usage

calc_X(fcts, n, rg_ll, rg_ul, gmode = "conservative")

Arguments

Details

For subbox-based classification, a value of 1 indicates that the complete subbox satisfies all response constraints, whereas a value of 0 indicates that the complete subbox is infeasible. A value of 2 identifies a boundary subbox that contains both feasible and infeasible points. In conservative mode, such boundary subboxes are treated as infeasible; in optimistic mode, they are treated as feasible. In point mode, the classification is instead performed directly at the grid points.

The resulting array provides a discrete inner or outer approximation of the continuous feasible region and can be passed to the optimization routines for identifying grid-aligned or continuously refined hyperrectangular operating regions.

Value

A list with components:

code

Integer status code: 0 for success and -1 for an error reported by the native implementation.

X

An integer array with dimensions rep(n, d) if code == 0; otherwise NULL. Values are 0 for invalid, 1 for valid, and 2 for indefinite grid elements.

gmode

The grid-classification mode used.

n

The grid resolution per coordinate.

d

The number of factor dimensions.

num_fcts

The number of quadratic functions used.

Examples

fcts <- list(
  list(
    c = 0,
    b = c(0, 0),
    Q = diag(2),
    lim_ll = 0.25,
    lim_ul = 1
  )
)

calc_X(
  fcts = fcts,
  n = 20,
  rg_ll = c(-1, -1),
  rg_ul = c(1, 1),
  gmode = "conservative"
)

Convert coefficient vectors to OptOR quadratic functions

Description

Converts named regression coefficient vectors into the quadratic-function representation used by OptOR,

f(x) = c + b^\top x + x^\top Qx.

Usage

coef_to_cbQ(coefficients, factors)

Arguments

Details

Interaction coefficients are split equally between the two symmetric off-diagonal entries of Q. Thus, a fitted term with coefficient \beta_{AB} for AB is represented by Q_{AB} = Q_{BA} = \beta_{AB}/2, so that ⁠x' Q x⁠ reproduces the original interaction coefficient.

Equivalent term labels are not allowed within the same coefficient vector. For example, "A:B" and "B:A" denote the same interaction, while "I(A^2)" and "I(A * A)" denote the same pure quadratic term.

Value

A named list with one element per response. Each response element is a list with components:

c

The intercept as a numeric scalar. If no intercept was supplied, 0.

b

A named numeric vector of linear coefficients in the order given by factors. Missing linear terms are represented by 0.

Q

A named symmetric numeric matrix of quadratic coefficients with rows and columns ordered according to factors. Missing terms are represented by 0.

The factor vector is additionally stored as the "factors" attribute of the returned list.

See Also

lm_to_cbQ()

Examples

coefficients <- list(
  yield = c(
    "(Intercept)" = -254.0857,
    time = 8.993016,
    temp = -0.750000,
    "I(time^2)" = -0.06202356,
    "time:temp" = 0.01
  ),
  viscosity = c(
    "(Intercept)" = -9954.86,
    time = -0.03105469,
    temp = 115.05, 
    "I(temp * temp)" = -0.33
  )
)

coef_to_cbQ(
  coefficients = coefficients,
  factors = c("time", "temp")
)

Find extrema of a quadratic fct on a hyperrectangle

Description

Computes the global minimum and maximum of a quadratic function

q(x) = c + b^\top x + x^\top Qx

over a continuous axis-aligned hyperrectangle.

Usage

find_extrema(fct, hr_ll, hr_ul)

Arguments

Value

A list with components:

code

Integer status code: 0 for success and -1 for an error reported by the native implementation.

min

The global minimum, or NA_real_ if no result was returned.

max

The global maximum, or NA_real_ if no result was returned.

argmin

A point at which the minimum is attained, or NULL.

argmax

A point at which the maximum is attained, or NULL.

Examples

fct <- list(
  c = 0,
  b = c(0, 0),
  Q = diag(2)
)

find_extrema(
  fct = fct,
  hr_ll = c(-1, -2),
  hr_ul = c(1, 2)
)

Convert fitted linear models to OptOR quadratic functions

Description

Converts a list of fitted lm models into the quadratic-function representation used by OptOR,

f(x) = c + b^\top x + x^\top Qx.

Usage

lm_to_cbQ(models, factors)

Arguments

Details

This function extracts the named coefficient vector from each model and passes the resulting list to coef_to_cbQ(). Consequently, the fitted model may contain only an optional intercept, untransformed linear terms, pure quadratic terms written as I(A^2) or I(A * A), and two-factor interactions written as A:B.

Models with aliased or otherwise non-finite coefficients are rejected. Categorical effects, transformations other than the supported pure quadratic terms, and interactions involving transformed variables are not supported.

Value

A named list with one element per model. Each element contains the components c, b, and Q describing the fitted response as c + b^\top x + x^\top Qx. See coef_to_cbQ() for the precise structure. The factor vector is additionally stored as the "factors" attribute of the returned list.

See Also

coef_to_cbQ()

Examples

dat <- data.frame(
  yield = c(76.5, 77.0, 78.0, 79.5, 79.9, 80.3, 78.4, 75.6),
  viscosity = c(62, 60, 66, 59, 72, 69, 68, 71),
  time = c(80, 80, 90, 90, 85, 85, 92.07, 77.93),
  temp = c(170, 180, 170, 180, 175, 175, 175, 175)
  )

models <- list(
  yield = lm(yield ~ time + temp + I(time^2) + time:temp, data = dat),
  viscosity = lm(viscosity ~ time + temp + I(temp^2), data = dat)
)

lm_to_cbQ(
  models = models,
  factors = c("time", "temp")
)

Compute inner and outer continuous operating rectangles

Description

Finds a grid-based continuous axis-aligned operating hyperrectangle for regions defined by quadratic response limits. In conservative mode, the function returns a guaranteed feasible hyperrectangle obtained from the globally optimal conservative grid hyperrectangle followed by continuous expansion. In optimistic mode, it returns an outer hyperrectangle whose volume provides a global upper bound on the unknown maximum feasible continuous volume.

Usage

optimal_cont_hr(
  fcts,
  n,
  rg_ll,
  rg_ul,
  ctype = NULL,
  cwidth = NULL,
  cll = NULL,
  cul = NULL,
  gmode = "conservative",
  verbose = TRUE
)

Arguments

Value

A list with components:

code

Integer status code: 0 if a hyperrectangle was found, -1 if none was found, and -2 if an error occurred.

ll

Continuous lower bounds of the returned hyperrectangle, or NULL.

ul

Continuous upper bounds of the returned hyperrectangle, or NULL.

volume

Continuous volume of the returned hyperrectangle, or NA_real_.

gmode

The grid-classification mode used.

Examples

fcts <- list(
  list(
    c = 0,
    b = c(0, 0),
    Q = diag(2),
    lim_ll = 0.25,
    lim_ul = 1
  )
)

optimal_cont_hr(
  fcts = fcts,
  n = 100,
  rg_ll = c(-1, -1),
  rg_ul = c(1, 1),
  verbose = FALSE
)

Find an optimal hyperrectangle in a binary grid

Description

Finds a maximum-volume axis-aligned hyperrectangle consisting entirely of feasible grid cells in a binary matrix or array. Optional constraints can require the returned hyperrectangle to contain a prescribed interval or to have a minimum width in selected dimensions.

Usage

optimal_grid_hr(
  X,
  ctype = NULL,
  cwidth = NULL,
  cll = NULL,
  cul = NULL,
  verbose = TRUE
)

Arguments

Details

X must be a binary array containing only the values 0 and 1, where 1 denotes a feasible grid cell and 0 an infeasible grid cell. The array is expected to use column-major order, following the usual R convention.

Value

A list with components:

code

Integer status code: 0 if a hyperrectangle was found, -1 if none was found, and -2 if an error occurred.

ll

One-based lower grid indices, or NULL if no solution was returned.

ul

One-based upper grid indices, or NULL if no solution was returned.

vol

Number of grid cells in the returned hyperrectangle, or NA_integer_ if no solution was returned.

Examples

X <- matrix(
  c(
    1, 1, 0,
    1, 1, 0,
    0, 1, 1
  ),
  nrow = 3,
  byrow = TRUE
)

optimal_grid_hr(X, verbose = FALSE)