SimBiology from Scripts II: Parameter scanning

In a previous post, I (not so) briefly showed how to load the SimBiology file, select from it the model and simulation configuration settings, and evaluate the model with SimBiology’s simulation engine.

That’s great if you only needed the results for one model with one configuration. I’m guessing that won’t be the case for most use cases, though. In my own research, I am more often interested in how a system’s evolution changes across different initial configurations. For a specie or parameter of interest, I create a range of values to explore, and re-simulate my model for each parameter value in that range. Then I can compare the model outputs to analyze how the variations impacted the system.

SimBiology has a feature for performing these sort of studies, which it calls parameter scanning. However, these parameter scans run painfully slow through SimBio’s graphical interface (surprise, surprise), worsening with increases to model size or complexity. And this is just scanning over a single parameter. SimBiology often becomes unstable for scans of two or more parameters.

This frustration is almost wholly avoidable if we handle our SimBiology models programmatically instead. Today, I’ll demonstrate a simple way to replicate SimBio’s parameter scan process from a MATLAB script. Basically, we will decide on a parameter to vary, and a range of values we want to explore. We setup an array of values spanning that range, loop through that array, and run a simulation for each iteration.

The Model

Okay, let’s get started! This example assumes a very simple chemical reaction network ⇀ ⇀ C where k1 and k2 are kinetic rate constants for the chemical reactions where A becomes B, and B becomes C, respectively. Let’s say that we are interested in how k1 impacts levels of species C ultimately..… Read More

SimBiology from Scripts I: loading and running simulations programmatically

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 documentation1,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.… Read More