Documentation

You can download all pdf documents listed below as a tar.gz or a zip archive.

Before running PsN

PsN Configuration.pdf
Known Bugs and Workarounds.pdf

PsN common options

PsN common options.pdf
List of common options for PsN tools.

PsN Tools

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

Running a PsN tool

Type the PsN tool name on the command line and then hit ↵ 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 you must give the name of at least one model file to use the PsN tool execute. If you 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 tools enter the following command on the command line:

$ psn -h

To get a list of available tools 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 tool, for example vpc, enter the command:

$ psn -h vpc

For more details on a specific tool, for example vpc, use the command:

$ vpc -help

Input options to PsN tool

All PsN tools accept a set of options which allow you to modify the behaviour of the tool. Some options are required for the tool, other options are specific for a certain tool and cannot be used together with other tools and finally there are a lot of common options.

Specific options:

For example, the bootstrap tool 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 tool.

$ bootstrap -samples=50 file.mod

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

$ bootstrap -h

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

$ bootstrap -h samples

Common options:

The various PsN tools share many building blocks, and many command line options are common to all PsN tools. 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 tool 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 user guide.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 tool 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 tool

If a PsN tool 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 tool can always be resumed. To resume a tool, the PsN directory created by the tool 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 tool will see that a directory already exists and the information in that directory will therefore be used to continue the bootstrap run.


Documentation for developers and testers

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