.. _simple_mtut_example:
      
Generate multiple data sets and Fit using Simple |poppk| Model
################################################################

The tutorial example above generates a single data set from user specified true |fx| values. In |popy| it is possible to generalise this approach and sample true |fx| values multiple times to create multiple data sets. Then fit the same model to each data set.

In this section we walk through how to generate multiple data sets using a :ref:`mtut_script`, using the same simple one compartment model as shown in :numref:`fig_simple_popkp_diagram_tut`.

.. _running_a_mtut_script_simple:
 
Running the MTut Script
------------------------

..
    duplication of text w.r.t. docs for builtin_mtut_example

This multi tutorial example makes use of a single script file, ``c:\PoPy\examples\mtut_example1.pyml``
                            
:ref:`open_a_popy_command_prompt` to setup the |popy| environment in the folder ``c:\PoPy\examples\``

With the |popy| environment enabled, you can call :ref:`popy_run` on the :ref:`mtut_script` from the command line:-

.. code-block:: console

    popy run mtut_example1.pyml
    
to run the script.

Running a :ref:`mtut_script` can take a considerable amount of time, as it is equivalent to running a :ref:`tut_script` multiple times. 
However in this toy example we only run the fit/gen cycle 30 times and only a small number of the |fx| parameters are estimated.

.. _syntax_of_mtut_script:

Syntax of MTut Script
------------------------

The :ref:`mtut_script` specifies the number of populations to sample as follows:-

.. code-block:: pyml

    OUTPUT_OPTIONS: {n_pop_samples: 30}

The :ref:`mtut_script` encodes **both** the data generation and fitting in the |gen_effects| and |fit_effects| sections, like a :ref:`tut_script`. The syntax is the same. In this example the |gen_effects| section is as follows:-

.. literalinclude::  /case-studies/quick_start/mtut_example1/mtut_sections/GEN_EFFECTS.pyml
    :language: pyml      

And the |fit_effects| section is as follows:-

.. literalinclude::  /case-studies/quick_start/mtut_example1/mtut_sections/FIT_EFFECTS.pyml
    :language: pyml      

Here the generated values of |fke|, |fpnoise| and |fke_isv| are sampled from uniform distributions. The fitting process is initialised with (constant) values in the centre of the uniform distribution, used to sample the generating |fe| values.
    
.. _summary_of_simple_mtut_results:

Summary of MTut Results
-------------------------------

The :ref:`mtut_script` should generate an output folder containing three new scripts:-

.. code-block::

    mtut_example1.pyml_output/
        mtut_example1_mgen.pyml
        mtut_example1_mfit.pyml
        mtut_example1_mcomp.pyml
                                              
The purpose of each of theses scripts is as follows:-

.. _table_mtut_output_scripts_simple:

.. list-table:: Scripts output by a multi tutorial script
    :header-rows: 1
    
    * - Script
      - Purpose
      - Documentation

    * - \*_mgen.pyml
      - Generate multiple synthetic data sets from model
      - :ref:`mgen_script`

    * - \*_mfit.pyml
      - Fit model to multiple synthetic data sets
      - :ref:`mfit_script`

    * - \*_mcomp.pyml
      - Compare gen model and fit model |fx|
      - :ref:`mcomp_script`
 
The :ref:`mgen_script` is very similar to the :ref:`gen_script` described in :ref:`tut_syntax_simple` and the :ref:`mfit_script` is very similar to the :ref:`fit_script` described in :ref:`simple_fit_example`. See :ref:`files_generated_by_mtut_script` for more info. 
   
Here we mainly discuss the :ref:`mcomp_script` outputs, which processes the results of :ref:`mgen_script` and :ref:`mfit_script`. The simplest output is a visual comparison of the true and fitted |fx| values as shown in :numref:`table_true_vs_mfit_fx_plots_builtin_f_ke_f_ke_isv_fpnoise_simple`.

.. _table_true_vs_mfit_fx_plots_builtin_f_ke_f_ke_isv_fpnoise_simple:

.. list-table:: Fitted model vs true scatter plots for |fke|, |fke_isv| and |fpnoise|
    :class: image_table
    
    * - .. thumbnail:: /case-studies/quick_start/mtut_example1/fx_scatter/fitted_vs_true_for_f_ke_.*
      - .. thumbnail:: /case-studies/quick_start/mtut_example1/fx_scatter/fitted_vs_true_for_f_ke_isv_.*
      - .. thumbnail:: /case-studies/quick_start/mtut_example1/fx_scatter/fitted_vs_true_for_f_pnoise_.*
      
In :numref:`table_true_vs_mfit_fx_plots_builtin_f_ke_f_ke_isv_fpnoise_simple` the blue dots are a scatter plot of fitted |fx| vs true |fx|. The green dots are initial |fx| vs true |fx|. For example in the case of |fke| the true values are sampled as follows:-

.. code-block:: pyml

    f[KE] ~ unif(0.05,0.15)
    
|ie| the true values are uniformly sampled in the range [0.05,0.15]. The fitted |fke| parameters are modelled as follows:-
    
.. code-block:: pyml

    f[KE] ~ P0.1
 
The initial values for |fke| are always 0.1, see green dots in a horizontal line on the left graph in :numref:`table_true_vs_mfit_fx_plots_builtin_f_ke_f_ke_isv_fpnoise_simple`. The 'P' specifies that the fitting value of |fke| is restricted to positive numbers. The final fitting values are the blue dots on the left graph in :numref:`table_true_vs_mfit_fx_plots_builtin_f_ke_f_ke_isv_fpnoise_simple`. For |fke| the blue dots are clustered along the black 45 degree line. Hence fitting for |fke| works well, this agrees with the initial findings in :ref:`simple_fit_example`. The blue dots for |fke_isv| and |fpnoise| (centre and right graphs in :numref:`table_true_vs_mfit_fx_plots_builtin_f_ke_f_ke_isv_fpnoise_simple`) are not as tightly clustered around the 45 degree line, indicating these parameters are harder to identify than |fke|. However both |fke_isv| and |fpnoise| show a reasonable correlation between the true and fitted values.
      
Note it might well be possible to carry out a more statistical analysis of correlation between the true and fitted |fx|, for example finding a line of best fit through the scatter plot data. The :ref:`mcomp_script` outputs are all saved to \.csv files, see :ref:`files_generated_by_mcomp_script`, which could easily be loaded into |r| or other statistical packages for further analysis. 
