Package: ratesb-python
ratesb_python: Rate Law Analysis for SBML and Antimony Modelsratesb_pythonis 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.InstallationTo installratesb_python, execute the following command in your terminal:pipinstallratesb_pythonUsageBelow is an example demonstrating how to use the ratesb_python package with file input:fromratesb_pythonimportAnalyzer# Assuming `model` is your SBML or Antimony modelanalyzer=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 correctnessanalyzer.check_all()results=analyzer.results# Display all errors and warningsprint(results)# Display only warningswarnings=results.get_warnings()forreaction,messagesinwarnings.items():print(reaction,messages)# Retrieve messages for a specific reactionmessages=results.get_messages_by_reaction("Reaction1")print(messages)# Remove messages for a specific reactionresults.remove_messages_by_reaction("Reaction1")# Get number of errors and warningsprint("Num Errors: ",results.count_errors())print("Num Warnings: ",results.count_warnings())Errors and WarningsErrors0001: No rate law entered0002: Expecting reactant in rate law but not foundWarningsCommon Warnings1001: Rate law contains only number1002: Unrecognized rate law from the standard list (and the custom list if given)1003: Flux is not increasing as reactant increases1004: Flux is not decreasing as product increases1005: Expecting boundary species reactant in rate law but not found1006: Expecting parameters to be constantsReversibility1010: Irreversible reaction kinetic law contains productsNaming Conventions1020: 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'Formatting Conventions:1030: Elements of the same type are not ordered properly1031: Formatting convention not followed (compartment before parameters before species)1032: Denominator not in alphabetical order1033: Numerator and denominator not in alphabetical order1034: Numerator convention not followed and denominator not in alphabetical order1035: Denominator convention not followed1036: Numerator not in alphabetical order and denominator convention not followed1037: Numerator and denominator convention not followedNote 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.SBOTerm Annotations:1040: Uni-directional mass action annotation not following recommended SBO terms1041: Uni-term with the moderator annotation not following recommended SBO terms1042: Bi-directional mass action or Bi-terms with the moderator annotation not following recommended SBO terms1043: Michaelis-Menten kinetics without an explicit enzyme annotation not following recommended SBO terms1044: Michaelis-Menten kinetics with an explicit enzyme annotation not following recommended SBO termsFor more details about warnings and errors, please refer to "View Error Codes" button inRateSB.Default Rate Law ClassificationsBefore 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 thesource code.Using Custom Rate Law Classificationsratesb_pythonallows 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:name: A string that specifies the name of the rate law.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.optional_symbols: An array of symbols not necessarily required in the model's rate law.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]Release Notes0.1.0initial release, used SBMLKinetics for rate law classifications0.2.0removed numpy dependencyupdated rate law classifications scheme, no longer using SBMLKinetics for rate law classificationsRestructured code for web integration0.2.1removed Analyzer.check()added get_all_checks() to get the info about all checksimproved testing to full coverage except for trivial onesimproved exception messagesallowed string of Antimony or SBML model as inputsimplified the import statementrevised existing and added new method and class comments0.2.2bug fixescreated github workflow for CI0.2.3include .json filesfixed path finding issue0.2.4updated instructions in readmeContributingContributions toratesb_pythonare 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 ourGitHub repo.DevelopingLicenseratesb_pythonis licensed under the MIT license. Please see the LICENSE file for more information.Future WorksImplement stoichiometry checks for mass actions.Perform checks after default classification to optimize performance.Known IssuesThere are some sympy builtin symbols that will raise error such as "S", so a reaction like "S->P; k1*S" would not work.ContactFor additional queries, please contact Longxuan Fan atlongxuan@usc.edu.We hope ratesb_python assists you effectively in your model rate law analysis!ReferencesXu, 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