Set initial estimates in parameter records

Source: R/set-param.R

set_theta(), set_omega(), and set_sigma() enable updating THETA, OMEGA, and SIGMA records by specifying a full-length parameter vector or matrix. These functions handle mapping from the parameter space to the corresponding option.

set_theta(records, values, fmt = "%.3G", bounds = c("keep", "discard"))

set_omega(records, values, fmt = "%.3G", representation = c("keep", "reset"))

set_sigma(records, values, fmt = "%.3G", representation = c("keep", "reset"))

Arguments

records

An nmrec_ctl_records object.

values

Overwrite the parameter's initial estimates in records with these values. The length must match the full length defined by the combination of the parameter's records.

For THETA, values must be a vector. For OMEGA and SIGMA, values can be

  1. the square matrix, in which case the values in the lower triangle (including the diagonal) are used

  2. a vector in row-major order for values in the lower triangle (including diagonal).

Use NA in values to skip updating the corresponding option.

fmt

Convert each value to a string with this sprintf() format specifier.

bounds

Whether to keep or discard the existing bounds when setting the initial estimates in THETA records.

representation

Whether to keep alternative representation options like SD and CORRELATION or reset to the default representation (variance and covariance).

For OMEGA and SIGMA records, NONMEM supports specifying diagonal and off-diagonal initial estimates in a different representation than the default, variance and covariance. If values are the final estimates from a previous NONMEM run, the alternative representation options should be discarded because NONMEM always outputs variances and covariances.

NA values can lead to records and options being "untouched" (i.e. not overwritten with the value from values). Even when "reset" is specified, alternative options are not discarded for untouched records (in the case of BLOCK records, where the option applies to all values in the block) or for untouched options (in the case of DIAGONAL records, where the options apply to individual initial estimates).

Details

Constraints and limitations

  • These functions update initial estimates only if they are explicitly defined in the control stream.

    For example, consider the update of $THETA (1)x4. That defines four initial estimates, but only the first explicitly appears. Calling set_theta() with a value of c(5, 6, 7, 8) gives a result of (5)x4.

  • The caller must specify a value with a size that matches what is defined by the parameter records.

  • Using additional parameter records for priors is not supported and will lead to a size mismatch between the parameter and its records. Instead use more specific record names (such as THETAP and THETAPV).

See also

set_record_option() for setting option by name, extract_param for getting a vector or matrix of initial estimates

Examples

ctl <- parse_ctl(c(
  "$PROBLEM ex",
  "$THETA 2",
  "$THETA (30)x2",
  "$OMEGA BLOCK(3)",
  "0.1",
  "0.01 0.1",
  "0.01 0.01 0.1"
))
set_theta(ctl, c(10, 40, 20))
ctl
#> $PROBLEM ex
#> $THETA 10
#> $THETA (40)x2
#> $OMEGA BLOCK(3)
#> 0.1
#> 0.01 0.1
#> 0.01 0.01 0.1

new_omega <- matrix(
  c(
    0.5, 0.2, 0.2,
    0.2, NA, 0.2,
    0.2, 0.2, 0.7
  ),
  nrow = 3, byrow = TRUE
)
# The upper triangle doesn't come into play; let's zero it for clarity, but
# it would be fine to leave as is.
new_omega[upper.tri(new_omega)] <- 0
new_omega
#>      [,1] [,2] [,3]
#> [1,]  0.5  0.0  0.0
#> [2,]  0.2   NA  0.0
#> [3,]  0.2  0.2  0.7
set_omega(ctl, new_omega)
ctl
#> $PROBLEM ex
#> $THETA 10
#> $THETA (40)x2
#> $OMEGA BLOCK(3)
#> 0.5
#> 0.2 0.1
#> 0.2 0.2 0.7