Paper

Author: longxf21

paper/paper.md

@@ -35,15 +35,20 @@ Mechanistic models in systems biology are essential tools for simulating and und
 
 The  `ratesb_python` package evaluates rate laws against a library of predefined types to identify anomalies that may compromise the accuracy of mechanistic models. This process involves categorizing rate laws based on their mathematical characteristics and examining their performance within the context of the model. Such analysis enables `ratesb_python` to identify potential errors and warnings, including discrepancies in reactant usage or abnormal reaction fluxes. For example, if the rate law provided for the reaction $2 H_2 + O_2 \rightarrow 2 H_2O$ is $k_1 [H_2]^2 [O_2] [H_2O]^2$ (where $k_1$ is a constant), ``ratesb_python`` reports an error since there is no defined classification for the rate law since the products are included ($[H_2O]$).
 
+Moreover, `ratesb_python` extends beyond symbolic comparisons employed by existing tools (such as SBMLKinetics [@Xu2023]) by implementing a **randomized polynomial identity test** for identifying and classifying rate laws. This approach provides polynomial-time complexity compared to the generally non-polynomial complexity of purely symbolic methods. The added benefit is that the algorithm is not restricted to a set of pre-coded equations, thereby enabling more flexible customization: users can readily define their own rate laws and instruct `ratesb_python` to check whether a provided rate law matches a generalized or custom-defined functional form. This functionality is especially beneficial for researchers who need to handle specialized or novel rate laws that do not necessarily fit the standard templates.
+
 # Software Description
 
 `ratesb_python` analyzes rate laws to detect errors and warns about violations of best practices. Input to ``ratesb_python`` can be a file path to a model in the SBML or Antimony [@Smith2009] formats, or a string in the Antimony format. The output is text and/or Python objects. Control over inputs and outputs is managed by ``analyzer.py``.
 
-Central to ``ratesb_python`` is the ability to classify rate laws according to widely used types such as: mass action, Michaelis-Menten, and zeroth order kinetics. ``ratesb_python`` relies heavily on approaches employed in SBMLKinetics [@Xu2023], which uses the ``sympy`` package to do symbolic analysis of rate laws. `ratesb_python` refines and extends these approaches to increase the accuracy of classification and to improve performance.
+Central to ``ratesb_python`` is the ability to classify rate laws according to widely used types such as: mass action, Michaelis-Menten, and zeroth order kinetics. ``ratesb_python`` relies heavily on approaches employed in SBMLKinetics [@Xu2023], which uses the ``sympy`` package to do symbolic analysis of rate laws. However, `ratesb_python` refines and extends these approaches by using a randomized polynomial identity test, providing a more efficient and customizable framework for classifying rate laws. This functionality is complemented by `custom_classifier.py`, which offers users the flexibility to define and classify rate laws via a structured JSON format. This adaptability is crucial for tailoring the tool to specific research requirements, highlighting `ratesb_python`'s commitment to user-defined customization. Default classifications are detailed in `default_classifier.json`.
+
+Error and warning messages generated during the analysis are systematically managed within `messages.json`, ensuring users are well-informed of any issues detected during the examination process. The results of these analyses are succinctly presented through the `Results` class in `results.py`, providing users with a clear description of the findings. 
 
-This functionality is complemented by `custom_classifier.py`, which offers users the flexibility to define and classify rate laws via a structured JSON format. This adaptability is crucial for tailoring the tool to specific research requirements, highlighting `ratesb_python`'s commitment to user-defined customization. Default classifications are detailed in `default_classifier.json`.
+**Error Code Rationale and Organization**  
+`ratesb_python` employs *grouped error codes* to systematically guide users in identifying and addressing issues with rate law classification. This ensures that common issues (e.g., missing reactants, invalid product usage, or typographical mistakes) are clearly distinguished from more severe problems (e.g., completely undefined rate laws). The codes also serve developers by providing a standardized mechanism for adding new checks or extending existing ones. Detailed explanations of these codes, along with examples, can be found both in the `messages.json` file and in the [official documentation](https://longxf-ratesb-python.readthedocs-hosted.com/en/latest/). By grouping related issues under specific ranges of codes, `ratesb_python` makes it easier for users to trace potential errors to their underlying causes and for developers to introduce new error or warning categories without breaking the existing structure.
 
-Error and warning messages generated during the analysis are systematically managed within `messages.json`, ensuring users are well-informed of any issues detected during the examination process. The results of these analyses are succinctly presented through the `Results` class in `results.py`, providing users with a clear description of the findings. Here is a summary of the error and warning codes along with their descriptions:
+Below is a summary of the error and warning codes along with their brief descriptions:
 
 +------------+---------+---------------------------------------------------------------+
 | Code       | Type    | Brief Description                                             |