pmxparframe: Create a `data.frame` of from outputs and metadata

Description

This can be viewed as the first step in creating a nice-looking HTML table of model parameters. It combines the "raw" model outputs with metadata and produces and data.frame, conceived as an intermediate between the raw outputs and formatted table, but may also be useful in its own right. The decoupling of raw outputs from the final table is viewed as essential for flexibility.

Usage

pmxparframe(outputs, meta = get_metadata(outputs))

Arguments

outputs

A list of outputs from fitting the model (see Details).

Value

A data.frame with a row for each parameter, and the following columns:

name: name of the parameter (character)
fixed: fixed or estimated? (logical)
est: estimated value (numeric)
se: standard error (numeric)
rse: percent relative standard error (numeric)
lci95: lower bound of 95% confidence interval (numeric)
uci95: upper bound of 95% confidence interval (numeric)
pval: p-value for test of null hypothesis that value is zero (numeric)
shrinkage: percent shrinkage if applicable (numeric)

Other attributes from meta will also be preserved as columns. The order of the rows is determined by the order of the parameters in meta (the order in outputs is irrelevant).

Details

One of the key features of the approach taken in this package is that it decouples the "raw" outputs of the model from the presentation of results. A metadata description of the desired presentation of results is what links the two. This allows, for example, parameters to be presented in a different order, or on a different scale, than they were specified in the model. Hence, it provides more flexibility and control over the presentation than other approaches.

outputs is a named list, with the following elements:

est: estimated values (i.e., point estimates)
se: standard errors
fixed: designates parameters that were fixed rather than estimated
shrinkage: for random effects, the estimated percent shrinkage

est, se and fixed have essentially the same structure. They can be either flat named lists, or more structured named lists containing the following elements:

th : named list (or vector) of fixed effects
om : named list (or vector) of individual-level random effects expressed as standard deviations
om_cov : individual-level random effects expressed as a variance-covariance matrix
om_cor : individual-level random effects expressed as a matrix of correlations (off-diagonal elements) and standard deviations (diagonal elements)
sg : named list (or vector) of observation-level random effects expressed as standard deviations

meta is a list. Each element of meta is a named (sub)list representing a parameter. Each parameter is described by a series of attributes (not R attributes, but named list items). Of these, the only one that is required is name, which must match the name of the parameter used in outputs as it is used to make that association. The optional attributes include:

label: A descriptive label.
units: Units, if applicable.
type: Parameters can be grouped into sections by type. The standard types are:
- Structural: Structural model parameters
- CovariateEffect: Parameters that relate covariates to structural parameters
- IIV: Inter-individual (i.e., between-subject) variability
- IOV: Inter-occasion variability
- RUV: Residual unexplained variability
trans: Parameters can be presented on a (back)transformed scale (e.g., antilog). Importantly, transformation are also applied to standard errors (by "propagation of errors", also known as the delta method) to preserve (asymptotic) correctness, and to the endpoints of confidence intervals (note: this typically leads to non-symmetric intervals). Only a small set of transformations are currently recognized and supported, which include:
- identity: no transformation
- %, percent-scale
- exp: antilog
- ilogit: inverse-logit
- CV%: intended specifically for IIV parameters, where the associated structural parameter is log-normally distributed, transforms the standard deviation \(\omega\) to percent coefficient of variation by the formula \(100\times\sqrt{\exp(\omega^2)-1}\)
- SD (CV%): similar to the above, but the parameter remains on its original scale (i.e., standard deviation) with the percent coefficient of variation displayed in parentheses next to it (does not affect standard errors or confidence intervals).

Examples

Run this code

# NOT RUN {
outputs <- list(
  est = list(
    th = list(CL = 0.482334, VC = 0.0592686),
    om = list(nCL = 0.315414, nVC = 0.536025),
    sg = list(ERRP = 0.0508497)),
  se = list(
    th = list(CL = 0.0138646, VC = 0.00555121),
    om = list(nCL = 0.0188891, nVC = 0.0900352),
    sg = list(ERRP = 0.00182851)),
  fixed = list(
    th = list(CL = FALSE, VC = FALSE),
    om = list(nCL = FALSE, nVC = FALSE),
    sg = list(ERRP = FALSE)),
  shrinkage = list(nCL = 9.54556, nVC = 47.8771))

meta <- list(
  parameters = list(
    list(name="CL", label="Clearance", units="L/h", type="Structural"),
    list(name="VC", label="Volume", units="L", type="Structural", trans="exp"),
    list(name="nCL", label="On Clearance", type="IIV", trans="SD (CV%)"),
    list(name="nVC", label="On Volume", type="IIV"),
    list(name="ERRP", label="Proportional Error", units="%", type="RUV", trans="%")))

pmxparframe(outputs, meta)
# }