Python API Reference

For many biologists, working with SBML models is familiar, but translating them into meaningful visual representations can be challenging. The SBMLNetwork Python Package provides an intuitive way to explore SBML-based visualized networks without requiring advanced programming knowledge. By abstracting away visualization complexities, this API allows users to focus on biological insights rather than rendering details.

The following sections dive into each core class of the SBMLNetwork, including Network, Compartment, Species, and Reaction, showing how they expose SBML data and the visual elements they own.

Network

The Network class is the central entry-point of the SBMLNetwork API. The fastest way to obtain a Network instance is the load() class method:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

# Network Extents
print(net.get_size())

A Network object holds every visual element derived from an SBML model— Compartment, Species, and Reaction —so its structure mirrors the hierarchy of the underlying file. The diagram below shows how these core components are organized and how they relate to each other in the visualized network.

For a full list of methods exposed by the Network class, click the link to view the API reference.

Compartment

The Compartment class represents a spatial or logical container within the SBMLNetwork model. It groups related biological species and reactions within a defined boundary—just as compartments do in SBML itself.

After loading a model you can:

• Get just the IDs (strings) with get_compartment_ids().

• Retrieve one compartment by ID with get_compartment().

• Get the full list of compartment objects via get_compartments_list().

Example:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

# Get compartment ids
compartment_ids = net.get_compartment_ids()

# Single compartment
compartment = net.get_compartment(compartment_ids[0])
print(compartment.get_compartment_id())

# All compartments
for comp in net.get_compartments_list():
   print(comp.get_compartment_id())

In the visualization context, each Compartment includes its own Shapes and Labels, which define how the compartment is drawn and annotated in the rendered network diagram. The diagram below shows how a Compartment connects to its Shape and Label elements:

For a full list of methods exposed by the Compartment class, click the link to view the API reference.

Species

The Species class represents individual biological entities within the SBMLNetwork model — for example, molecules, proteins, or genes. Each Species corresponds to a node in the network diagram and visually communicates its presence and role in the system.

After loading a model you can:

• Get just the IDs (strings) with get_species_ids().

• Retrieve one species by ID with get_species().

• Get the full list of species objects via get_species_list().

Example:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

# Get Species ids
species_ids = net.get_species_ids()

# Single species
species = net.get_species(species_ids[0])
print(species.get_species_id())

# All species
for sp in net.get_species_list():
   print(sp.get_species_id())

In the visualization context, each Species includes its own Shapes and Labels, which define how the species is drawn and annotated within the network. The diagram below shows how a Species connects to its Shape and Label elements:

For a full list of methods exposed by the Species class, click the link to view the API reference.

Reaction

The Reaction class represents an interaction or transformation within the SBMLNetwork model — for example, a biochemical reaction or regulatory event. Each Reaction links Species together and shows how entities are converted, produced, or modified as part of the network’s dynamic behavior.

After loading a model you can:

• Get just the IDs (strings) with get_reaction_ids().

• Retrieve one reaction by ID with get_reaction().

• Get the full list of reaction objects via get_reactions_list().

Example:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

# Get reaction ids
reaction_ids = net.get_reaction_ids()

# Single reaction
rxn = net.get_reaction(reaction_ids[0])
print(rxn.get_reaction_id())

# All reactions
for r in net.get_reactions_list():
   print(r.get_reaction_id())

Visually, each Reaction includes its own Reaction Center, Labels, Curves, which define how the reaction is drawn, annotated, and connected to other components in the diagram.

The diagram below shows how a Reaction connects to its Curves, Reaction Center, and Labels elements:

For a full list of methods exposed by the Reaction class, click the link to view the API reference.

Shape

The Shape class captures the geometric appearance of any network element (Compartment, Species, or Reaction). A Shape contains the type of geometry (e.g., rectangle, ellipse, polygon), its position and dimensions in the diagram, and styling info such as border or fill colour. Every visual object that appears on the canvas can have mutliple Shapes associated with it.

After loading a model and retreiving a model element, you can

• Retrieve the first associated Shape with get_shape().

• Retrieve all the Shape objects associated with the network element get_shapes_list() helper.

Example:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

# Get species ids
species_ids = net.get_species_ids()

# Shape for a specific species
species_shape = net.get_species(species_ids[0]).get_shape()
print(species_shape.get_type())

# Add a new shape to the species
net.get_species(species_ids[0]).add_shape("ellipse")

# All shapes for a species
for sh in net.get_species(species_ids[0]).get_shapes_list():
    print(sh.get_type())

A Shape records the styling and geometry details needed to draw a network element. The diagram below shows the inheritance structure: the abstract base Shape class is extended by concrete shapes like Rectangle, Ellipse, and Polygon.

For a full list of methods exposed by the Shape abstract class and its concrete subclasses, click the link to view the API reference.

Label

The Label class defines the textual annotations attached to a network element (such as a Compartment, Species, or Reaction). A Label stores the displayed text, its position, and optional styling like font size, colour, or alignment. Every visual object on the canvas can have multiple Labels to describe different features or details.

After loading a model and retrieving a network element, you can:

• Get the first Label for that element with get_label().

• Retrieve all Label objects attached to the element with get_labels_list().

Example:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

# Get Species ids
species_ids = net.get_species_ids()

# First label for a specific species
species_label = net.get_species(species_ids[0]).get_label()
print(species_label.get_text(), species_label.get_position())

# Add a new label to the first species
new_label = net.get_species(species_ids[0]).add_label("New Label", relative_position=(10, 10))

# All labels for the same species
for label in net.get_species(species_ids[0]).get_labels_list():
    print(label.get_text(), label.get_position())

For a full list of methods exposed by the Label class, click the link to view the API reference.

Curve

The Curve class represents the graphical connection between elements in a reaction, typically used to draw the edges that link species to a reaction center and to each other. A Curve holds one or more Curve Segments, which define its actual path (straight lines or Bezier curves), and an optional Arrowhead that indicates the direction or type of connection.

Each Reaction can have multiple Curve — for example, to draw edges from reactants to the reaction center and then to products.

After loading a model and retrieving a Reaction or Species, you can:

• Retrieve all Curves associated with a Reaction using get_curves_list().

• Retrieve all Curves connected to a Species using get_curves_list().

Example:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

# Get species and reaction ids
species_id = net.get_species_ids()[0]
reaction_id = net.get_reaction_ids()[0]

# All Curves for a Reaction
for curve in net.get_reaction(reaction_id).get_curves_list():
   print(len(curve.get_segments()))

# All Curves in a Reaction that connect to a specific Species
for curve in net.get_reaction(reaction_id).get_curves_list(species_id):
   print(len(curve.get_segments()))

# All Curves connected to a Species
for curve in net.get_species(species_id).get_curves_list():
   print(len(curve.get_segments()))

# All Curves connected to a Species, filtered by Reaction
for curve in net.get_species(species_id).get_curves_list(reaction_id):
   print(len(curve.get_segments()))

A Curve contains all the details needed to draw its path and arrowhead. The diagram below shows how a Curve contains multiple Curve Segments and may include an optional Arrowhead.

For a full list of methods exposed by the Curve class, click the link to view the API reference.

Reaction Center

The Reaction Center represents the visual anchor point of a Reaction in the network diagram. It serves as the central location where Curves connect reactants, products, and modifiers.

A Reaction Center can be represented in two ways:

• As a Curve — for simple or implicit visual styles where the connection itself acts as the anchor.

• As a list of Shapes — for explicit, node-like visual centers that mirror how Species or Compartments are drawn.

After loading a model and retrieving a Reaction, you can:

• Get the Reaction Center with get_center().

Example:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

reaction_id = net.get_reaction_ids()[0]

# Get the Reaction Center
center = net.get_reaction(reaction_id).get_center()

# If the center is a list of Shapes
if center.is_shapes():
   for shape in center.get_shapes_list():
       print(shape.get_type())

# Switch to curve
center.switch_to_curve()

# If the center is a Curve
if center.is_curve():
   print(len(center.get_curve().get_segments()))

For a full list of methods exposed by the Reaction Center class, click the link to view the API reference.

CurveSegment

The CurveSegment class represents an individual segment of a Curve path— a straight line or cubic Bézier curve defined by a start point, an end point, and two control handles.

After loading a model and retrieving a Curve, you can:

• Get a specific segment by index with get_segment().

• Iterate all segments via get_segments_list() or the segments property.

Example:

import sbmlnetwork as sn

net = sn.load("my_model.xml")

# Get reaction id
reaction_id = net.get_reaction_ids()[0]

# Get curve segment coordinates
curve = net.get_reaction(reaction_id).get_curves_list()[0]
seg = curve.get_segment(0)
print(seg.get_start(), seg.get_end())

For a full list of methods exposed by the CurveSegment class, click the link to view the API reference.

ArrowHead

The ArrowHead class encapsulates the arrow head at the end of a Curve in a Reaction. It provides methods to retrieve and modify the arrow head’s identifier, bounding box position and size, and any underlying geometric shapes and styling.

After loading a model and retrieving a Curve in a Reaction, you can:

• Obtain the ArrowHead instance via Curve.get_arrow_head().

• Inspect or update its position, size, shapes, and styling.

Example:

import sbmlnetwork as sn

# Load the SBML model
net = sn.load("my_model.xml")

# Get reaction id
reaction_id = net.get_reaction_ids()[0]

arrow_head = None

# Find the first species that is a product of the reaction
for species in net.get_species_list():
    if species.get_role(reaction_id) == "product":
        arrow_head = species.get_arrow_heads()[0]
        break

# Inspect identifier and position
print("ID:", arrow_head.get_id())
print("Position:", arrow_head.get_relative_position())

For a full list of methods exposed by the ArrowHead class, click the link to view the API reference.

Detailed API Reference Index

This section provides direct links to the detailed API reference pages for each SBMLNetwork class. Use the list below to navigate to the full method and attribute documentation.

• Network
• Compartment
• Species
• Reaction
• Shape
• Rectangle
• Ellipse
• Polygon
• Label
• Curve
• Reaction Center
• CurveSegment
• ArrowHead