# PREDICTIONS

A required verbatim section that defines model `p[X]` prediction variables, but also compares `p[X]` variables to `c[X]` data and evaluates likelihoods or samples new `c[X]` data.

The PREDICTIONS section takes as input `c[X]`, `m[X]` and `s[X]` variables and outputs `p[X]` data. The PREDICTIONS section is required in the following scripts:-

- Tut Script
- Gen Script
- Fit Script
- Sim Script
- MTut Script
- MGen Script
- MFit Script
- MSim Script

i.e. Any Gen Script/Sim Script that samples new data points or any Fit Script that evaluates likelihoods requires a PREDICTIONS section.

## Example PREDICTIONS for PK Model

The example below is used in Fitting a Two Compartment PopPK Model.

    PREDICTIONS: |
        p[DV_CENTRAL] = s[CENTRAL]/m[V1]
        var = m[ANOISE]**2 + m[PNOISE]**2 * p[DV_CENTRAL]**2
        c[DV_CENTRAL] ~ norm(p[DV_CENTRAL], var)

In a Fit Script the PREDICTIONS section above computes a likelihood by comparing the `p[DV_CENTRAL]` predictions computed by the model and the `c[DV_CENTRAL]` values found in the data file.

The noise model is a combined additive and proportional noise model. See Residual Error Model for more details on types of noise model.

Note that in Generate a Two Compartment PopPK Data Set, the PREDICTIONS section is exactly the same as above, however the interpretation of this line is different:-

    c[DV_CENTRAL] ~ norm(p[DV_CENTRAL], var)

In a Gen Script this line is now used to sample new values of `c[DV_CENTRAL]` when creating a new data set.

The dual nature of the ‘~’ symbol allows the same PREDICTIONS section to be re-used throughout multiple scripts.

## Example PREDICTIONS for PD Model

See Direct PD Model for an example Tut Script, using the following PREDICTIONS section for a PD model:-

    PREDICTIONS: |
        clabel[TIME] = "Time (minutes)"
        plabel[MARKER] = "Biomarker concentration (mg/L)"
        p[MARKER] = s[MARKER]
        var = m[ANOISE]**2
        c[MARKER] ~ norm(p[MARKER], var)

In the above example the structure of the PREDICTIONS section is the same as the Example PREDICTIONS for PK Model, however this time the likelihood/sampling is between the `c[MARKER]` data and `p[MARKER]` predictions, using an additive noise model.

A more complex PREDICTIONS section is shown below. See Direct PD Model Simultaneous PK/PD Parameter fit:-

    PREDICTIONS: |
        clabel[TIME] = "Time (minutes)"
        plabel[MARKER] = "Biomarker concentration (mg/L)"
        plabel[CENTRAL] = "Drug concentration (mg/L)"
        p[CENTRAL] = s[CENTRAL]/m[V]
        c[CENTRAL] ~ norm(p[CENTRAL], m[PK_ANOISE]**2)
        p[MARKER] = s[MARKER]
        c[MARKER] ~ norm(p[MARKER], m[PD_ANOISE]**2)

If the PREDICTIONS block occurs in a Gen Script then both the `c[CENTRAL]` and `c[MARKER]` fields are sampled. If this PREDICTIONS section is included in a Fit Script then there are two different data fields that contribute to the likelihood, namely ‘CENTRAL’ and ‘MARKER’.

In the Fit Script case the likelihood is evaluated for a particular ‘~’ expression for every observation row in the data set. The contribution to the likelihood of a particular `c[X]` variable can also be controlled by the `c[X_FLAG]` field, if present in the data file. This mechanism avoids erroneously computing likelihoods against null values. This is similar to Nonmem’s MDV flag, but each PoPy `c[X]` variable is allowed to have it’s own `c[X_FLAG]`.

Note that Nonmem is restricted to a single DV field. The only way to perform a simultaneous fit within Nonmem is to mangle the data set by concatenating different fields into one column, because you can only have one likelihood per data row. This is unpleasant and error prone. The PoPy syntax above avoids this nightmare and handles any number of fields elegantly without changing the natural data file structure.

## Rules for PREDICTIONS section

Like all verbatim sections, the PREDICTIONS section of the configuration file accepts free form Python pseudocode, but there are some rules regarding which variables are allowed in a PREDICTIONS section as follows:-

- Only `p[X]` and local variables can be defined on the left hand side using ‘=’
- Only `c[X]` can be defined on the left hand side using ‘~’
- `m[X]` and `s[X]` are only allowed on the right hand side of expressions
- `c[X]` must be in the data file or defined in the PREPROCESS section in a Fit Script
- `c[X]` must be defined within the LEVEL_PARAMS in a Gen Script or Tut Script.
- `m[X]` must be defined in the MODEL_PARAMS section
- `s[X]` must be defined in the DERIVATIVES section

You can not use `f[X]`, `r[X]` or `t[X]` etc. variables at all in this section.

Like all verbatim sections it is possible to introduce syntax errors by writing malformed Python. Such errors will be reported when PoPy attempts to compile or run the PREDICTIONS function as a temporary .py file.