# 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[CEN] = s[CENTRAL]/m[V1]
        var = m[ANOISE]**2 + m[PNOISE]**2 * p[CEN]**2
        c[DV_CENTRAL] ~ norm(p[CEN], 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.

Each PoPy `c[X]` variable is allowed to have it’s own `c[X_FLAG]`, which enables PoPy to handles any number of fields elegantly without changing the natural data file structure. This is especially useful when performing a simultaneous fit with more than one measured variable because there is no requirement to mangle the data set by concatenating different fields into one column.

## Example PREDICTIONS for BLQ Observations

If your data file contains some observations which are recorded as BLQ, i.e. they are below the LLQ of the assay used to measure drug concentrations. Then to include these data points in your analysis you can use a ~rectnorm() distribution, see below:-

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

This formulation will model observations `c[DV_CENTRAL]` below LLQ as the likelihood of being in the range [-inf,LLQ] and observations greater than LLQ using a standard ~norm() distribution likelihood. See ~rectnorm() distribution for more information on this topic.

## 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 EFFECTS in a Gen Script or GEN_EFFECTS in a 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.