colab-icon Interactive online version

Getting started

Install and import sme

[1]:
!pip install -q sme
import sme
from matplotlib import pyplot as plt
print("sme version:", sme.__version__)
sme version: 1.1.0

Importing a model

  • to load an existing model: sme.open_sbml_file('model_filename.xml')

  • to load a built-in example model: sme.open_example_model()

[2]:
my_model = sme.open_example_model()

Getting help

  • to see the type of an object: type(object)

  • to print a one line description of an object: repr(object)

  • to print a multi-line description of an object: print(object)

  • to get help on an object, its methods and properties: help(object)

[3]:
type(my_model)
[3]:
sme.Model
[4]:
repr(my_model)
[4]:
"<sme.Model named 'Very Simple Model'>"
[5]:
print(my_model)
<sme.Model>
  - name: 'Very Simple Model'
  - compartments:
     - Outside
     - Cell
     - Nucleus
  - membranes:
     - Outside <-> Cell
     - Cell <-> Nucleus
[6]:
help(my_model)
Help on Model in module sme object:

class Model(pybind11_builtins.pybind11_object)
 |  the spatial model
 |
 |  Method resolution order:
 |      Model
 |      pybind11_builtins.pybind11_object
 |      builtins.object
 |
 |  Methods defined here:
 |
 |  __init__(...)
 |      __init__(self: sme.Model, filename: str) -> None
 |
 |  __repr__(...)
 |      __repr__(self: sme.Model) -> str
 |
 |  __str__(...)
 |      __str__(self: sme.Model) -> str
 |
 |  export_sbml_file(...)
 |      export_sbml_file(self: sme.Model, filename: str) -> None
 |
 |
 |      exports the model as a spatial SBML file
 |
 |      Args:
 |          filename (str): the name of the file to create
 |
 |  export_sme_file(...)
 |      export_sme_file(self: sme.Model, filename: str) -> None
 |
 |
 |      exports the model as a sme file
 |
 |      Args:
 |          filename (str): the name of the file to create
 |
 |  import_geometry_from_image(...)
 |      import_geometry_from_image(self: sme.Model, filename: str) -> None
 |
 |
 |      sets the geometry of each compartment to the corresponding pixels in the supplied geometry image
 |
 |      Note:
 |          Currently this function assumes that the compartments maintain the same colour
 |          as they had with the previous geometry image. If the new image does not contain
 |          pixels of each of these colours, the new model geometry will not be valid.
 |          The size of a pixel (in physical units) is also unchanged by this function.
 |
 |      Args:
 |          filename (str): the name of the geometry image to import
 |
 |  simulate(...)
 |      simulate(*args, **kwargs)
 |      Overloaded function.
 |
 |      1. simulate(self: sme.Model, simulation_time: float, image_interval: float, timeout_seconds: int = 86400, throw_on_timeout: bool = True, simulator_type: sme.SimulatorType = <SimulatorType.Pixel: 1>, continue_existing_simulation: bool = False) -> std::vector<sme::SimulationResult, std::allocator<sme::SimulationResult> >
 |
 |
 |                 returns the results of the simulation.
 |
 |                 Args:
 |                     simulation_time (float): The length of the simulation in model units of time, e.g. `5.5`
 |                     image_interval (float): The interval between images in model units of time, e.g. `1.1`
 |                     timeout_seconds (int): The maximum time in seconds that the simulation can run for. Default value: 86400 = 1 day.
 |                     throw_on_timeout (bool): Whether to throw an exception on simulation timeout. Default value: `true`.
 |                     simulator_type (sme.SimulatorType): The simulator to use: `sme.SimulatorType.DUNE` or `sme.SimulatorType.Pixel`. Default value: Pixel.
 |                     continue_existing_simulation (bool): Whether to continue the existing simulation, or start a new simulation. Default value: `false`, i.e. any existing simulation results are discarded before doing the simulation.
 |
 |                 Returns:
 |                     SimulationResultList: the results of the simulation
 |
 |                 Raises:
 |                     RuntimeError: if the simulation times out or fails
 |
 |
 |      2. simulate(self: sme.Model, simulation_times: str, image_intervals: str, timeout_seconds: int = 86400, throw_on_timeout: bool = True, simulator_type: sme.SimulatorType = <SimulatorType.Pixel: 1>, continue_existing_simulation: bool = False) -> std::vector<sme::SimulationResult, std::allocator<sme::SimulationResult> >
 |
 |
 |                 returns the results of the simulation.
 |
 |                 Args:
 |                     simulation_times (str): The length(s) of the simulation in model units of time as a comma-delimited list, e.g. `"5"`, or `"10;100;20"`
 |                     image_intervals (str): The interval(s) between images in model units of time as a comma-delimited list, e.g. `"1"`, or `"2;10;0.5"`
 |                     timeout_seconds (int): The maximum time in seconds that the simulation can run for. Default value: 86400 = 1 day.
 |                     throw_on_timeout (bool): Whether to throw an exception on simulation timeout. Default value: `true`.
 |                     simulator_type (sme.SimulatorType): The simulator to use: `sme.SimulatorType.DUNE` or `sme.SimulatorType.Pixel`. Default value: Pixel.
 |                     continue_existing_simulation (bool): Whether to continue the existing simulation, or start a new simulation. Default value: `false`, i.e. any existing simulation results are discarded before doing the simulation.
 |
 |                 Returns:
 |                     SimulationResultList: the results of the simulation
 |
 |                 Raises:
 |                     RuntimeError: if the simulation times out or fails
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  compartment_image
 |      list of list of list of int: an image of the compartments in this model
 |
 |  compartments
 |      CompartmentList: the compartments in this model
 |
 |      a list of :class:`Compartment` that can be iterated over,
 |      or indexed into by name or position in the list.
 |
 |      Examples:
 |          the list of compartments can be iterated over:
 |
 |          >>> import sme
 |          >>> model = sme.open_example_model()
 |          >>> for compartment in model.compartments:
 |          ...     print(compartment.name)
 |          Outside
 |          Cell
 |          Nucleus
 |
 |          or a compartment can be found using its name:
 |
 |          >>> cell = model.compartments["Cell"]
 |          >>> print(cell.name)
 |          Cell
 |
 |          or indexed by its position in the list:
 |
 |          >>> last_compartment = model.compartments[-1]
 |          >>> print(last_compartment.name)
 |          Nucleus
 |
 |  membranes
 |      MembraneList: the membranes in this model
 |
 |      a list of :class:`Membrane` that can be iterated over,
 |      or indexed into by name or position in the list.
 |
 |      Examples:
 |          the list of membranes can be iterated over:
 |
 |          >>> import sme
 |          >>> model = sme.open_example_model()
 |          >>> for membrane in model.membranes:
 |          ...     print(membrane.name)
 |          Outside <-> Cell
 |          Cell <-> Nucleus
 |
 |          or a membrane can be found using its name:
 |
 |          >>> outer = model.membranes["Outside <-> Cell"]
 |          >>> print(outer.name)
 |          Outside <-> Cell
 |
 |          or indexed by its position in the list:
 |
 |          >>> last_membrane = model.membranes[-1]
 |          >>> print(last_membrane.name)
 |          Cell <-> Nucleus
 |
 |  name
 |      str: the name of this model
 |
 |  parameters
 |      ParameterList: the parameters in this model
 |
 |      a list of :class:`Parameter` that can be iterated over,
 |      or indexed into by name or position in the list.
 |
 |      Examples:
 |          the list of parameters can be iterated over:
 |
 |          >>> import sme
 |          >>> model = sme.open_example_model()
 |          >>> for parameter in model.parameters:
 |          ...     print(parameter.name)
 |          param
 |
 |          or a parameter can be found using its name:
 |
 |          >>> p = model.parameters["param"]
 |          >>> print(p.name)
 |          param
 |
 |          or indexed by its position in the list:
 |
 |          >>> last_param = model.parameters[-1]
 |          >>> print(last_param.name)
 |          param
 |
 |  ----------------------------------------------------------------------
 |  Static methods inherited from pybind11_builtins.pybind11_object:
 |
 |  __new__(*args, **kwargs) from pybind11_builtins.pybind11_type
 |      Create and return a new object.  See help(type) for accurate signature.

Viewing model contents

  • the compartments in a model can be accessed as a list: model.compartments

  • the list can be iterated over, or an item looked up by index or name

  • other lists of objects, such as species in a compartment, or parameters in a reaction, behave in the same way

Iterating over compartments

[7]:
for compartment in my_model.compartments:
    print(repr(compartment))
<sme.Compartment named 'Outside'>
<sme.Compartment named 'Cell'>
<sme.Compartment named 'Nucleus'>

Get compartment by name

[8]:
cell_compartment = my_model.compartments["Cell"]
print(repr(cell_compartment))
<sme.Compartment named 'Cell'>

Get compartment by list index

[9]:
last_compartment = my_model.compartments[-1]
print(repr(last_compartment))
<sme.Compartment named 'Nucleus'>

Display geometry of compartments

[10]:
fig, axs = plt.subplots(nrows=1, ncols=len(my_model.compartments), figsize=(18, 12))
for (ax, compartment) in zip(axs, my_model.compartments):
    ax.imshow(compartment.geometry_mask, interpolation='none')
    ax.set_title(f"{compartment.name}")
    ax.set_xlabel("x")
    ax.set_ylabel("y")
plt.show()
../../_images/sme_notebooks_getting_started_17_0.png

Display parameter names and values

[11]:
my_reac = my_model.compartments['Nucleus'].reactions['A to B conversion']
print(my_reac)
for param in my_reac.parameters:
    print(param)
<sme.Reaction>
  - name: 'A to B conversion'

<sme.ReactionParameter>
  - name: 'k1'
  - value: '0.3'

Editing model contents

  • model parameters and object names can be changed by assigning new values to them

[12]:
print("name:", my_model.name)
name: Very Simple Model
[13]:
my_model.name = 'New model name!'
[14]:
print("name:", my_model.name)
name: New model name!
[15]:
print("k1 value:", my_model.compartments['Nucleus'].reactions['A to B conversion'].parameters['k1'].value)
k1 value: 0.3
[16]:
my_model.compartments['Nucleus'].reactions['A to B conversion'].parameters['k1'].value = 0.72
[17]:
print("k1 value:", my_model.compartments['Nucleus'].reactions['A to B conversion'].parameters['k1'].value)
k1 value: 0.72

Exporting a model

  • to export the model to a SBML file: model.export_sbml_file('model_filename.xml')

[18]:
my_model.export_sbml_file('model.xml')