{
"cells": [
{
"attachments": {},
"cell_type": "markdown",
"id": "e1699266",
"metadata": {},
"source": [
"# Simple SBML example\n"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "ef7315d5",
"metadata": {},
"source": [
"This notebook creates a simple model in [SBML version 3 level 1](https://synonym.caltech.edu/documents/specifications/level-3/version-1/core/release-3/) for illustration. We then use [BasiCO](https://basico.readthedocs.io/en/latest/) to build and run a simulation of the SBML model. BasiCO is a simplified interface to using COPASI from python."
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "c59a3e71",
"metadata": {},
"source": [
"## 1) Including libraries"
]
},
{
"cell_type": "code",
"execution_count": 16,
"id": "4b7c5a24",
"metadata": {},
"outputs": [],
"source": [
"import os\n",
"import libsbml\n",
"from combine_notebooks import RESULTS_DIR\n",
"from basico import load_model, run_time_course, get_reaction_parameters, get_species\n",
"from combine_notebooks.validation.validation_sbml import validate_sbml"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "dfb6d8d0",
"metadata": {},
"source": [
"## 2) Declaring the SBML model"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "f544db5b",
"metadata": {
"lines_to_next_cell": 0
},
"source": [
"Create an empty SBMLDocument object. It's a good idea to check for\n",
"possible errors. Even when the parameter values are hardwired like\n",
"this, it is still possible for a failure to occur (e.g., if the\n",
"operating system runs out of memory)."
]
},
{
"cell_type": "code",
"execution_count": 17,
"id": "ae6bbf46",
"metadata": {
"lines_to_next_cell": 0
},
"outputs": [],
"source": [
"try:\n",
" document = libsbml.SBMLDocument(3, 1)\n",
"except ValueError:\n",
" raise SystemExit('Could not create SBMLDocument object')"
]
},
{
"cell_type": "markdown",
"id": "a2426962",
"metadata": {},
"source": [
"Create the basic Model object inside the SBMLDocument object. To\n",
"produce a model with complete units for the reaction rates, we need\n",
"to set the 'timeUnits' and 'extentUnits' attributes on Model. We\n",
"set 'substanceUnits' too, for good measure, though it's not strictly\n",
"necessary here because we also set the units for individual species\n",
"in their definitions."
]
},
{
"cell_type": "code",
"execution_count": 18,
"id": "63e6af9a",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0"
]
},
"execution_count": 18,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"model = document.createModel()\n",
"model.setTimeUnits(\"second\")\n",
"model.setExtentUnits(\"mole\")\n",
"model.setSubstanceUnits('mole')"
]
},
{
"cell_type": "markdown",
"id": "800b6957",
"metadata": {},
"source": [
"Create a unit definition we will need later. Note that SBML Unit\n",
"objects must have all four attributes 'kind', 'exponent', 'scale'\n",
"and 'multiplier' defined."
]
},
{
"cell_type": "code",
"execution_count": 19,
"id": "58e1cd4a",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0"
]
},
"execution_count": 19,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"per_second = model.createUnitDefinition()\n",
"per_second.setId('per_second')\n",
"unit = per_second.createUnit()\n",
"unit.setKind(libsbml.UNIT_KIND_SECOND)\n",
"unit.setExponent(-1)\n",
"unit.setScale(0)\n",
"unit.setMultiplier(1)"
]
},
{
"cell_type": "markdown",
"id": "b3277911",
"metadata": {},
"source": [
"Create a compartment inside this model, and set the required\n",
"attributes for an SBML compartment in SBML Level 3."
]
},
{
"cell_type": "code",
"execution_count": 20,
"id": "e5ec79db",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0"
]
},
"execution_count": 20,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"c1 = model.createCompartment()\n",
"c1.setId('c1')\n",
"c1.setConstant(True)\n",
"c1.setSize(1)\n",
"c1.setSpatialDimensions(3)\n",
"c1.setUnits('litre')"
]
},
{
"cell_type": "markdown",
"id": "0ec2e677",
"metadata": {},
"source": [
"Create two species inside this model, set the required attributes\n",
"for each species in SBML Level 3 (which are the 'id', 'compartment',\n",
"'constant', 'hasOnlySubstanceUnits', and 'boundaryCondition'\n",
"attributes), and initialize the amount of the species along with the\n",
"units of the amount."
]
},
{
"cell_type": "code",
"execution_count": 21,
"id": "2a942cb8",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0"
]
},
"execution_count": 21,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"s1 = model.createSpecies()\n",
"s1.setId('S1')\n",
"s1.setCompartment('c1')\n",
"s1.setConstant(False)\n",
"s1.setInitialAmount(5)\n",
"s1.setSubstanceUnits('mole')\n",
"s1.setBoundaryCondition(False)\n",
"s1.setHasOnlySubstanceUnits(False)\n",
"\n",
"s2 = model.createSpecies()\n",
"s2.setId('S2')\n",
"s2.setCompartment('c1')\n",
"s2.setConstant(False)\n",
"s2.setInitialAmount(0)\n",
"s2.setSubstanceUnits('mole')\n",
"s2.setBoundaryCondition(False)\n",
"s2.setHasOnlySubstanceUnits(False)"
]
},
{
"cell_type": "markdown",
"id": "0d118d66",
"metadata": {},
"source": [
"Create a parameter object inside this model, set the required\n",
"attributes 'id' and 'constant' for a parameter in SBML Level 3, and\n",
"initialize the parameter with a value along with its units."
]
},
{
"cell_type": "code",
"execution_count": 22,
"id": "8e4d6ce7",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0"
]
},
"execution_count": 22,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"k = model.createParameter()\n",
"k.setId('k')\n",
"k.setConstant(True)\n",
"k.setValue(1)\n",
"k.setUnits('per_second')"
]
},
{
"cell_type": "markdown",
"id": "8cd2796b",
"metadata": {},
"source": [
"Create a reaction inside this model, set the reactants and products,\n",
"and set the reaction rate expression (the SBML \"kinetic law\"). We\n",
"set the minimum required attributes for all of these objects. The\n",
"units of the reaction rate are determined from the 'timeUnits' and\n",
"'extentUnits' attributes on the Model object."
]
},
{
"cell_type": "code",
"execution_count": 23,
"id": "f03557f6",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0"
]
},
"execution_count": 23,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"r1 = model.createReaction()\n",
"r1.setId('r1')\n",
"r1.setReversible(False)\n",
"r1.setFast(False)\n",
"\n",
"species_ref1 = r1.createReactant()\n",
"species_ref1.setSpecies('S1')\n",
"species_ref1.setConstant(True)\n",
"\n",
"species_ref2 = r1.createProduct()\n",
"species_ref2.setSpecies('S2')\n",
"species_ref2.setConstant(True)\n",
"\n",
"math_ast = libsbml.parseL3Formula('k * S1 * c1')\n",
"\n",
"kinetic_law = r1.createKineticLaw()\n",
"kinetic_law.setMath(math_ast)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "39c5e5d1",
"metadata": {},
"source": [
"## 3) Write, print and validate the generated model"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "b726b49b",
"metadata": {},
"source": [
"And we're done creating the basic model. Here we will check if the SBML is valid."
]
},
{
"cell_type": "code",
"execution_count": 25,
"id": "f407d8bc",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"--------------------------------------------------------------------------------\n",
"validation error(s) : 0\n",
"validation warning(s) : 0\n",
"--------------------------------------------------------------------------------\n"
]
}
],
"source": [
"# validate file\n",
"validate_sbml(document, units_consistency=False)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "44c1bfd6",
"metadata": {},
"source": [
"Now save a text string containing the model into an XML file."
]
},
{
"cell_type": "code",
"execution_count": 26,
"id": "199d4f04",
"metadata": {
"lines_to_next_cell": 2
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"\n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
"\n",
"\n"
]
}
],
"source": [
"file_loc = str(RESULTS_DIR) + \"/hello_world_sbml.xml\"\n",
"os.makedirs(os.path.dirname(file_loc), exist_ok=True)\n",
"libsbml.writeSBMLToFile(document, file_loc)\n",
"xml = open(file_loc).read()\n",
"print(xml)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "a8b6a58c",
"metadata": {},
"source": [
"## 4) Simulating the model"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "cf6ef008",
"metadata": {},
"source": [
"Now we will load to model into COPASI (basico) so we can run a simulation."
]
},
{
"cell_type": "code",
"execution_count": 27,
"id": "0ad895c1",
"metadata": {},
"outputs": [],
"source": [
"model = load_model(file_loc)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "d1d249d1",
"metadata": {},
"source": [
"To verify our species parameters for s1 and s2 we can call get_species, which returns a dataframe with all information about the species."
]
},
{
"cell_type": "code",
"execution_count": 28,
"id": "9d3a22c9",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" compartment | \n",
" type | \n",
" unit | \n",
" initial_concentration | \n",
" initial_particle_number | \n",
" initial_expression | \n",
" expression | \n",
" concentration | \n",
" particle_number | \n",
" rate | \n",
" particle_number_rate | \n",
" key | \n",
" sbml_id | \n",
"
\n",
" \n",
" | name | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
" | \n",
"
\n",
" \n",
" \n",
" \n",
" | S1 | \n",
" c1 | \n",
" reactions | \n",
" mol/l | \n",
" 5.0 | \n",
" 3.011071e+24 | \n",
" | \n",
" | \n",
" 5.0 | \n",
" 3.011071e+24 | \n",
" -5.0 | \n",
" -3.011071e+24 | \n",
" Metabolite_0 | \n",
" S1 | \n",
"
\n",
" \n",
" | S2 | \n",
" c1 | \n",
" reactions | \n",
" mol/l | \n",
" 0.0 | \n",
" 0.000000e+00 | \n",
" | \n",
" | \n",
" 0.0 | \n",
" 0.000000e+00 | \n",
" 5.0 | \n",
" 3.011071e+24 | \n",
" Metabolite_1 | \n",
" S2 | \n",
"
\n",
" \n",
"
\n",
"
\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" value | \n",
" reaction | \n",
" type | \n",
" mapped_to | \n",
"
\n",
" \n",
" | name | \n",
" | \n",
" | \n",
" | \n",
" | \n",
"
\n",
" \n",
" \n",
" \n",
" | (r1).k1 | \n",
" 1.0 | \n",
" r1 | \n",
" global | \n",
" k | \n",
"
\n",
" \n",
"
\n",
"