Learn more about SimBiology

Fitting Pharmacokinetic Model Parameters in the SimBiology Desktop

On this page…
Fitting Parameters Opening a SimBiology Project Adding a Model Task to Fit Parameters Performing Population Fitting Performing Individual Fitting About Simulation Settings and Specifying Alternate Values for Initial Estimates Visualizing Parameter Fitting Results and Generating Diagnostic Plots

Fitting Parameters

The following steps show you one of the workflows you can use in the SimBiology desktop to fit a PK model and estimate parameters.

1. Open a project containing the data and the model as described in Opening a SimBiology Project. To learn more about how to add data to a project, and how to create a PK model, see Importing Data and Creating Pharmacokinetic Models.

2. Add a task that lets you fit parameters as shown in Adding a Model Task to Fit Parameters.

3. Choose the type of fitting:

   • To perform population fitting see Performing Population Fitting.

   • To perform individual fitting see Performing Individual Fitting.

4. (Optional) Specify alternate values for initial guesses of the parameter values and apply the values during parameter fitting. For more information on apply alternate values and to learn about constraints on simulation settings, see About Simulation Settings and Specifying Alternate Values for Initial Estimates.

5. Run the task and visualize results as shown in Visualizing Parameter Fitting Results and Generating Diagnostic Plots.

Back to Top

Opening a SimBiology Project

Follow these steps to open a project if you have already saved the project containing the data and the model.

1. In the MATLAB Command Window, type:

   simbiology

   The SimBiology desktop opens.

2. Select File > Open Project to open the Open SimBiology Project dialog box.

3. Browse to and select the .sbproj format file containing the project.

4. Click Open. The project opens in the SimBiology desktop.

Back to Top

Adding a Model Task to Fit Parameters

• Select Tasks > Add Task to ModelName > Fit Parameters. The Project Explorer updates with the Parameter Fit task and the new task pane opens.

Back to Top

Performing Population Fitting

Specifying the Type of Fitting, the Data to Fit, and Parameters to Estimate

These settings are in the Parameter Fit task pane as shown.

1. Click the Estimation Settings tab if needed.

2. From the Estimation Method list, select population fit (NLMEFIT). This method uses the nlmefit function from the Statistics Toolbox and lets you specify whether the parameters being estimated have random effects. The task returns the fixed effects for the population fit as well as the individual random effects.

3. The Parameters to Estimate table shows the SimBiology parameters, species, and compartments to estimate. To add parameters to this table, enter a name. Alternatively, from the Model Components table (on the right), click and drag the model component and drop it on the Parameters to Estimate table.

   Tip   If the name entered in the table is invalid, you see a red indicator next to the row.

4. In the Parameters to Estimate table, select Fixed to estimate the parameter. In addition, select the Random check box if you want to calculate random effects as well.

   Note   You must specify that at least one component has a random effect. If however, you select all the components as having random effects, this might affect performance depending on the number of components to be estimated.

5. The Initial Estimate column contains the initial guess for the value of the parameter (Value property), the compartment volume (Capacity property), or the species initial amount (InitialAmount property). Double-click a cell to edit the value.

6. From the Data To Fit list select the data set to use in fitting.

   The Data Label column lists the column headers found in the data set.

7. The Classification list is populated with the selection that the column headings are presumed to represent in the software. If the classification is correct, go to the next step. If the classification is missing or incorrect you can change it as follows:

   From the Classification list, select the mapping that applies to each column of the data set.

   For the column in the data set that represents ...	Select ...
   The group ID	group
   Time of dosing and sampling	independent variable
   Bolus dose amount	dose (bolus)
   Infusion dose amount	dose (infusion)
   Dose exhibiting zero-order absorption	dose (zero-order
   Dose exhibiting first-order absorption	dose (first-order)
   The measured amount or concentration of the compound.	response
   The rate of infusion (results of calculation from infusion amount and infusion time)	infusion rate

   Note   You can select each classification type only once. For example, you cannot classify one column as dose (bolus) and another as dose (infusion). Similarly, you cannot select two different columns as response.

8. The Model Component Name column specifies the component in the model that represents the column in the data set. The Model Component Name column is only available to columns in the data that represent the dose received and the observed response.

   If the Model Component Name column lists the correct component, skip to the next step. If the name of the component is incorrect, correct it as follows:

   From the Model Components table (on the right), click and drag the correct model component and drop it on the Model Component Name row that you want to change.

9. You can run the parameter fitting task with the default settings by clicking (Run).

Specifying the Covariance Matrix for Population Fits

For population fitting (population fit (NLMEFIT)) you can specify the covariance matrix pattern of random effect parameters and select the method used to approximate the NLME model likelihood, as shown below.

1. Click the Algorithm Settings tab.

2. In the Covariance Matrix Pattern of Random Effect Parameters section select one of the following:

   • Click Diagonal (default) to specify a diagonal covariance matrix (no covariance relationship between the random effects).

   • Click Full to specify that there is a covariance relationship between each of the random effects.

   • Select specific check boxes to specify block diagonals indicating covariance between a subset of the random effect parameters.

     For example, the figure below indicates covariance between the parameters k_absorption and Clearance_Central.

     

3. From the Method to Approximate the Non-linear Mixed Effects Model Likelihood list, select one of the following:

   • 'LME' — (Default) Use the likelihood for the linear mixed-effects model at the current conditional estimates of the parameters.

   • 'RELME' — Use the restricted likelihood for the linear mixed-effects model at the current conditional estimates of the parameters.

   • 'FO' — First-order Laplacian approximation without random effects.

   • 'FOCE' — First-order Laplacian approximation at the conditional estimates of the random effects.

4. To run the parameter fitting task with the default tolerance settings, click Run. The parameter fitting task runs and generates the plots and results discussed in Visualizing Parameter Fitting Results and Generating Diagnostic Plots.

Also see nlmefit in the Statistics Toolbox documentation for more information.

Setting Tolerance and Maximum Iteration for Population Fits

You can optionally set tolerances and specify maximum iterations as follows:

1. Click the Algorithm Settings tab.

2. Under Advanced Settings, from the Optimization Function list, select fminsearch (default) or fminunc (available if Optimization Toolbox is installed).

3. From the Covariance Matrix Parameterization list, specify the algorithm used internally for the scaled covariance matrix. Select Cholesky factorization of the matrix logarithm or Cholesky factorization.

4. In the Termination Tolerance on Estimated Fixed and Random Effect Parameters box, specify a tolerance; the default is 1.0E-4.

5. In the Termination Tolerance on Log-Likelihood Function box, specify a tolerance; the default is 1.0E-4.

6. In the Maximum Iterations box, specify the maximum number of iterations allowed. The default is 200.

Obtaining the Status of Fitting

By default the parameter fitting task dynamically plots the progress of the fitting task. The task displays plots of the fixed effects (β), the estimates for the diagonal elements of the covariance matrix for the random effects (Ψ), and the log-likelihood. This functionality is useful for large and complex models when the time taken to return the results is expected to be longer than a few minutes.

The following figure shows the type of plot obtained.

To turn the status reporting functionality on or off:

1. Click the Algorithm Settings tab.

2. Select or clear the Show progress of the Parameter Fit task.

Tips for interpreting status plots:

• The fitting function tries to maximize the log-likelihood. When the plot begins to display a flat line, this might indicate that maximization is complete. Try setting the maximum iterations to a lower number to reduce the number of iterations you need and improve performance. See Performing Population Fitting Using sbionlmefit, for information on how to set the maximum iterations.

• Plots for the fixed effects (β) and the estimates for the diagonal elements of the covariance matrix for the random effects (Ψ), should show convergence. If you see oscillations, or jumps without accompanying improvements in the log-likelihood, the model may be over-parameterized. Try the following:

  • Reduce the number of fixed effects

  • Reduce the number of random effects

  • Simplify the covariance matrix pattern of random effects

Back to Top

Performing Individual Fitting

Specifying the Type of Fitting, the Data to Fit, and the Parameters to Estimate

These settings are in the Parameter Fit task pane as shown.

1. Click the Estimation Settings tab if needed.

2. From the Estimation Method list, select individual fit (NLINFIT). individual fit (NLINFIT) uses the nlinfit function from the Statistics Toolbox.

3. The Parameters to Estimate table shows the SimBiology parameters, species, and compartments to estimate. To add parameters to this table, enter a name, or from the Model Components table (on the right), click and drag the model component and drop it on the Parameters to Estimate table.

   Tip   If the name entered in the table is invalid you see a red indicator next to the row.

4. In the Parameters to Estimate table select or clear the Estimate check box to estimate a parameter.

5. The Initial Estimate column contains the initial guess for the value of the parameter (Value property), the compartment volume (Capacity property), or the species amount (InitialAmount property). Double-click a cell to edit the value.

6. From the Data To Fit list, select the data set to use in fitting.

   The Data Label column lists the column headers found in the data set.

7. The Classification list is populated with the selection that the column headings are presumed to represent in the software. If the classification is correct go to the next step. If the classification is missing or incorrect, you can change it as follows:

   From the Classification list, select the mapping that applies to each column of the data set.

   For the column in the data set that represents ...	Select ...
   The group ID	group
   Time of dosing and sampling	independent variable
   Bolus dose amount	dose (bolus)
   Infusion dose amount	dose (infusion)
   Dose exhibiting zero-order absorption	dose (zero-order
   Dose exhibiting first-order absorption	dose (first-order)
   The measured amount or concentration of the compound.	response
   the rate of infusion (results of calculation from infusion amount and infusion time)	infusion rate

   Note   You can only select each classification type once. For example, you cannot classify one column as dose (bolus) and another as dose (infusion). Similarly, you cannot select two different columns as response.

8. The Model Component Name column specifies the component in the model that represents the column in the data set. The Model Component Name column is only available to columns in the data that represent the dose received and the observed response.

   If the Model Component Name column lists the correct component, skip to the next step. If the name of the component is incorrect, correct it as follows:

   From the Model Components table (on the right), click and drag the correct model component and drop it on the Model Component Name row that you want to change.

9. You can run the parameter fitting task with the default settings by clicking (Run).

Setting Tolerance and Maximum Iteration for Individual Fits

1. Click the Algorithm Settings tab.

2. In the Termination Tolerance on the Estimated Coefficients box, specify a tolerance; the default is 1.0E-8.

3. In the Termination Tolerance on the Residual Sum of Squares box, specify a tolerance; the default is 1.0E-8.

4. In the Maximum Iterations box, specify the maximum number of iterations allowed. The default is 100.

Back to Top

About Simulation Settings and Specifying Alternate Values for Initial Estimates

In the Simulation Settings tab you can specify Variants that let you store and apply alternate values for model components during a simulation. For more information about variants and how to add variants see Storing and Applying Alternate Model Values Using Variants.

• In the Simulation Settings tab, under Variants, select or clear the Use In Task check box for a variant to use in the task.

  Note   The fitting functions (population fit (NLMEFIT) and individual fit (NLINFIT)) use the initial estimate values specified in the Estimation Settings tab, as the initial parameter estimates when fitting parameters (overriding the values in the variant).

By default, the Configuration Settings list contains a default configuration set which is the active configuration set. You can add other configuration sets or change the settings in the default configuration set as shown in Performing Simulations in the SimBiology Desktop.

From the Configuration Settings list you can select a different configuration set to use in the parameter fitting task. For the chosen configuration set, you can specify model components for which you want to record the data, in the Data Logging tab. The task results include a plot that shows the results of simulating the model using the estimated values returned by the parameter fit task. The result include the components that you selected in the Data Logging tab.

The model object's default configuration set uses the sundials solver.

If you change the solver type in the configuration set being used, during fitting there is a temporary change to sundials to support events in the model, and the change is reversed after returning the results. If you want to change tolerance options for simulations, select a deterministic solver and use the tolerance options provided in the deterministic solver. The fitting functions (sbionlmefit or sbionlinfit) will use the tolerance options specified in the deterministic solver.

Back to Top

Visualizing Parameter Fitting Results and Generating Diagnostic Plots

To run the parameter fitting task, click (Run). The parameter fitting task runs and generates plots and results. If you chose to run the population fit task, the task returns results for individual fits and the population fit.

In the Project Explorer under Parameter Fit, the task adds a Data item containing the following results:

• For individual fits:

  • Estimated parameter values for each group

  • Mean and standard deviation for the estimated values

  • The estimated covariance matrix for each group

• For population fits:

  • Estimated parameter values

  • Estimated random effects

  • The maximized log-likelihood for the fitted model

  • The estimated error variance for the fitted model

  • The Akaike information criterion (AIC) for the fitted model

  • The Bayesian information criterion (BIC) for the fitted model

  • The standard errors for the estimates of the fixed effects

  • The error degrees of freedom for the model

  • Estimated Covariance Matrix of Random Effects

The task also generates the following diagnostic plots for individual and population fits:

• The predicted time courses and observations for an individual or the population

  

• Observed versus predicted values

  

• Residuals versus time, group or predictions

  

• Distribution of the Residuals

  

• A box-plot for random effects or parameter estimates from individual fitting

  

For help on working with plots and a description of each plot type, see the SimBiology context-sensitive help for the Parameter Fit pane.

1. From the SimBiology desktop, select Help > SimBiology Desktop Help.

2. In the Project Explorer, select Parameter Fit.

See also, Visualizing Results Using Plot Types

Back to Top

Fitting Pharmacokinetic Model Parameters at the Command Line

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS