ruvsearch#

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

Running#

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

To initiate RUVsearch in Python/R:

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

start_model = read_model('path/to/model')
start_model_results = read_modelfit_results('path/to/model')
res = run_ruvsearch(model=start_model, results=start_model_results)

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

pharmpy run ruvsearch path/to/model

Arguments#

Mandatory#

Argument

Description

model

Start model

results

ModelfitResults for the start model

Optional#

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.001)

skip

List of residual error models to not consider

strictness

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

Models#

The various residual error models tested by RUVsearch 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#

RUVsearch 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. (Due to the similarity between the power error model and the combined error model, the combination of these two error models is not considered in the procedure. E.g., if the power error model is selected in the current iteration, the combined error model will be skipped in the next iteration automatically.)

digraph G { draw [ label = "Input model"; shape = rect; ]; ruvsearch [ 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 -> ruvsearch -> select -> update -> better; better -> done [label = "No"]; better -> ruvsearch [label = "Yes (max 3 times)"] }

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

The RUVsearch results#

The results object contains the start model, the residual error models based on the conditional weighted residual(CWRES) of the start model, the candidate models, 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 ruvsearch run:

res = run_ruvsearch(model=start_model, results=start_model_results)

The cwres_models table contains information on the residual error models, such as the iteration times, the changes of OFV compared to the base CWRES model and some key parameter estimates.

dofv parameters
model dvid iteration
IIV_on_RUV 1 1 10.479721 {'omega': 0.027766}
combined 1 1 1.385268 {'sigma_add': 0.000367, 'sigma_prop': 0.967365}
power 1 1 0.002792 {'theta': 0.00123}
time_varying1 1 1 3.117041 {'theta': 1.0976}
time_varying2 1 1 6.555154 {'theta': 1.12252}
time_varying3 1 1 6.336641 {'theta': 1.14299}
combined 1 2 1.091207 {'sigma_add': 0.000337, 'sigma_prop': 1.05242}
power 1 2 0.065738 {'theta': 0.006105}
time_varying1 1 2 3.654562 {'theta': 1.10545}
time_varying2 1 2 7.046578 {'theta': 1.12659}
time_varying3 1 2 7.519115 {'theta': 1.15573}
combined 1 3 1.612710 {'sigma_add': 0.00054, 'sigma_prop': 1.04769}
power 1 3 1.643741 {'theta': -0.030825}

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

description n_params d_params dofv ofv parent_model
step model
0 mox3 8 0 0.000000 -2460.704469 mox3
1 best_ruvsearch_1 IIV_on_RUV 9 1 12.957378 -2473.661847 mox3
2 best_ruvsearch_2 IIV_on_RUV+time_varying3 10 1 35.269102 -2495.973571 best_ruvsearch_1

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 POP_VC_estimate POP_CL_estimate POP_MAT_estimate IIV_VC_estimate IIV_VC_IIV_CL_estimate IIV_CL_estimate IIV_MAT_estimate RUV_PROP_estimate IIV_RUV1_estimate time_varying_estimate
step model
0 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
1 best_ruvsearch_1 IIV_on_RUV True 0 0 -2473.661847 -2455.661847 -2435.047712 8.0 3.80 105.794 27.3091 0.528620 0.076793 0.039924 0.074889 0.707665 0.081095 0.039675 NaN
2 best_ruvsearch_2 IIV_on_RUV+time_varying3 True 0 0 -2495.973571 -2475.973571 -2453.068976 9.0 4.71 106.733 27.3094 0.532547 0.071628 0.038470 0.075048 0.705429 0.044311 0.040734 1.42509
[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