From 3c5f7e8b3e49dc9f32e36fc62a4dd971562514e5 Mon Sep 17 00:00:00 2001 From: Aldrich Fan Date: Tue, 21 May 2024 06:58:12 -0700 Subject: [PATCH] Initial edit on read the docs --- docs/source/classifications.rst | 22 ++++++++++ docs/source/custom_classifications.rst | 34 +++++++++++++++ docs/source/errors_and_warnings.rst | 46 +++++++++++++++++++++ docs/source/index.rst | 18 ++++++-- docs/source/installation.rst | 8 ++++ docs/source/quickstart.rst | 25 +++++++++++ docs/source/ratesb_python.common.rst | 53 ------------------------ docs/source/ratesb_python.rst | 18 -------- docs/source/tests.rst | 53 ------------------------ docs/source/usage.rst | 57 ++++++++++++++++++++++++++ 10 files changed, 206 insertions(+), 128 deletions(-) create mode 100644 docs/source/classifications.rst create mode 100644 docs/source/custom_classifications.rst create mode 100644 docs/source/errors_and_warnings.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/quickstart.rst delete mode 100644 docs/source/ratesb_python.common.rst delete mode 100644 docs/source/ratesb_python.rst delete mode 100644 docs/source/tests.rst create mode 100644 docs/source/usage.rst diff --git a/docs/source/classifications.rst b/docs/source/classifications.rst new file mode 100644 index 0000000..838e352 --- /dev/null +++ b/docs/source/classifications.rst @@ -0,0 +1,22 @@ +Default Rate Law Classifications +================================ + +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`_. + +.. _source code: https://github.com/sys-bio/ratesb_python/tree/main/ratesb_python/common diff --git a/docs/source/custom_classifications.rst b/docs/source/custom_classifications.rst new file mode 100644 index 0000000..90fe3dc --- /dev/null +++ b/docs/source/custom_classifications.rst @@ -0,0 +1,34 @@ +Using Custom Rate Law Classifications +===================================== + +`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: + +.. code-block:: json + + [ + { + "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)"] + } + ] diff --git a/docs/source/errors_and_warnings.rst b/docs/source/errors_and_warnings.rst new file mode 100644 index 0000000..69c93af --- /dev/null +++ b/docs/source/errors_and_warnings.rst @@ -0,0 +1,46 @@ +Errors and Warnings +=================== + +`ratesb_python` generates detailed errors and warnings to help you ensure your models are robust and accurate. + +### Errors +- **0001**: No rate law entered +- **0002**: Expecting reactant in rate law but not found + +### Warnings +#### Common Warnings +- **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 + +#### Reversibility +- **1010**: Irreversible reaction kinetic law contains products + +#### Naming Conventions +- **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' + +#### Formatting Conventions +- **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 + +#### SBOTerm Annotations +- **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`_. + +.. _RateSB: https://sys-bio.github.io/ratesb/ diff --git a/docs/source/index.rst b/docs/source/index.rst index f19e80f..65fe4dc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,10 +10,20 @@ Welcome to ratesb_python's documentation! :maxdepth: 2 :caption: Contents: - modules - ratesb_python - ratesb_python.common - tests + quickstart + installation + usage + errors_and_warnings + classifications + custom_classifications + testing + release_notes + contributing + license + future_works + known_issues + contact + references Indices and tables ================== diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..1e9ba3e --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,8 @@ +Installation +============ + +To install `ratesb_python`, execute the following command in your terminal: + +.. code-block:: bash + + pip install ratesb_python diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..fa71d0c --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,25 @@ +Quick Start Guide +================= + +This guide provides a quick introduction to using `ratesb_python`. + +Installation +------------ + +To install `ratesb_python`, execute the following command in your terminal: + +.. code-block:: bash + + pip install ratesb_python + +Basic Usage +----------- + +Here's a simple example of how to use `ratesb_python`: + +.. code-block:: python + + from ratesb_python import check_model + print(check_model("S->P;k1*S")) + +For more detailed usage examples, refer to the :ref:`usage` section. diff --git a/docs/source/ratesb_python.common.rst b/docs/source/ratesb_python.common.rst deleted file mode 100644 index b04c08b..0000000 --- a/docs/source/ratesb_python.common.rst +++ /dev/null @@ -1,53 +0,0 @@ -ratesb\_python.common package -============================= - -Submodules ----------- - -ratesb\_python.common.analyzer module -------------------------------------- - -.. automodule:: ratesb_python.common.analyzer - :members: - :undoc-members: - :show-inheritance: - -ratesb\_python.common.custom\_classifier module ------------------------------------------------ - -.. automodule:: ratesb_python.common.custom_classifier - :members: - :undoc-members: - :show-inheritance: - -ratesb\_python.common.reaction\_data module -------------------------------------------- - -.. automodule:: ratesb_python.common.reaction_data - :members: - :undoc-members: - :show-inheritance: - -ratesb\_python.common.results module ------------------------------------- - -.. automodule:: ratesb_python.common.results - :members: - :undoc-members: - :show-inheritance: - -ratesb\_python.common.util module ---------------------------------- - -.. automodule:: ratesb_python.common.util - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: ratesb_python.common - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/ratesb_python.rst b/docs/source/ratesb_python.rst deleted file mode 100644 index db2c662..0000000 --- a/docs/source/ratesb_python.rst +++ /dev/null @@ -1,18 +0,0 @@ -ratesb\_python package -====================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - ratesb_python.common - -Module contents ---------------- - -.. automodule:: ratesb_python - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/tests.rst b/docs/source/tests.rst deleted file mode 100644 index 3d483a4..0000000 --- a/docs/source/tests.rst +++ /dev/null @@ -1,53 +0,0 @@ -tests package -============= - -Submodules ----------- - -tests.test\_analyzer module ---------------------------- - -.. automodule:: tests.test_analyzer - :members: - :undoc-members: - :show-inheritance: - -tests.test\_biomodels module ----------------------------- - -.. automodule:: tests.test_biomodels - :members: - :undoc-members: - :show-inheritance: - -tests.test\_classifier module ------------------------------ - -.. automodule:: tests.test_classifier - :members: - :undoc-members: - :show-inheritance: - -tests.test\_results module --------------------------- - -.. automodule:: tests.test_results - :members: - :undoc-members: - :show-inheritance: - -tests.test\_util module ------------------------ - -.. automodule:: tests.test_util - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: tests - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..30d1166 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,57 @@ +Usage +===== + +This section provides detailed usage examples for `ratesb_python`. + +Simple Example +-------------- + +Here’s a simple example of using `ratesb_python`: + +.. code-block:: python + + from ratesb_python import check_model + print(check_model("S->P;k1*S")) + +Complex Example +--------------- + +For more complex use cases, follow the example below: + +.. code-block:: python + + 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())