Time Series Sensitivities

Note

For these demonstrations we use a toy sbml model prepackaged with roadrunner

Using time series sensitivities

In this example we show you how to use roadrunners time series sensitivities feature. Roadrunner will integrate the model and compute sensitivities at each time step.

Start integration with sensitivities at 0, end at 10 and collect 11 data points The return type is a 4-Tuple, a time vector and a 3D sensitivity matrix with dimensions time x parameters x variables - that is, an array of matrices corresponding to the time points in the time vector with parameters down the rows and model variables (species) accross the columns. The third and forth elements are row and column names respectively.

import roadrunner
from roadrunner import RoadRunner
from roadrunner.tests.TestModelFactory import TestModelFactory, getAvailableTestModels
from os.path import join, dirname

# note: use getAvailableTestModels() to see options for test models.
sbml = TestModelFactory("OpenLinearFlux").str() # get the test model's sbml string

# print(sbml) # uncomment if you want to see the sbml

# Create a RoadRunner instance
model = RoadRunner(sbml)
sensSolver = model.getSensitivitySolver()

time, sens, rownames, colnames = model.timeSeriesSensitivities(0, 10, 11)

print("time: ", time)
print("rownames: ", rownames)
print("colnames: ", colnames)
print(sens)

fname = join(dirname(__file__), "OpenLinearFluxSensitivities.png")
roadrunner.plotTimeSeriesSens(time, sens, rownames, colnames, ncol=2, fname=fname)
print(f"Plot image saved to \"{fname}\"")

Selecting parameters

By default, all model parameters are automatically selected. You can be more selective about which parameters to compute sensitivities for. This will have a performance advantage, because sensitivities are only computed for the parameters specified here.

from roadrunner import RoadRunner
from roadrunner.tests.TestModelFactory import TestModelFactory, getAvailableTestModels


# note: use getAvailableTestModels() to see options for test models.
sbml = TestModelFactory("OpenLinearFlux").str() # get the test model's sbml string

# print(sbml) # uncomment if you want to see the sbml

# Create a RoadRunner instance
model = RoadRunner(sbml)
sensSolver = model.getSensitivitySolver()

time, sens, rownames, colnames = model.timeSeriesSensitivities(0, 10, 11, params=["kin"])

print("time: ", time)
print("rownames: ", rownames)
print("colnames: ", colnames)
print(sens)

Selecting Species

By default, all model species are returned in the results matrix. We can be more selective by using the species argument. This does not have any additional performance advantage and in fact cost additional resources because the full results matrix is sliced to select the selected columns.

from roadrunner import RoadRunner
from roadrunner.tests.TestModelFactory import TestModelFactory, getAvailableTestModels


# note: use getAvailableTestModels() to see options for test models.
sbml = TestModelFactory("OpenLinearFlux").str() # get the test model's sbml string

# print(sbml) # uncomment if you want to see the sbml

# Create a RoadRunner instance
model = RoadRunner(sbml)
sensSolver = model.getSensitivitySolver()

time, sens, rownames, colnames = model.timeSeriesSensitivities(0, 10, 11, species=["S1"])

print("time: ", time)
print("rownames: ", rownames)
print("colnames: ", colnames)
print(sens)

Sensitivity Method

RoadRunner time series sensitivities uses cvodes under the hood. By default, we use the “simultaneous” method, whereby sensitivity equations are solved at the same time as the variables in the ODE’s. This can be changed so that the variables are solved first followed by the sensitivity equations; aka in a staggered approach.

from roadrunner import RoadRunner
from roadrunner.tests.TestModelFactory import TestModelFactory, getAvailableTestModels


# note: use getAvailableTestModels() to see options for test models.
sbml = TestModelFactory("OpenLinearFlux").str() # get the test model's sbml string

# print(sbml) # uncomment if you want to see the sbml

# Create a RoadRunner instance
model = RoadRunner(sbml)
sensSolver = model.getSensitivitySolver()

sensSolver.setValue("sensitivity_method", "staggered")
time, sens, rownames, colnames = model.timeSeriesSensitivities(0, 10, 11, k=0)

print("using a staggered approach")
print("time: ", time)
print("rownames: ", rownames)
print("colnames: ", colnames)
print(sens)
sensSolver.setValue("sensitivity_method", "simultaneous") # return to simultaneous mode

Sensitivity Difference Quotient Method

RoadRunner via cvodes uses finite differences for approximating gradients. By default we use the “centered” method, while the alternative is the “forward” method Both methods are implemented in cvodes and automatically figure out the best value of delta (perturbation amount) to use. Moreover, there is an adaptive switching mechanism in use that makes it unlikely that users should need to modify this setting.

from roadrunner import RoadRunner
from roadrunner.tests.TestModelFactory import TestModelFactory, getAvailableTestModels


# note: use getAvailableTestModels() to see options for test models.
sbml = TestModelFactory("OpenLinearFlux").str() # get the test model's sbml string

# print(sbml) # uncomment if you want to see the sbml

# Create a RoadRunner instance
model = RoadRunner(sbml)
sensSolver = model.getSensitivitySolver()



sensSolver.setValue("DQ_method", "forward")
time, sens, rownames, colnames = model.timeSeriesSensitivities(0, 10, 11, k=0)


print("using forward method of finite different approximation")
print("time: ", time)
print("rownames: ", rownames)
print("colnames: ", colnames)
print(sens)
sensSolver.setValue("DQ_method", "centered") # put back the default value

Sensitivity Solver Type

By default, RoadRunner uses the sundials “newton” nonlinear solver. This can be changed to the “fixed_point” nonlinear solver

from roadrunner import RoadRunner
from roadrunner.tests.TestModelFactory import TestModelFactory, getAvailableTestModels


# note: use getAvailableTestModels() to see options for test models.
sbml = TestModelFactory("OpenLinearFlux").str() # get the test model's sbml string

# print(sbml) # uncomment if you want to see the sbml

# Create a RoadRunner instance
model = RoadRunner(sbml)
sensSolver = model.getSensitivitySolver()



# By default, RoadRunner uses the sundials "newton" nonlinear solver.
# This can be changed to the fixed_point nonlinear solver
sensSolver.setValue("nonlinear_solver", "fixed_point")
time, sens, rownames, colnames = model.timeSeriesSensitivities(0, 10, 11, k=0)

print("using the fixed point nonlinear solver")
print("time: ", time)
print("rownames: ", rownames)
print("colnames: ", colnames)
print(sens)