Script Hierarchies
===================

|popy| scripts form a hierarchical structure whereby a script can be instructed
to create and run other child scripts (which we call *subscripts*) 
for additional "downstream" processing after it has completed its main task.

A ``tut`` script, for example, can create and run 
``gen``, ``fit``, ``comp`` and ``tutsum`` scripts. 
In turn, a ``gen`` script can create and run 
``grph``, ``sim`` and ``gensum`` scripts 
to plot observations, simulate new data at dense time points, and 
summarize the ``gen`` results.

The complete script hierarchy for a single population, 
which starts with a :ref:`tut_script`,
is shown in :numref:`fig_tut_script_hierarchy` and shows the many actions
you can perform in |popy|.

.. _fig_tut_script_hierarchy:

.. figure:: /tutorials/hierarchy_diagrams/tut_script_hierarchy.*
    :width: 90%
    :align: center
    
    Hierarchy of all child scripts for a parent :ref:`tut_script`.

When fitting to real-life data (rather than synthetically-generated data), 
you typically use only the ``fit`` branch of the hierarchy as shown in 
:numref:`fig_fit_script_hierarchy`.

.. _fig_fit_script_hierarchy:

.. figure:: /tutorials/hierarchy_diagrams/fit_script_hierarchy.*
    :width: 50%
    :align: center
    
    Hierarchy of child scripts for a parent :ref:`fit_script`.

Subscripts are specified in the :ref:`tut-x-output-scripts-x-spec` section
of the parent script which, in the case of our ``tut`` script, contains

.. literalinclude:: 
    /case-studies/quick_start/builtin_tut_example/tut_sections/OUTPUT_SCRIPTS.pyml
    :language: pyml     

which instructs ``tut`` to create and run a ``gen`` script, then a ``fit``
script, then a ``comp`` script, and finally a ``tutsum`` script.

Subscripts can either be ignored (``output_mode: none``), 
created but not run (``output_mode: create``)
or created and run (``output_mode: run``). 
Most subscripts are created and run by default, though some of the more 
time-consuming subscripts are only created (to be run manually by the user at a 
later date).

In the case of a ``tut`` script, its only function is to create 
(and optionally run) a suite of subscripts for 
``gen``, ``fit``, ``comp`` and ``tutsum``; 
it does no other processing of its own 
and is primarily a tool for learning and rapid prototyping. 
(This book makes extensive use of :ref:`tut_scripts<tut_script>`
to illustrate different :ref:`indiv_pkpd_index`.)
When creating these subscripts, their fields are typically
populated using content from the parent script to ensure consistency within 
the hierarchy.

Running the :ref:`tut_script` will create an output folder 
containing the four derived subscripts:

.. code-block::

    my_first_tut_script.pyml_output/
        my_pkpd_model_gen.pyml
        my_pkpd_model_fit.pyml
        my_pkpd_model_comp.pyml
        my_pkpd_model_tutsum.pyml

(These files are named after the default script ``name`` property - 
"my_pkpd_model" - which is user-definable.)

We will now examine each of these scripts in turn.

