Last modified date:7/9/20
Legal Notice | Contact Certara
© 2020 Certara USA, Inc. All rights reserved.
Most modeling projects will use three ASCII files: a data file in *.dat, *.csv or *.txt format, a *.txt file that maps the model data columns to Phoenix model columns, and a Phoenix model file in *.mdl or *.txt format. The *.mdl extension is used as a convention to identify PML model files.
Data files
Model files
Column mappings
The ASCII model data files *.dat, *.csv or *.txt are used for model fitting and the data can be delimited by a space, a comma, or a tab. The first row should identify the column names, and must be preceded by ##. For example, the first row of the example Theophylline dataset listed below looks like this:
## id, wt, dose, time, conc.
Only the period “.” character is an acceptable decimal separator.
Caution:The column header line in a PML dataset must be preceded by ## or Phoenix will not recognize the column headers.
Each subsequent row must contain data for each field. Use a period “.” to represent a null value. The data for the first subject in the example Theophylline dataset thbates.dat (found in …\Examples\NLME\Command Line\Model 3 or Model 4) are shown below.
thbates.dat
## xid wt dose time yobs
1 79.6 4.02 0 .74
1 79.6 4.02 .25 2.84
1 79.6 4.02 .57 6.57
1 79.6 4.02 1.12 10.5
1 79.6 4.02 2.02 9.66
1 79.6 4.02 3.82 8.58
1 79.6 4.02 5.1 8.36
1 79.6 4.02 7.03 7.47
1 79.6 4.02 9.05 6.89
1 79.6 4.02 12.12 5.94
1 79.6 4.02 24.37 3.28
The vast majority of memory is allocated and de-allocated dynamically as needed. In most cases, peak total memory demands for the Phoenix engines are easily accommodated within the memory available on modern computers (typically at least one gigabyte of memory per processor). However, there are still a number of static limits on model parameters as follows.
Maximum number of subjects=120,000 (This limit applies to all engines except the nonparametric engine, where the maximum number of subjects is 1000.)
Maximum number of observations per subject=unlimited (See limit on total number of observations below.)
Maximum total number of observations=480,000
Maximum number of thetas (fixed effects)=1000 (This includes both fixed effects that are frozen to a user-specified value, as well as free fixed effects that are included in the likelihood optimization, which is given below as 401.)
Maximum number of etas (random effects)=101 (This is also the maximum dimension of the Omega matrix in the diagonal case. Although, if Omega has a full or partial block structure, the maximum dimension will be less (see remarks below for free parameters).)
Maximum number of free parameters to be optimized=401 (This includes both free fixed effect, residual error model, and Omega parameters. Only non-zero Omega parameters on and below the diagonal are counted against this limit. Thus a full block matrix with Neta random effects will consume Neta*(Neta+1)/2 of these parameters, while a diagonal matrix will only consume Neta parameters. Omega matrices with a block diagonal structure will fall somewhere in between as determined by the particular block structure.
Maximum number of QRPEM samples=no limit (Large values (e.g., > 100,000) may cause difficulties with total static+dynamic peak memory demands. Typical values of QRPEM sample size range between 300 and 10,000 and should cause no problems.
Maximum number of iterations=10,000.
Maximum number of covariate categories or occasions=40.
Depending on the available memory and actual combination of model and run parameters, it is possible for very large models technically within the above static limits to require more dynamically allocated memory than is available. However, this should be an extremely rare occurrence and the overwhelming majority of population NLME models should easily fit.
The Phoenix model file is an ASCII text file that contains the model definition statements. It must follow the general form:
mdl(variables){
statements
}
where mdl is the assigned model name. All models are called test by default, but users can rename them. The (variables) parentheses are normally empty (), but they can contain a list of variables when the model is used in trial simulation. See “Modeling Syntax” for details of the available statements.
The model file for the Theophylline example is shown below. See “Theophylline PML example” for an annotated example.
fm3theophx.mdl
fm1theo(){
# Theophylline model example coding
# One compartment model with first order absorption
# Single dose at time=0, explicit concentration prediction formula
covariate(dose,time)
fixef(
tvlKa=c(, 0.5,)
tvlKe=c(, -2.5,)
tvlCl=c(, -3.0,)
)
ranef(
diag(nlKa, nlCl)=c(1.0 1.0)
)
stparm(
Ka=exp(tvlKa+nlKa)
Ke=exp(tvlKe)
)
V=Cl/Ke
cpred=dose
*Ka
/(V*(Ka-Ke))
*(exp(-Ke*time)-exp(-Ka*time))
error(eps1=c(.5))
observe(cObs=cpred+eps1)
}
This is an example model file of a well-known model, and it shows how to code an explicit closed-form single-dose solution. Note that any text string that is initiated by '#' is treated as a comment and does not affect model execution. Later examples show how to create models using differential equations, which are more adaptable to multiple dosing regimens and to trial simulation.
The example above shows a style in which indentation is used consistently throughout. This makes the model self-outlining for readability, and indicates a careful discipline, which makes errors less likely.
Including files in the generated C++ code
If one or more of the following statement appears in the PML outside of the model definition:
include(“MyIncludeFile.h”)
test(){ # model definition
…
}
where MyIncludeFile.h is the name of any C-style include file (enclosed in double quotes), it results in the following code being inserted near the top of the generated C++ file Model.cpp:
#include(“MyIncludeFile.h”)
This can be useful for purposes such as allowing access to additional functions that a user might include in the compile-and-link step for models.
Last modified date:7/9/20
Legal Notice | Contact Certara
© 2020 Certara USA, Inc. All rights reserved.