
.. _files_generated_by_fit_script:

Files Generated by Fit Script
=============================

You can examine the fit_script log file and the html output. However it is useful to also
understand the files output to disk by a fitting script.

The files generated in the same folder as 'fit_example1.pyml' are:-

.. code-block:: console

    fit_example1.pyml.html
    fit_example1.pyml.run.main.log
    
Here 'fit_example1.pyml.html' is a shortcut to the web page output. 'fit_example1.pyml.run.main.log', contains a copy of the text output to the console whilst running :ref:`popy_run`. This text file acts as an audit trail if you want to review the output of running the fit script later, or text search the console output for example.

The main file outputs from 'fit_example1.pyml' are contained in the folder called:-

.. code-block:: console

    fit_example1.pyml_output
 
The default convention for most |popy| scripts is to generate an output folder for each individual script as follows:-

.. code-block:: python

    script_name + '_output'
    
This simple convention has the useful facility of guaranteeing a unique output folder for each |popy| script file, so you can run multiple \*.pyml files in the same folder without worrying about over-writing output from other scripts (something other |poppkpd| systems struggle with).

Note if you attempt to run the same \*.pyml file twice than |popy| will ask you if you want to over-write the previous output folder. You can force |popy| to over-write existing folders using:-

.. code-block:: console
 
    $ popy_run -o fit_example1.pyml

See :ref:`popy_run` for more command line switch options.

The contents of the 'fit_example1.pyml_output' are determined by the |output_scripts| section of the 'fit_example1.pyml' script file:-

.. literalinclude:: 
    /_autogen/quick_start/fit_example1/fit_sections/OUTPUT_SCRIPTS.pyml
    :language: pyml

This section requests that a :ref:`sim_script`, :ref:`msim_script` and :ref:`fitsum_script` child script are created after the main :ref:`fit_script` has finished. Note the :ref:`sim_script` and :ref:`fitsum_script` will also be run automatically. So you end up with output folders on disk with this structure:-

.. code-block:: console

    fit_example1.pyml_output/
        fit/
        msim/
        sim/
        sum/

in which

* **fit** contains the results of running the :ref:`fit_script`
* **msim** is a :ref:`msim_script` that can be run later to generate a :term:`visual predictive check`
* **sim** is the results of running :ref:`sim_script` to create smoother profile curves from the fitted results
* **sum** is a html summary of the fitted model

This system of |popy| automatically generating new **child** scripts to process the results of an original **parent** script (which is called using :ref:`popy_run`) is key concept in how |popy| works, see :ref:`typical_workflows`. It is hierarchical scripting of hierarchical |poppkpd| modelling!

Note the |output_scripts| section is entirely optional. If you remove the |output_scripts| section from the 'fit_example1.pyml', then you just end up with a single output folder as follows:-

.. code-block:: console

    fit_example1.pyml_output/fit
    
We will now look at the outputs of the individual scripts in each subfolder.

.. _fit_script_outputs:

Fit Script Outputs
~~~~~~~~~~~~~~~~~~

The 'fit' subfolder has the following structure:-

.. code-block:: console

    fit_example1.pyml_output/
        fit/
            _temp
            observed_data
            sol0
            sol00
            sol1
            solN
            compartment_diagram.dot
            compartment_diagram.svg
            OBJV_vs_time.csv
        
In this folder, the files are as follows:-

* 'compartment_diagram.dot' - dot |graphviz| file derived from |derivatives|
* 'compartment_diagram.svg' - scalable vector graphics file displaying the compartment structure, derived from the \.dot file
* 'OBJV_vs_time.csv' - table showing objective value vs time, see :ref:`OBJV_vs_time<obj_vs_time_fit_example1>`

The subfolders are:-

* _temp - Temporary folder used by |popy| to create |python| functions
* observed_data - Contains filtered copy of 'fit_example1_data.csv' input data
* solX - Where X is one of [0,00,1,N]

You can examine the '_temp' folder when debugging, if one of the '.py' python functions derived from the 'fit_example1.pyml' script has not compiled properly. Or just for the curious.

The 'observed data' folder is a copy of the input data, which contains the original data set but may have been filtered using an optional |preprocess|.

The solX folders each contain the current :term:`solution<solutions>` at each stage of processing. As follows:-

* sol00 - Solution using initial |fx| and all |rx| =0.0
* sol0 - Solution using initial |fx| and fitted |rx|
* sol1 - Solution for first fitting method
* sol2 - Solution for second fitting method (not present for 'fit_example1.pyml')
* solXXX - Solution for further fitting methods ...
* solN - Final Solution (copy of sol1 folder for 'fit_example1.pyml')

Each solution folder contains multiple files the principle files being:-

* cur_fx_params.txt - |fx| parameters in human readable format
* cur_rx_params.txt - |rx| parameters in human readable format
* cur_obj_value.txt - current objective value

There are also various \.csv files which are more verbose, but easier to load in to software programs, e.g. |popy| or |r| for example.

Note sol00, sol0 and solN each contain a single :term:`solution<solutions>`. However here the 'sol1' folder contains the results of applying the 'JOE' fitting method and has a slightly different structure:-

.. code-block:: console

    fit_example1.pyml_output/
        fit/
            solXXX/
                itYYY/

Where XXX is the fitting method and YYY is the results of single iteration of the 'JOE' fitting algorithm.

The final solution for the :ref:`fit_script` are at this location on disk:-

.. code-block:: console

    fit_example1.pyml_output/
        fit/
            solN/
               

.. _sim_script_outputs_simple:

Sim Script Outputs
~~~~~~~~~~~~~~~~~~

The :ref:`fit_script` creates the child :ref:`sim_script` within the 'sim' subfolder:- 
 
.. code-block:: console
 
    fit_example1.pyml_output/
        sim/
            fit_example1_sim.pyml
 
The 'fit_example1_sim.pyml' script, is run automatically after the 'fit_example1.pyml' script has finished. This :ref:`sim_script` creates **dense** profile plots of the fitted model predicted values at time steps of 1.0, which can then be compared with the original simulated data for each individual.     

The full set of dense data plots for all individuals are located in this folder on disk:-

.. code-block:: console

    fit_example1.pyml_output/
        sim/
            dense/
                DV_CENTRAL,DV_CENTRAL,DV_CENTRAL_wrt_TIME_spag_graphs
            
..  comment 
    difficult to link here, so don't bother
    Or see the graphs rendered in html in :ref:`fit_example1_dense_sim_plots`.

For more information see :ref:`files_generated_by_sim_script`.
    
.. _msim_outputs_simple:

MSim Script Outputs
~~~~~~~~~~~~~~~~~~~~~

The :ref:`fit_script` creates the child :ref:`msim_script` within the 'msim' subfolder:- 
 
.. code-block:: console
 
    fit_example1.pyml_output/
        msim/
            fit_example1_msim.pyml
            
This :ref:`msim_script` is generated by the original fit_script but |not| run automatically due to this line:-

.. code-block:: console

    MSIM: {output_mode: gen_script_only}

The purpose of the msim script is to generate a :term:`visual predictive check` by simulating from the fitted model and comparing the simulated curves to the original data set. Running the 'msim' script is described in :ref:`simple_msim_example1`.
    
For more information on files output once the :ref:`msim_script` is run see :ref:`files_generated_by_msim_script`.
    
.. _fitsum_outputs_simple:
    
FitSum Outputs
~~~~~~~~~~~~~~~

The :ref:`fit_script` creates the child :ref:`fitsum_script` within the 'sum' subfolder:- 
 
.. code-block:: console
 
    fit_example1.pyml_output/
        sum/
            fit_example1_fitsum.pyml
 
The purpose of this script is to summarise the fit/sim output using automatically generated web pages. 

This **sum** tool displays the output from running a :ref:`fit_script` and the child :ref:`sim_script` on disk in a convenient format. For more information see :ref:`files_generated_by_fitsum_script`.

The output from **sum** tools is also used to automate large parts of this documentation.
