# FIT_METHODS

A required section that defines how PoPy estimates the `f[X]` and `r[X]` model parameters given a data file.

The FIT_METHODS section is required in the following scripts:-

- Tut Script
- Fit Script
- MTut Script
- MFit Script

i.e. Any script that estimates PK/PD model parameters is required to have a FIT_METHODS section.

## FIT_METHODS Structure

The FIT_METHODS section is a list of fitting methods to be applied in order to estimate the `f[X]` and `r[X]` variables of a PK/PD model, for example:-

    FIT_METHODS:
        - <fitter1>: {}
        - <fitter2>: {}
        - <fitter3>: {}

This allows in this case <fitter1> to initialise the `f[X]` for <fitter2> and for <fitter2> to then initialise the `f[X]` for <fitter3> etc..

In the long term it will be possible to apply multiple fitting methods, for example methods that globally initialise the `f[X]` followed by local fitting methods such as JOE and maybe later more time consuming fitting approaches such as IMP.

With the first release of PoPy the only available fitting method is JOE.

## JOE Fitting Method

JOE stands for Joint Optimisation and Estimation and is PoPy’s approximate equivalent of Nonmem’s ITS (Iterative Two Stage) or FOCE (First Order Conditional Estimation) fitting methods.

All these methods use a first order version of the Laplace approximation to make the computation of the likelihood function tractable. See [Wang2007] for details. We refer to this likelihood as the FOCE ObjV, which was first described in [Lindstrom1990], but is now most commonly associated with the popular FOCE fitting method in Nonmem.

Given the same PK/PD model, data file and same `f[X]` and `r[X]` variables. JOE, ITS and FOCE will return the same FOCE ObjV.

The methods differ in how they update the `f[X]` provided in a Fit Script by the modeller to estimate the final optimised `f[X]`. Given the same `f[X]` values all three methods obtain empirical bayes estimates of the `r[X]` variables in a very similar way.

In a Nonmem model FOCE sometimes obtains better `f[X]` estimates than ITS and vice versa. Hence the existence of two fitting methods for the same FOCE ObjV in Nonmem. In PoPy we provide JOE as one unified approach to optimising the FOCE ObjV for a given Fit Script and data file.

Note JOE, ITS and FOCE fitting methods are deterministic and fundamentally different from the stochastic sampling methods such as SAEM and IMP. SAEM and IMP that also estimate `f[X]` for PK/PD models, but the stochastic Objective Value is not based on the Laplace approximation used in the FOCE ObjV.

### JOE Fitting Example

The simplest way to use JOE in a Fit Script is as follows:-

    FIT_METHODS: [JOE:{}]

This single line, runs the JOE fitting method with the default settings. Note that the square bracket notation ‘[]’ is required because ‘FIT_METHODS’ expects a list. Or equivalently:-

    FIT_METHODS:
        - JOE: {}

Where the ‘-‘ is YAML notation for a list item.

One of the simplest JOE parameters is ‘max_n_main_iterations’:-

    FIT_METHODS:
        - JOE:
            max_n_main_iterations: 100

Which sets the number of times the `f[X]` parameters are updated. The JOE fitting proceeds iteratively with interleaved `f[X]` and `r[X]` updates. Setting this limit forces PoPy to stop after a finite number of iterations.

If you miss out ‘max_n_main_iterations’ it defaults to 50. Another option is as follows:-

    FIT_METHODS:
        - JOE:
            max_n_main_iterations: 0

This only updates the `r[X]` parameters and leaves the `f[X]` fixed. In Nonmem this is achieved using the EONLY flag.

Another common setting is the ‘CONVERGER’ field. There are three possible settings:-

- NONE - no convergence termination - estimation stops when ‘max_n_main_iterations’ is reached
- OBJ_INC - terminate convergence if the ObjV increases
- OBJ_SIM - terminate convergence if the ObjV is similar between iterations

These settings decide when a Fit Script will return the final `f[X]` estimates.

The default setting for JOE fitting is ‘OBJ_INC’, hence:-

    FIT_METHODS:
        - JOE:
            max_n_main_iterations: 100

Is the same as:-

    FIT_METHODS:
        - JOE:
            max_n_main_iterations: 100
            CONVERGER: {OBJ_INC: {}}

And the fit estimation will stop as soon as any iteration increases the ObjV. To allow the ObjV to increase during fitting, i.e. if the likelihood gets worse between iterations, but you wish the search to continue, use:-

    FIT_METHODS:
        - JOE:
            max_n_main_iterations: 100
            CONVERGER: {OBJ_SIM: {}}

Here ‘OBJ_SIM’ will terminate the estimation when two consecutive iterations return similar objective values (within a relative tolerance of 1e-06).

Note that when fitting complex models the ObjV usually decreases at each iteration, but occasionally increases. This is due to fact that `f[X]` and `r[X]` are optimised separately. Separate optimisation is necessary for computational efficiency. However optimising components of the likelihood independently can mean the combined ObjV increases. The ‘OBJ_SIM’ option above is designed to allow the search to continue in these cases.