Running Tasks

The SimBiology® desktop lets you analyze models of dynamic systems using tasks. Each task is a MATLAB® script with a user interface that performs an analysis on the model, such as simulation, parameter estimation, or sensitivity calculation. You can configure a task in the Task Editor. As you configure the task, the SimBiology desktop updates the corresponding script automatically and lets you view the task code.

For most tasks, the desktop shows simulation results in the Live Plots area of the Task Editor while the tasks are running. There are certain tasks that do not show any plots. For tasks that support Live Plots, the desktop shows a time plot by default, and the results are updated live. Certain tasks show additional plots, such as a scan or sensitivity plot. You can customize these plots. For instance, you can add experimental data points to compare with simulation results, or select only a few quantities of interest to plot. For details, see Configuring Live Plots.

You can further explore model behavior using the Explorer Tools, which let you alter parameter values, initial conditions, and dose schedules. Each time you alter the value of a quantity, the task automatically reruns using the new value, and you can see the updated results in the Live Plots area. For details, see Exploring Models.

The desktop saves the task results as Last Run (task name - model name). Each time you run the same task, the results are overwritten. You can save the results under a different name to avoid overwriting them. The Explorer tab of the Task Editor has options to save and export simulation data, or navigate to the Data panel. For details, see Task Results.

Configuring Live Plots

For most tasks, a time plot of all quantities is shown by default. Depending on the task, the desktop shows additional plots such as sensitivity or scan plots or may not show any plot. For those tasks that support Live Plots, you can add more plots by first turning on Live Plots on the Editor tab and then selecting Add Plots from the Explorer tab.

You can configure what is plotted in each plot. Suppose that you are interested in selecting model quantities that are plotted in the Live Plots area after a task completes. Right-click the plot, and select Define States to Plot > Plot State Data > Select.

The desktop also lets you define a mathematical expression to plot by selecting Define Math Data to Plot. The expression must be a MATLAB expression that uses any of the legend names or time as variables. The expression must evaluate to a numeric value. For instance, suppose that you have concentration–time curves of two species with the legend names s and sP, where s corresponds to the concentration of an unphosphorylated protein, and sP corresponds to the phosphorylated concentration. You can add a plot to see the fraction of phosphorylated protein by entering sP./(s+sP) as an expression, where s+sP represents the total concentration of the protein. Another example would be to plot the amount of a species in terms of concentration. To do so, first add a plot entry for the species S and another for the compartment V via Define States of Plot. Then define the mathematical expression S./V, which plots the species concentration instead of amount.

You can add experimental data to the time plot to compare with the simulation results by selecting Plot External Data > Add. You can select a data set that is in the MATLAB workspace or load one from a file.

To configure axes and line properties of a plot, select Properties from the context menu of the plot. For instance, you can specify a linear or log scale for the x- or y-axis of each plot.

To highlight a line or data point of a simulated quantity in the plot, you can click its name in the legend. You can also click a line or data point, and the corresponding legend name is highlighted. Use this highlighting feature to look at the simulation data of a specific quantity among many others, or to see which quantity corresponds to the simulation data that you are interested in.

You can overlay results from each task run to compare simulation data. Select Overlay Results from the Explorer tab. Then every time you run the task, the desktop plots the results from the current run on top of the results from previous runs. For example, suppose that you can have a set of values for immunological parameters of a healthy person represented by a variant and a different set of values for a cancer patient represented by another variant. You can then simulate the model with each variant and overlay the predictions for both cases to see the changes in model behavior.

Most tasks show one or more plots while they are running. Details on the plots for the most common tasks are described in the following sections.


This task shows a time plot of all simulated quantities. You can disable the automatic creation of the time plot when you run the task in the Preferences > Tasks > Create line plot in Task Explorer on Simulation Task run.

Calculate Sensitivities

This task shows a time plot and a sensitivity plot. The sensitivity plot is shown after the task finishes running. The plot displays the time-dependent sensitivities to parameter values and initial conditions as a bar graph. Use the context menu of the plot for more options, such as sorting the values in an ascending or descending order. You can disable the automatic creation of the sensitivity plot by clearing Preferences > Tasks > Create sensitivity plot in Task Explorer on Sensitivity Task run completion.

Run Scan

This task shows a scan plot and a time plot. For each parameter scan, the desktop performs a mathematical evaluation on the simulation data and returns a scalar value. The scan plot plots this value versus the scan parameter. You can add more scan plots by selecting Add Plot > Scan Plot on the Editor tab. Then you can define the mathematical expression to evaluate by selecting Plot Math Data > Add.

You must define the expression as out = expression, and the expression must return a scalar. In the scan plot, the evaluated results (out) are plotted on the y-axis and the scan parameter on the x-axis. If you have multiple scan variables, you can select which scan parameter is plotted on the x-axis. In the expression, you can refer to any quantity by its name. If the name of a quantity is not a valid MATLAB variable name, enclose it in square brackets, such as [DNA polymerase+]. To check if the expression has any errors or warning, click Verify.

You can disable the automatic creation of the scan plot by clearing Preferences > Tasks > Create scan plot in Task Explorer on Scan Task run.

As an illustration, the scan plot shows the maximum value of the first quantity in the time plot versus the scan variable. You can write custom MATLAB code to plot. For instance, suppose Drug_Central is the name of a species that represents the concentration of the drug in the system, and time is the simulation time variable. You can plot the time point at which the drug concentration is at its maximum using the following expression.

out = time(Drug_Central == max(Drug_Central)); 

Run Scan with Sensitivities

This task combines the Calculate Sensitivities and Run Scan tasks. It shows a scan plot and time plot. As an illustration, the scan plot shows time-dependent sensitivities of the first quantity with respect to the scan parameter. For details on how to configure a scan plot, see Run Scan. You can disable the automatic creation of the scan plot by clearing Preferences > Tasks > Create scan plot in Task Explorer on Scan with Sensitivities Task run.

Run Group Simulation

This task shows a trellis time plot, where each subplot represents a group or an individual. The plot shows the response data against the simulated values for each group. If you have multiple responses, you can select responses to plot by selecting Edit Properties on the Explorer tab.

Fit Data

Instead of Live Plots, this task shows the Progress Plot that provides live feedback on the status of the fit, except when using nlinfit as the estimation method. For instance, it displays fitting quality measures, such as the log-likelihood, and estimated parameter values for each function iteration. The Progress Plot opens in a new figure window. This task does not support plots in the Live Plots area or the Explorer Tools.

To turn off the Progress Plot, clear Show progress of the Fit Data task in the Algorithm Settings section. For details, see Progress Plot.

Exploring Models

The SimBiology desktop provides explorer tools that let you iterate through different parameter values, initial conditions, and dosing schedules without modifying the base model. When you change a value, the desktop automatically reruns the task using the new value, and the results are updated in the Live Plots. You can overlay results from each run to see the changes in model behavior. For a summary of quantity values used for each run, open the MultiRun Viewer from the Explorer tab. You can also calculate statistics, such as the area under the curve of a drug concentration profile, to gain additional insight.

You can turn the Explorer Tools on and off by selecting Explorer on the Editor tab. If you turn it off, the desktop does not use the values defined in the tools during the task run.

Adjust Quantities

You can explore how changes to quantity values affect the model behavior. To add a quantity to explore, select Define Quantities to Adjust from the Options menu. The desktop adds a slider for you to change the quantity value. Each time you move the slider, the desktop reruns the task using the new slider value by default. You can overlay the simulation results from each run and compare them.

Use the Options menu to configure the slider behavior and properties. For instance, to stop the task from being run each time you move the slider, clear Run Task When Quantity Changes Value. To change the range of the slider, select Define Slider Properties.

Adjust Doses

An increase in a species amount or concentration due to an external stimulus, such as an oral or intravenous administration of a drug, can be modeled using an element called a dose. The Adjust Doses tool lets you create doses to explore different dosing regimens and their effects on the model behavior.

To add a dose to explore, select Create Dose Schedule to Explore from the Options menu. A dose plot is shown along with the dose properties that you can adjust. To add doses at specific times and values, first click the green plus button on the right of the plot, and then click inside the plot. You can use the sliders to adjust the dose properties such as dose amount or dose time. To remove a dose, select the corresponding line in the plot. Then click the red minus button on the right of the plot. Any unchecked dose is not applied to the model during the task run.

You can also explore an existing dose by selecting Choose Existing Dose to Explore. When exploring, the desktop does not change the existing dose properties. To avoid double dosing, do not select the same dose in the Doses to Apply section of the task.

Calculate Statistics

You can evaluate a mathematical expression on the simulation results. The expression can be any valid MATLAB expression that returns a numeric value. In your expression, you can refer to any quantity by its name. If the name of a quantity is not a valid MATLAB variable name, enclose it in square brackets such as [DNA polymerase+]. You can also refer to the simulation time variable as time. To add an expression, select Define Statistics to Calculate from the Options menu. For instance, to calculate the AUC (area under the curve) of the concentration-time curve of a drug, use the expression trapz(time,Drug).

For a task that runs multiple simulations, such as the Run Scan task, the desktop evaluates the expression at the end of each simulation. Open MultiRun Viewer to view all the calculated results.

Related Topics