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 Tut Script, is shown in Fig. 1 and shows the many actions you can perform in PoPy.

Fig. 1 Hierarchy of all child scripts for a parent 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 Fig. 2.

Fig. 2 Hierarchy of child scripts for a parent Fit Script.

Subscripts are specified in the OUTPUT_SCRIPTS section of the parent script which, in the case of our tut script, contains

OUTPUT_SCRIPTS:
    GEN: {output_mode: run, sim_time_step: 1.0}
    FIT: {output_mode: run, sim_time_step: 1.0}
    COMP: {output_mode: run}
    TUTSUM: {output_mode: run}

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 tut_scripts to illustrate different Simulating A Single Individual.) When creating these subscripts, their fields are typically populated using content from the parent script to ensure consistency within the hierarchy.

Running the Tut Script will create an output folder containing the four derived subscripts:

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.