Configuring Tasks

For each task, you can configure model-related settings such as the model to simulate, simulation-related settings such as the simulation stop time, and task-specific settings such as values to scan in a parameter scan task.

As you configure these settings, the desktop checks for errors and warnings and flags them using message indicators. You can hover over the indicators to get more information about the errors or warnings. More information about each section is described in the context-sensitive help of each section. You can open it by hovering over the information icon next to each section.

When you are selecting model elements such as parameters to estimate or doses to use during the analysis, you can use the Component Palette tool that provides a complete list of model quantities, doses, and variants. You can open the tool from the Editor tab and drag and drop model elements onto corresponding task sections. You can also use the down arrow key from within the table of each section to select model elements. In some of the tables, each row has a check box in the first column. When the box is checked, the corresponding row item is active and used during the analysis. You can use the context menu of each table for more options such as showing a quantity in the diagram view.

Configuring Model-Related Settings

Each task lets you specify a model to analyze. If the model simulation is expected to take a long time or the task is going to simulate the model multiple times (such as the Run Scan task), you can accelerate the model to improve performance. You can enable the acceleration by selecting the check box in the Model section.

You can also specify which doses and variants to use during the model analysis. Suppose that you have two different sets of parameter values for the normal and cancer patients stored in separate variants. You can specify which variant to use during simulation by selecting it in the Variants to Apply section of the task. Similarly, different doses can be selected in the Doses to Apply section to evaluate various dosing regimens or combine dosing schedules to assess different combination therapies. You can also generate variants with final quantity values after the model simulation or parameter estimation by selecting the corresponding option in the Variants to Generate section of the Simulation or Fit Data task.

Configuring Simulation-Related Settings

Each model has the default simulation settings associated with it. These settings include simulation time options, solver options, compile options, and data logging options. You can access these options by selecting Simulation Settings from the Editor tab of the task editor. When you change these simulation settings, it affects every task that is using the same model.

It is possible to overwrite some of the default simulation settings for certain tasks. These settings are the simulation stop time, states to log, solver type, and log decimation. In the corresponding section of a task, you can choose to use either the simulation settings value or a custom value specific for the task only. If you select the custom value option, that value is applied to the current task only and no other tasks.

Configuring Task-Specific Settings

Some of the tasks have unique settings that must be configured before the tasks can be run.

Fit Data

This task lets you estimate model parameters by fitting the model to experimental time-course data, using either nonlinear regression or nonlinear mixed-effects (NLME) methods.

Consider grouped data containing measured drug concentrations at different times for multiple individuals. You can estimate parameters for each individual or simultaneously fit all individuals to estimate a single set of values. Select the Pool data check box in the Estimation Method section to estimate one set of parameter values for all individuals. This option is available for all methods except for the mixed-effects methods (nlmefit and nlmefitsa).

In the Estimated Parameters section, you can select which parameters to estimate and specify parameter transformations as needed. For example, some parameters such as compartment volume and clearance are positive physical quantities, and log transformation reflects the underlying physical constraint and generally improves fitting. Use logit or probit transforms for parameters that have values from 0 through 1, such as bioavailability. You can also specify the lower and upper bounds for each estimated parameter for some of the estimation methods. For a list of methods that supports parameter bounds, see Supported Methods for Parameter Estimation.

If your data contains any dosing information such as dose amount for each patient at each dose time, use the Dosing Information section to define the mapping between the dose column of the data and the corresponding model species that is being dosed. In the table of the section, select the name of the dose variable (Dose Column Name), the dosed species (Dose Component Name), and the type of dose (Dose Configuration).

You can map the measured or observed response data column (dependent variable) to the corresponding model quantity in the Response and Error Model Information section. For cases of multiple responses, SimBiology lets you specify an error model for each response or one error model for all responses. There are four error models, namely, constant, proportional, combined, and exponential. For a list of methods that support multiple error models, see Supported Methods for Parameter Estimation. In addition to these error models, you can also specify weights for each response.

You can also customize some of the common settings of the selected estimation method in Algorithm Settings. For instance, you can increase the maximum iterations if the algorithm fails to converge within the default limit. You can specify additional algorithm settings in Advanced Algorithm Settings. For example, if you want to use the Levenberg-Marquardt algorithm for the lsqnonlin method, enter Algorithm = 'levenberg-marquardt'. To see a complete list of all options for the selected estimation method, click the hyperlink provided in the section.

For an illustrated example of fitting PK profile data using a least-squares method, see Estimate Pharmacokinetic Parameters Using SimBiology Desktop.

For mixed-effects problems, SimBiology lets you estimate population parameters (fixed effects) while considering individual variations (random effects) using nlmefit or nlmefitsa estimation methods (Statistics and Machine Learning Toolbox™ is required). Consider grouped data containing measured drug concentrations at different times for multiple individuals. The objective is to estimate population PK parameters, such as volume of the central compartment Central and clearance Cl, and the random effect of each individual. For the ith individual, the mixed-effects model can be described as Centrali=θ1+ηi and Cli=θ2+ηi, where θ1 and θ2 are fixed effects and ηi is the random effect of the ith individual. Random effects are assumed to be multivariate normally distributed ηiN(0,Ψ), where Ψ is the covariance matrix of random effects.

SimBiology represents the model as Central = theta1+eta1 and Cl = theta2+eta2 in Estimated Parameters. The drop-down menu of the Expression column displays a list of available expressions for each parameter. You can also enter your own expression, but the fixed effect names must always start with theta and random effect names must start with eta.

You can define the structure of Ψ in Covariance Matrix Pattern of Random Effect Parameters. Each check box indicates a variance or covariance parameter that is being estimated. By default, SimBiology assumes no covariance among random effects, that is, uses a diagonal covariance matrix.

You can also specify individual-specific covariates such as patient weight that linearly relate to an estimated parameter in the Covariates section. In the table of the section, select the name of covariate column from the data. SimBiology allows centering of covariates to improve interpretability of the model. For instance, you may want to mean center the weight of each patient to help interpret the fixed effects and compare results with and without the covariate. If there are multiple covariates, you can standardize each of them by using an appropriate scaling method that may help you compare these covariates and select some of them.

Once you have defined a covariate, the task automatically updates the expression list for each parameter in Estimated Parameters to include additional parameter-covariate relationships, such as Cl = exp(theta2+theta3*tWeight+eta2). theta3 is the fixed effect of weight on Cl and tWeight is the (transformed) weight. For details, see CovariateModel.

After the completion of the task, you can generate a variant that contains model quantities with final estimated values. For an unpooled fit, that is, estimating one set of parameter values for each individual or group, you can generate group-specific variants, meaning one variant for each group. You can also generate a variant that contains the mean estimated values (averaged across all groups). You can select the corresponding option in the Variants to Generate section of the task.

Calculate Sensitivities

This task helps you investigate parameter effects on system dynamics. It lets you calculate local, time-dependent sensitivities of one or more species with respect to parameter values and species initial conditions. Suppose that you want to calculate the sensitivity of a receptor protein with respect to a model parameter to see if the parameter has any influence on the receptor dynamics. You can specify the receptor species as the sensitivity output (numerator) and the parameter as the input (denominator) in the Sensitivities to Compute section. SimBiology® lets you specify species, parameters, and constant compartments as inputs (and species and parameters as outputs) for sensitivity calculation. The computed sensitivities can be normalized by selecting the appropriate method in the Normalization section. For instance, if you want to normalize with respect to the sensitivity output only, select the Half normalization. Select Full to make the data dimensionless. For details, see Normalization. You cannot run the sensitivity analysis task on models that contain events, algebraic rules, or non-constant compartments. For an illustrated example, see Identify Important Network Components from an Apoptosis Model Using Sensitivity Analysis.

Run Scan

This task lets you explore how a model behaves with different quantity values or repeat dose information, namely, dose start times, amounts, rates, and intervals. The task simulates a model multiple times, each time using different values for those quantities or doses of interest. Suppose you want to explore how varying the value of a forward rate parameter affects the final concentration of a product species. You can specify the parameter in Values to Scan. Use the Values to Scan Defined With section to specify what values to generate for scanning. You can define the values using custom MATLAB code. Alternatively, if you have Statistics and Machine Learning Toolbox, you can generate values from a multivariate normal distribution or using Latin hypercube sampling.

Run Ensemble Simulation

This task performs multiple simulations of a model using a stochastic solver. It lets you compare and analyze fluctuations in the behavior of a model over repeated stochastic simulations. Because stochastic simulations rely on an element of probability, sequential runs produce different results. Therefore, multiple stochastic runs are often needed to determine the probability distribution of the simulation results. Use the Number of Runs section to define the total number of stochastic simulations. If you want all the runs to have a consistent time vector, the data must be interpolated using the linear or zero-order hold method specified in the Interpolation section. By default, the task saves the time and quantity data of each state at each simulation time step. You can record the data less often by increasing the value of LogDecimation.

Run Group Simulation

This task lets you simulate each group or patient from grouped data. Suppose that the data contain measurements of drug plasma concentration at different times for multiple patients and dosing amount for each patient. You can use this task to simulate each patient and compare the results to the experimental data.

In the Map Between Data and Model section, you must specify a grouping variable, an independent variable, and a dependent variable (response). Map at least one response data column (Dependent1) to the corresponding model quantity. Similarly, you can map any dose column (Dose1) to the corresponding model species that is being dosed.

Once you start running the task, it applies any specified dose to the corresponding species, and simulates each group. It plots the response data column against the simulated values for the corresponding model quantity. As you compare the simulation results to experimental data, you can further explore the model behavior under different parameter values or species initial conditions using the Explorer Tools.

Related Topics