Documentation

Download all pdf documents listed below as a tar.gz or zip archive.

Before running PsN

PsN Installation.pdf
PsN configuration.pdf
PsN and NONMEM7.pdf
Known bugs and workarounds.pdf

Programs/scripts available in PsN

PsN
List available PsN scripts.
common options
List options common to most PsN scripts.
execute
NONMEM runs are started using one or multiple model files.
parallel retries
Run multiple copies of a single model with tweaked initial estimates in parallel.
update inits
Update a model file with parameter estimates from NONMEM output.
bootstrap
Bootstrap using the percentile or BCa method.
sir
Parameter uncertainty from Sampling Importance Resampling
precond
Estimate a model using preconditioning.
randtest
Randomization testing.
benchmark
Benchmarking of NONMEM settings.
rawresults
Create a rawresults file from a set of list files.
covmat
Create an empirical covariance matrix based on a rawresults file.
sse
Stochastic Simulation and Estimation
npc
Numerical Predictive Check
vpc
Visual Predictive Check
Two-page poster on Visual Predictive Checks for censored and categorical data.pdf
Separate description of automatic binning in vpc.pdf
cdd
Case Deletion Diagnostics
simeval
Simulation-Evaluation diagnostics of outliers. Was ebe pde.
frem
Full random effects model
llp
Log-Likelihood Profiling around maximum-likelihood parameter estimates.
scm
Stepwise Covariate Model-building
Some extensively commented example/template configuration files for scm:
Standard template
Backward search template
Linearization template
Different parameterizations for different covariates
All default parameterizations explicitly using code section
Grouping of categorical covariate
Centering of bivariate covariate
Emax and other special parameterizations
xv scm
Cross-validated Stepwise Covariate Model-building
boot scm
Bootstrapped Stepwise Covariate Model-building
lasso
Covariate model building using the lasso method
runrecord guide runrecord template
RunRecord
mcmp
Monte-Carlo Mapped Power.
mimp
Multiple imputation
nca
Non-compartmental analysis
pvar
Parametric variability
gls
Generalized Least Squares approximations of the residual error model
sumo
Summary of Output from NONMEM
linearize
Linearize a model.
data_stats
Print simple statistics for dataset columns.
extended grid
non-parametric estimation on the extended grid.
nonpb
Non-Parametric Bootstrap
pind
Individual Probabilities
se_of_eta
Standard Errors of Etas
nmoutput2so
Convert output from NONMEM to the DDMoRe standardised output format (so).
resmod
Residual modelling.
transform
Transform model files, i.e. boxcox, remove_iov.

Running a PsN script

A PsN script is run by first typing its name on the command line (e.g. a DOS comand prompt) and then pressing enter, e.g.:

$ execute

The above command will give you this message:

At least one model file must be specified. Use 'execute -h' for help.

This means that to use execute to start a NONMEM execution you must give the name of at least one model file. If you then enter:

$ execute file.mod

This will start the NONMEM execution using the model file "file.mod". It will also create a directory called "modelfit_dirX", where "X" is the number of the directory starting from one. The numbers of any additional directories will be increased by one for each time you run "execute". This makes it possible to do multiple runs at the same time in one directory. After the run you will find the output from NONMEM in the file named "file.lst", and any table files specified in the model file.

Getting help

All user-guide documents are available in the folder "doc" in the PsN installation package. It can be copied to a directory of choice during the PsN installation.

PsN also has an extensive command line help system. To get a list of available scripts enter the following command on the command line (e.g. a DOS comand prompt):

$ psn -h

To get a list of available scripts with a one-line description of each (i.e. the list at the top of this page) enter the following command on the command line:

$ psn -help

.To print a one-line description of a specific script, for example "vpc", enter the command:

$ psn -h vpc

For more details on a spcific script, for example "vpc", use the command:

$ vpc -help

Input options to PsN scripts

Specific options: All PsN scripts accept a set of options which allow you to modify the behaviour of the script. Please see for example, the bootstrap creates 200 new data sets from the original data by default. However the number of data sets can be limited to for example 50, by changing the number in the -sample option in the bootstrap script.

$ bootstrap -samples=50 file.mod

The '-samples' option is unique to the bootstrap script. To get a list of the unique options available for a specific script you can use the command (e.g. for the bootstrap script):

$ bootstrap -h

To get more information about a spcific option you can use the command:

$ bootstrap -h samples

Common options: The various PsN scripts share many building blocks, and many command-line options are common to all PsN scripts. The '-threads' option is an example of a common option:

$ bootstrap -samples=50 -threads=6 file.mod

In this example the threads option makes the bootstrap utility run six NONMEM runs in parallel (on a cluster of computers or on multiple processors). To list all common PsN options enter:

$ psn_options -h

The Common options userguide.pdf describes these options in much more detail.

PsN Directory structure

PsN needs to create quite a few files to keep track of its executions as well as to enable resuming. During the execution the scripts also create many NONMEM model-, data- and output files. In order to keep things manageable we have decided to order all files in a generic directory structure. You will get the output summaries from the command line tools, but it may still be useful to orient yourself in the directory structure. You can, for instance, find individual NONMEM run outputs as well as logs from PsN. To make it a bit easier we have created the PsN Directory Guide, which is a small guide to the structure of the directories.  

Restarting a PsN script

If a PsN script is stopped before it has finished it is possible to resume it from where it stopped. This is handled in PsN by the creation of a checkpoint after each NONMEM run. From this checkpoint a script can always be resumed. To resume a script the PsN directory created by the script that stopped must be specified. In addition, the options used in the run that stopped must be defined. The options and their values are saved in the file "command.txt" under the directory from which you are resuming. If, for example, a bootstrap run in a directory named bootstrap_dir1 stopped before it was finished it can easily be resumed by:

$ bootstrap -samples=50 -threads=6 -directory=bootstrap_dir1

In the example above the bootstrap utility will see that a directory already exists and the information in that directory will therefore be used to continue the bootstrap run.

Print the PsN version

To print the version of PsN that you are using enter:

$ psn -version

If you want to use other installed versions of PsN the Common options userguide.pdf describes how to do that.

To print the versions of NONMEM that PsN has access to, as defined in psn.conf, enter:

$ psn -nm_version

You can use a special NONMEM version from this list via the option -nm_version, for example

$ execute -nm_version=vi_big file.mod

Documentation for developers and testers

The Developers guide.pdf contains information for developers and for those in need of information about how to run the PsN test suite.