Skip to contents

Create parameter table data.frame using `NMreadExt()` and `NMreadParsText()`

Source: R/createParameterTable.R
createParameterTable.Rd

Automated parameter table creation of Nonmem models. Currently, requires a covariance step.

Usage

createParameterTable(
  file.lst,
  args.ParsText = NULL,
  df.repair = NULL,
  by.repair = "symbol",
  df.labs,
  drop.symbol,
  file.ext,
  df.boot,
  df.panels,
  script = NULL
)

Arguments

file.lst

Control stream. If possible, it is recommended to use output control stream. You can also use input control stream.

args.ParsText

List of arguments to be passes to `NMreadParsText()`. This will only be used if `df.labs` is omitted.

df.repair

Optional table of labels to overwrite results from `NMreadParsText()`. Useful to correct table issues without rerunning the model. This is only relevant if df.labs is omitted, and `NMreadParsText()` is run by `createParameterTable()`. Notice, the `df.labs` argument provides full flexibility to construct the labels before running `createParameterTable()`, and `dt.labels` is only a solution to a more specific case. `dt.labels` is likely to be re-designed or even dropped in the future.

by.repair

If `dt.labels` provided, names of columns to merge by.

df.labs

An optional data.frame with parameter labels. If provided, this will be the only source of labels and other columns like units, transformations, etc.

drop.symbol

Symbol values to not include. To be specific, rows with these values in the symbol column will be omitted in the generated table.

Details

The following columns are attempted used and may be modified. It is important for the user to understand how these must be formatted.

In many cases, a combination of args.ParsText and df.repair+by.repair is an easy way to have createParameterTable() do all the work. This will use NMreadParsText() and mergeCoal() to repair the table. If this is insufficient, the labels can be read into a data.frame first and passed as df.labs. In that case, other tools like NMrelate() can also be used.

createParameterTable looks for and uses the following columns as available:

  • symbol Typically, the variable name associated with the parameter. "CL".

  • label The parameter label. "Clearance".

  • trans Parameter transformation (character strings). See below for possible strings.

  • unit The parameter unit. "L/h".

  • panel Blocks of parameters types. See below for options.

Adding rse, CI.l, CI.u, and corr

Descriptive columns generated by createParameterTable:

  • tab.est The value column to be shown in parameter tables. The format depends on the parameter type and the transformation.

  • tab.est.ltx A latex version of tab.est

  • parameter.ltx. A latex version of the parameter name (like theta(1)). In case a THETA is log tranformed, an asterisk (*) is appended, for logit transformed THETAs, two asterisks (**) are appended. This is for footnoteing that the parameter estimates are shown on the physiologigical or natural scale.

### Guideline for panel column: ## THETA: struct (default), cov (covariates), RV (residual variability parameters) ## OMEGA: IIV/BSV (default), IOV/BOV ## OMEGA off diag: (handled automatically) ## SIGMA: (handled automatically)

trans is used for the following:

- Transformation: Model parameters (say THETA(1)) values and CI to the scale of the interpretable parameter, (say CL).

- Formatting: For Theta's trans equalling addErr and propErr gives formatting as residual standard deviations for additive and proportional error terms, respectively.

### trans column: ## THETA: none (default), log/logTrans, logit, addErr/SD, propErr/CV ## OMEGA: lognormal (default), normal ## OMEGA off diag: (handled automatically) ## SIGMA: Not implemented.

##' For THETAs Inverse of log (inverse is exp) and logit (NMcalc::invlogit) will be applied to parameter values and confidence intervals. SE and RSE are calculated before the backtransformation and must be interpreted on the scale of the estimated THETA, not the scale of the transformed parameter (e.g. Clerance when CL=EXP(THETA+...).

On OMEGA's, the lognormal distribut is for CL=EXP(THETA +ETA) , normal is for additive effects: PAR=EXP(THETA) + ETA.

Formatting of CV for OMEGAs trans="normal" or "none": CV=se/est trans="lognormal" : CV=sqrt(exp(OMEGA[i,i])-1)

SIGMA's are sorted and grouped as residual error terms, but specific formatting of additive, proportional or exponential is missing. Estimates reported are of the variances and correlations.

Off-diagonals in OMEGA and SIGMA

These should be fully automated. They are automatically identified, and labels should be auto-generated based on labels of the associated diagonal elements. I don't think the labeling is implemented yet, but it should be relatively simple.

Off-diagonal estimates are shown as correlations. But SE is standard error of the variances or cov-variances. For off-diagonal elements, the scale of the estimate (correlation) and the scale of the associated uncertainty (covariance) are different.

Columns created by createParameterTable

tab.lab I proposed descriptive label for the parameter. Combines label, (only for structural thetas) symbol and unit.

panel.label

Latex versions (.ltx columns) are generated using dplR::latexify. Because dplR is not included in MPN, and we need just that one function from dplR, the function has been copied into NMwork instead.

See also

formatParameterTable