Updated some docs, paper ready to be submitted

docs/source/API.rst

@@ -1,8 +1,8 @@
 API Documentation
 =================
 
-common.analyzer Module
-----------------------
+Analyzer
+--------
 
 .. automodule:: common.analyzer
  :members:

paper/paper.bib

@@ -0,0 +1,53 @@
+@Article{Xu2023,
+ author={Xu, Jin},
+ title={SBMLKinetics: a tool for annotation-independent classification of reaction kinetics for SBML models},
+ journal={BMC Bioinformatics},
+ year={2023},
+ month={Jun},
+ day={13},
+ volume={24},
+ number={1},
+ pages={248},
+ abstract={Reaction networks are widely used as mechanistic models in systems biology to reveal principles of biological systems. Reactions are governed by kinetic laws that describe reaction rates. Selecting the appropriate kinetic laws is difficult for many modelers. There exist tools that attempt to find the correct kinetic laws based on annotations. Here, I developed annotation-independent technologies that assist modelers by focusing on finding kinetic laws commonly used for similar reactions.},
+ issn={1471-2105},
+ doi={10.1186/s12859-023-05380-3},
+ url={https://doi.org/10.1186/s12859-023-05380-3}
+}
+
+@article{Hucka2003,
+ author = {Hucka, M. and Finney, A. and Sauro, H. M. and Bolouri, H. and Doyle, J. C. and Kitano, H. and Arkin, A. P. and Bornstein, B. J. and Bray, D. and Cornish-Bowden, A. and Cuellar, A. A. and Dronov, S. and Gilles, E. D. and Ginkel, M. and Gor, V. and Goryanin, I. I. and Hedley, W. J. and Hodgman, T. C. and Hofmeyr, J.-H. and Hunter, P. J. and Juty, N. S. and Kasberger, J. L. and Kremling, A. and Kummer, U. and Le Novère, N. and Loew, L. M. and Lucio, D. and Mendes, P. and Minch, E. and Mjolsness, E. D. and Nakayama, Y. and Nelson, M. R. and Nielsen, P. F. and Sakurada, T. and Schaff, J. C. and Shapiro, B. E. and Shimizu, T. S. and Spence, H. D. and Stelling, J. and Takahashi, K. and Tomita, M. and Wagner, J. and Wang, J., and the rest of the SBML Forum:},
+ title = "{The systems biology markup language (SBML): a medium for representation and exchange of biochemical network models}",
+ journal = {Bioinformatics},
+ volume = {19},
+ number = {4},
+ pages = {524-531},
+ year = {2003},
+ month = {03},
+ abstract = "{Motivation: Molecular biotechnology now makes it possible to build
+elaborate systems models, but the systems biology community needs
+information standards if models are to be shared, evaluated and developed
+cooperatively.Results: We summarize the Systems Biology Markup Language (SBML)
+Level 1, a free, open, XML-based format for representing biochemical
+reaction networks. SBML is a software-independent language for describing
+models common to research in many areas of computational biology, including
+cell signaling pathways, metabolic pathways, gene regulation, and others.Availability: The specification of SBML Level 1 is freely
+available from http://www.sbml.org/Contact: [email protected]*To whom correspondence
+ should be addressed.}",
+ issn = {1367-4803},
+ doi = {10.1093/bioinformatics/btg015},
+ url = {https://doi.org/10.1093/bioinformatics/btg015},
+ eprint = {https://academic.oup.com/bioinformatics/article-pdf/19/4/524/48903880/bioinformatics\_19\_4\_524.pdf},
+}
+
+@article{Smith2009, 
+ title={Antimony: A modular model definition language}, 
+ volume={25}, 
+ DOI={10.1093/bioinformatics/btp401}, 
+ number={18}, 
+ journal={Bioinformatics}, 
+ author={Smith, Lucian P. and Bergmann, Frank T. and Chandran, Deepak and Sauro, Herbert M.}, 
+ year={2009}, 
+ month={Jul}, 
+ pages={2452–2454}
+} 
+

paper/paper.md

@@ -0,0 +1,55 @@
+# Summary
+
+`ratesb_python` is a Python package that analyzes mechanistic models of biological systems that consist of networks of chemical reactions like $2 H_2 + O_2 \rightarrow 2 H_2O$. The package focuses on rate laws of reactions, algebraic expressiona that specify the rate at which reactants (e.g., $H_2, O_2$) are converted into products (e.g., $O_2$). ``ratesb_python`` analyzes rate laws to detect errors and warnings that affect the robustness and accuracy of models that use the SBML (Systems Biology Markup Language) community standard for model model descriptions [@Hucka2003].
+
+# Statement of Need
+
+Mechanistic models in systems biology are essential tools for simulating and understanding the intricacies of complex biological systems, and a wide variety of rate laws are used. One commonly used rate law is *mass action* in which the reaction rate is proportional to the product of the concentrations of the reactants. To illustrate, consider a reaction in which $m$ molecules of $A$ combine with $n$ molecules of $B$ to produce $r$ molecules of $C$, or $m A + n B \rightarrow r C$. The mass action rate law is $k*[A]^m*[B]^n$, where $[x]$ is the concentration of $x$ and $k$ is a constant.
+
+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]$).
+
+# 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.
+
+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. Here is a summary of the error and warning codes along with their descriptions:
+
++------------+---------+---------------------------------------------------------------+
+| Code | Type | Brief Description |
+| | | |
++:==========:+:=======:+:=============================================================:+
+| 1-2 | Errors | Issues with missing rate laws or expected reactants. |
++------------+---------+---------------------------------------------------------------+
+| 1001 | Warning | Numeric-only rate law. |
++------------+---------+---------------------------------------------------------------+
+| 1002 | Warning | Rate law unrecognized. |
++------------+---------+---------------------------------------------------------------+
+| 1003-1004 | Warning | Flux relationship issues with reactants and products. |
++------------+---------+---------------------------------------------------------------+
+| 1005 | Warning | Missing boundary species reactant. |
++------------+---------+---------------------------------------------------------------+
+| 1006 | Warning | Non-constant parameters in rate law. |
++------------+---------+---------------------------------------------------------------+
+| 1010 | Warning | Products in irreversible reaction rate law. |
++------------+---------+---------------------------------------------------------------+
+| 1020-1022 | Warning | Naming conventions for parameters not followed. |
++------------+---------+---------------------------------------------------------------+
+| 1030-1037 | Warning | Issues with ordering and formatting conventions in rate laws. |
++------------+---------+---------------------------------------------------------------+
+| 1040-1044 | Warning | Annotations not following recommended SBO terms. |
++============+=========+===============================================================+
+| Error and warning messages to aid in rate law analysis. |
++======================================================================================+
+
+
+# Integration with Other Tools and API Capabilities
+
+`ratesb_python` is designed as a flexible, modular API and standalone tool, enabling integration with various systems biology tools to facilitate rate law analysis in biological modeling projects. Its development in ``python`` ensures compatibility with prevalent scientific computing tools, allowing it to be added to existing systems or tailored for specific applications. It works well with tools that are widely used in the SBML community, such as ``libantimony`` and ``libsbml``. Additionally, `ratesb_python` serves an educational purpose, offering a practical tool for computational biology courses where students can learn about rate law analysis by interacting with and modifying the API.
+
+# Future Work
+
+Future developments for `ratesb_python` include enriching the library of checks and optimizing the performance of classification algorithms. The goal is to expand the tool's capabilities, making it a more comprehensive resource for developers and researchers alike, and to introduce customization options for error and warning management, further enhancing its utility in systems biology.

ratesb_python/common/analyzer.py

@@ -144,9 +144,8 @@ class Analyzer:
  for processing SBML models, and SBMLKinetics for analyzing SBML models and classifying 
  rate laws. The class can return errors and warnings based on the specified checks.
  
- Attributes:
- results (Results): An instance of the Results class used to store and retrieve 
- analysis results. For more details, refer to the documentation of the Results class.
+ :param results: An instance of the Results class used to store and retrieve analysis results.\
+ :type results: Results
  """
 
  @staticmethod
@@ -168,8 +167,10 @@ def list_check(code):
  """
  Returns a string representation of the check corresponding to the provided code.
 
- Args:
- code (int): The code of the check.
+ :param code: The code of the check.
+ :type code: int
+ :return: A string representation of the check.
+ :rtype: str
  """
  ret = str(code) + ": "
  if code not in ALL_CHECKS:

ratesb_python/common/custom_classifier.py

@@ -113,7 +113,7 @@ def validate(self):
  if warnings:
  self.warning_message = 'Some items in your JSON file were invalid and have been removed.\nDetails:\n'
  self.warning_message += '\n'.join(warnings)
- 
+
  def permute(self, arr):
  """Generates all permutations of a list.