.. _validate_popy:

Validate |popy|
####################

Before using |popy| for an important analysis it is best to run the validation process. This verifies that the outputs of your |popy| installation agree with the outputs obtained by the developers of |popy|.

.. _check_popy_installed:

Check the |popy| Configuration
===================================

To see the current configuration, :ref:`open_a_popy_command_prompt` and type:-

.. code-block:: console

    popy info

and you should see something like this:-
    
.. literalinclude:: popy_info_output_activated.inc
    :language: console 

showing the paths used by |popy|, a few internal variables, and details about the licence (if you have run :ref:`popy_activate`).

.. _run_the_validator:

Run the Validator
======================

Because computers vary in their architecture, it is possible that running the same code and the same script could give different results on different installations. We therefore bundle a tool, :ref:`popy_validate`, that runs |popy| on a suite of examples and compares the results you compute locally to some reference results generated at |wdl|. 

These :ref:`validation_examples` are largely drawn from the |ddmore| repository and cover models with different features, |eg| inter-occasion variability.

To run this suite of examples :ref:`open_a_popy_command_prompt` and type:-

.. code-block:: console

    popy validate
    
Some of the examples take a few minutes to run, the full validation takes about 20 minutes, but you should only need to run the validation once.

If the validation is successful, you should get output on the command line as the validation examples are processed. The end of the output should look like:-
    
.. literalinclude:: popy_validate_output.inc
    :language: console 

which will also be written to the log file 'validation_script.pyml.run.main.log' in the 'validation' subdirectory of your |popy| installation, which is normally located at ``c:\PoPy\validation\validation_script.pyml.run.main.log``.

This log file can be used as a form of verification for a validation report, if |popy| is to be used in a commercial setting.

.. _validation_examples:

Validation Examples
=====================

The validation examples are often taken from the publicly available |ddmore| repository. Typically these are a |nm_ctl_file| and |nm_dat_file| that together illustrate fitting a |pkpd| model.  

You can see the validation examples supplied with |popy| in the ``c:\PoPy\validation`` folder.
    
Each subdirectory contains a 'readme.txt' file that gives a brief overview of the example and how it was created from the |ddmore| equivalent.
    
:numref:`table_validation_egs` lists each of the models in this folder:-

.. _table_validation_egs:

.. list-table:: Validation Models
    :header-rows: 1
    
    * - Name
      - Summary
      - Link
      - Citation
     
    * - ddmore0061
      - Combined |bolus| + |infusion| |pk| model. 
      - :ddmore_link:`0061`
      - [Harling2015]_
      
    * - ddmore0093
      - Circadian function with covariates. 
      - :ddmore_link:`0093`
      - [Cheung2015]_
    
    * - ddmore0215
      - Markov and dropout hazard.
      - :ddmore_link:`0215`
      - [Girard2012]_  
    
    * - ddmore0238
      - |poppk| with |infusion| dosing + |iov|.
      - :ddmore_link:`0238`
      - [Germovsek2017]_   
      

Troubleshoot
================

If the validation fails for any reason, please contact the |popy| developers at |email|.
