resmod#

The resmod tool is a general tool to decide the best residual error model given a start model.

Running#

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

To initiate resmod in Python/R:

from pharmpy.tools import run_resmod

start_model = read_model('path/to/model')
res = run_resmod(model=start_model)

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

pharmpy run resmod path/to/model

Arguments#

Argument

Description

groups

Number of groups to use for the time varying model (default is 4)

p_value

p-value for model selection (default is 0.05)

skip

List of residual error models to not consider

model

Start model

Models#

The various residual error models tested by resmod can be found in the table below together with links to detailed documentation of the functions used to create them.

Model name

Function

IIV_on_RUV

set_iiv_on_ruv

power

set_power_on_ruv

combined

set_combined_error_model

time_varying

set_time_varying_error_model

Procedure#

Resmod is doing modeling on the conditional weighted residual [Ibrahim] of the fit of the input model to quickly assess which residual model to select. The input model is then updated with the new residual error model and fit to see if the selected residual error model was indeed better. This is done multiple times to see if additional features of the residual error model should be added.

digraph G { draw [ label = "Input model"; shape = rect; ]; resmod [ label = "Run residual error models"; shape = rect; ]; select [ label = "Select best model"; shape = rect; ]; update [ label = "Update and run input model"; shape = rect; ] better [ label = "Significantly better?"; shape = diamond; ] done [ label = "Done"; shape = rect; ] draw -> resmod -> select -> update -> better; better -> done [label = "No"]; better -> resmod [label = "Yes (max 3 times)"] }

Selection is done using the likelihood ratio test and a default p-value of 0.05.

The resmod results#

The results object contains the candidate models, the start model, and the selected best model (based on the input selection criteria). The tool also creates various summary tables which can be accessed in the results object, as well as files in .csv/.json format.

Consider a standard resmod run:

res = run_resmod(model=start_model)

The summary_tool table contains information such as which feature each model candidate has, the difference to the start model, and final ranking:

description dofv ofv rank parent_model
model
best_resmod_2 IIV_on_RUV+time_varying3 35.269102 -2495.973571 1.0 best_resmod_1
best_resmod_1 IIV_on_RUV 12.957378 -2473.661847 2.0 mox3
mox3 0.000000 -2460.704469 NaN mox3

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.modeling.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,1)_estimate OMEGA(2,2)_estimate OMEGA(3,3)_estimate SIGMA(1,1)_estimate IIV_RUV1_estimate time_varying_estimate
model
mox3 True 0 0 -2460.704469 -2444.704469 -2423.757516 NaN 9.73 106.707 27.5434 0.531596 0.077743 0.038888 0.072309 0.704770 0.093311 NaN NaN
best_resmod_1 IIV_on_RUV True 0 0 -2473.661847 -2455.661847 -2435.047712 8.0 3.91 105.794 27.3091 0.528620 0.076793 0.039924 0.074889 0.707665 0.081095 0.039675 NaN
best_resmod_2 IIV_on_RUV+time_varying3 True 0 0 -2495.973571 -2475.973571 -2453.068976 9.0 4.67 106.733 27.3094 0.532547 0.071628 0.038470 0.075048 0.705429 0.044311 0.040734 1.42509

A summary table of predicted influential individuals and outliers can be seen in summary_individuals_count. See pharmpy.modeling.summarize_individuals_count_table() for information on the content of this table.

parent_model inf_selection inf_params out_obs out_ind inf_outlier
model
mox3 mox3 0 0 0 1 0
best_resmod_1 mox3 0 0 0 0 0
best_resmod_2 best_resmod_1 0 0 0 0 0

Finally, you can see different individual statistics summary_individuals. See pharmpy.modeling.summarize_individuals() for information on the content of this table.

parent_model outlier_count ofv dofv_vs_parent predicted_dofv predicted_residual
model ID
mox3 110 mox3 0.0 -16.215727 0.000000 0.164274 0.450202
112 mox3 0.0 -25.655144 0.000000 0.195425 0.960585
113 mox3 0.0 -39.708324 0.000000 0.090461 -0.848498
121 mox3 0.0 -39.762729 0.000000 0.052021 -1.239462
123 mox3 0.0 -25.236530 0.000000 0.065148 -0.571347
... ... ... ... ... ... ... ...
best_resmod_2 1403 best_resmod_1 0.0 -12.229762 0.244582 0.161981 1.509910
1404 best_resmod_1 0.0 -20.715966 -0.373696 0.084489 0.647642
1405 best_resmod_1 0.0 -24.423148 1.344772 0.083776 -0.259395
1406 best_resmod_1 0.0 -39.419741 0.101415 0.024651 -0.443543
1407 best_resmod_1 0.0 -48.774540 0.124023 0.183088 0.977222

219 rows × 6 columns

Ibrahim

Moustafa M. A. Ibrahim, Rikard Nordgren, Maria C. Kjellsson, Mats O. Karlsson. Model-Based Residual Post-Processing for Residual Model Identification. The AAPS Journal 2018 https://doi.org/10.1208/s12248-018-0240-7