.. _inter_occasion_variation:

Inter-Occasion Variation (IOV)
################################

Just as PK parameters can vary from one individual to the next, they can also vary *within* an individual over a period of time. Clearances and volumes, for example, can often vary from day-to-day, particularly where inflammation plays a role but even in healthy volunteers. Absorption parameters can also vary substantially with each dosing occasion, sometimes to the extent that IOV is even greater than ISV. As a result, when drugs are administered on multiple occasions it may be important to model this variation, too [KarlssonSheiner1993]_.

Data Synthesis with IOV
=========================
.. note:: See the :ref:`sum_link_d1cmp_cl_iov_tut` and :ref:`sum_link_d1cmp_cl_iov_05_tut` for the :ref:`tut_script` used to generate results in this section. 

First, we generate some new data with both ISV and IOV by making more changes to the |effects| section of the script:

#. move values that vary between occasions (just the time points :pyml:`t[RESET]`, :pyml:`t[DOSE]` and :pyml:`t[OBS]`, unless the dose amount, :pyml:`c[AMT]` varies with occasion) from the |id| level into a new level, |occasion|.
#. add to the |occasion| level an occasion-specific covariate, :pyml:`c[OCC]`, that indicates the occasion, and an occasion-specific random effect, :pyml:`r[CL_iov]`, that is responsible for inter-occasion variation in the model parameter *CL*.
#. add to the |pop| level a population-specific fixed effect, :pyml:`f[CL_iov]`, that specifies the :term:`variance` (|ie| the spread) of the inter-occasional random effects, :pyml:`r[CL_iov]`.

.. literalinclude:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov/gen_sections/EFFECTS.pyml
    :language: pyml

(Here we have also reduced the population to ten individuals with three occasions each in order to maintain 30 time courses.)

.. note:: 
    Adding the |occasion| level below the |id| level tells |popy| that there are multiple occasions for an individual, much as adding |id| below |pop| says that there are multiple subjects in the population. Every occasion therefore inherits the parameters defined in the levels above. (See |effects|.)
    
The IOV random effect is then added to its ISV sibling in the |model_params| section of the script:

.. literalinclude:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov/gen_sections/MODEL_PARAMS.pyml
    :language: pyml

The remaining sections (|eg| |derivatives| and |predictions|) remain the same.

As with ISV, this added variation changes the shape of the predicted curves over the set of individuals in the population (:numref:`fig_iov_examples`). Depending on the magnitude of the variances, the set of curves may overlap such that it is difficult to separate the individuals or they may form tight clusters. (The overlap will also increase with bigger populations.)

.. list-table:: Population graphs with increasing ISV: (left) CL_isv=0.2, CL_iov=0.1; (right) CL_isv=0.5, CL_iov=0.01
    :name: fig_iov_examples

    * - .. thumbnail:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov/images/gen_dense/comb_spag.*
      - .. thumbnail:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov_05/images/gen_dense/comb_spag.*

      
Naïve IOV Fit
==========================
.. note:: See  :ref:`sum_link_d1cmp_cl_iov_naive_tut` for the :ref:`tut_script` used to generate results in this section. 

As with ISV, we can investigate the effect of excluding IOV from a fit to data where IOV exists by fixing the :pyml:`f[CL_iov]` variance to zero.

.. literalinclude:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov_naive/fit_sections/EFFECTS.pyml
    :language: pyml

Again, although the population parameters are close to their "true" values, the noise parameters and the ISV are all bigger than they should be in order to capture the IOV that has not been modelled

.. literalinclude:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov_naive/final_fx_params.txt
    :language: pyml

and we use the resulting objective function value,
    
.. literalinclude:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov_naive/d1cmp_cl_iov_naive_fit.pyml_output/fit/solN/final_obj_value.txt

as a reference.


Mixed Effect IOV Fit
==========================
.. note:: See  :ref:`sum_link_d1cmp_cl_iov_tut` for the :ref:`tut_script` used to generate results in this section. 

Adding IOV to the model by making :pyml:`f[CL_iov]` a free parameter

.. literalinclude:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov/fit_sections/EFFECTS.pyml
    :language: pyml

results in population parameters that are again close to their "true" values, this time including the variance parameters. This reflects the intuition that a correctly defined model requires less variance to capture the observed deviations from the population estimates. 
    
.. literalinclude:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov/final_fx_params.txt
    :language: pyml

As with the ISV example, the final objective function value,
    
.. literalinclude:: /_autogen/pop_examples/compartment_models/d1cmp_cl_iov/d1cmp_cl_iov_fit.pyml_output/fit/solN/final_obj_value.txt

is also significantly lower, indicating a better fit of the model to the observed concentrations.
