# METHOD_OPTIONS

Type: dict_record

method options for fit_script

Example:-

    METHOD_OPTIONS:
        py_module: fit
        rand_seed: 12345
        float_format: default

## py_module

Type: one_of(fit)

Python module required to process this script file

Example:-

    py_module: fit

## rand_seed

Type: int / auto

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

Example:-

    rand_seed: 12345

## float_format

Type: str

Format string for numerical output

Example:-

    float_format: default

# PARALLEL

Type: one_of_record

one of many possible servers

Example:-

    PARALLEL:
        SINGLE: {}

## SINGLE

Type: dict_record

single process server spec.

Example:-

    SINGLE: {}

## MPI_WORKERS

Type: dict_record

MPI local server spec.

Example:-

    MPI_WORKERS:
        n_workers: auto

### n_workers

Type: int / auto

Number of workers to use on this machine, defaults to number of processors, but could be more or fewer.

Example:-

    n_workers: auto

# DESCRIPTION

Type: dict_record

Description fields for script.

Example:-

    DESCRIPTION:
        name: example
        title: A PKPD model
        author: A.N. Other
        abstract: |
        keywords: []

## name

Type: str

Unique name used to distinguish script

Example:-

    name: example

## title

Type: str

A longer text string that could serve as a title

Example:-

    title: A PKPD model

## author

Type: str

Author of the model

Example:-

    author: A.N. Other

## abstract

Type: verbatim

Abstract paragraph describing model

Example:-

    abstract: |

## keywords

Type: list

Keywords list used to categorise models.

Example:-

    keywords: []

# FILE_PATHS

Type: dict_record

file paths for fit_script

Example:-

    FILE_PATHS:
        input_data_file: input.csv
        output_folder: auto
        temp_folder: auto
        log_folder: auto
        output_file_ext: ['svg']
        delete_old_files_flag: False
        input_solution_file: none
        output_iteration_results: True

## input_data_file

Type: input_file

path to input comma separated value file in popy data format

Example:-

    input_data_file: input.csv

## output_folder

Type: output_folder / auto

Output folder - results of computation stored here

Example:-

    output_folder: auto

## temp_folder

Type: output_folder / auto

Temp folder - temporary files stored here

Example:-

    temp_folder: auto

## log_folder

Type: output_folder / auto

Log folder - log files stored here

Example:-

    log_folder: auto

## output_file_ext

Type: list_of(pdf,png,svg)

Output file extension - determines graphical output file format.

Example:-

    output_file_ext: ['svg']

## delete_old_files_flag

Type: bool

Option to delete any existing files before running.

Example:-

    delete_old_files_flag: False

## input_solution_file

Type: input_file / none

Solution containing f[X] values from a previous run.

Example:-

    input_solution_file: none

## output_iteration_results

Type: bool

Option to output iteration-by-iteration values.

Example:-

    output_iteration_results: True

# DATA_FIELDS

Type: dict_record

data fields for popy.dat.fields object

Example:-

    DATA_FIELDS:
        type_field: TYPE
        id_field: ID
        time_field: TIME

## type_field

Type: str

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

Example:-

    type_field: TYPE

## id_field

Type: str

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

Example:-

    id_field: ID

## time_field

Type: str

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

Example:-

    time_field: TIME

# PREPROCESS

Type: verbatim

Code that preprocesses the input data. Use this to filter rows and create derived covariates.

Example:-

    PREPROCESS: |

# EFFECTS

Type: repeat_verb_record

EFFECT params to define hierarchical population model

Example:-

    EFFECTS:
        POP: |
            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

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

# MODEL_PARAMS

Type: verbatim

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

Example:-

    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]

# STATES

Type: verbatim

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

Example:-

    STATES: |

# DERIVATIVES

Type: verbatim

Define how the covariates and effects determine flows between compartments.

Example:-

    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]

# PREDICTIONS

Type: verbatim

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

Example:-

    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)

# ODE_SOLVER

Type: one_of_record

one of many possible solvers

Example:-

    ODE_SOLVER:
        SCIPY_ODEINT:
            atol: 1e-06
            rtol: 1e-06
            max_nsteps: 10000000
            use_supersections: True
            use_jacobian: False
            use_sens: False
            use_tcrit: False

## NO_SOLVER

Type: dict_record

Null method for blank derivatives.

Example:-

    NO_SOLVER: {}

## ANALYTIC

Type: dict_record

Analytic method for solving ODE

Example:-

    ANALYTIC:
        use_supersections: auto
        use_sens: True

### use_supersections

Type: bool / auto

Option to combine sections into supersections, which can make PoPy run faster, however with discontinuous ODE params you may need to turn this off (closer to nonmem approach).

Example:-

    use_supersections: auto

### use_sens

Type: bool

Option to use sensitivity equations in ode solver.

Example:-

    use_sens: True

## SCIPY_ODEINT

Type: dict_record

odeint solver record

Example:-

    SCIPY_ODEINT:
        atol: 1e-06
        rtol: 1e-06
        max_nsteps: 10000000
        use_supersections: auto
        use_jacobian: False
        use_sens: True
        use_tcrit: False

### atol

Type: float

Absolute tolerance of ode solver.

Example:-

    atol: 1e-06

### rtol

Type: float

Relative tolerance of ode solver.

Example:-

    rtol: 1e-06

### max_nsteps

Type: int

Maximum number of steps allowed in ode solver.

Example:-

    max_nsteps: 10000000

### use_supersections

Type: bool / auto

Option to combine sections into supersections, which can make PoPy run faster, however with discontinuous ODE params you may need to turn this off (closer to nonmem approach).

Example:-

    use_supersections: auto

### use_jacobian

Type: bool

Option to use jacobian in ode solver.

Example:-

    use_jacobian: False

### use_sens

Type: bool

Option to use sensitivity equations in ode solver.

Example:-

    use_sens: True

### use_tcrit

Type: bool

Option to set lsoda tcrit to start and end of subsection. Note this is an experimental option.

Example:-

    use_tcrit: False

## CPPODE

Type: dict_record

C++ version of original cvode c library.

Example:-

    CPPODE:
        atol: 1e-06
        rtol: 1e-06
        max_nsteps: 10000000
        use_supersections: auto
        use_sens: True

### atol

Type: float

Absolute tolerance of ode solver.

Example:-

    atol: 1e-06

### rtol

Type: float

Relative tolerance of ode solver.

Example:-

    rtol: 1e-06

### max_nsteps

Type: int

Maximum number of steps allowed in ode solver.

Example:-

    max_nsteps: 10000000

### use_supersections

Type: bool / auto

Option to combine sections into supersections, which can make PoPy run faster, however with discontinuous ODE params you may need to turn this off (closer to nonmem approach).

Example:-

    use_supersections: auto

### use_sens

Type: bool

Option to use sensitivity equations in ode solver.

Example:-

    use_sens: True

## CPPLSODA

Type: dict_record

C++ version of original cvode c library.

Example:-

    CPPLSODA:
        atol: 1e-06
        rtol: 1e-06
        max_nsteps: 10000000
        use_supersections: auto
        use_sens: True
        hmin: 1e-12

### atol

Type: float

Absolute tolerance of ode solver.

Example:-

    atol: 1e-06

### rtol

Type: float

Relative tolerance of ode solver.

Example:-

    rtol: 1e-06

### max_nsteps

Type: int

Maximum number of steps allowed in ode solver.

Example:-

    max_nsteps: 10000000

### use_supersections

Type: bool / auto

Option to combine sections into supersections, which can make PoPy run faster, however with discontinuous ODE params you may need to turn this off (closer to nonmem approach).

Example:-

    use_supersections: auto

### use_sens

Type: bool

Option to use sensitivity equations in ode solver.

Example:-

    use_sens: True

### hmin

Type: float

Minimum step size of ode solver.

Example:-

    hmin: 1e-12

# FIT_METHODS

Type: list_record

one of many possible fitters

Example:-

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

## JOE

Type: dict_record

Joint Optimisation and Estimation method

Example:-

    JOE:
        ODE_SOLVER: {INHERIT: {}}
        output_timing_flag: False
        output_warning_detail_flag: True
        max_n_main_iterations: 50
        CONVERGER: {OBJ_INC: {}}
        recompute_jacobians_flag: False
        use_laplacian: False
        use_chain: True
        use_lm_jac: True
        reset_re_flag: True

### output_timing_flag

Type: bool

Option to output timing info.

Example:-

    output_timing_flag: False

### output_warning_detail_flag

Type: bool

Option to output warning detail.

Example:-

    output_warning_detail_flag: True

### max_n_main_iterations

Type: int

Maximum number of iterations

Example:-

    max_n_main_iterations: 50

### CONVERGER

Type: one_of_record

Convergence methods.

Example:-

    CONVERGER:
        OBJ_INC: {}

#### NONE

Type: dict_record

No convergence testing.

Example:-

    NONE: {}

#### OBJ_INC

Type: dict_record

Objective function increase converger.

Example:-

    OBJ_INC: {}

#### OBJ_SIM

Type: dict_record

Objective function similar converger.

Example:-

    OBJ_SIM: {}

### recompute_jacobians_flag

Type: bool

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

Example:-

    recompute_jacobians_flag: False

### use_laplacian

Type: bool

Option to use full laplacian to compute hessian in objective function term4, this is much slower than using the expectation of the outer product of the jacobian

Example:-

    use_laplacian: False

### use_chain

Type: bool

Option to use chain rule when computing derivatives.

Example:-

    use_chain: True

### use_lm_jac

Type: bool

Option to use custom jacobian when optimising r[X] using L-M.

Example:-

    use_lm_jac: True

### reset_re_flag

Type: bool

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

Example:-

    reset_re_flag: True

## ND

Type: dict_record

None Derivative Optimisation method

Example:-

    ND:
        ODE_SOLVER: {INHERIT: {}}
        output_timing_flag: False
        output_warning_detail_flag: True
        max_n_main_iterations: 50
        CONVERGER: {OBJ_INC: {}}
        recompute_jacobians_flag: False
        use_laplacian: False
        use_chain: True
        use_lm_jac: True
        use_central_diffs_from_start: False
        reset_re_flag: True
        central_diff_switch_flag: True
        var_fx_bobyqa_opt_flag: True

### output_timing_flag

Type: bool

Option to output timing info.

Example:-

    output_timing_flag: False

### output_warning_detail_flag

Type: bool

Option to output warning detail.

Example:-

    output_warning_detail_flag: True

### max_n_main_iterations

Type: int

Maximum number of iterations

Example:-

    max_n_main_iterations: 50

### CONVERGER

Type: one_of_record

Convergence methods.

Example:-

    CONVERGER:
        OBJ_INC: {}

#### NONE

Type: dict_record

No convergence testing.

Example:-

    NONE: {}

#### OBJ_INC

Type: dict_record

Objective function increase converger.

Example:-

    OBJ_INC: {}

#### OBJ_SIM

Type: dict_record

Objective function similar converger.

Example:-

    OBJ_SIM: {}

### recompute_jacobians_flag

Type: bool

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

Example:-

    recompute_jacobians_flag: False

### use_laplacian

Type: bool

Option to use full laplacian to compute hessian in objective function term4, this is much slower than using the expectation of the outer product of the jacobian

Example:-

    use_laplacian: False

### use_chain

Type: bool

Option to use chain rule when computing derivatives.

Example:-

    use_chain: True

### use_lm_jac

Type: bool

Option to use custom jacobian when optimising r[X] using L-M.

Example:-

    use_lm_jac: True

### use_central_diffs_from_start

Type: bool

Use central differencing from the start.

Example:-

    use_central_diffs_from_start: False

### reset_re_flag

Type: bool

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

Example:-

    reset_re_flag: True

### central_diff_switch_flag

Type: bool

Allow switch to central differences, instead of forward diff

Example:-

    central_diff_switch_flag: True

### var_fx_bobyqa_opt_flag

Type: bool

Option to include var f[X] in BOBYQA optimisation

Example:-

    var_fx_bobyqa_opt_flag: True

## FOCE

Type: dict_record

First order conditional estimation method

Example:-

    FOCE:
        ODE_SOLVER: {INHERIT: {}}
        output_timing_flag: False
        output_warning_detail_flag: True
        max_n_main_iterations: 50
        CONVERGER: {OBJ_INC: {}}
        recompute_jacobians_flag: False
        use_laplacian: False
        use_chain: True
        use_central_diffs_from_start: False
        use_lm_jac: True
        reset_re_flag: True
        central_diff_switch_flag: True

### output_timing_flag

Type: bool

Option to output timing info.

Example:-

    output_timing_flag: False

### output_warning_detail_flag

Type: bool

Option to output warning detail.

Example:-

    output_warning_detail_flag: True

### max_n_main_iterations

Type: int

Maximum number of iterations

Example:-

    max_n_main_iterations: 50

### CONVERGER

Type: one_of_record

Convergence methods.

Example:-

    CONVERGER:
        OBJ_INC: {}

#### NONE

Type: dict_record

No convergence testing.

Example:-

    NONE: {}

#### OBJ_INC

Type: dict_record

Objective function increase converger.

Example:-

    OBJ_INC: {}

#### OBJ_SIM

Type: dict_record

Objective function similar converger.

Example:-

    OBJ_SIM: {}

### recompute_jacobians_flag

Type: bool

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

Example:-

    recompute_jacobians_flag: False

### use_laplacian

Type: bool

Option to use full laplacian to compute hessian in objective function term4, this is much slower than using the expectation of the outer product of the jacobian

Example:-

    use_laplacian: False

### use_chain

Type: bool

Option to use chain rule when computing derivatives.

Example:-

    use_chain: True

### use_central_diffs_from_start

Type: bool

Use central differencing from the start.

Example:-

    use_central_diffs_from_start: False

### use_lm_jac

Type: bool

Option to use custom jacobian when optimising r[X] using L-M.

Example:-

    use_lm_jac: True

### reset_re_flag

Type: bool

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

Example:-

    reset_re_flag: True

### central_diff_switch_flag

Type: bool

Allow switch to central differences, instead of forward diff

Example:-

    central_diff_switch_flag: True

# COVARIANCE

Type: one_of_record

Covariance methods used to estimate standard errors.

Example:-

    COVARIANCE:
        NO_COVARIANCE: {}

## NO_COVARIANCE

Type: dict_record

Do NOT compute covariance matrix and standard errors.

Example:-

    NO_COVARIANCE: {}

## SANDWICH

Type: dict_record

Use sandwich operator to estimate covariance matrix.

Example:-

    SANDWICH:
        var_covariance_flag: False
        inv_hessian_flag: False

### var_covariance_flag

Type: bool

Optionally compute standard errors for f[X] covariance elements this could take a long time for large covariance matrices. Note the results of the standard error computation for the main f[X] parameters combined with the variances will be different.

Example:-

    var_covariance_flag: False

### inv_hessian_flag

Type: bool

Optionally invert the hessian and output results to disk. this is mainly to generate PoPy documentation output.

Example:-

    inv_hessian_flag: False

## NONMEM

Type: dict_record

Use sandwich operator to estimate covariance matrix.

Example:-

    NONMEM:
        var_covariance_flag: False
        inv_hessian_flag: False

### var_covariance_flag

Type: bool

Optionally compute standard errors for f[X] covariance elements this could take a long time for large covariance matrices. Note the results of the standard error computation for the main f[X] parameters combined with the variances will be different.

Example:-

    var_covariance_flag: False

### inv_hessian_flag

Type: bool

Optionally invert the hessian and output results to disk. this is mainly to generate PoPy documentation output.

Example:-

    inv_hessian_flag: False

# OUTPUT_SCRIPTS

Type: dict_record

List of scripts to output for further processing

Example:-

    OUTPUT_SCRIPTS:
        GRPH: {output_mode: none, share_axes: False, y_scale: linear}
        SIM:
            output_mode: run
            sim_time_step: 1.0
            share_axes: False
            comb_grph_flag: False
            y_scale: linear
        MSIM:
            output_mode: create
            y_scale: linear
            x_var: TIME_SINCE_LAST_DOSE
            split_field: none
        FITSUM: {output_mode: run}

## GRPH

Type: dict_record

Options to pass to grph script.

Example:-

    GRPH:
        output_mode: none
        share_axes: False
        y_scale: linear

### output_mode

Type: one_of(none,create,run)

Output options.

Example:-

    output_mode: none

### share_axes

Type: bool

Option to share axes between individuals when plotting graphical data

Example:-

    share_axes: False

### y_scale

Type: one_of(linear,log)

y axis scale - can be either ‘linear’ or ‘log’.

Example:-

    y_scale: linear

## SIM

Type: dict_record

Options to pass to sim script.

Example:-

    SIM:
        output_mode: none
        sim_time_step: -1.0
        share_axes: False
        comb_grph_flag: False
        y_scale: linear

### output_mode

Type: one_of(none,create,run)

Output options.

Example:-

    output_mode: none

### sim_time_step

Type: 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:-

    sim_time_step: -1.0

### share_axes

Type: bool

Option to share axes between individuals when plotting graphical data

Example:-

    share_axes: False

### comb_grph_flag

Type: bool

Option to output combined spag graph plot PoPy documentation sometimes requires this

Example:-

    comb_grph_flag: False

### y_scale

Type: one_of(linear,log)

y axis scale - can be either ‘linear’ or ‘log’.

Example:-

    y_scale: linear

## MSIM

Type: dict_record

options to pass to msim script.

Example:-

    MSIM:
        output_mode: none
        y_scale: linear
        x_var: TIME_SINCE_LAST_DOSE
        split_field: none

### output_mode

Type: one_of(none,create,run)

Output options.

Example:-

    output_mode: none

### y_scale

Type: one_of(linear,log)

y axis scale - can be either ‘linear’ or ‘log’.

Example:-

    y_scale: linear

### x_var

Type: str

x axis variable name.

Example:-

    x_var: TIME_SINCE_LAST_DOSE

### split_field

Type: str

field in c[X] data use each value to split data.

Example:-

    split_field: none

## FITSUM

Type: dict_record

options to pass to fitsum_script.

Example:-

    FITSUM:
        output_mode: none

### output_mode

Type: one_of(none,create,run)

Output options.

Example:-

    output_mode: none