# 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:-

    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 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:-

    fit_example1.pyml_output

The default convention for most PoPy scripts is to generate an output folder for each individual script as follows:-

    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 PopPK/PD 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:-

    $ popy_run -o fit_example1.pyml

See 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:-

    OUTPUT_SCRIPTS:
        SIM: {output_mode: gen_script_and_run, sim_time_step: 1.0}
        MSIM: {output_mode: gen_script_only}
        FITSUM: {output_mode: gen_script_and_run}

This section requests that a Sim Script, MSim Script and FitSum Script child script are created after the main Fit Script has finished. Note the Sim Script and FitSum Script will also be run automatically. So you end up with output folders on disk with this structure:-

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

in which

- fit contains the results of running the Fit Script
- msim is a MSim Script that can be run later to generate a visual predictive check
- sim is the results of running 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 popy_run) is key concept in how PoPy works, see Typical Workflows. It is hierarchical scripting of hierarchical PopPK/PD 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:-

    fit_example1.pyml_output/fit

We will now look at the outputs of the individual scripts in each subfolder.

## Fit Script Outputs

The ‘fit’ subfolder has the following structure:-

    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 OBJV_vs_time

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 solution at each stage of processing. As follows:-

- sol00 - Solution using initial `f[X]` and all `r[X]` =0.0
- sol0 - Solution using initial `f[X]` and fitted `r[X]`
- 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 - `f[X]` parameters in human readable format
- cur_rx_params.txt - `r[X]` 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 solution. However here the ‘sol1’ folder contains the results of applying the ‘JOE’ fitting method and has a slightly different structure:-

    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 Fit Script are at this location on disk:-

    fit_example1.pyml_output/
        fit/
            solN/

## Sim Script Outputs

The Fit Script creates the child Sim Script within the ‘sim’ subfolder:-

    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 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:-

    fit_example1.pyml_output/
        sim/
            dense/
                DV_CENTRAL,DV_CENTRAL,DV_CENTRAL_wrt_TIME_spag_graphs

For more information see Files Generated by Sim Script.

## MSim Script Outputs

The Fit Script creates the child MSim Script within the ‘msim’ subfolder:-

    fit_example1.pyml_output/
        msim/
            fit_example1_msim.pyml

This MSim Script is generated by the original fit_script but not run automatically due to this line:-

    MSIM: {output_mode: gen_script_only}

The purpose of the msim script is to generate a 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 Visual Predictive Check for Simple PopPK Model.

For more information on files output once the MSim Script is run see Files Generated by MSim Script.

## FitSum Outputs

The Fit Script creates the child FitSum Script within the ‘sum’ subfolder:-

    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 Fit Script and the child Sim Script on disk in a convenient format. For more information see Files Generated by Fitsum Script.

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