Format p-values

Description

Format p-values

Usage

fpval(
  pval,
  digits = 3,
  eps = 0.001,
  alpha = 0.05,
  star.symbol = "*",
  html = FALSE,
  unicode.le = FALSE
)

Arguments

Value

A character vector of the same length as pval.

See Also

base::format.pval

Examples

x <- c(1, 0.5, 0.05, 0.049, 0.01, 0.001, 0.0001, 0.00001)
fpval(x, html=FALSE, unicode.le=FALSE)

Method for printing in a knitr context

Description

Method for printing in a knitr context

Usage

## S3 method for class 'pmxpartab'
knit_print(x, ...)

Arguments

Value

A 'character' vector (see knitr::knit_print).

Parse a parameter description string

Description

Parse a parameter description string

Usage

parse_parameter_description(string)

Arguments

Value

A named list.

Examples

# Example 1: all elements present
x <- "CL, label='Clearance', units='L/h', trans=exp, type='Structural'"
parse_parameter_description(x)

# Example 2: Some elements missing (trans), will take default value (NULL)
x <- "CL, label='Clearance', units='L/h', type='Structural'"
parse_parameter_description(x)

# Example 3: Only the name is given
x <- "CL"
parse_parameter_description(x)

# Example 4: positional arguments
x <- "CL, 'Clearance', 'L/h', type='Structural'"
parse_parameter_description(x)

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

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).

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).

See Also

pmxpartab

Examples

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)

Generate an formatted HTML table of parameter estimates

Description

Generate an formatted HTML table of parameter estimates

Usage

pmxpartab(
  parframe,
  columns = c(est = "Estimate", rse = "RSE%", ci95 = "95% CI", shrinkage =
    "Shrinkage"),
  sections = !is.null(parframe$type),
  section.labels = c(Structural = "Typical Values", CovariateEffect =
    "Covariate Effects", RUV = "Residual Error", IIV = "Between Subject Variability", IOV
    = "Inter-Occasion Variability"),
  footnote = NULL,
  show.fixed.to.zero = FALSE,
  merge.units = TRUE,
  na = "-",
  digits = 3
)

Arguments

Value

An object of class "pmxpartab". This is essentially just an HTML character string that displays in the default web browser or viewer when printed (as per htmltools::print.html()).

See Also

pmxparframe

Examples

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="%")))

pmxpartab(pmxparframe(outputs, meta),
    columns=c(est="Estimate", rse="RSE%", ci95="95% CI", shrinkage="Shrinkage"),
    footnote="CI=confidence interval; RSE=relative standard error.")


# An example using a Cox model, where we construct the parframe manually:
library(survival)
cph.fit <- coxph(Surv(time, status) ~ ph.ecog + age, data=lung)
parframe <- with(summary(cph.fit), data.frame(
    name  = c("ph.ecog", "age"),
    label = c("ECOG performance score", "Age"),
    est   = coefficients[,"exp(coef)"],
    pval  = coefficients[,"Pr(>|z|)"],
    lci95 = conf.int[,"lower .95"],
    uci95 = conf.int[,"upper .95"]
))
pmxpartab(parframe=parframe,
    columns=c(est="HR", ci95="95% CI", pval="P-Value"))

Print pmxpartab object

Description

Print pmxpartab object

Usage

## S3 method for class 'pmxpartab'
print(x, ...)

Arguments

Details

In an interactive context, the rendered table will be displayed in a web browser. Otherwise, the HTML code will be printed as text.

Value

Returns x invisibly.

Read meta information from a YAML file

Description

Read meta information from a YAML file

Usage

read_meta(meta.file = "meta.yaml")

Arguments

Value

A list if the file exists, otherwise NULL.

Read NONMEM output

Description

Read NONMEM output

Usage

read_nm_output(
  rundir = getwd(),
  runname = basename(normalizePath(rundir)),
  lst.file = file.path(rundir, sprintf("%s.lst", runname)),
  ext.file = file.path(rundir, sprintf("%s.ext", runname)),
  shk.file = file.path(rundir, sprintf("%s.shk", runname)),
  phi.file = file.path(rundir, sprintf("%s.phi", runname)),
  phm.file = file.path(rundir, sprintf("%s.phm", runname)),
  cov.file = file.path(rundir, sprintf("%s.cov", runname)),
  cor.file = file.path(rundir, sprintf("%s.cor", runname)),
  bootstrap.file = file.path(rundir, "bootstrap", sprintf("raw_results_%s.csv",
    runname)),
  meta = read_meta(file.path(rundir, "meta.yaml")),
  th_names = meta$namemap$theta,
  om_names = meta$namemap$omega,
  sg_names = meta$namemap$sigma,
  use.vcov = FALSE,
  ...
)

Arguments

Details

All arguments are optional. If a particular output file cannot be found, then it is simply skipped (and the resulting object won't contain the components that would normally be read from there).

Value

A named list with components containing the outputs from the NONMEM run. Notably, the components th, om and sg contain the final estimates of the THETA, SD(ETA) and SD(EPS) parameters respectively (SD means standard deviation).