mntools 0.1.0__tar.gz

mntools-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: mntools
+Version: 0.1.0
+Summary: Metabolic Network Tools.
+Keywords: bioinformatics,metabolic networks,metabolic network analysis,cheminformatics
+Author: Casper Asbjørn Eriksen
+Author-email: Casper Asbjørn Eriksen <casbjorn@imada.sdu.dk>
+License-Expression: GPL-3.0-only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Dist: chemrecon==0.1.5
+Requires-Dist: python-libsbml==5.21.1
+Requires-Dist: ruff>=0.15.10
+Requires-Dist: ty>=0.0.31
+Maintainer: Casper Asbjørn Eriksen
+Maintainer-email: Casper Asbjørn Eriksen <casbjorn@imada.sdu.dk>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Metabolic Network Tools
+
+---
+
+MNTools is a library for loading and representing metabolic networks.
+It uses [ChemRecon](gitlab.com/casbjorn/chemrecon) as its backend for handling database information.

mntools-0.1.0/README.md

@@ -0,0 +1,6 @@
+# Metabolic Network Tools
+
+---
+
+MNTools is a library for loading and representing metabolic networks.
+It uses [ChemRecon](gitlab.com/casbjorn/chemrecon) as its backend for handling database information.

mntools-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "mntools"
+version = "0.1.0"
+
+# Metadata
+description = "Metabolic Network Tools."
+authors = [
+    { name = 'Casper Asbjørn Eriksen', email = 'casbjorn@imada.sdu.dk' }
+]
+maintainers = [
+    { name = 'Casper Asbjørn Eriksen', email = 'casbjorn@imada.sdu.dk' }
+]
+readme = { file = "README.md", content-type = "text/markdown" }
+license = 'GPL-3.0-only'
+keywords = [
+    'bioinformatics',
+    'metabolic networks',
+    'metabolic network analysis',
+    'cheminformatics'
+]
+classifiers = [
+    'Programming Language :: Python :: 3.12',
+    'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
+    'Topic :: Scientific/Engineering :: Bio-Informatics',
+    'Topic :: Scientific/Engineering :: Chemistry'
+]
+
+# Dependencies
+requires-python = ">=3.12"
+dependencies = [
+    "chemrecon == 0.1.5", # Database backend
+    "python-libsbml==5.21.1", # For parsing SBML files
+    "ruff>=0.15.10",
+    "ty>=0.0.31",
+]
+
+# Build
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true
+
+
+# Development tools
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff",
+    "ty",
+]
+
+[tool.ruff.format]
+line-ending = "lf"

mntools-0.1.0/src/mntools/__init__.py

@@ -0,0 +1,14 @@
+"""Metabolic Network Tools."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from mntools.compartment import Compartment
+from mntools.metabolicnetwork import (
+    MetabolicNetwork,
+)
+from mntools.metabolite import Metabolite
+from mntools.reaction import Reaction
+from mntools.species import Species
+from mntools.types import Side, StoichCoeff

mntools-0.1.0/src/mntools/compartment.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from mntools.species import Species
+
+
+class Compartment:
+    """todo."""
+
+    id: str  #: Primary identifier
+    name: str  #: Name, if present
+
+    # Network
+    _species: list[Species]
+
+    # Getters
+    def species(self) -> list[Species]:
+        return self._species
+
+    # Setters
+    def __init__(self, id: str, name: Optional[str]):
+        self.id = id
+        self.name = name if name is not None else id
+
+        self._species = list()
+
+    def add_species(self, species: Species):
+        if species in self._species:
+            raise ValueError(f"Species {species} already in compartment {self.id}.")
+        self._species.append(species)
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return self.id

mntools-0.1.0/src/mntools/constants.py

@@ -0,0 +1,19 @@
+"""Various tables."""
+
+# Names and ids to recognize the extracellular compartment.
+extracellular_names: set[str] = {
+    "external",
+    "extracellular",
+    "external_species",
+    "c_e",
+    "e",
+    "External_Species",
+    "C_e",
+    "extracellular space",
+}
+
+biomass_names: set[str] = {
+    "biomass",
+    "growth",
+    "biomass reaction",
+}

mntools-0.1.0/src/mntools/load/__init__.py

@@ -0,0 +1,3 @@
+"""Loaders for various formats are defined here."""
+
+from mntools.load.loader_sbml import load_from_sbml

mntools-0.1.0/src/mntools/load/loader_sbml.py

@@ -0,0 +1,208 @@
+from math import isnan
+from typing import Optional
+
+import chemrecon
+import libsbml
+
+from mntools import Compartment, MetabolicNetwork, Reaction, Species, StoichCoeff
+from mntools.constants import biomass_names
+
+
+def load_from_sbml(
+    filename: str,
+    metabolite_annotation_type: Optional[str] = "autodetect",
+    reaction_annotation_type: Optional[str] = "autodetect",
+) -> MetabolicNetwork:
+
+    model = MetabolicNetwork(name="test", filename=filename)
+
+    # Read the SBML
+    reader = libsbml.SBMLReader()
+    sbml_file = reader.readSBML(filename)
+    sbml_model: libsbml.Model = sbml_file.getModel()
+
+    # Annotation parser
+    annotation_parser = libsbml.RDFAnnotationParser()
+
+    # Determine the name of the model
+    # TODO
+    # Fall back to filename if name not found
+
+    # Determine type of id annotations
+    metabolite_annotation: Optional[chemrecon.IdentifierTypeCompound]
+    reaction_annotation: Optional[chemrecon.IdentifierTypeReaction]
+    match metabolite_annotation_type:
+        case "autodetect":
+            # Autodetect from the annotations
+            metabolite_annotation = parse_metabolite_id_type(sbml_model)
+        case None:
+            # No annotation type set
+            metabolite_annotation = None
+        case _:
+            # Try to parse the string
+            metabolite_annotation = chemrecon.recognize_id_type_compound(
+                metabolite_annotation_type
+            )
+
+    match reaction_annotation_type:
+        case "autodetect":
+            # Autodetect from the annotations
+            reaction_annotation = parse_reaction_id_type(sbml_model)
+        case None:
+            # No annotation type set
+            reaction_annotation = None
+        case _:
+            # Try to parse the string
+            reaction_annotation = chemrecon.recognize_id_type_reaction(
+                reaction_annotation_type
+            )
+
+    model.set_metabolite_annotation_type(metabolite_annotation)
+    model.set_reaction_annotation_type(reaction_annotation)
+
+    # Load compartments
+    sbml_compartment_list = sbml_model.getListOfCompartments()
+    for sbml_compartment in sbml_compartment_list:
+        id = sbml_compartment.getId()
+        name = sbml_compartment.getName()
+
+        compartment = Compartment(id=id, name=name)
+        model.add_compartment(compartment)
+
+    # Load species
+    sbml_species_list = sbml_model.getListOfSpecies()
+    for sbml_species in sbml_species_list:
+        id = sbml_species.getId()
+        name = sbml_species.getName()
+        compartment_id = sbml_species.getCompartment()
+        compartment = model.get_or_create_compartment(compartment_id)
+
+        # Annotations
+        species_annotation_strs: set[str] = set()
+        for cvterm in sbml_species.getCVTerms():
+            for i in range(cvterm.getNumResources()):
+                res = cvterm.getResourceURI(i)
+                if res.startswith("http://identifiers.org"):
+                    species_annotation_strs.add(res)
+                elif res.startswith("https://identifiers.org"):
+                    species_annotation_strs.add(res)
+
+        species = Species(id=id, name=name, compartment=compartment)
+        species.annotation_strs = species_annotation_strs
+        model.add_species(species)
+
+    # Load reactions
+    sbml_reaction_list = sbml_model.getListOfReactions()
+    for sbml_reaction in sbml_reaction_list:
+        id = sbml_reaction.getId()
+        name = sbml_reaction.getName()
+
+        # Get species which take part
+        lhs_float: dict[Species, float] = dict()
+        rhs_float: dict[Species, float] = dict()
+        lhs: dict[Species, StoichCoeff] = dict()
+        rhs: dict[Species, StoichCoeff] = dict()
+
+        for stoich_mult, listOfSpeciesRefs in [
+            (-1, sbml_reaction.getListOfReactants()),
+            (1, sbml_reaction.getListOfProducts()),
+        ]:
+            float_stoich_dict: dict[Species, float] = dict()
+            int_stoich_dict: dict[Species, int] = dict()
+
+            for sbml_species_ref in listOfSpeciesRefs:
+                stoich_float = sbml_species_ref.getStoichiometry()
+                species_id = sbml_species_ref.getSpecies()
+                species = model.get_species(species_id)
+                if species is None:
+                    raise ValueError(
+                        f"Reaction {id} refers to species {species_id} not found in model."
+                    )
+
+                if species in float_stoich_dict:
+                    # In this case, assume multiple entries correspond to stoichiometry
+                    float_stoich_dict[species] += 1
+                    int_stoich_dict[species] += 1
+
+                if isnan(stoich_float):
+                    # If no stoichiometry is provided, assume 1
+                    stoich_float = 1
+
+                float_stoich_dict[species] = stoich_float * stoich_mult
+                int_stoich_dict[species] = int(stoich_float * stoich_mult)
+
+            # Set the dicts
+            match stoich_mult:
+                case -1:
+                    lhs_float = float_stoich_dict
+                    lhs = int_stoich_dict
+                case 1:
+                    rhs_float = float_stoich_dict
+                    rhs = int_stoich_dict
+
+        # Annotations
+        reaction_annotation_strs: set[str] = set()
+        for cvterm in sbml_reaction.getCVTerms():
+            for i in range(cvterm.getNumResources()):
+                res = cvterm.getResourceURI(i)
+                if res.startswith("http://identifiers.org"):
+                    reaction_annotation_strs.add(res)
+                elif res.startswith("https://identifiers.org"):
+                    reaction_annotation_strs.add(res)
+
+        # Create reaction and add
+        reaction = Reaction(id=id, name=name, lhs=lhs, rhs=rhs)
+        reaction.annotation_strs = reaction_annotation_strs
+        model.add_reaction(reaction)
+
+    # Finalize and validate
+    model.process()
+    return model
+
+
+def is_id_special(id: str) -> bool:
+    """Whether a reaction/metabolite id is 'nonstandard', or in some sense apart from the majority of compounds.
+    For example, the biomass species is 'special'.
+    """
+    if id.lower() in biomass_names:
+        return True
+
+    return False
+
+
+def parse_metabolite_id_type(
+    sbml_model: libsbml.Model,
+) -> Optional[chemrecon.IdentifierTypeCompound]:
+    id_strings: list[str] = list()
+    sbml_species_list = sbml_model.getListOfSpecies()
+    for sbml_species in sbml_species_list:
+        species_id = sbml_species.getId()
+        id_strings.append(species_id)
+
+    # Check if ChEbI
+    if all(s.startswith("M_chebi") for s in id_strings if not is_id_special(s)):
+        return chemrecon.C_CHEBI
+
+    # Check if BiGG
+    if all(s.startswith("M_") for s in id_strings if not is_id_special(s)):
+        return chemrecon.C_BIGG
+
+    # If none found, return none
+    return None
+
+
+def parse_reaction_id_type(
+    sbml_model: libsbml.Model,
+) -> Optional[chemrecon.IdentifierTypeReaction]:
+    id_strings: list[str] = list()
+    sbml_reaction_list = sbml_model.getListOfReactions()
+    for sbml_reaction in sbml_reaction_list:
+        reaction_id = sbml_reaction.getId()
+        id_strings.append(reaction_id)
+
+    # Check if BiGG
+    if all(s.startswith("R_") for s in id_strings if not is_id_special(s)):
+        return chemrecon.R_BIGG
+
+    # If none found, return none
+    return None

mntools-0.1.0/src/mntools/metabolicnetwork.py

@@ -0,0 +1,308 @@
+"""Main class for defining a metabolic network."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any, Optional
+
+import chemrecon
+from chemrecon.utils.get_id_type import get_id_from_identifiers_org
+
+from mntools.compartment import Compartment
+from mntools.metabolite import Metabolite
+from mntools.reaction import Reaction
+from mntools.species import Species
+from mntools.types import Side, StoichCoeff
+from mntools.warning import ModelWarning
+
+# Notes:
+#  SBML: id and metaid (see: https://sbml.org/documents/elaborations/metaid_syntax/)
+#   - id: Must conform to XML id standard
+#   - metaid: Legacy - does not need to conform to XML id standard
+#  Only use ID - metaid is always just id, but with meta_ prefix or similar.
+
+
+class MetabolicNetwork:
+    """A chemical reaection network."""
+
+    # Basics
+    name: str
+    filename: str  #: Filename from which this was created.
+    model_text: Optional[str]  #: The text file defining the model, if available.
+    native_repr: Any  #:
+
+    # Annotations
+    _metabolite_annotation_type: Optional[chemrecon.IdentifierTypeCompound]
+    _reaction_annotation_type: Optional[chemrecon.IdentifierTypeReaction]
+
+    # Network
+    _species: list[Species]
+    _metabolites: list[Metabolite]
+    _reactions: list[Reaction]
+    _compartments: list[Compartment]
+
+    # Network graph
+    # TODO
+
+    # Lookup tables
+    _compartment_lookup: dict[str, Compartment]  # Lookup for compartments by suffix
+    _species_lookup: dict[str, Species]
+    _metabolite_lookup: dict[str, Metabolite]
+    _reaction_lookup: dict[str, Reaction]
+
+    # Meta
+    loader: Optional[
+        Any  # TODO
+    ]  #: The loader, which created this network, if any. Can be used to access load warnings (parser warnings).
+    warnings: list[
+        ModelWarning
+    ]  #: Any semantic uncertainties encountered when loading the network.
+
+    # Getters
+    # ------------------------------------------------------------------------------------------------------------------
+    def all_species(self) -> list[Species]:
+        return self._species
+
+    def all_metabolites(self) -> list[Metabolite]:
+        return self._metabolites
+
+    def all_reactions(self) -> list[Reaction]:
+        return self._reactions
+
+    def all_compartments(self) -> list[Compartment]:
+        return self._compartments
+
+    def get_species(self, identifier: str) -> Optional[Species]:
+        return self._species_lookup.get(identifier, None)
+
+    def get_metabolite(self, identifier: str) -> Optional[Metabolite]:
+        return self._metabolite_lookup.get(identifier, None)
+
+    def get_reaction(self, identifier: str) -> Optional[Reaction]:
+        return self._reaction_lookup.get(identifier, None)
+
+    def get_compartment(self, identifier: str) -> Optional[Compartment]:
+        return self._compartment_lookup.get(identifier, None)
+
+    def get_or_create_compartment(self, identifier: str) -> Compartment:
+        if identifier in self._compartment_lookup:
+            return self._compartment_lookup[identifier]
+        else:
+            compartment = Compartment(id=identifier, name=None)
+            self.add_compartment(compartment)
+            return compartment
+
+    # Analysis
+    # ----------------------------------------------------------------------------------------------------------
+    # TODO get graph
+
+    # TODO get stoich matrix
+
+    # Warnings
+    # ----------------------------------------------------------------------------------------------------------
+    def get_warnings_and_errors(self) -> list[ModelWarning]:
+        """List all the errors and warnings encountered when loading this model."""
+        # TODO
+        raise NotImplementedError()
+
+    # Metabolic network creation
+    # ----------------------------------------------------------------------------------------------------------
+    def __init__(
+        self,
+        name: str,
+        filename: str,
+        model_text: Optional[str] = None,
+    ):
+        """ """
+        # Model information
+        self.name = name
+        self.filename = filename.split("/")[-1]
+        self.model_text = model_text
+
+        # Annotations
+        self._metabolite_annotation_type = None
+        self._reaction_annotation_type = None
+
+        # Reaction network
+        self._species = list()
+        self._metabolites = list()
+        self._reactions = list()
+        self._compartments = list()
+
+        self._species_lookup = dict()
+        self._metabolite_lookup = dict()
+        self._reaction_lookup = dict()
+        self._compartment_lookup = dict()
+
+        # Meta
+        self.warnings = list()
+
+    # Set annotations
+    def set_metabolite_annotation_type(
+        self, annotation_type: Optional[chemrecon.IdentifierTypeCompound]
+    ):
+        """If the 'id' field of the model correspond to specific database annotations, MNTools can extract database
+        entries from the ids. Enter a string like 'bigg' or 'chebi' to associate a database entry with the compound ids.
+        """
+        self._metabolite_annotation_type = annotation_type
+
+    def set_reaction_annotation_type(
+        self, annotation_type: Optional[chemrecon.IdentifierTypeReaction]
+    ):
+        """If the 'id' field of the model correspond to specific database annotations, MNTools can extract database
+        entries from the ids. Enter a string like 'bigg' or 'chebi' to associate a database entry with the reaction ids.
+        """
+        self._reaction_annotation_type = annotation_type
+
+    # Adding network elements
+    def add_species(self, species: Species):
+        self._species.append(species)
+        self._species_lookup[species.id] = species
+
+        # Add to compartment
+        species.compartment.add_species(species)
+
+    def add_metabolite(self, metabolite: Metabolite):
+        self._metabolites.append(metabolite)
+        self._metabolite_lookup[metabolite.id] = metabolite
+        for species in metabolite.species():
+            if species.associated_metabolite is not None:
+                raise ValueError(
+                    f"Attempting to assign metabolite to {species} already associated with metabolite {metabolite}."
+                )
+            species.associated_metabolite = metabolite
+
+    def add_reaction(self, reaction: Reaction):
+        self._reactions.append(reaction)
+        self._reaction_lookup[reaction.id] = reaction
+        for species, coeff in reaction.get_species_with_sum_stoichiometry().items():
+            species.add_reaction(reaction, coeff)
+
+    def add_compartment(self, compartment: Compartment):
+        if compartment.id in self._compartment_lookup:
+            raise ValueError(f"Compartment with id {compartment.id} already exists.")
+        self._compartments.append(compartment)
+        self._compartment_lookup[compartment.id] = compartment
+
+    def process(self):
+        """To be called after adding all elements to the model. Will perform sanity checks and
+        post-processing."""
+
+        # Identify and create metabolites (identify species across compartments).
+        # - by name
+        name_lookup_dict: dict[str, set[Species]] = defaultdict(set)
+        for s in self._species:
+            if s.name is not None:
+                name_lookup_dict[s.name].add(s)
+        for common_name, species_set in name_lookup_dict.items():
+            metabolite = Metabolite(
+                species_set, unified_id=common_name, unified_by="name"
+            )
+            self.add_metabolite(metabolite)
+
+        # TODO also try to identify compounds based on annotation
+        #  - If BiGG/ChEBI: Can parse based on common prefix
+
+        # When metabolites are created, we can process the metabolites/compartments information for all
+        # reactions
+        for r in self._reactions:
+            r.process()
+
+        # Remove empty compartments
+        compartments_to_remove: list[Compartment] = list()
+        for comp in self._compartments:
+            if len(comp.species()) == 0:
+                compartments_to_remove.append(comp)
+
+        compartment_keys_to_remove: list[str] = list()
+        for comp in compartments_to_remove:
+            self._compartments.remove(comp)
+            compartment_keys_to_remove.append(comp.id)
+
+        for key in compartment_keys_to_remove:
+            del self._compartment_lookup[key]
+
+        # Validate
+        #  - All species are in a compartment
+        for s in self._species:
+            if s.compartment is None or s.compartment not in self._compartments:
+                raise ValueError(f"Species {s} is not in a compartment.")
+
+        # - Verify that all species have associated metabolite
+        for s in self._species:
+            if s.associated_metabolite is None:
+                raise ValueError(f"Species {s} does not have metabolite assigned.")
+
+        # - Verify reactions
+        # TODO
+
+        # Finalize
+        pass
+
+    def create_annotations(self):
+        """Adds the annotations as ChemRecon proto-entries (with no looked-up recon id).
+        So the entry annotations may or may not exist in ChemRecon.
+        TODO add a method which also looks up the entries.
+        """
+        # Load all identifiers
+        compound_annotation_str_map: dict[str, Optional[chemrecon.Compound]] = dict()
+        reaction_annotation_str_map: dict[str, Optional[chemrecon.Reaction]] = dict()
+        for s in self.all_species():
+            for annotation_str in s.annotation_strs:
+                compound_annotation_str_map[annotation_str] = None
+        for r in self.all_reactions():
+            for annotation_str in r.annotation_strs:
+                reaction_annotation_str_map[annotation_str] = None
+
+        # Create 'prototype' entries from the identifiers.org strings
+        prototype_entries_compound: dict[str, chemrecon.Compound] = dict()
+        for compound_str in compound_annotation_str_map.keys():
+            id_org_result = get_id_from_identifiers_org(
+                compound_str, chemrecon.IdentifierTypeCompound
+            )
+            if id_org_result is not None:
+                prototype_entries_compound[compound_str] = chemrecon.Compound(
+                    id_type=id_org_result[0].enum_type,
+                    source_id=id_org_result[0].std_identifier(id_org_result[1]),
+                )
+        prototype_entries_reaction: dict[str, chemrecon.Reaction] = dict()
+        for reaction_str in reaction_annotation_str_map.keys():
+            id_org_result = get_id_from_identifiers_org(
+                reaction_str, chemrecon.IdentifierTypeCompound
+            )
+            if id_org_result is not None:
+                prototype_entries_reaction[reaction_str] = chemrecon.Reaction(
+                    id_type=id_org_result[0].enum_type,
+                    source_id=id_org_result[0].std_identifier(id_org_result[1]),
+                )
+
+        # Assign the prototype entries
+        for s in self.all_species():
+            s.entries = set()
+            for annotation_str in s.annotation_strs:
+                try:
+                    s.entries.add(prototype_entries_compound[annotation_str])
+                except KeyError:
+                    # Not found. TODO log warning?
+                    pass
+
+        for r in self.all_reactions():
+            r.entries = set()
+            for annotation_str in r.annotation_strs:
+                try:
+                    r.entries.add(prototype_entries_reaction[annotation_str])
+                except KeyError:
+                    # Not found. TODO log warning?
+                    pass
+
+        # Add entries to metabolites (union of entries of associated species)
+        for m in self.all_metabolites():
+            m.entries = set.union(*[s.entries for s in m.species()])
+            pass
+
+        # Done.
+        pass
+
+    def lookup_annotations(self):
+        # TODO method for getting additional data from the looked up annotations in the ChemRecon db.
+        pass

mntools-0.1.0/src/mntools/metabolite.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterable, Optional
+
+import chemrecon
+
+from mntools.warning import ModelWarning
+
+if TYPE_CHECKING:
+    from mntools.compartment import Compartment
+    from mntools.species import Species
+
+
+class Metabolite:
+    """
+    In this model, a `Metabolite` is a set of species that are in different compartments.
+    """
+
+    id: str  #: Primary identifier
+    name: str  #:
+
+    # Annotations
+    primary_entry: Optional[chemrecon.Compound]
+    entries: set[chemrecon.Compound]
+    unified_by: str
+
+    # Network
+    _species: set[Species]
+    _species_by_compartment: dict[Compartment, Species] = dict()
+
+    # Meta
+    warnings: list[ModelWarning]
+
+    def species(self) -> set[Species]:
+        return self._species
+
+    def get_species_in_compartment(self, compartment: Compartment) -> Optional[Species]:
+        return self._species_by_compartment.get(compartment, None)
+
+    def __init__(self, species: Iterable[Species], unified_id: str, unified_by: str):
+        """The 'unified_by' field determines the common field unifying the species that make up the compound."""
+        self._species = set()
+        self.id = unified_id
+        self.unified_by = unified_by
+        self._species_by_compartment = dict()
+        for s in species:
+            if s in self._species:
+                raise ValueError(f"Species {s} already in metabolite {self.id}.")
+            self._species.add(s)
+            self._species_by_compartment[s.compartment] = s
+
+        # Derive name/id from the species
+        if self.unified_by == "name":
+            self.name = unified_id
+
+        # Derive entries
+        self.entries = next(iter(species)).entries
+        for s in species:
+            if s.entries != self.entries:
+                # TODO raise warning
+                self.entries.update(s.entries)
+
+        # The primary entry of the metabolite is the primary entry of the species only if all agree.
+        primary_entry = next(iter(species)).primary_entry
+        if all(s.primary_entry == primary_entry for s in species):
+            self.primary_entry = primary_entry
+        else:
+            self.primary_entry = None
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return self.id

mntools-0.1.0/src/mntools/reaction.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+import chemrecon
+
+from mntools import compartment
+from mntools.types import Side
+from mntools.warning import ModelWarning
+
+if TYPE_CHECKING:
+    from mntools.compartment import Compartment
+    from mntools.metabolite import Metabolite
+    from mntools.species import Species
+    from mntools.types import StoichCoeff
+
+
+class Reaction:
+    """A reaction."""
+
+    id: str  #: Primary identifier
+    name: str  #:
+
+    # Annotations
+    primary_entry: Optional[chemrecon.Reaction]
+    entries: set[chemrecon.Reaction]
+    annotation_strs: set[str]
+
+    # Network
+    _species: dict[Side, dict[Species, StoichCoeff]]
+    _metabolites: dict[Side, set[Metabolite]] = dict()
+    _compartments: dict[Side, set[Compartment]] = dict()
+
+    # Meta
+    warnings: list[ModelWarning]
+
+    # Properties
+    is_biomass_reaction: bool
+    #  - Reversibility
+    #  - TODO reversible?
+    #  - Transport reactions
+    #  - TODO types (simple, antiporter, synporter ...)?
+    is_transport_reaction: bool  #: We consider a reaction a transport reaction if it spans more than 1 compartment
+    is_transport_reaction_1to1: (
+        bool  #: A transport reaction involving only the transported metabolites.
+    )
+
+    # Getters
+    def get_lhs(self) -> dict[Species, StoichCoeff]:
+        return self._species[Side.L]
+
+    def get_rhs(self) -> dict[Species, StoichCoeff]:
+        return self._species[Side.R]
+
+    def get_lhs_metabolites(self) -> dict[Metabolite, StoichCoeff]:
+        return {
+            s.associated_metabolite: coeff
+            for s, coeff in self._species[Side.L].items()
+            if s.associated_metabolite is not None
+        }
+
+    def get_rhs_metabolites(self) -> dict[Metabolite, StoichCoeff]:
+        return {
+            s.associated_metabolite: coeff
+            for s, coeff in self._species[Side.R].items()
+            if s.associated_metabolite is not None
+        }
+
+    def get_species(self) -> set[Species]:
+        """Get the species which appear on both the LHS and RHS, if any."""
+        return set(self._species[Side.L].keys()) | set(self._species[Side.R].keys())
+
+    def get_metabolites(self) -> set[Metabolite]:
+        """Get the metabolites involved in the reaction (species independent of compartment)."""
+        return set(self._metabolites[Side.L]) | set(self._metabolites[Side.R])
+
+    def get_species_with_sum_stoichiometry(self) -> dict[Species, StoichCoeff]:
+        """Get all species involved and their stoichiometric coefficient.
+        If a species appears on both sides, the sum stoichiometric coefficient is listed.
+        """
+        return {
+            s: self._species[Side.L].get(s, 0) + self._species[Side.R].get(s, 0)
+            for s in self._species[Side.L].keys() | self._species[Side.R].keys()
+        }
+
+    def get_metabolites_with_sum_stoichiometry(self) -> dict[Metabolite, StoichCoeff]:
+        """Get all metabolites involved and their stoichiometric coefficient.
+        If a metabolite appears on both sides, the sum stoichiometric coefficient is listed.
+        This lists _metabolites_, not species.
+        So if this is a transport reaction, the sum stoichiometry should be 0.
+        """
+        # TODO
+        raise NotImplementedError()
+
+    def get_compartment(self) -> Optional[Compartment]:
+        """If not a transport reaction, return the compartment in which the reaction takes place."""
+        if self.is_transport_reaction:
+            return None
+        else:
+            assert (
+                len(self._compartments[Side.L]) == 1
+                and len(self._compartments[Side.R]) == 1
+            ), "Reaction should only involve one compartment"
+            return next(iter(self._compartments[Side.L]))
+
+    def get_compartments(self) -> set[Compartment]:
+        """Get the compartments of hte species involved in the reaction."""
+        return set(self._compartments[Side.L]) | set(self._compartments[Side.R])
+
+    def __init__(
+        self,
+        id: str,
+        name: Optional[str],
+        lhs: dict[Species, StoichCoeff],
+        rhs: dict[Species, StoichCoeff],
+    ):
+        # Annotation
+        self.id = id
+        self.name = name if name is not None else id
+        self.primary_entry = None
+        self.entries = set()
+        self.annotation_strs = set()
+
+        # Network
+        self._species = {Side.L: lhs, Side.R: rhs}
+        self._metabolites = dict()
+        self._compartments = dict()
+
+        # Properties
+        # TODO determine whether this represents biomass
+        self.is_biomass_reaction = False
+
+    def process(self):
+        # Assign metabolites and compartments
+        self._metabolites[Side.L] = set()
+        self._metabolites[Side.R] = set()
+        self._compartments[Side.L] = set()
+        self._compartments[Side.R] = set()
+        for side in [Side.L, Side.R]:
+            for s in self._species[side]:
+                self._compartments[side].add(s.compartment)
+                if s.associated_metabolite is not None:
+                    self._metabolites[side].add(s.associated_metabolite)
+                else:
+                    # TODO raise a warning?
+                    pass
+
+        # Identify whether this is a transport reaction
+        match len(self.get_compartments()):
+            # TODO other types of transport reactions (synporter, antiporter, etc.)?
+            case 1:
+                self.is_transport_reaction = False
+                self.is_transport_reaction_1to1 = False
+            case 2:
+                # Direct transport
+                self.is_transport_reaction = True
+
+                # Check whether 1-to-1 (same metabolites in both compartments)
+                if self._metabolites[Side.L] == self._metabolites[Side.R]:
+                    self.is_transport_reaction_1to1 = True
+                else:
+                    self.is_transport_reaction_1to1 = False
+
+            case _:
+                # Multiple compartments involved.
+                # TODO improve support for this case
+                self.is_transport_reaction = True
+                self.is_transport_reaction_1to1 = False
+
+        # Reversibility
+        # TODO:
+        #  - Check if set in SBML?
+        #  - Check if has an inverse reaction somewhere?
+
+        # Done processing this reaction
+        pass
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return self.id

mntools-0.1.0/src/mntools/species.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any, Optional
+
+import chemrecon
+
+from mntools.warning import ModelWarning
+
+if TYPE_CHECKING:
+    from mntools.compartment import Compartment
+    from mntools.metabolite import Metabolite
+    from mntools.reaction import Reaction
+    from mntools.types import StoichCoeff
+
+
+class Species:
+    """
+    A species is a type of entity that can participate in reactions.
+    In this model, a species is a `Metabolite` in a particular `Compartment`.
+    """
+
+    id: str  #: Primary identifier
+    name: str  #:
+
+    # Annotations
+    primary_entry: Optional[chemrecon.Compound]
+    entries: set[chemrecon.Compound]
+    annotation_strs: set[str]
+    is_biomass: bool
+
+    # Network
+    compartment: Compartment
+    associated_metabolite: Optional[Metabolite]
+    _in_reactions: dict[Reaction, StoichCoeff]
+
+    # Meta
+    warnings: list[ModelWarning]
+
+    # Getters
+    def get_reactions(self) -> dict[Reaction, StoichCoeff]:
+        """Get a list of reactions that this species participates in.
+        If the species appears on both sides of the reaction, the sum stoichiometric coefficient is listed.
+        """
+        return {r: stoich for r, stoich in self._in_reactions.items() if stoich != 0}
+
+    # Creation
+    def add_reaction(self, reaction: Reaction, stoich: StoichCoeff):
+        if reaction in self._in_reactions:
+            raise ValueError(f"Species {self.id} already in reaction {reaction.id}.")
+        self._in_reactions[reaction] = stoich
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return self.id
+
+    def __init__(
+        self,
+        id: str,
+        name: Optional[str],
+        compartment: Compartment,
+    ):
+        self.id = id
+        self.name = name if name is not None else id
+        self.primary_entry = None
+        self.entries = set()
+        self.annotation_strs = set()
+        self.compartment = compartment
+        self._in_reactions = defaultdict(int)
+        self.associated_metabolite = None
+        self.warnings = list()
+
+        # TODO determine whether this represents biomass
+        self.is_biomass = False

mntools-0.1.0/src/mntools/types.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class Side(Enum):
+    L = -1
+    R = 1
+
+
+type StoichCoeff = int

mntools-0.1.0/src/mntools/utils/stoichiometry.py

@@ -0,0 +1,9 @@
+import math
+from fractions import Fraction
+
+
+def scale_to_integer(values: list[float]) -> list[int]:
+    fracs = [Fraction(v) for v in values]
+    denominator_lcm = math.lcm(*[f.denominator for f in fracs])
+    ints = [int(f * denominator_lcm) for f in fracs]
+    return ints

mntools-0.1.0/src/mntools/warning.py

@@ -0,0 +1,16 @@
+class ModelWarning(Exception):
+    """A warning emitted by the model loading procedure."""
+
+    message: str
+
+
+# Types of warnings
+# --------------------------------------------------------------------------------------------------------------
+class SyntaxWarning(ModelWarning):
+    """Something wrong with the syntax of the SBML file."""
+
+    # TODO
+    pass
+
+
+# TODO warn when different annotations between species with the same name(compound)