Network

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

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— Compartments, Species, and Reactions —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.

Core Methods

Loading and Saving

load(sbml)

Load an SBML model into the network. Accepts file paths, XML strings, or Antimony strings.

Parameters:

sbml (str) – SBML file path, XML content, or Antimony model string

Returns:

The Network instance (for method chaining)

Return type:

Network

save(file_name=None, update_network_extents=False)

Save the network to an SBML file if a file name is provided, or return the SBML XML string otherwise.

Parameters:

• file_name (str) – Output file path (optional)

• update_network_extents (bool) – Whether to recalculate canvas size before saving

Returns:

If file_name is provided, returns True on success and False on failure. If file_name is None, returns the SBML string representation of the network.

Return type:

bool | str

draw(file_name=None, update_network_extents=False)

Render and display (or save) the network visualization.

Parameters:

• file_name (str) – Save figure to this file (optional)

• update_network_extents (bool) – Whether to recalculate canvas size before drawing

Example

import sbmlnetwork as sn

# Load a model from file
net = sn.SBMLNetwork().load("my_model.xml")

# Save to a new file, updating extents
net.save("output.xml", update_network_extents=True)

# Render and save visualization
net.draw("network.png", update_network_extents=True)

Canvas and Background

get_size()

Return the current canvas dimensions as a tuple (width, height).

Return type:

tuple[int, int]

set_size(width, height)

Set the canvas dimensions to the specified width and height.

Parameters:

• width (int) – Canvas width in pixels

• height (int) – Canvas height in pixels

get_background_color()

Return the current background color of the network canvas.

Return type:

str

set_background_color(color)

Set the background color of the network canvas.

Parameters:

color (str) – Color string (e.g., “#f0f0f0”)

Example

import sbmlnetwork as sn

# Initialize and draw default canvas
net = sn.load("my_model.xml")

# Inspect and modify canvas size
width, height = net.get_size()
print(f"Default size: {width}x{height}")
net.set_size((800, 600))

# Inspect and modify background
current_bg = net.get_background_color()
print(f"Default background: {current_bg}")
net.set_background_color("#f0f0f0")
net.draw()

Accessing Network Elements

get_compartments_list()

Return a list-like wrapper over all compartments in the network.

Return type:

CompartmentList

get_compartment(id)

Fetch a single compartment by its SBML identifier.

Parameters:

id (str) – The SBML id of the compartment

Returns:

The matching Compartment object

get_species_list()

Return a list-like wrapper over all species in the network.

Return type:

SpeciesList

get_species(id)

Fetch a single species by its SBML identifier.

Parameters:

id (str) – The SBML id of the species

Returns:

The matching Species object

get_reactions_list()

Return a list-like wrapper over all reactions in the network.

Return type:

ReactionList

get_reaction(id)

Fetch a single reaction by its SBML identifier.

Parameters:

id (str) – The SBML id of the reaction

Returns:

The matching Reaction object

add_additional_element(element_id, element_type='rectangle', position=(0, 0), size=(100, 100))

Add a custom graphical element to the network canvas.

Parameters:

• element_id (str) – Unique identifier for the element

• element_type (str) – Shape type (e.g., “rectangle”, “ellipse”)

• position (tuple) – (x, y) coordinates

• size (tuple) – (width, height) dimensions

Returns:

The created AdditionalElement object

remove_additional_element(element)

Remove a custom graphical element from the network.

Parameters:

element – Element ID or AdditionalElement instance to remove

add_independent_label(text, x, y, width, height)

Add a free-floating text label to the network canvas.

Parameters:

• text (str) – Label text content

• x (float) – X coordinate

• y (float) – Y coordinate

• width (float) – Label width

• height (float) – Label height

Returns:

The created Label object

remove_independent_label(label)

Remove an independent text label from the canvas.

Parameters:

label (str) – Label ID or text content to remove

Example

import sbmlnetwork as sn

# Load network
net = sn.load("my_model.xml")

# List all compartments
for comp in net.get_compartments_list():
   print(comp.id)

# Fetch and inspect one species
species = net.get_species_list()[0]
print(species.id)

# List and fetch reactions
for rxn in net.get_reactions_list():
   print(rxn.id)

r1 = net.get_reactions_list()[0]
print({r1.id})

# Add a custom element and label
elem = net.add_additional_element("box1", "rectangle", position=(50,50), size=(100,30))
label = net.add_independent_label("Custom Box", 50, 50, 100, 30)

Layout and Positioning

auto_layout(max_num_connected_edges=3, reset_fixed_position_elements=False, fixed_position_nodes=None, iterations=-1)

Arrange network elements automatically using a force-directed algorithm.

Parameters:

• max_num_connected_edges (int) – Maximum edges per node for layout decisions

• reset_fixed_position_elements (bool) – If True, clear existing fixed positions before layout

• fixed_position_nodes (list) – List of element IDs to keep fixed (default: None)

• iterations (int) – Number of layout iterations (-1 for automatic convergence)

auto_style(max_num_connected_edges=3)

Apply automatic styling heuristics based on network connectivity.

Parameters:

max_num_connected_edges (int) – Maximum edges per node for styling logic

update_network_extents()

Recalculate and update the canvas size to fit all elements after layout or styling changes.

Example

import sbmlnetwork as sn

# Load and prepare network
net = sn.load("my_model.xml")

# Perform auto-layout with default settings
net.auto_layout()

# Optionally fix a key node in place
net.auto_layout(fixed_position_nodes=[net.get_species_ids()[0]], reset_fixed_position_elements=True)

# Apply auto-styling to adjust line widths and colors
net.auto_style()

# Ensure the canvas encompasses all nodes
net.update_network_extents()

# Render the final layout
net.draw("laid_out_network.png")

Styling

get_style()

Return the active visual-style theme.

set_style(style_name)

Apply a predefined style.

get_styles_options()

List all available style names.

get_font_color()

Return the current text color for all network labels.

set_font_color(color)

Set the text color for all network labels.

get_font_size()

Return the current font size for all network text.

set_font_size(size)

Set the font size for all network text.

get_font_family()

Return the font family currently in use.

set_font_family(family)

Set the font family for all network text.

is_text_bold()

Check whether all network text is rendered in bold.

set_text_bold(flag=True)

Enable or disable bold formatting for all network text.

is_text_italic()

Check whether all network text is rendered in italic.

set_text_italic(flag=True)

Enable or disable italic formatting for all network text.

get_border_color()

Return the border color used for network elements.

set_border_color(color)

Set the border color for all network elements.

get_border_thickness()

Return the current border thickness for network elements.

set_border_thickness(thickness)

Set the border thickness for all network elements.

get_fill_color()

Return the fill color used for network elements.

set_fill_color(color)

Set the fill color for all network elements.

Example

import sbmlnetwork as sn

# Load and prepare network
net = sn.load("my_model.xml")

# Theme and style
available = net.get_styles_options()
print("Styles:", available)
net.set_style("escher")

# Typography adjustments
net.set_font("Helvetica")
net.set_font_size(14)
net.set_font_color("#333333")
net.set_text_bold(True)
net.set_text_italic(False)

# Element appearance
net.set_border_color("#666666")
net.set_border_thickness(5)
net.set_fill_color("#ffffff")

# Render updated network
net.draw("styled_network.png")

Data Visualization

show_fluxes(data, log_scale=False, min_threshold=None, skip_hidden_elements=True)

Color reactions by numeric flux values.

Parameters:

• data (float | dict[str, float]) –

  Either:

  1. A single float representing a simulation time (in time units of your model). In this mode, SBMLNetwork will invoke the simulation engine (i.e., Tellurium) to compute reaction fluxes at that time point and then color reactions accordingly. Example:

     # Simulate the model for 5.0 time units, then color by flux
     net.show_fluxes(5.0)
     

  2. A dict mapping individual reaction IDs to their flux values (floats). - Keys: SBML Reaction Ids. - Values: Flux magnitudes (floats).

     • Positive → forward flux

     • Negative → reverse flux

     Example:

     flux_map = {
         'HEX1': 0.85,     # forward 0.85 units
         'PGI_rev': -0.30  # reverse 0.30 units
     }
     net.show_fluxes(flux_map, log_scale=True, min_threshold=0.05)
     

• log_scale (bool) – If True, apply a logarithmic color scale to flux magnitudes (default: False).

• min_threshold (float) – Minimum absolute flux value to display. Reactions with |flux| below this threshold are omitted (default: None).

• skip_hidden_elements (bool) – If True, skip reactions marked as hidden in the current layout (default: True).

Raises:

KeyError – If a dict-mode key does not match any reaction ID in the model.

Returns:

None

hide_fluxes()

Remove any flux-based coloring from reactions.

show_concentrations(data, log_scale=False, min_threshold=None, show_by='color', skip_hidden_elements=True, min_size=10, max_size=100)

Visualize species concentrations by coloring or resizing glyphs.

Parameters:

• data (float | dict[str, float]) –

  Either:

  1. A single float representing a simulation time (in your model’s time units). SBMLNetwork will invoke the simulation engine (i.e., Tellurium) to compute species concentrations at that time point, then visualize accordingly.

     Example:

     # Simulate for 10.0 time units, then color by concentration
     net.show_concentrations(10.0, show_by="color")
     

  2. A dict mapping individual species IDs to their concentration values (floats). - Keys: SBML Species Ids. - Values: Concentration magnitudes (floats).

     Example:

     conc_map = {
         'A': 5.2,    # concentration 5.2 units for species “A”
         'B': 0.75    # concentration 0.75 units for species “B”
     }
     net.show_concentrations(
         conc_map,
         log_scale=True,
         min_threshold=0.1,
         show_by="size",
         min_size=5,
         max_size=50
     )
     

• log_scale (bool) – If True, apply a logarithmic scale to concentration values (default: False).

• min_threshold (float) – Minimum concentration to display. Species with values below this threshold are omitted (default: None).

• show_by (str) – Choose how to visualize values: - "color" – color glyphs by concentration (default) - "size" – resize glyphs between min_size and max_size based on concentration

• skip_hidden_elements (bool) – If True, skip any species marked as hidden in the current layout (default: True).

• min_size (float) – Minimum glyph size when show_by="size" (default: 10).

• max_size (float) – Maximum glyph size when show_by="size" (default: 100).

Raises:

KeyError – If a dict-mode key does not match any species ID in the model.

Returns:

None

hide_concentrations()

Remove any concentration-based coloring or sizing from species.

Example

import sbmlnetwork as sn

# Load network
net = sn.load("my_model.xml")

reaction_ids = net.get_reaction_ids()

flux_data = {}
initial_flux = 1.0
for reaction_id in reaction_ids:
    flux_data[reaction_id] = initial_flux
    initial_flux += 0.5

# Visualize fluxes on reactions
net.show_fluxes(flux_data, log_scale=True, min_threshold=0.5)
net.draw("flux_network.png")

# Remove flux visualization
net.hide_fluxes()

species_ids = net.get_species_ids()

conc_data = {}
initial_conc = 1.0
for species_id in species_ids:
    conc_data[species_id] = initial_conc
    initial_conc += 0.2

# Visualize concentrations on species by color
net.show_concentrations(conc_data, show_by="color")
net.draw("concentration_network_color.png")

# Remove concentration visualization
net.hide_concentrations()

# Visualize concentrations on species by size
net.show_concentrations(conc_data, show_by="size", min_size=20, max_size=80)
net.draw("concentration_network_size.png")

# Clear concentration visualization
net.hide_concentrations()

Grouping

group_reactions(reactions, color=None)

Visually group related reactions into a single composite object.

Parameters:

• reactions (list[str | Reaction]) – List of reaction IDs or Reaction objects

• color (str) – Optional fill color for the group

Returns:

A ReactionGroup instance

Example

import sbmlnetwork as sn

# Load network
net = sn.load("my_model.xml")

# Define a group of reactions
reaction_ids = net.get_reaction_ids()[:-1]

# Group the reactions with a specific color
group = net.group_reactions(reaction_ids, color="lightgreen")

# Draw the network with grouped reactions highlighted
net.update_network_extents()
net.draw("grouped_network.png")

Visibility Controls

show()

Make all network elements visible on the canvas.

Returns:

None

hide()

Hide all network elements from view.

Returns:

None

Example

import sbmlnetwork as sn

# Load network
net = sn.load("my_model.xml")

# Hide every element before rendering
net.hide()
net.draw("hidden_network.png")

# Reveal all elements and render again
net.show()
net.draw("full_network.png")

Library Information

get_version()

Return the version string of the underlying SBMLNetwork library.

Return type:

str

Example

import sbmlnetwork as sn

# Load network (or simply instantiate)
net = sn.load("my_model.xml")

# Print library version
print(f"SBMLNetwork version: {net.get_version()}")