.. _output_scripts:

OUTPUT_SCRIPTS
##################

An optional section that controls the **child** scripts that are created and possibly run after a **parent** script has finished running. 

The |output_scripts| section is available in the following scripts:-

* :ref:`tut_script`
* :ref:`gen_script`
* :ref:`fit_script`
* :ref:`sim_script`
* :ref:`msim_script`
* :ref:`mtut_script`

|ie| Any script that can generate **child** scripts may have an |output_scripts| section.

.. _structure_of_output_scripts:

Structure of OUTPUT_SCRIPTS
=============================

The |output_scripts| in all :ref:`script_formats` share a common format, as follows:-

.. code-block:: pyml

    OUTPUT_SCRIPTS:
        <child_script1>: {output_mode: run}
        <child_script2>: {output_mode: create}
        <child_script3>: {output_mode: none}

The |output_scripts| section is a :term:`dict` record. i.e it is a |python| dictionary with child script names as keys.

All child script sections share the 'output_mode' field, which can take the following values:-

* run - create the child script and run it
* create - create the child script, but do |not| run it
* none - do |not| create the child script

Generally if a child script is not mentioned in the parent script the 'output_mode' defaults to 'none'.

The available child scripts are dependent on the parent |script_type|. Also there maybe additional options for each child script, see examples below for more concrete details.
        
.. _output_scripts_tut_example:

Example OUTPUT_SCRIPTS for tut_script
=======================================

The example below is used in :ref:`builtin_tut_example`.

.. literalinclude:: 
    /_autogen/quick_start/builtin_tut_example/tut_sections/OUTPUT_SCRIPTS.pyml
    :language: pyml

This specifies that a child :ref:`gen_script`, :ref:`fit_script`, :ref:`comp_script` and :ref:`tutsum_script` are all run.

Note it's possible to miss out the |output_scripts| section from a :ref:`tut_script`, then the default settings are run, which is equivalent to:-

.. code-block:: pyml

    OUTPUT_SCRIPTS:
        GEN: {output_mode: run, sim_time_step: -1.0, grph_list: ["OBS_vs_TIME"]}
        FIT: {output_mode: run, sim_time_step: -1.0, grph_list: ["OBS_vs_TIME"]}
        COMP: {output_mode: none}
        TUTSUM: {output_mode: run}

This results in more limited tutorial outputs compared to the previous example.

.. _output_scripts_gen_example:

Example OUTPUT_SCRIPTS for gen_script
=======================================

The example below is used in :ref:`builtin_gen_example`.

.. literalinclude:: 
    /_autogen/quick_start/builtin_gen_example/gen_sections/OUTPUT_SCRIPTS.pyml
    :language: pyml

This specifies that a child :ref:`sim_script` and :ref:`gensum_script` are run.

Note it's possible to miss out the |output_scripts| section from a :ref:`gen_script`, then the default settings are run, which is equivalent to:-

.. code-block:: pyml

    OUTPUT_SCRIPTS:
        GRPH: {output_mode: none, grph_list: ["OBS_vs_TIME"]}
        SIM: {output_mode: none, grph_list: ["OBS_vs_TIME"], sim_time_step: -1.0}
        GENSUM: {output_mode: none}

|ie| if you miss out the |output_scripts| then you just get the :ref:`gen_script` output and no further processing, as you might expect.
        
.. _output_scripts_fit_example:

Example OUTPUT_SCRIPTS for fit_script
=======================================

The example below is used in :ref:`builtin_fit_example`.

.. literalinclude:: 
    /_autogen/quick_start/builtin_fit_example/fit_sections/OUTPUT_SCRIPTS.pyml
    :language: pyml

This specifies that a child :ref:`sim_script` and :ref:`fitsum_script` are run and a :ref:`msim_script` is created on disk but |not| run automatically.

Note it's possible to miss out the |output_scripts| section from a :ref:`fit_script`, then the default settings are run, which is equivalent to:-

.. code-block:: pyml

    OUTPUT_SCRIPTS:
        GRPH: {output_mode: none, grph_list: ["OBS_vs_TIME"]}
        SIM: {output_mode: none, grph_list: ["OBS_vs_TIME"], sim_time_step: 1.0}
        MSIM: {output_mode: none, vpc_list: ["OBS_vs_TIME_VPC"]}
        FITSUM: {output_mode: none}

|ie| if you miss out the |output_scripts| then you just get the :ref:`fit_script` output and no further processing, as you might expect.

.. _output_scripts_sim_example:

Example OUTPUT_SCRIPTS for sim_script
=======================================

The example below is from a :ref:`sim_script` generated by a :ref:`fit_script` in :ref:`builtin_fit_example`.

.. literalinclude:: 
    /_autogen/quick_start/builtin_fit_example/sim_sections/OUTPUT_SCRIPTS.pyml
    :language: pyml

The single 'GRPH' child script above, is used to plot the results of the :ref:`sim_script` simulated |pk| curves.

You can edit the 'GRPH' options to control the graphical output.
    
.. _output_scripts_msim_example:

Example OUTPUT_SCRIPTS for msim_script
=======================================

The example below is from a :ref:`msim_script` generated by a :ref:`fit_script` in :ref:`builtin_fit_example`.

.. code-block:: pyml

    OUTPUT_SCRIPTS:
        VPC:
            output_mode: run
            vpc_list: ["COMB_QUANT_SIM_VPC"]
            
.. comment

            y_var_src_list: ['sim', 'orig']
            y_var_list: ['DV_CENTRAL_sim', 'DV_CENTRAL']
            x_var: TIME_SINCE_LAST_DOSE

The single 'VPC' child script above, is used to plot a |vpc| using the results of the :ref:`msim_script` multi population simulated |pk| curves.
    
You can edit the 'VPC' options to control the graphical output.
    
.. _output_scripts_mtut_example:

Example OUTPUT_SCRIPTS for mtut_script
=======================================

The example below is used in :ref:`builtin_mtut_example`.

.. code-block:: pyml

    OUTPUT_SCRIPTS: 
        MGEN: {output_mode: run}
        MFIT: {output_mode: run}
        MCOMP: {output_mode: run, dot_size: 12} 

This :ref:`mtut_script` outputs and runs a :ref:`mgen_script`,  :ref:`mfit_script` and :ref:`mcomp_script`. 

Notice you can optionally alter the size of the dots on the :ref:`mcomp_script` scatter plots using the 'dot_size' field.




