Merge pull request #14 from cfrioux/meneinc

Incremental scope

CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+# MeneTools v3.3.0 (2023-01-05)
+
+## Add
+
+* `Mene scope_inc` identifies the number of steps needed either to produce targets or all producible compounds (computed with menescope) starting from nutrients
+* tests and doc for `Mene scope_inc` 
+* CHANGELOG.md file
+
+## Modify
+
+* Remove uneeded imports
+* Update license year
+
+# MeneTools v3.2.1 (2022-03-18)
+
+## Fix
+
+- Latest clyngor versions led to errors that can be preventing by not using the clingo module when calling solver #12 
+
+## Test
+
+- Tests are no longer done for Python 3.6 but for versions 3.7, 3.8, 3.9
+
+## Doc
+
+- A small typo is fixed
+
+## Others
+
+- `.gitignore` has been updated
+
+# MeneTools v3.2.0 (2021-08-21)
+
+## Add
+
+* `Mene seed` identifies compounds that would be considered as seeds in network expansion because they are produced by exchange reactions
+
+## Doc
+
+* Update with Meneseed
+
+## Tests
+
+* New tests for Meneseed
+
+## Others
+
+* The MeneTools project is now mirrored on [Gitlab Inria](https://gitlab.inria.fr/pleiade/menetools) via GH CI.
+
+# MeneTools v3.1.1 (2021-02-22)
+
+## Licence
+
+MeneTools is now under the LGPL licence.
+
+## Doc
+
+Update documentation with the latest citation for MeneTools.
+
+# MeneTools v3.1.0 (2020-12-01)
+
+## Add
+
+* `mene scope` now returns (in the json output and API call) a dictionnary with 2 keys: 
+    * the usual list of compounds in the scope
+    * the list of seeds that are also predicted to be produced by the organism
+
+## Tests
+
+* new tests for the latest version of `mene scope`
+
+# MeneTools v3.0.2 (2020-11-18)
+
+## Add
+
+* Menedead: to identify deadends in metabolic network.
+* Windows and MacOS tests in GitHub Actions.
+* Windows compatibility.
+
+# MeneTools v3.0.1 (2020-10-30)
+
+## Add
+
+* Error message if SBML files have no reactions.
+
+# MeneTools v3.0.0 (2020-10-26)
+
+## Add
+
+* Merge all commands into one command with subcommands: e.g. `menescope` becomes `mene scope` 
+* Version can now be retrieved with `mene --version`
+
+## Fix
+
+* Typos
+
+# MeneTools v2.1.0 (2020-09-09)
+
+## Add
+
+* Meneacti to retrieve activable reactions from nutrients
+* Documentation for Meneacti
+
+## Fix
+
+* typos
+* output format of Menecheck in console
+* 
+# MeneTools v2.0.6 (2020-05-21)
+
+* Use of Clyngor for ASP computations
+* Improved documentation
+* Calls directly from python scripts are possible
+* Use of loggers
+* Beta developments of Menepath and Menecof 

README.md

@@ -10,6 +10,7 @@ MeneTools are Python (3.6 and higher) tools to explore the producibility potenti
 * obtain compounds that if added to the nutrients, would ensure the producibility of targets (`Mene cof`)
 * identify metabolic deadends, _i.e._ metabolites that act as reactants of reactions but never as products, or metabolites that act as products of reactions but never as reactants. This is a purely structural analysis (`Mene dead`)
 * identify exchanged compounds in metabolic networks based on exchange reactions, _i.e._ outputs of reactions that do not have reactants (`Mene seed`).
+* identify the number of steps needed either to produce targets or all producible compounds (computed with menescope) starting from nutrients (`Mene scope_inc`).
 
 MeneTools follows the producibility in metabolic networks as defined by the [network expansion](http://www.ncbi.nlm.nih.gov/pubmed/15712108) algorithm.
 Mainly, two rules are followed:
@@ -19,7 +20,7 @@ Mainly, two rules are followed:
 A metabolite that is producible from a set of nutrients is described as being "in the scope of the seeds".
 The computation is made using logic solvers (Answer Set Programming). The present modelling ignores the stoichiometry of reactions (2A + B --> C is considered equivalent to A + B --> C), and is therefore suited to non-curated or draft metabolic networks.
 
-**Menescope** computes the set of metabolites that are producible from a set of nutrients: its provides the scope of the seeds in a metabolic network. **Menecheck** assesses whether a list of target metabolites are producible from the nutrients in a metabolic model, following the network expansion algorithm. **Meneacti** has a similar functioning than Menetools but focuses on activable reactions. It computes all reactions that can be activated from the nutritional environment (i.e. whose sets of reactants are in the scope). **Menepath** (*beta* version) proposes a pathway (set of reactions) that explains the producibility of a given target metabolite from the seeds. The objective if to find a path of reactions for metabolites of interest. **Menecof** (*beta* version) proposes compounds that would unblock the producibility of taregt metabolites if they were producible. It can therefore identify missing cofactor for the modelling or compounds that would need to be added to the growth medium of the modelled organism. **Menedead** (*beta* version) identifies deadends in a metabolic network. Deadends are compounds which are not produced or consumed (meaning that they are not reactant or product of a reaction).
+**Menescope** computes the set of metabolites that are producible from a set of nutrients: its provides the scope of the seeds in a metabolic network. **Menecheck** assesses whether a list of target metabolites are producible from the nutrients in a metabolic model, following the network expansion algorithm. **Meneacti** has a similar functioning than Menetools but focuses on activable reactions. It computes all reactions that can be activated from the nutritional environment (i.e. whose sets of reactants are in the scope). **Menepath** (*beta* version) proposes a pathway (set of reactions) that explains the producibility of a given target metabolite from the seeds. The objective if to find a path of reactions for metabolites of interest. **Menecof** (*beta* version) proposes compounds that would unblock the producibility of taregt metabolites if they were producible. It can therefore identify missing cofactor for the modelling or compounds that would need to be added to the growth medium of the modelled organism. **Menedead** (*beta* version) identifies deadends in a metabolic network. Deadends are compounds which are not produced or consumed (meaning that they are not reactant or product of a reaction). **Meneseed** (*beta* version) returns metabolites produced by reaction without reactants. **Menescope_inc** (*beta* version) computes the number of steps needed by the expansion algorithm to reach either (1) targets o (2) all producible compounds.
 
 **If you use MeneTools, please cite:**
 
@@ -47,7 +48,7 @@ pip install menetools
 ## Usage
 
 ```
-usage: mene [-h] [-v] {acti,check,cof,dead,path,scope,seed} ...
+usage: mene [-h] [-v] {acti,check,cof,dead,path,scope,seed,scope_inc} ...
 
 Explore the producibility potential in a metabolic network using the network
 expansion algorithm. For specific help on each subcommand use: mene {cmd}
@@ -60,7 +61,7 @@ optional arguments:
 subcommands:
   valid subcommands:
 
-  {acti,check,cof,dead,path,scope,seed}
+  {acti,check,cof,dead,path,scope,seed,scope_inc}
     acti                Get activable reactions in a metabolic network,
                         starting from seeds.
     check               Check the producibility of targets from seeds in a
@@ -75,6 +76,9 @@ subcommands:
     scope               Get producible metabolites in a metabolic network,
                         starting from seeds.
     seed                Get metabolites from exchange reactions in a metabolic network.
+    scope_inc           Get the steps of the network expansion to produce
+                        either targets or all the producible compounds,
+                        starting from seeds.
 
 Requires Clingo and clyngor package: "pip install clyngor clyngor-with-clingo"
 
@@ -261,6 +265,32 @@ from menetools import run_meneseed
 
 model = run_meneseed(draft_sbml='required',output='optional')
 ```
+
+### MENESCOPE_INC
+
+Menescope_inc identifies the number of steps needed by the expansion algorithm to reach either (1) specific targets or (2) all producible compounds.
+The results are for each step, the producible metabolites.
+
+```
+usage: mene scope_inc [-h] -d DRAFTNET -s SEEDS [-t TARGETS] [--output OUTPUT]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d DRAFTNET, --draftnet DRAFTNET
+                        metabolic network in SBML format
+  -s SEEDS, --seeds SEEDS
+                        seeds in SBML format
+  -t TARGETS, --targets TARGETS
+                        targets in SBML format
+  --output OUTPUT       json output file
+```
+
+```python
+from menetools import run_menescope_inc
+
+model = run_menescope_inc(draft_sbml='required',seeds_sbml='required',targets_sbml='optional',output='optional')
+```
+
 ## Acknowledgements
 
 Many thanks to

menetools/__init__.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2017-2021 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
+# Copyright (C) 2017-2023 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
@@ -19,8 +19,9 @@
 from menetools.menepath import run_menepath
 from menetools.menedead import run_menedead
 from menetools.meneseed import run_meneseed
+from menetools.menescope_inc import run_menescope_inc
 
 
-__version__="3.2.1"
+__version__="3.3.0"
 """Define the version of the package.
 """

menetools/__main__.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2017-2021 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
+# Copyright (C) 2017-2023 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
@@ -33,6 +33,7 @@
 from menetools.menepath import run_menepath
 from menetools.menedead import run_menedead
 from menetools.meneseed import run_meneseed
+from menetools.menescope_inc import run_menescope_inc
 from shutil import which
 
 VERSION = pkg_resources.get_distribution("menetools").version
@@ -230,6 +231,14 @@ def main():
         ]
     )
 
+    scope_inc_parser = subparsers.add_parser(
+        "scope_inc",
+        help="Get the steps of the network expansion to produce either targets or all the producible compounds, starting from seeds.",
+        parents=[
+            parent_parser_d, parent_parser_s, parent_parser_t, parent_parser_o
+        ]
+    )
+
     args = parser.parse_args()
 
     # If no argument print the help.
@@ -251,6 +260,8 @@ def main():
         run_menescope(args.draftnet, args.seeds, args.output)
     elif args.cmd == "seed":
         run_meneseed(args.draftnet, args.output)
+    elif args.cmd == "scope_inc":
+        run_menescope_inc(args.draftnet, args.seeds, args.targets, args.output)
     else:
         logger.critical("Invalid commands for mene.")
         parser.print_help()

menetools/encodings/get_incremental_scope.lp

@@ -0,0 +1,43 @@
+% Copyright (C) Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
+% This program is free software: you can redistribute it and/or modify
+% it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or
+% (at your option) any later version.
+% This program is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+% GNU Lesser General Public License for more details.
+% You should have received a copy of the GNU Lesser General Public License
+% along with this program.  If not, see <http://www.gnu.org/licenses/>
+
+#include <incmode>.
+
+#program base.
+
+% Set the seeds as compounds producible at step 0.
+dscope(M, 0) :- seed(M).
+
+#program step(t).
+
+% Set the seeds as compounds producible at each step.
+dscope(M, t) :- seed(M).
+
+% Find the compounds producible from the producible compounds of the previous step (plus the seeds).
+dscope(M, t) :- product(M,R), dreaction(R),
+           dscope(M2, t-1): reactant(M2,R).
+
+% Test reversibility of reaction.
+dscope(M, t) :-  reactant(M,R), dreaction(R), reversible(R),
+           dscope(M2, t-1): product(M2,R).
+
+% Compute the size of the scope at each step t.
+dscopeSize(ScopeSize, t) :- ScopeSize=#sum{1,M : dscope(M, t)}.
+
+% Two possible goals:
+% - either targets are given as input and the programm will check the number of step to produce these targets. WARNING if the targets are not producible, it will enter an infinite loop.
+% - or it will try to reach the same scope size as the one computed from a menescope (by using maxscope(MaxScope) given as input).
+#program check(t).
+:- target(F), query(t), not dscope(F, t).
+:- not dscopeSize(ScopeSize, t), query(t), maxscope(MaxScope), ScopeSize == MaxScope.
+
+#show dscope/2.

menetools/meneacti.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python3
 #-*- coding: utf-8 -*-
 
-# Copyright (C) 2017-2021 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
+# Copyright (C) 2017-2023 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
@@ -15,15 +15,11 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>
 
-import argparse
 import json
-import inspect
 import logging
-import os
 import sys
 
-from clyngor import as_pyasp
-from menetools import utils, query, sbml
+from menetools import query, sbml
 from xml.etree.ElementTree import ParseError
 
 logger = logging.getLogger('menetools.meneacti')

menetools/menecheck.py

@@ -1,7 +1,7 @@
 #!python
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2017-2021 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
+# Copyright (C) 2017-2023 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
@@ -15,13 +15,11 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>
 
-import argparse
 import json
 import logging
 import sys
 
 from menetools import utils, query, sbml
-from clyngor import as_pyasp
 from xml.etree.ElementTree import ParseError
 
 logger = logging.getLogger('menetools.menecheck')

menetools/menecof.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 #-*- coding: utf-8 -*-
 
-# Copyright (C) 2017-2021 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
+# Copyright (C) 2017-2023 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
@@ -15,18 +15,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>
 
-import argparse
-import inspect
 import json
 import logging
-import os
 import re
 import sys
 
 from .utils import clean_up
 from .query import get_unproducible, get_cofs_weighted, get_cofs, get_intersection_of_optimal_solutions_cof, get_union_of_optimal_solutions_cof, get_optimal_solutions_cof
 from .sbml import readSBMLspecies_clyngor, make_weighted_list_of_species, readSBMLnetwork_clyngor
-from clyngor import as_pyasp
 from clyngor.as_pyasp import TermSet, Atom
 from xml.etree.ElementTree import ParseError
 

menetools/menedead.py

@@ -1,7 +1,7 @@
 #!python
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2017-2021 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
+# Copyright (C) 2017-2023 Clémence Frioux & Arnaud Belcour - Inria Dyliss - Pleiade
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
@@ -17,11 +17,9 @@
 
 import json
 import logging
-import os
 import sys
 
-from menetools import utils, query, sbml
-from pkg_resources import resource_filename
+from menetools import query, sbml
 from xml.etree.ElementTree import ParseError
 
 logger = logging.getLogger('menetools.menedead')