Extract initial estimates from parameter records

Construct a numeric object from initial estimates defined by control stream records:

• extract_theta() returns a vector of initial estimates defined by THETA records.

• extract_omega() and extract_sigma() return a matrix of initial estimates for OMEGA and SIGMA records.

extract_theta(records, mark_flags = NULL, type = c("init", "low", "up"))

extract_omega(records, mark_flags = NULL)

extract_sigma(records, mark_flags = NULL)

Arguments

records

An nmrec_ctl_records object.

mark_flags

A vector of NONMEM flags (i.e. valueless options such as FIXED or SD). For each specified flag, construct a boolean vector (for THETA) or matrix (for OMEGA and SIGMA) indicating whether the flag is "active" for the value. Any valid spelling of the flag name is allowed.

For example, passing a value of "fix" would indicate whether a FIXED flag is in effect for each value. The flag may be linked to an individual initial estimate (e.g., FIXED for a THETA or diagonal OMEGArecord) or linked to all values in the record (e.g., FIXED for a THETA or block OMEGA record). In either case, the boolean vector or matrix is always the same shape as the return value.

The same result will be returned regardless of type. For example, passing mark_flags = "fix" and type = "up" would yield TRUE for a THETA initial estimate of (1,2 FIX).

The results are stored in a named list as the "nmrec_flags" attribute attached to the return value, with the names corresponding to the resolved flag names.

type

Which THETA value to return: initial estimate ("init", the default), the lower bound ("low"), or the upper bound ("up").

Value

A vector (for THETA) or a square matrix (for OMEGA and SIGMA). For matrix values, the upper triangle is always filled with NA values.

The "nmrec_record_size" attribute attached to the return value indicates the number of values that come from each record. For matrix results, the value corresponds to the size along the diagonal.

Details

Constraints and limitations

• These functions return initial estimates only if they are explicitly defined in the control stream. All other values are returned as NA. For example, a record of $THETA (1)x4 is returned as c(1, NA, NA, NA).

• If additional parameter records are used for priors, those are included in the result. To avoid this, instead use more specific record names (such as THETAP and THETAPV).

See also

set_param for setting parameter options from values

Examples

ctl <- parse_ctl(c(
  "$PROBLEM ex",
  "$THETA 2 FIX",
  "$THETA (10,30)x2",
  "$OMEGA BLOCK(3)",
  "0.1",
  "0.01 0.1",
  "0.01 0.01 0.1"
))
extract_theta(ctl)
#> [1]  2 30 NA
#> attr(,"nmrec_record_size")
#> [1] 1 2
extract_theta(ctl, type = "low")
#> [1] NA 10 NA
#> attr(,"nmrec_record_size")
#> [1] 1 2
extract_theta(ctl, mark_flags = "fixed")
#> [1]  2 30 NA
#> attr(,"nmrec_record_size")
#> [1] 1 2
#> attr(,"nmrec_flags")
#> attr(,"nmrec_flags")$fixed
#> [1]  TRUE FALSE    NA
#> 

extract_omega(ctl)
#>      [,1] [,2] [,3]
#> [1,] 0.10   NA   NA
#> [2,] 0.01 0.10   NA
#> [3,] 0.01 0.01  0.1
#> attr(,"nmrec_record_size")
#> [1] 3