.. _builtin_tut_example:

Running Your First ``tut`` Script
#####################################################

Having created a ``tut`` script:

.. code-block:: console

    popy create tut my_first_tut_script.pyml

you may now run it to examine the results and how they correspond to the 
contents of the script:

.. code-block:: console

    popy run my_first_tut_script.pyml

which will create an output folder called ``my_first_tut_script.pyml_output``
into which it saves all outputs 
(apart than log files and a link to the ``tutsum`` HTML report, 
both of which are created in the same folder as the 
``my_first_tut_script.pyml`` input script).

If you ran the script already, a ``main`` log file will already exist which
will prompt |popy| to ask whether you want to overwrite any previous results.

If you answer "n" (for No) then |popy| will terminate, leave the previous
results unchanged, and suggest options that will re-run the script safely.

If you answer "y" (for Yes) then the previous results will be overwritten and 
lost for good, so be sure this is what you want. Use the ``-o`` command line
argument to forcibly overwrite existing results without prompting (|eg| when
running |popy| in an automated environment), or use the ``-t`` command line
argument to create fresh outputs with timestamped filenames for posterity.

.. note::

    Because the ``main`` log file is used to indicate existing results, 
    we do not recommend manually deleting log files 
    in case valuable results get overwritten.

To view the summarized results of the ``tut`` script, open the 
``my_first_tut_script.pyml.html`` file in a web browser and follow the links
to various output files.

You can compare your local html output with the pre-computed documentation output
(:ref:`sum_link_builtin_tut_example_tut`) 
though you should expect some minor numerical differences when 
comparing against results computed on different hardware.

.. toctree::
    :maxdepth: 1

    examples/script-hierarchies
    examples/tut-gen-subscript
    examples/tut-fit-subscript
    examples/tut-tutsum-subscript

.. 
    .. _syntax_tut_script_builtin:

    Syntax of Tut Script
    ======================

    The major structural difference between a :ref:`fit_script` or 
    :ref:`gen_script` and a :ref:`tut_script` is that the 
    generating |effects| are encoded in |gen_effects| and the 
    fitting |effects| are encoded in |fit_effects|. 
    For example the |gen_effects| section for this tutorial example is as follows:

    .. literalinclude:: 
        /case-studies/quick_start/builtin_tut_example/tut_sections/GEN_EFFECTS.pyml
        :language: pyml      
        
    And the |fit_effects| section is as follows:-

    .. literalinclude:: 
        /case-studies/quick_start/builtin_tut_example/tut_sections/FIT_EFFECTS.pyml
        :language: pyml     
        
    The |gen_effects| get passed to the :ref:`gen_script` 
    and the |fit_effects| get passed to the :ref:`fit_script`. 
    From the examples above you can see that the GEN_EFFECTS->POP section has:

    .. code-block:: pyml

        f[X] = true_value
        
    Whereas the FIT_EFFECTS->POP section has:-

    .. code-block:: pyml

        f[X] ~ P starting_value
        
    Reflecting the fact that the |fx| are known constants for a :ref:`gen_script`,
    but are unknown values to be estimated in a :ref:`fit_script`.




.. comment
    .. _rerun_tut_builtin:

    Re-run the tutorial
    =====================

    You can familiarise yourself with |popy|'s various features by tweaking the tutorial example and re-running. 
    A simple way of avoiding overwriting previous results is to do:-

    .. code-block:: console
        
        copy builtin_tut_example.pyml builtin_tut_example_v2.pyml

    and modifying the script with your chosen text editor.    

    When you are happy with the edited file, do:-

    .. code-block:: console

        popy run builtin_tut_example_v2.pyml

    For example, you can adjust the amount of data generated, in this section:-

    .. code-block:: pyml

        GEN_EFFECTS:
            ID: |
                c[ID] = sequential(50)
                t[DOSE] = 2.0
                t[OBS] ~ unif(1.0, 50.0; 5)
                # t[OBS] = range(1.0, 50.0; 5)
                    
    Note the 'range' function can sample time points evenly (instead of randomly). This usually makes the model fitting easier as the data points span the time range better. You can experiment with the number of doses or make a random sample of dose times for each individual.

    You can also edit the underlying model or compartment structure, see the |model_params| or |derivatives| sections.

    Another possibility is changing the fitted model only, i.e take a copy of this file:-

    .. code-block::

        builtin_tut_example.pyml_output/
            builtin_tut_example_fit.pyml

    Name it 'builtin_tut_example_fit_v2.pyml', change the model structure or compartment. Then do:-

    .. code-block:: console

        popy run builtin_tut_example_fit_v2.pyml
        
    Using a different model from the underlying generative model should result in a worse fit (using say an |akaike_inf| to compare fits).


