SimBiology is a toolkit for MATLAB that allows one to build and simulate models of dynamic systems easily, especially for systems biological applications like modeling pharmacokinetics/biochemical reaction networks. While its usual draw is the easy-to-use and fast-to-learn GUI, SimBiology has a programmatic interface too, enabling models to be built and simulated from the MATLAB console or a script. I’ve found the GUI is great for model building, but complicated simulations or parameter scans are much slower when performed from the interface.

Unfortunately, the SimBiology documentation^1,2 can be a little cryptic, and it lacks a “Getting Started”-level tutorial to understand the basics. So over the next few tutorials, I’ll try to fill this void.

Today I want to give you the simplest introduction to the script-level SimBiology tools: loading an existing SimBiology model, configuring a few parameters and settings, and running a simulation. I’ll assume you already have an existing SimBiology project (story as a .sbproj file.)

Loading a SimBiology project file

First we must load the SimBiology project file containing the model of interest. This is done by calling sbioload() and assigning its output to a variable.

file = sbioload('./PATH/TO/YOUR/file.sbproj');

The path should be relative to your current working directory, or an absolute path. I prefer the latter (e.g. /Users/username/Models/modelfile.sbproj) as MATLAB working directories can be easily mixed up.

We can then access our models through the file variable. By default, a single model is stored in model.m1. Additional models can be accessed at file.m2, file.m3, and so on. If the file contained 6 models, they would be accessible through file.m1 through file.m6. They are in order of creation. Always double-check the ordering of your models through the GUI.

firstModel = file.m1;
% secondModel = file.m2;
% thirdModel = file.m3;

Configuring the Simulation Settings

Simulations are controlled through ConfigSets, which allow us to set the Simulation Solver, the length of the simulation, and other settings concerning unit conversion, fault tolerance, and so forth. I’ll explain the options available in a later tutorial. For now, we will load the default configuration, and set a custom SolverType (which algorithm used to solve the ODEs representing our system) and StopTime (the length of “simulated time” to evaluate.)

cs = getconfigset(firstModel, 'default');
set(cs, 'SolverType', 'ode15s');
set(cs, 'StopTime', 1000);

Setting Specie and Parameter values

By default, the simulation will use whatever values assigned in the model file for rate parameters, species, volumes, and other quantities. But these can be changed on the fly if needed (especially useful in parameter scanning.)

firstModel.Parameters(1).value = 3.0E5;
firstModel.Parameters(2).value = 1.9E-7;
firstModel.Species(1).InitialValue = 1500;

The code above assigns values to Parameter 1 and Parameter 2, and the initial amount of Species 1. The numbering isn’t straightforward, i.e. defined parameters are ordered by creation time.

firstModel.Parameters
firstModel.Species

This will output a list of the Parameters and Species, giving their index number, name within the model, and values.

There is of course much more that we can configure. SimBiology model objects contain the list of species, parameters, reactions, compartments, rules, events, and doses, along with the any numeric values you’ve assigned. We can manipulate any of these components and settings from the MATLAB console, which can be helpful in more complicated simulations. I will describe these in more details in a later tutorial.

Running a simulation

Once you’ve made any adjustments to the settings and values, it’s time to run the simulation. This, of all things, is the easiest part. We call sbiosimulate(m, cs, [], []), which simulates model m for ConfigSet cs. The function output contains the results.

results = sbiosimulate(m, cs, [], []);
timeData = results.Time;
specieData = results.Data;

The timeData variable contains a column vector of all timePoints spit out by the algorithm, while specieData spits out a matrix where each column corresponds to an individual column, and each row gives the amount of that species (whether in molecules or concentrations) at each time point (i.e. specieData(10, 2) is the amount of Species 2 at the time point timeData(2).) The units for time and specie quantity are defined in the simulation ConfigSet, which will be covered in a later tutorial. The specie ordering is the same as before (e.g. model.Specie(1) is stored in column 1.) Check if unsure by calling “model.Species” from the MATLAB console.

And that’s it! That’s the basic structure for evaluating a model programmatically with SimBiology! Next time, we will discuss when running simulations from a script is helpful: parameter scanning.