{
"cells": [
{
"attachments": {},
"cell_type": "markdown",
"id": "073456b9",
"metadata": {},
"source": [
"[](https://mybinder.org/v2/gh/combine-org/combine-notebooks/main?labpath=%2Fnotebooks%2Fsbml.ipynb)\n",
"\n",
"\n"
]
},
{
"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 Level 3 Version 1](https://synonym.caltech.edu/documents/specifications/level-3/version-1/core/release-3/) for illustration. The SBML model will consist of two chemical species called `S1` and `S2`, as well as a compartment where those chemicals reside. We also add a basic reaction that converts `S1` irreversibly into `S2`. 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. The result of that simulation can be seen in the plot below.\n",
"\n",
"
\n",
"\n",
"
"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "c59a3e71",
"metadata": {},
"source": [
"## 1) Including libraries and helper functions"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "0d76b18a",
"metadata": {},
"source": [
"Note: Please uncomment the line below if you use the Google Colab."
]
},
{
"cell_type": "code",
"execution_count": 14,
"id": "ae75df10",
"metadata": {},
"outputs": [],
"source": [
"#%pip install git+https://github.com/combine-org/combine-notebooks"
]
},
{
"cell_type": "code",
"execution_count": 15,
"id": "4b7c5a24",
"metadata": {},
"outputs": [],
"source": [
"from pathlib import Path\n",
"\n",
"import libsbml\n",
"from basico import load_model, run_time_course, get_reaction_parameters, get_species\n",
"import matplotlib.pyplot as plt\n",
"\n",
"from combine_notebooks import RESULTS_DIR\n",
"from combine_notebooks.validation.validation_sbml import validate_sbml"
]
},
{
"cell_type": "code",
"execution_count": 16,
"id": "cfd51931",
"metadata": {},
"outputs": [],
"source": [
"def pretty_print(doc_before : libsbml.SBMLDocument, doc_after : libsbml.SBMLDocument = None):\n",
" # Break the original SBML into lines\n",
" original_document = libsbml.writeSBMLToString(doc_before)\n",
" original_document_lines = original_document.split('\\n')\n",
" # Print the entire document in red\n",
" if doc_after == None:\n",
" original_document = '\\n'.join(original_document_lines)\n",
" print(\"\\x1b[31m\" + original_document + \"\\x1b[0m\") # ANSI escape used to print colours here\n",
" # If a new document is also given, highlight the lines that have changed\n",
" else:\n",
" # Split the updated SBML into lines\n",
" new_document = libsbml.writeSBMLToString(doc_after)\n",
" new_document_lines = new_document.split('\\n')\n",
" # Iterate over each new line\n",
" for new_line in new_document_lines:\n",
" # Print any new lines in red, otherwise print normally\n",
" if new_line in original_document_lines:\n",
" print(new_line)\n",
" else:\n",
" print(\"\\x1b[31m\" + new_line + \"\\x1b[0m\") # ANSI escape used to print colours here"
]
},
{
"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. You may also want to check for possible errors. Even when the parameter values are hardwired like this, it is still possible for a failure to occur (e.g., if the operating system runs out of memory). "
]
},
{
"cell_type": "code",
"execution_count": 17,
"id": "ae6bbf46",
"metadata": {
"lines_to_next_cell": 0
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\u001b[31m\n",
"\n",
"\u001b[0m\n"
]
}
],
"source": [
"document = libsbml.SBMLDocument(3, 1)\n",
"\n",
"pretty_print(document)"
]
},
{
"attachments": {},
"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": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"\u001b[31m\u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m\u001b[0m\n",
"\n"
]
}
],
"source": [
"start_doc = libsbml.SBMLDocument(document)\n",
"\n",
"model = document.createModel()\n",
"model.setTimeUnits(\"second\")\n",
"model.setExtentUnits(\"mole\")\n",
"model.setSubstanceUnits('mole')\n",
"\n",
"pretty_print(start_doc, document)"
]
},
{
"attachments": {},
"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": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\n",
"\n"
]
}
],
"source": [
"start_doc = libsbml.SBMLDocument(document)\n",
"\n",
"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)\n",
"\n",
"pretty_print(start_doc, document)"
]
},
{
"attachments": {},
"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": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"\n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
" \n",
"\n",
"\n"
]
}
],
"source": [
"start_doc = libsbml.SBMLDocument(document)\n",
"\n",
"c1 = model.createCompartment()\n",
"c1.setId('c1')\n",
"c1.setConstant(True)\n",
"c1.setSize(1)\n",
"c1.setSpatialDimensions(3)\n",
"c1.setUnits('litre')\n",
"\n",
"pretty_print(start_doc, document)"
]
},
{
"attachments": {},
"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": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"\n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
" \n",
"\n",
"\n"
]
}
],
"source": [
"start_doc = libsbml.SBMLDocument(document)\n",
"\n",
"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)\n",
"\n",
"pretty_print(start_doc, document)"
]
},
{
"attachments": {},
"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": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"\n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
" \n",
"\n",
"\n"
]
}
],
"source": [
"start_doc = libsbml.SBMLDocument(document)\n",
"\n",
"k = model.createParameter()\n",
"k.setId('k')\n",
"k.setConstant(True)\n",
"k.setValue(1)\n",
"k.setUnits('per_second')\n",
"\n",
"pretty_print(start_doc, document)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "8cd2796b",
"metadata": {},
"source": [
"Create a reaction inside this model, set the reactants and products. 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.\n",
"NOTE: The reactants and products refer the species already in the model. "
]
},
{
"cell_type": "code",
"execution_count": 23,
"id": "f03557f6",
"metadata": {},
"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",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
" \n",
"\n",
"\n"
]
}
],
"source": [
"start_doc = libsbml.SBMLDocument(document)\n",
"\n",
"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",
"pretty_print(start_doc, document)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"id": "c10fec68",
"metadata": {},
"source": [
"Set the reaction rate expression (the SBML \"kinetic law\"). Here we are using MathML to model the equation ; $k \\times S1 \\times c1$\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 24,
"id": "691507e3",
"metadata": {},
"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",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
"\u001b[31m \u001b[0m\n",
" \n",
" \n",
" \n",
"\n",
"\n"
]
}
],
"source": [
"start_doc = libsbml.SBMLDocument(document)\n",
"\n",
"math_ast = libsbml.parseL3Formula('k * S1 * c1')\n",
"\n",
"kinetic_law = r1.createKineticLaw()\n",
"kinetic_law.setMath(math_ast)\n",
"\n",
"pretty_print(start_doc, document)\n"
]
},
{
"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": [
"RESULTS_DIR.mkdir(parents=True, exist_ok=True)\n",
"file_loc = RESULTS_DIR / \"hello_world_sbml.xml\"\n",
"libsbml.writeSBMLToFile(document, str(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": [
"
![\"Open](\"https://colab.research.google.com/assets/colab-badge.svg\"){kind=icon}
![\"SBML](\"./results/sbml_plot.png\")
\n",
"