ratesb_python is a Python package designed for analyzing rate laws in SBML (Systems Biology Markup Language) and Antimony models, which are commonly used in systems biology for representing biological networks. This package offers a user-friendly API to help ensure that your models are robust and accurate by providing detailed warnings and errors related to rate laws.

For detailed documentation, please visit ReadTheDocs.

To install ratesb_python, execute the following command in your terminal:

pip install ratesb_python

Below are examples demonstrating how to use the ratesb_python package with file input:

Simple example:

from ratesn_python import check_model
print(check_model("S->P;k1*S"))

Complex example:

from ratesb_python import Analyzer

# Assuming `model` is your SBML or Antimony model
analyzer = Analyzer("path/to/model.xml", "path/to/custom_classifications.json")
# or:
analyzer2 = Analyzer("S1->P1; k1 * S1") # custom classification file is optional

# Analyze the model for rate law correctness
analyzer.check_all()
results = analyzer.results

# Display all errors and warnings
print(results)

# Check selected errors and warnings
analyzer.checks([1, 2, 1001, 1002])

# No need to set results = analyzer.results again as results updates automatically
print(results)

# Display only warnings
warnings = results.get_warnings()
for reaction, messages in warnings.items():
    print(reaction, messages)

# Retrieve messages for a specific reaction
messages = results.get_messages_by_reaction("Reaction1")
print(messages)

# Remove messages for a specific reaction
results.remove_messages_by_reaction("Reaction1")

# Get number of errors and warnings
print("Num Errors: ", results.count_errors())
print("Num Warnings: ", results.count_warnings())

• 0001: No rate law entered
• 0002: Expecting reactant in rate law but not found

• 1001: Rate law contains only number
• 1002: Unrecognized rate law from the standard list (and the custom list if given)
• 1003: Flux is not increasing as reactant increases
• 1004: Flux is not decreasing as product increases
• 1005: Expecting boundary species reactant in rate law but not found
• 1006: Expecting parameters to be constants

• 1010: Irreversible reaction kinetic law contains products

• 1020: We recommend that these parameters start with 'k'
• 1021: We recommend that these parameters start with 'K'
• 1022: We recommend that these parameters start with 'V'

• 1030: Elements of the same type are not ordered properly
• 1031: Formatting convention not followed (compartment before parameters before species)
• 1032: Denominator not in alphabetical order
• 1033: Numerator and denominator not in alphabetical order
• 1034: Numerator convention not followed and denominator not in alphabetical order
• 1035: Denominator convention not followed
• 1036: Numerator not in alphabetical order and denominator convention not followed
• 1037: Numerator and denominator convention not followed
• Note that in 1035-1037, adding a parameter with species in the denominator's product terms differs from standard Michaelis-Menten kinetics, so we do not perform these checks.

• 1040: Uni-directional mass action annotation not following recommended SBO terms
• 1041: Uni-term with the moderator annotation not following recommended SBO terms
• 1042: Bi-directional mass action or Bi-terms with the moderator annotation not following recommended SBO terms
• 1043: Michaelis-Menten kinetics without an explicit enzyme annotation not following recommended SBO terms
• 1044: Michaelis-Menten kinetics with an explicit enzyme annotation not following recommended SBO terms

For more details about warnings and errors, please refer to "View Error Codes" button in RateSB.

Before the analysis, we classify each rate law into different categories (Xu, 2023). If a rate law does not belong to any of the default classes or the custom classification file provided, a warning will be raised.

The following categories are used for classifying rate laws:

• Zeroth order (ZERO): No reactant or product in the rate law.
• Uni-Directional Mass Action (UNDR): Direct, one-way reactions where all reactants influencing the rate law and resulting in a single product.
• Uni-Directional Mass Action with an Activator (UNDR-A): Similar to UNDR but includes an essential activator.
• Irreversible Enzymatic non-Mass Action Rate Law: Features at least one enzyme and not all reactants in the rate law.
• Bi-Directional Mass Action (BIDR): Covers reversible reactions with all reactants and products in the rate law.
• Bi-Directional Mass Action with Activator(s) (BIDR-A): Reversible reactions with activators, including enzymes different from reactants and products.
• Reversible Enzymatic non-Mass Action Rate Law: For reversible reactions where not all reactants or products are in the rate law, including at least one enzyme.
• Michaelis-Menten (MM): Describes enzymatic reactions based on substrate concentration, following specific Michaelis-Menten formulas without explicitly mentioning the enzyme.
• Michaelis-Menten with explicit enzyme (MMcat): Michaelis-Menten model explicitly incorporating the enzyme in the reaction rate equation.
• Allosteric and Inhibitors: Michaelis-Menten format affected by allosteric effects or inhibitors, altering reaction rates through enzyme or substrate modulation.
• Reversible Michaelis-Menten: Accounts for reaction reversibility in Michaelis-Menten format.
• Hill Equation: Describes enzyme kinetics in cooperative binding scenarios, relating reaction rate to substrate concentration through a sigmoidal curve.

The details of the default rate law classifications can be found in the source code.

ratesb_python allows the use of custom rate law classifications. To utilize this, you must create a JSON file defining your rate laws. Each rate law object in the JSON file should include:

1. name: A string that specifies the name of the rate law.

2. expression: A valid mathematical equation using specific symbols (compartment, parameter, reactant1, reactant2, reactant3, product1, product2, product3, and enzyme). "species" is NOT allowed, instead you should specify whether a species is reactant, product or enzyme. Any other symbols should not be used in the expression. Mathematical operators such as +, -, *, /, **, and parentheses should be used to construct the equation.

3. optional_symbols: An array of symbols not necessarily required in the model's rate law.

4. power_limited_species: An array of species where the power (exponent) matters in the analysis. If a species is listed here, it should be raised to a specific power in the rate law (specified in the expression).

Here's an example of how to define your rate laws in the JSON file:

[
    {
        "name": "Unidirectional Mass Action with two reactants",
        "expression": "compartment * parameter * reactant1 * reactant2**2",
        "optional_symbols": ["compartment", "parameter"],
        "power_limited_species": ["reactant1,reactant2"]
    },
    {
        "name": "Michaelis Menten",
        "expression": "compartment * parameter * reactant1 / (reactant1 + parameter)",
        "optional_symbols": ["compartment"],
        "power_limited_species": ["reactant1"]
    },
    {
        "name": "Your own rate law",
        "expression": "use: compartment, parameter, reactant1, reactant2, reactant3, product1, product2, product3, enzyme. Do NOT use: species",
        "optional_symbols": ["symbols that do not have to include in a rate law"],
        "power_limited_species": ["RateSB will pay attention to the power of these species (power matters in this case) symbols that have to be set to a certain power in a rate law (please specify power in the expression)"]
    }
    // Add more custom rate laws as needed
]

For testing, run

python -m unittest

• initial release, used SBMLKinetics for rate law classifications

• removed numpy dependency
• updated rate law classifications scheme, no longer using SBMLKinetics for rate law classifications
• Restructured code for web integration

• removed Analyzer.check()
• added get_all_checks() to get the info about all checks
• improved testing to full coverage except for trivial ones
• improved exception messages
• allowed string of Antimony or SBML model as input
• simplified the import statement
• revised existing and added new method and class comments

• bug fixes
• created github workflow for CI

• include .json files
• fixed path finding issue

• updated instructions in readme

• Separated model reading from analysis
• Tested on 1054 biomodels and fixed bugs
• Added check_model method to allow user to use the package with one line
• Solved when running sympy with sympy builtin symbols that raise error such as "S", a reaction like "S->P;k1*S" would work now

• Created ReadTheDocs
• Bug Fixes
• Improved test coverage to 99%

Contributions to ratesb_python are welcomed! Whether it's bug reports, feature requests, or new code contributions, we value your feedback and contributions. Please submit a pull request or open an issue on our GitHub repo.

ratesb_python is licensed under the MIT license. Please see the LICENSE file for more information.

• Implement stoichiometry checks for mass actions.
• Perform checks after default classification to optimize performance.
• Give user option to not use the default rate law classification to improve performance

N/A

For additional queries, please contact Longxuan Fan at longxuan@usc.edu.

We hope ratesb_python assists you effectively in your model rate law analysis!

Xu, J. SBMLKinetics: a tool for annotation-independent classification of reaction kinetics for SBML models. BMC Bioinformatics 24, 248 (2023). https://doi.org/10.1186/s12859-023-05380-3