:orphan:

.. The content of this file was generated
.. automatically by the popy.conf.fio.rstdoc_writer module


.. _tut_spec:



.. _tut-method_options_spec:

METHOD_OPTIONS
**************

Type: :term:`dict_record <dict_record>`

method options for tut_script

Example:-

.. code-block:: pyml

    METHOD_OPTIONS:
        py_module: tut
        rand_seed: 12345
        float_format: default


.. _tut-method_options-py_module_spec:

py_module
=========

Type: :term:`one_of(tut) <one_of>`

Python module required to process this script file

Example:-

.. code-block:: pyml

    py_module: tut


.. _tut-method_options-rand_seed_spec:

rand_seed
=========

Type: :term:`int <int>` / :term:`auto <auto>`

Option to set seed to make run result
reproducible -e.g. when debugging.

Example:-

.. code-block:: pyml

    rand_seed: 12345


.. _tut-method_options-float_format_spec:

float_format
============

Type: :term:`str <str>`

Format string for numerical output

Example:-

.. code-block:: pyml

    float_format: default


.. _tut-description_spec:

DESCRIPTION
***********

Type: :term:`dict_record <dict_record>`

Description fields for script.

Example:-

.. code-block:: pyml

    DESCRIPTION:
        name: pk_first_order
        title: First order absorption model with peripheral compartment
        author: J.R. Hartley
        abstract: |
            A two compartment PK model with bolus dose and
            first order absorption, similar to a nonmem advan4trans4 model.
        keywords: ['tutorial', 'pk', 'advan4', 'dep_two_cmp', 'first order']


.. _tut-description-name_spec:

name
====

Type: :term:`str <str>`

Unique name used to distinguish script

Example:-

.. code-block:: pyml

    name: pk_first_order


.. _tut-description-title_spec:

title
=====

Type: :term:`str <str>`

A longer text string that could serve as a title

Example:-

.. code-block:: pyml

    title: First order absorption model with peripheral compartment


.. _tut-description-author_spec:

author
======

Type: :term:`str <str>`

Author of the model

Example:-

.. code-block:: pyml

    author: J.R. Hartley


.. _tut-description-abstract_spec:

abstract
========

Type: :term:`verbatim <verbatim>`

Abstract paragraph describing model

Example:-

.. code-block:: pyml

    abstract: |
        A two compartment PK model with bolus dose and
        first order absorption, similar to a nonmem advan4trans4 model.


.. _tut-description-keywords_spec:

keywords
========

Type: :term:`list <list>`

Keywords list used to categorise models.

Example:-

.. code-block:: pyml

    keywords: ['tutorial', 'pk', 'advan4', 'dep_two_cmp', 'first order']


.. _tut-file_paths_spec:

FILE_PATHS
**********

Type: :term:`dict_record <dict_record>`

file paths

Example:-

.. code-block:: pyml

    FILE_PATHS:
        output_folder: auto
        output_file_ext: ['svg']
        output_iteration_results: True


.. _tut-file_paths-output_folder_spec:

output_folder
=============

Type: :term:`output_folder <output_folder>` / :term:`auto <auto>`

Output folder - results of computation stored here

Example:-

.. code-block:: pyml

    output_folder: auto


.. _tut-file_paths-output_file_ext_spec:

output_file_ext
===============

Type: :term:`list_of(pdf,png,svg) <list_of>`

Output file extension - determines graphical output file format.

Example:-

.. code-block:: pyml

    output_file_ext: ['svg']


.. _tut-file_paths-output_iteration_results_spec:

output_iteration_results
========================

Type: :term:`bool <bool>`

Option to output iteration-by-iteration values.

Example:-

.. code-block:: pyml

    output_iteration_results: True


.. _tut-data_fields_spec:

DATA_FIELDS
***********

Type: :term:`dict_record <dict_record>`

data fields for popy.dat.fields object

Example:-

.. code-block:: pyml

    DATA_FIELDS:
        type_field: TYPE
        id_field: ID
        time_field: TIME


.. _tut-data_fields-type_field_spec:

type_field
==========

Type: :term:`str <str>`

Field name in data file that contains row type info, e.g. obs/dose etc

Example:-

.. code-block:: pyml

    type_field: TYPE


.. _tut-data_fields-id_field_spec:

id_field
========

Type: :term:`str <str>`

Field name in data file that contains identity string for each data row e.g. obs/dose etc

Example:-

.. code-block:: pyml

    id_field: ID


.. _tut-data_fields-time_field_spec:

time_field
==========

Type: :term:`str <str>`

Field name in data file that contains time or event for each data row

Example:-

.. code-block:: pyml

    time_field: TIME


.. _tut-level_params_spec:

LEVEL_PARAMS
************

Type: :term:`repeat_record <repeat_record>`

Level params to define hierarchical population model

Example:-

.. code-block:: pyml

    LEVEL_PARAMS:
        GLOBAL:
            split_field: None

            split_dict: {}

            gen_params: |
                c[AMT] = 100.0
                f[KA] = 0.2
                f[CL] = 2.0
                f[V1] = 50
                f[Q] = 1.0
                f[V2] = 80
                f[KA_isv,CL_isv,V1_isv,Q_isv,V2_isv] = [
                    [0.1],
                    [0.01, 0.03],
                    [0.01, -0.01, 0.09],
                    [0.01, 0.02, 0.01, 0.07],
                    [0.01, 0.02, 0.01, 0.01, 0.05],
                ]
                f[PNOISE] = 0.15

            fit_params: |
                f[KA] ~ P1.0
                f[CL] ~ P1.0
                f[V1] ~ P20
                f[Q] ~ P0.5
                f[V2] ~ P100
                f[KA_isv,CL_isv,V1_isv,Q_isv,V2_isv] ~ spd_matrix() [
                    [0.05],
                    [0.01, 0.05],
                    [0.01, 0.01, 0.05],
                    [0.01, 0.01, 0.01, 0.05],
                    [0.01, 0.01, 0.01, 0.01, 0.05],
                ]
                f[PNOISE] ~ P0.1

        INDIV:
            split_field: ID

            split_dict: "*"

            gen_params: |
                c[ID] = sequential(50)
                t[DOSE] = 2.0
                t[OBS] ~ unif(1.0, 50.0; 5)
                # t[OBS] = range(1.0, 50.0; 5)
                r[KA, CL, V1, Q, V2] ~ mnorm([0,0,0,0,0], f[KA_isv,CL_isv,V1_isv,Q_isv,V2_isv])

            fit_params: |
                r[KA, CL, V1, Q, V2] ~ mnorm([0,0,0,0,0], f[KA_isv,CL_isv,V1_isv,Q_isv,V2_isv])


.. _tut-level_params-split_field_spec:

split_field
===========

Type: :term:`str <str>`

Field to split level into sub levels

Example:-

.. code-block:: pyml

    split_field: none


.. _tut-level_params-split_dict_spec:

split_dict
==========

Type: :term:`dict <dict>` / :term:`star <star>`

Defines named subsets, defined by ranges of split field values

Example:-

.. code-block:: pyml

    split_dict: {}


.. _tut-level_params-gen_params_spec:

gen_params
==========

Type: :term:`verbatim <verbatim>`

Defines f[X] and r[X] variables in split field ranges
for gen_scripts

Example:-

.. code-block:: pyml

    gen_params: |


.. _tut-level_params-fit_params_spec:

fit_params
==========

Type: :term:`verbatim <verbatim>`

Defines f[X] and r[X] variables in split field ranges
for fit_scripts

Example:-

.. code-block:: pyml

    fit_params: |


.. _tut-model_params_spec:

MODEL_PARAMS
************

Type: :term:`verbatim <verbatim>`

Defines the mapping from c[X], f[X] and r[X] variables to individual model m[X] parameters.

Example:-

.. code-block:: pyml

    MODEL_PARAMS: |
        m[KA] = f[KA] * exp(r[KA])
        m[CL] = f[CL] * exp(r[CL])
        m[V1] = f[V1] * exp(r[V1])
        m[Q] = f[Q] * exp(r[Q])
        m[V2] = f[V2] * exp(r[V2])
        m[ANOISE] = 0.001
        m[PNOISE] = f[PNOISE]


.. _tut-states_spec:

STATES
******

Type: :term:`verbatim <verbatim>`

Optional section for setting initial values of s[X] variables
can also set slabel[X] text labels.

Example:-

.. code-block:: pyml

    STATES: |


.. _tut-derivatives_spec:

DERIVATIVES
***********

Type: :term:`verbatim <verbatim>`

Define how the covariates and effects determine flows
between compartments.

Example:-

.. code-block:: pyml

    DERIVATIVES: |
        # s[DEPOT,CENTRAL,PERI] = @dep_two_cmp_cl{dose:@bolus{amt:c[AMT]}}
        d[DEPOT] = @bolus{amt:c[AMT]} - m[KA]*s[DEPOT]
        d[CENTRAL] = m[KA]*s[DEPOT] - s[CENTRAL]*m[CL]/m[V1] - s[CENTRAL]*m[Q]/m[V1]  + s[PERI]*m[Q]/m[V2]
        d[PERI] = s[CENTRAL]*m[Q]/m[V1] - s[PERI]*m[Q]/m[V2]


.. _tut-predictions_spec:

PREDICTIONS
***********

Type: :term:`verbatim <verbatim>`

Define the final predicted m[X] variables to be output
by the compartment model system.

Example:-

.. code-block:: pyml

    PREDICTIONS: |
        p[DV_CENTRAL] = s[CENTRAL]/m[V1]
        var = m[ANOISE]**2 + m[PNOISE]**2 * p[DV_CENTRAL]**2
        c[DV_CENTRAL] ~ norm(p[DV_CENTRAL], var)


.. _tut-ode_solver_spec:

ODE_SOLVER
**********

Type: :term:`one_of_record <one_of_record>`

one of many possible solvers

Example:-

.. code-block:: pyml

    ODE_SOLVER:
        SCIPY_ODEINT: {atol: 1e-06, rtol: 1e-06, max_nsteps: 10000000, use_sens: False}


.. _tut-ode_solver-no_solver_spec:

NO_SOLVER
=========

Type: :term:`dict_record <dict_record>`

Null method for blank derivatives.

Example:-

.. code-block:: pyml

    NO_SOLVER: {}


.. _tut-ode_solver-analytic_spec:

ANALYTIC
========

Type: :term:`dict_record <dict_record>`

Analytic method for solving ODE

Example:-

.. code-block:: pyml

    ANALYTIC: {}


.. _tut-ode_solver-scipy_odeint_spec:

SCIPY_ODEINT
============

Type: :term:`dict_record <dict_record>`

odeint solver record

Example:-

.. code-block:: pyml

    SCIPY_ODEINT:
        atol: 1e-06
        rtol: 1e-06
        max_nsteps: 10000000
        use_sens: False


.. _tut-ode_solver-scipy_odeint-atol_spec:

atol
----

Type: :term:`float <float>`

Absolute tolerance of ode solver.

Example:-

.. code-block:: pyml

    atol: 1e-06


.. _tut-ode_solver-scipy_odeint-rtol_spec:

rtol
----

Type: :term:`float <float>`

Relative tolerance of ode solver.

Example:-

.. code-block:: pyml

    rtol: 1e-06


.. _tut-ode_solver-scipy_odeint-max_nsteps_spec:

max_nsteps
----------

Type: :term:`int <int>`

Maximum number of steps allowed in ode solver.

Example:-

.. code-block:: pyml

    max_nsteps: 10000000


.. _tut-ode_solver-scipy_odeint-use_sens_spec:

use_sens
--------

Type: :term:`bool <bool>`

Option to use sensitivity equations in ode solver.

Example:-

.. code-block:: pyml

    use_sens: False


.. _tut-fit_methods_spec:

FIT_METHODS
***********

Type: :term:`list_record <list_record>`

one of many possible fitters

Example:-

.. code-block:: pyml

    FIT_METHODS:
        - JOE:
            ODE_SOLVER: {INHERIT: {}}
            max_n_main_iterations: 30
            CONVERGER: {OBJ_INC: {}}
            recompute_jacobians_flag: False
            use_chain: False
            reset_re_flag: True


.. _tut-fit_methods-joe_spec:

JOE
===

Type: :term:`dict_record <dict_record>`

Joint Optimisation and Estimation method

Example:-

.. code-block:: pyml

    JOE:
        ODE_SOLVER: {INHERIT: {}}
        max_n_main_iterations: 50
        CONVERGER: {OBJ_INC: {}}
        recompute_jacobians_flag: False
        use_chain: False
        reset_re_flag: True


.. _tut-fit_methods-joe-max_n_main_iterations_spec:

max_n_main_iterations
---------------------

Type: :term:`int <int>`

Maximum number of iterations

Example:-

.. code-block:: pyml

    max_n_main_iterations: 50


.. _tut-fit_methods-joe-converger_spec:

CONVERGER
---------

Type: :term:`one_of_record <one_of_record>`

Convergence methods.

Example:-

.. code-block:: pyml

    CONVERGER:
        OBJ_INC: {}


.. _tut-fit_methods-joe-converger-none_spec:

NONE
^^^^

Type: :term:`dict_record <dict_record>`

No convergence testing.

Example:-

.. code-block:: pyml

    NONE: {}


.. _tut-fit_methods-joe-converger-obj_inc_spec:

OBJ_INC
^^^^^^^

Type: :term:`dict_record <dict_record>`

Objective function increase converger.

Example:-

.. code-block:: pyml

    OBJ_INC: {}


.. _tut-fit_methods-joe-converger-obj_sim_spec:

OBJ_SIM
^^^^^^^

Type: :term:`dict_record <dict_record>`

Objective function similar converger.

Example:-

.. code-block:: pyml

    OBJ_SIM: {}


.. _tut-fit_methods-joe-recompute_jacobians_flag_spec:

recompute_jacobians_flag
------------------------

Type: :term:`bool <bool>`

Option to recompute jacobians more often, e.g in noise optimiser.

Example:-

.. code-block:: pyml

    recompute_jacobians_flag: False


.. _tut-fit_methods-joe-use_chain_spec:

use_chain
---------

Type: :term:`bool <bool>`

Option to use chain rule when computing derivatives.

Example:-

.. code-block:: pyml

    use_chain: False


.. _tut-fit_methods-joe-reset_re_flag_spec:

reset_re_flag
-------------

Type: :term:`bool <bool>`

Reset r[X]=0.0 before each r[X] optimisation

Example:-

.. code-block:: pyml

    reset_re_flag: True


.. _tut-covariance_spec:

COVARIANCE
**********

Type: :term:`one_of(none,default,nonmem) <one_of>`

Method for computing standard errors

Example:-

.. code-block:: pyml

    COVARIANCE: none


.. _tut-output_scripts_spec:

OUTPUT_SCRIPTS
**************

Type: :term:`dict_record <dict_record>`

scripts to output for further processing

Example:-

.. code-block:: pyml

    OUTPUT_SCRIPTS:
        GEN: {output_mode: gen_script_and_run, sim_time_step: 1.0, share_axes: True}
        FIT: {output_mode: gen_script_and_run, sim_time_step: 1.0, share_axes: True}
        COMP: {output_mode: gen_script_and_run}
        TUTSUM: {output_mode: gen_script_and_run}


.. _tut-output_scripts-gen_spec:

GEN
===

Type: :term:`dict_record <dict_record>`

options to pass to gen script.

Example:-

.. code-block:: pyml

    GEN:
        output_mode: no_output
        sim_time_step: -1.0
        share_axes: False


.. _tut-output_scripts-gen-output_mode_spec:

output_mode
-----------

Type: :term:`one_of(no_output,gen_script_only,gen_script_and_run) <one_of>`

Output options.

Example:-

.. code-block:: pyml

    output_mode: no_output


.. _tut-output_scripts-gen-sim_time_step_spec:

sim_time_step
-------------

Type: :term:`float <float>`

Size of time step when creating smooth curve predictions
note setting this to a negative value, results in
simulated predictions for each individual 
ONLY at time points in the original data set.

Example:-

.. code-block:: pyml

    sim_time_step: -1.0


.. _tut-output_scripts-gen-share_axes_spec:

share_axes
----------

Type: :term:`bool <bool>`

Option to share axes between individuals when plotting
graphical data

Example:-

.. code-block:: pyml

    share_axes: False


.. _tut-output_scripts-fit_spec:

FIT
===

Type: :term:`dict_record <dict_record>`

options to pass to fit script.

Example:-

.. code-block:: pyml

    FIT:
        output_mode: no_output
        sim_time_step: -1.0
        share_axes: False


.. _tut-output_scripts-fit-output_mode_spec:

output_mode
-----------

Type: :term:`one_of(no_output,gen_script_only,gen_script_and_run) <one_of>`

Output options.

Example:-

.. code-block:: pyml

    output_mode: no_output


.. _tut-output_scripts-fit-sim_time_step_spec:

sim_time_step
-------------

Type: :term:`float <float>`

Size of time step when creating smooth curve predictions
note setting this to a negative value, results in
simulated predictions for each individual 
ONLY at time points in the original data set.

Example:-

.. code-block:: pyml

    sim_time_step: -1.0


.. _tut-output_scripts-fit-share_axes_spec:

share_axes
----------

Type: :term:`bool <bool>`

Option to share axes between individuals when plotting
graphical data

Example:-

.. code-block:: pyml

    share_axes: False


.. _tut-output_scripts-comp_spec:

COMP
====

Type: :term:`dict_record <dict_record>`

options to pass to comp script.

Example:-

.. code-block:: pyml

    COMP:
        output_mode: no_output


.. _tut-output_scripts-comp-output_mode_spec:

output_mode
-----------

Type: :term:`one_of(no_output,gen_script_only,gen_script_and_run) <one_of>`

Output options.

Example:-

.. code-block:: pyml

    output_mode: no_output


.. _tut-output_scripts-tutsum_spec:

TUTSUM
======

Type: :term:`dict_record <dict_record>`

options to pass to tutsum script.

Example:-

.. code-block:: pyml

    TUTSUM:
        output_mode: no_output


.. _tut-output_scripts-tutsum-output_mode_spec:

output_mode
-----------

Type: :term:`one_of(no_output,gen_script_only,gen_script_and_run) <one_of>`

Output options.

Example:-

.. code-block:: pyml

    output_mode: no_output



