Merge pull request #132 from draeger-lab/dev

Due to changes in the planned-to-release version 2.0.0, which will lead to backward incompatibility for all functions, deprecation warnings for the end user were added to all modules and the documentation.
draeger-lab · Aug 26, 2024 · 833115f · 833115f
2 parents 60cad3d + ab1d0b6
commit 833115f
Show file tree

Hide file tree

Showing 33 changed files with 229 additions and 7 deletions.
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -3,6 +3,11 @@ refineGEMs package
 
 Here is an overview on all functions. All imports are mocked in ``autodoc_mock_imports`` in the ``conf.py`` file to enable automatic building.
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | Due to massive restructuring and extension, all functions have been moved into new modules.
+    | If you used any functions from refineGEMs until now and want to use version 2.0.0 in the future, make sure to check your code after the version change.
+
 refineGEMs.biomass module
 -------------------------
 
@@ -105,4 +110,5 @@ refineGEMs.sboann module
 .. automodule:: refinegems.sboann
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -94,6 +94,7 @@
 # -- Autodoc -----------------------------------------------------------------
 
 # we need those to display the code comments otherwise the functions cannot be imported
+'''
 autodoc_mock_imports = ["psycopg2", 
                         "gffutils",
                         "cplex.exceptions",
@@ -115,10 +116,12 @@
                         "ols_client",
                         "charges",
                         "click",
+                        "databases",
                         "yaml",
                         "sortedcontainers",
                         "colorama",
                         "matplotlib",
                         "seaborn",
                         "venn"
-                        ]
+                        ]
+'''
diff --git a/docs/source/in_silico_media_generation.rst b/docs/source/in_silico_media_generation.rst
@@ -1,5 +1,11 @@
 From laboratory to *in silico* medium
-==========================================
+======================================
+
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | Using the new setup, the generation of *in silico* media changed slightly. 
+    | Please refer to the newer documentation page after the version change or when using `SPECIMEN <https://github.com/draeger-lab/SPECIMEN>`__.
+
 
 .. hint:: 
    If you want to use the medium with ``refineGEMs.growth`` add the definition to the database schema ``sbo_media_db.sql`` 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -5,6 +5,13 @@ to help with the curation of genome-scale metabolic models (GEMS).
 
 .. hint:: For bug reports please write issues on the `GitHub page <https://github.com/draeger-lab/refinegems/issues>`__ or open a discussion `here <https://github.com/draeger-lab/refinegems/discussions>`__.
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | Due to massive restructuring and extension, all functions have been moved into new modules.
+    | If you used any functions from refineGEMs until now and want to use version 2.0.0 in the future, make sure to check your code after the version change.
+    | For the main pipeline in main.py see `SPECIMEN <https://github.com/draeger-lab/SPECIMEN>`__ as it will be deprecated from version 2.0.0 onwards.
+    | Beware that SPECIMEN only runs with refineGEMs 2.0.0 (starting with developmental versions).
+
 Overview
 --------
 

diff --git a/docs/source/modules/biomass.rst b/docs/source/modules/biomass.rst
@@ -1,6 +1,10 @@
 Correcting the biomass objective function
 =========================================
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | Functions have been moved to :py:mod:`refinegems.curation.biomass` and :py:mod:`refinegems.utility.util`.
+
 The biomass objective function (BOF) of CarveMe does not add up to 1 mmol/gDW/h directly after the draft reconstruction.
 However, to get feasible results from a model this reaction should add up to 1 mmol/gDW/h.
 Thus, the module `biomass` was created to check if the BOF of a model is consistent and if necessary the BOF is adjusted 

diff --git a/docs/source/modules/examples.ipynb b/docs/source/modules/examples.ipynb
@@ -5,7 +5,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Examples on how to use refineGEMs"
+    "# Examples on how to use refineGEMs\n",
+    "\n",
+    ".. warning::\n",
+    "\t    *Will be deprecated from version 2.0.0 onwards.*"
    ]
   },
   {

diff --git a/docs/source/modules/gapfill.rst b/docs/source/modules/gapfill.rst
@@ -1,6 +1,10 @@
 Filling gaps with refineGEMs
 ============================
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | New options for gap filling can be found under :py:mod:`refinegems.classes.gapfill`.
+
 There are two possibilities to use refineGEMs to fill gaps.
 
 Manual gap filling

diff --git a/docs/source/modules/growth.rst b/docs/source/modules/growth.rst
@@ -1,6 +1,10 @@
 Growth simulation with refineGEMs
 =================================
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | Functions have been (mostly) moved and extenden in :py:mod:`refinegems.analysis.growth`.
+
 Interpreting the results
 ------------------------
 Outputs a table with the column headers:

diff --git a/docs/source/modules/pathways.rst b/docs/source/modules/pathways.rst
@@ -1,6 +1,10 @@
 Addition of KEGG Pathways
 =========================
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | Functions have been moved to :py:mod:`refinegems.curation.pathways`.
+
 The KEGG database holds information on metabolic pathways. You can use this module to add KEGG pathways with the libSBML Groups plugin.
 
 The workflow of the script is as follows:

diff --git a/docs/source/modules/polish.rst b/docs/source/modules/polish.rst
@@ -1,6 +1,10 @@
 Polishing a CarveMe model
 =========================
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | Functions have been moved to :py:mod:`refinegems.curation.polish`.
+
 CarveMe version 1.5.1 leads to some irritations in the model, the scripts in ``polish`` enable for example the addition of BiGG IDs to the annotations as well as a correct formatting of the annotations.
 
 .. warning:: 

diff --git a/docs/source/modules/sboann.rst b/docs/source/modules/sboann.rst
@@ -1,6 +1,10 @@
 SBOannotator with refineGEMs
 ============================
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | Use SBOannotator directly or - after the version change - the access point :py:mod:`refinegems.utility.connections.run_SBOannotator` instead.
+
 RefineGEMs offers access to the functionalities of `SBOannotator <https://github.com/draeger-lab/SBOannotator>`__\ :footcite:p:`Leonidou2023_sboann`. 
 
 The ``sboann`` module is splitted into a lot of small functions which are all annotated, however when using it for SBO-Term annotation it only makes sense to run the function ``sbo_annotation``: 

diff --git a/docs/source/pipeline.rst b/docs/source/pipeline.rst
@@ -1,6 +1,11 @@
 Pipeline: From genome sequence to draft model
 =============================================
 
+.. warning:: 
+    | *Will be deprecated from version 2.0.0 onwards.*
+    | The idea for this workflow has been incorporated into `SPECIMEN <https://github.com/draeger-lab/SPECIMEN>`__ under the name PGAB (PGAP-based) workflow.
+    | Beware that SPECIMEN only runs with refineGEMs 2.0.0 (starting with developmental versions).
+
 Generating a model for an organism where no information on genes and proteins is obtainable via any database 
 causes the problem that the model will not contain valid database identifiers for any GeneProduct. To resolve this issue the 
 workflow in Figure :numref:`workflow` can be used.

diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -4,6 +4,12 @@ Usage
 Usage as standalone application
 -------------------------------
 
+.. warning:: 
+    | ``main.py`` will be deprecated from version 2.0.0 onwards.*
+    | For the main pipeline in main.py see the CarveMe-ModelPolisher-based (CMPB) workflow in `SPECIMEN <https://github.com/draeger-lab/SPECIMEN>`__.
+    | Beware that SPECIMEN only runs with refineGEMs 2.0.0 (starting with developmental versions).
+
+
 The script ``main.py`` can be used directly in the command line after
 entering the virtual environment with ``pipenv shell`` or ``conda activate <EnvName>``.
 
@@ -140,6 +146,11 @@ The repository structure has the following intention:
 Usage as python module
 ----------------------
 
+.. warning:: 
+    | *Function calls will be deprecated from version 2.0.0 onwards.*
+    | Due to massive restructuring and extension, all functions have been moved into new modules.
+    | If you used any functions from refineGEMs until now and want to use version 2.0.0 in the future, make sure to check your code after the version change.
+
 See :doc:`examples <modules/examples>` to learn how to use refineGEMs.
 Note that at this time most of the modules only make sense when you use the respective main functions:
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "refineGEMs"
-version = "1.4.2"
+version = "1.5.0"
 requires-python = ">=3.9, <3.11"
 authors = [
     {name = "Famke Baeuerle", email = "[email protected]"},
@@ -39,11 +39,12 @@ dependencies = [
     "biopython>=1.79",
     "bioregistry",
     "bioservices",
+    "Deprecated",
     "importlib-resources<=5.13.0",
     # MEMOTE > 0.14.0 -> depinfo >=2.0.0
     "memote>=0.13.0, <2.0.0",
     "pandas>=1.2.4",
-    "numpy>=1.20.3",
+    "numpy>=1.20.3, <2.0.0",
     "gffutils>=0.10.1",
     "markupsafe>=2.0.1",
     "depinfo>=1.7.0",

diff --git a/src/refinegems/analysis_biocyc.py b/src/refinegems/analysis_biocyc.py
@@ -11,6 +11,9 @@
 SmartTable one: Should contain 'Accession-2' and 'Reactions of gene', 
 SmartTable two: Should contain 'Reaction', 'Reactants of reaction', 'Products of reaction', 'EC-Number', 'Reaction-Direction' and 'Spontaneous?'
 SmartTable three: Should contain 'Compound', 'Chemical Formula' and 'InChI-Key'.
+
+.. warning:: 
+   *Deprecated as of version 2.0.0*: This idea for a gapfilling approach can be found in refinegems.classes.gapfill.BioCycGapFiller.
 """
 # Get all  possible genes by filtering .gff according to 'bio_type=protein_coding' & 'product=hypothetical protein'
 # Compare the list of genes with the ones already in the model & add all missing genes
@@ -29,6 +32,11 @@
 from refinegems.io import parse_fasta_headers
 import os
 
+import warnings
+mes = 'The refinegems.analysis_biocyc module will be deprecated from version 2.0.0 onwards. This idea for a gapfilling approach can be found in refinegems.classes.gapfill.BioCycGapFiller.'
+warnings.warn(mes,DeprecationWarning)
+warnings.warn(mes,FutureWarning)
+
 __author__ = "Gwendolyn O. Döbel and Dr. Reihaneh Mostolizadeh"
 
 

diff --git a/src/refinegems/analysis_db.py b/src/refinegems/analysis_db.py
@@ -1,4 +1,7 @@
 #!/usr/bin/env python
+""".. warning:: 
+    *Deprecated as of version 2.0.0*: Functionalities can be found in refinegems. @TODO
+"""
 import re
 import requests
 import sqlite3
@@ -13,6 +16,11 @@
 from ratelimit import limits, sleep_and_retry
 from multiprocessing import Pool
 
+import warnings
+mes = 'The refinegems.analysis_db module will be deprecated from version 2.0.0 onwards. For more information, refer to the documentation for 2.0.0.'
+warnings.warn(mes,DeprecationWarning)
+warnings.warn(mes,FutureWarning)
+
 __author__ = "Famke Baeuerle, Gwendolyn O. Döbel and Tobias Fehrenbach"
 
 

diff --git a/src/refinegems/analysis_kegg.py b/src/refinegems/analysis_kegg.py
@@ -8,6 +8,10 @@
 and the KEGG identifier of your organism.
 
 Due to the KEGG REST API this is relatively slow (model of size 1500 reactions - 20 min).
+
+.. warning:: 
+    *Deprecated as of version 2.0.0*: The functions have been sorted into different modules. The main idea of the 
+    gap filling via KEGG can be found in refinegems.classes.gapfill.KEGGapFiller 
 """
 
 import pandas as pd
@@ -19,6 +23,11 @@
 from refinegems.entities import get_model_genes, compare_gene_lists, get_model_reacs_or_metabs
 from refinegems.analysis_db import get_bigg2other_db, compare_bigg_model
 
+import warnings
+mes = 'The refinegems.analysis_kegg module will be deprecated from version 2.0.0 onwards. For more information, refer to the documentation for 2.0.0.'
+warnings.warn(mes,DeprecationWarning)
+warnings.warn(mes,FutureWarning)
+
 __author__ = "Famke Baeuerle"
 
 

diff --git a/src/refinegems/biomass.py b/src/refinegems/biomass.py
@@ -2,6 +2,10 @@
 """Most functions within this module were copied from the MEMOTE GitHub page and modified by Gwendolyn O. Döbel.
 
 This module provides functions to be used to assess the biomass weight as well as normalise it.
+
+.. warning:: 
+    *Deprecated as of 2.0.0*: Functionalities have been split into refinegems.curation.biomass and refinegems.utility.entities. 
+    For more information, refer to the updated documentation of version 2.0.0.
 """
 
 import os
@@ -15,6 +19,11 @@
 from memote.utils import truncate
 from typing import Union
 
+import warnings
+mes = 'The refinegems.biomass module will be deprecated from version 2.0.0 onwards. The functionalities can be found in the refinegems.curation.biomass and refinegems.utility.entities modules from 2.0.0 onwards.'
+warnings.warn(mes,DeprecationWarning)
+warnings.warn(mes,FutureWarning)
+
 __author__ = "MEMOTE and Gwendolyn O. Döbel"
 
 

diff --git a/src/refinegems/charges.py b/src/refinegems/charges.py
@@ -4,12 +4,20 @@
 When iterating through all metabolites present in a model, you will find several which have no defined charge (metab.getPlugin('fbc').isSetCharge() = false). This can lead to charge imbalanced reactions. This script takes information on metabolite charges from the ModelSEED database. A charge is automatically added to a metabolite if it has no defined charge and if there is only one charge denoted in ModelSEED. When multiple charges are present, the metabolite and the possible charges are noted and later returned in a dictionary.
 
 It is possible to use the correct_charges_from_db function with other databases. The user just needs to make sure that the compounds dataframe has a 'BiGG' and a 'charge' column.
+
+.. warning:: 
+    *Deprecated as of version 2.0.0*: Functionalities can be found in the submodule refinegems.curation.charges.
 """
 
 import pandas as pd
 from libsbml import Model as libModel
 from refinegems.modelseed import get_modelseed_compounds
 
+import warnings
+mes = 'The refinegems.charges module will be deprecated from version 2.0.0 onwards. The functionalities can be found in the refinegems.curation.charges module from 2.0.0 onwards.'
+warnings.warn(mes,DeprecationWarning)
+warnings.warn(mes,FutureWarning)
+
 __author__ = "Famke Baeuerle"
 
 

diff --git a/src/refinegems/comparison.py b/src/refinegems/comparison.py
@@ -2,6 +2,10 @@
 """ Provides functions to compare and visualize multiple models
 
 Can mainly be used to compare growth behaviour of multiple models. All other stats are shown in the memote report.
+
+.. warning:: 
+    *Deprecated as of version 2.0.0*: Functionalities have been split into refinegems.analysis.comparison and refinegems.classes.report. See the documentation 
+    for version 2.0.0 for more information.
 """
 
 import pandas as pd
@@ -17,6 +21,11 @@
 from refinegems.growth import growth_one_medium_from_default, growth_one_medium_from_minimal
 from refinegems.investigate import initial_analysis, get_reactions_per_sbo
 
+import warnings
+mes = 'The refinegems.growth module will be deprecated from version 2.0.0 onwards. The functionalities can be found in the refinegems.analysis.comparison and refinegems.classes.report modules from 2.0.0 onwards.'
+warnings.warn(mes,DeprecationWarning)
+warnings.warn(mes,FutureWarning)
+
 __author__ = "Famke Baeuerle"
 
 def plot_initial_analysis(models: list[libModel]):

diff --git a/src/refinegems/curate.py b/src/refinegems/curate.py
@@ -2,13 +2,21 @@
 """ Functions to enable annotation of entities using a manual curated table
 
 While working on GEMs the user might come across ill-annotated or missing metabolites, reactions and genes. This module aims to enable faster manual curation by  allowing to edit an excel table directly which is used to update the given model. This module makes use of the cvterms module aswell.
+
+.. warning:: 
+    *Deprecated as of version 2.0.0*: The (not removed) functionalities can be accessed via refinegems.curation.curate from 2.0.0 onwards.
 """
 import pandas as pd
 from tqdm.auto import tqdm
 from libsbml import Model as libModel
 from refinegems.cvterms import add_cv_term_reactions, add_cv_term_metabolites, metabol_db_dict, get_id_from_cv_term
 from refinegems.entities import create_gpr_from_locus_tag, create_reaction
 
+import warnings
+mes = 'The refinegems.curate module will be deprecated from version 2.0.0 onwards. The functionalities can be found in the refinegems.curation.curate module from 2.0.0 onwards.'
+warnings.warn(mes,DeprecationWarning)
+warnings.warn(mes,FutureWarning)
+
 __author__ = "Famke Baeuerle"
 
 

diff --git a/src/refinegems/cvterms.py b/src/refinegems/cvterms.py
@@ -2,10 +2,18 @@
 """ Helper module to work with annotations (CVTerms)
 
 Stores dictionaries which hold information the identifiers.org syntax, has functions to add CVTerms to different entities and parse CVTerms.
+
+.. warning:: 
+    *Deprecated as of version 2.0.0*: The functionalities have been moved to refinegems.utility.cvterms
 """
 import logging
 from libsbml import BIOLOGICAL_QUALIFIER, BQB_IS, BQB_OCCURS_IN, BQB_IS_HOMOLOG_TO, MODEL_QUALIFIER, BQM_IS_DESCRIBED_BY, Unit, CVTerm, Species, Reaction, GeneProduct, Group, SBase
 
+import warnings
+mes = 'The refinegems.growcvtermsth module will be deprecated from version 2.0.0 onwards. The functionalities can be found in the refinegems.utility.cvterms module from 2.0.0 onwards.'
+warnings.warn(mes,DeprecationWarning)
+warnings.warn(mes,FutureWarning)
+
 __author__ = "Famke Baeuerle and Gwendolyn O. Döbel"
 
 metabol_db_dict = {