IIVsearch#

The IIVsearch tool is a general tool to decide the best IIV structure given a start model. This includes deciding which IIV to keep and the covariance structure based on a chosen selection criteria.

Running#

The IIVsearch tool is available both in Pharmpy/pharmr and from the command line.

To initiate IIVsearch in Python/R:

from pharmpy.modeling import read_model
from pharmpy.tools import read_modelfit_results, run_iivsearch

start_model = read_model('path/to/model')
start_model_results = read_model_results('path/to/model')
res = run_iivsearch(algorithm='top_down_exhaustive',
                    model=start_model,
                    results=start_model_results,
                    iiv_strategy='no_add',
                    rank_type='bic',
                    cutoff=None)

This will take an input model model and run the brute force algorithm. IIVs on structural parameters (such as mean absorption time) will not be added to the input model since iiv_strategy is set to be ‘no_add’. The candidate models will be ranked using bic with default cutoff, which for BIC is none.

To run IIVsearch from the command line, the example code is redefined accordingly:

pharmpy run iivsearch path/to/model 'top_down_exhaustive' --iiv_strategy 'no_add' --rank_type 'bic'

Arguments#

Mandatory#

Argument

Description

algorithm

Algorithm to use (e.g. 'top_down_exhaustive')

model

Input model

results

ModelfitResults of input model

Optional#

Argument

Description

iiv_strategy

If/how IIV should be added to start model (default is to not add). See Adding IIV to the start model

rank_type

Which selection criteria to rank models on, e.g. OFV (default is BIC)

linearize

Decide wether or not to linearize model before starting the search. See linearization tool for more. Default value is False.

cutoff

Cutoff for the ranking function, exclude models that are below cutoff (default is none)

keep

List of IIVs to keep, either by parameter name or ETA name. Default is [“CL”]

strictness

strictness criteria for model selection. Default is “minimization_successful or (rounding_errors and sigdigs>= 0.1)”

correlation_algorithm

Specify if an algorithm different from the argument algorithm should be used when searching for the correlation structure for the added IIVs. If not specified, the same algorithm will be used when searching for which IIVs to add as well as for the correlation structure.

Note

In this documentation, “base model” will be used to describe the model which all candidates are based on. Note that if you have set iiv_strategy to anything other than ‘no_add’, this model will be different to the input model. The term “base model” can thus be either the input model or a copy with added IIVs.

Algorithms#

Different aspects of the IIV structure can be explored in the tool depending on which algorithm is chosen. The available algorithms can be seen in the table below.

Note

If only algorithm is specified, the same will be applied to correlation_algorithm if possible. If not, please see description below which would be used. We recommend setting both arguments if specific algorithms are wanted.

Algorithm

Description

'top_down_exhaustive'

Removes available IIV in all possible combinations. The covariance structure search will search all possible IIV variance and covariance structure

'bottom_up_stepwise'

Iteratively adds all available IIV, one at a time. After each addition, the best model is selected. The algorithm stops when no better model was found after adding a new ETA. The following covariance structure search uses the same approach as ‘top_down_exhaustive’

'skip'

Set this argument if you are certain to skip either the search for number of etas (algorithm='skip') or to skip the search for the best covariance structure (correlation_algorithm='skip'). However, if algorithm is set to skip, then correlation_algorithm need to be set to a valid value.

Adding IIV to the start model#

The iiv_strategy option determines whether or not IIV on the PK parameters should be added to the input model. The different strategies can be seen here:

Strategy

Description

'no_add'

Input model is kept as base model

'add_diagonal'

Diagonal IIV is added to all structural parameters

'fullblock'

IIV is added to all structural parameters, and all IIVs will be in a full block

Comparing and ranking candidates#

The supplied rank_type will be used to compare a set of candidate models and rank them. A cutoff may also be provided if the user does not want to use the default. The following rank functions are available:

Rank type

Description

'ofv'

ΔOFV. Default is to not rank candidates with ΔOFV < cutoff (default 3.84)

'aic'

ΔAIC. Default is to rank all candidates if no cutoff is provided.

'bic'

ΔBIC (iiv). Default is to rank all candidates if no cutoff is provided.

Information about how BIC is calculated can be found in pharmpy.modeling.calculate_bic().

The IIVsearch results#

The results object contains various summary tables which can be accessed in the results object, as well as files in .csv/.json format. The name of the selected best model (based on the input selection criteria) is also included.

Consider a iivsearch run:

res = run_iivsearch(algorithm='td_brute_force',
                    model=start_model,
                    results=start_model_results,
                    iiv_strategy='no_add',
                    rank_type='bic',
                    cutoff=None)

The summary_tool table contains information such as which feature each model candidate has, the difference to the start model (in this case comparing BIC), and final ranking:

description dbic bic rank parent_model
step model
1 iivsearch_no_of_etas_candidate3 [CL]+[VC] 4.282024 -1283.597406 1 mox2
mox2 [CL]+[VC]+[MAT] 0.000000 -1279.315382 2 mox2
iivsearch_no_of_etas_candidate2 [CL]+[MAT] -217.691571 -1061.623812 3 mox2
iivsearch_no_of_etas_candidate6 [CL] -385.641987 -893.673395 4 mox2
iivsearch_no_of_etas_candidate1 [VC]+[MAT] -631.871991 -647.443392 5 mox2
iivsearch_no_of_etas_candidate5 [VC] -633.419500 -645.895882 6 mox2
iivsearch_no_of_etas_candidate4 [MAT] -815.076729 -464.238653 7 mox2
iivsearch_no_of_etas_candidate7 [] -834.249063 -445.066319 8 mox2
2 iivsearch_block_structure_candidate1 [CL,VC] 81.971960 -1365.569365 1 iivsearch_no_of_etas_candidate3
iivsearch_no_of_etas_candidate3 [CL]+[VC] 0.000000 -1283.597406 2 iivsearch_no_of_etas_candidate3

To see information about the actual model runs, such as minimization status, estimation time, and parameter estimates, you can look at the summary_models table. The table is generated with pharmpy.tools.summarize_modelfit_results().

description minimization_successful errors_found warnings_found ofv aic bic runtime_total estimation_runtime THETA(1)_estimate THETA(2)_estimate THETA(3)_estimate OMEGA(1,1)_estimate OMEGA(2,2)_estimate OMEGA(3,3)_estimate SIGMA(1,1)_estimate IIV_CL_IIV_VC_estimate
step model
1 iivsearch_no_of_etas_candidate3 [CL]+[VC] True 0 1 -1292.178325 -1280.178325 -1261.189012 11.0 0.06 24.5333 104.2270 0.433544 0.481830 0.593578 NaN 0.209975 NaN
mox2 [CL]+[VC]+[MAT] True 0 0 -1292.186761 -1278.186761 -1259.530267 4.0 0.10 24.5328 104.2300 0.433676 0.481858 0.593654 0.00013 0.209972 NaN
iivsearch_no_of_etas_candidate2 [CL]+[MAT] True 0 0 -1070.204731 -1058.204731 -1039.215418 12.0 0.17 29.0366 98.9424 1.114210 0.594777 NaN 3.31998 0.401593 NaN
iivsearch_no_of_etas_candidate6 [CL] True 0 0 -897.963854 -887.963854 -868.641723 11.0 0.18 29.1049 103.1360 0.347648 0.396159 NaN NaN 0.574966 NaN
iivsearch_no_of_etas_candidate1 [VC]+[MAT] True 0 0 -656.024311 -644.024311 -625.034998 12.0 0.13 25.1164 239.1090 0.316164 NaN 3.414690 2.08352 0.736398 NaN
iivsearch_no_of_etas_candidate5 [VC] True 0 0 -650.186341 -640.186341 -620.864210 11.0 0.16 25.1064 234.6680 0.310155 NaN 3.247930 NaN 0.750954 NaN
iivsearch_no_of_etas_candidate4 [MAT] True 0 0 -468.529112 -458.529112 -439.206982 11.0 0.16 24.2929 127.9380 0.922906 NaN NaN 4.43473 0.744891 NaN
iivsearch_no_of_etas_candidate7 [] True 0 0 -445.066319 -437.066319 -417.411370 11.0 0.07 24.8058 110.6690 0.434563 NaN NaN NaN 0.810669 NaN
2 iivsearch_block_structure_candidate1 [CL,VC] True 0 0 -1378.440744 -1364.440744 -1343.160972 4.0 0.09 24.9055 106.9880 0.436279 0.516927 0.656304 NaN 0.215885 0.498114
iivsearch_no_of_etas_candidate3 [CL]+[VC] True 0 1 -1292.178325 -1280.178325 -1261.189012 11.0 0.06 24.5333 104.2270 0.433544 0.481830 0.593578 NaN 0.209975 NaN

Finally, you can see a summary of different errors and warnings in summary_errors. See pharmpy.tools.summarize_errors() for information on the content of this table.

time message
step model category error_no
1 iivsearch_no_of_etas_candidate3 WARNING 0 2022-06-14 15:28:07.371 MINIMIZATION SUCCESSFUL\n HOWEVER, PROBLEMS OCCURRED WITH THE MINIMIZATION.
2 iivsearch_no_of_etas_candidate3 WARNING 0 2022-06-14 15:28:07.371 MINIMIZATION SUCCESSFUL\n HOWEVER, PROBLEMS OCCURRED WITH THE MINIMIZATION.
On this page