Complete restructuring

Author: Paulocracy

README.md

@@ -1,60 +1,59 @@
-[![PyPI version](https://badge.fury.io/py/commodepy-Paulocracy.svg)](https://badge.fury.io/py/commodepy-Paulocracy)
+[![PyPI version](https://badge.fury.io/py/commodelpy.svg)](https://badge.fury.io/py/commodelpy)
 
-# commodepy
+# ComModelPy
 
 ## Description
 
-commodepy is a collection of Python [dataclasses](https://docs.python.org/3/library/dataclasses.html) and associated functions which aim to help one in generating stoichiometric metabolic models of communities which consist of one or multiple species. All dataclasses and functions are based on [cobrapy](https://github.com/opencobra/cobrapy).
+ComModelPy is a collection of Python [dataclasses](https://docs.python.org/3/library/dataclasses.html) and associated functions which aim to help one in generating stoichiometric metabolic models of communities which consist of one or multiple species. All dataclasses and functions are based on [cobrapy](https://github.com/opencobra/cobrapy).
 
-The underlying method for the definition of the generation of the community models and their MILP-based FBA analyses is the "RedCom" method as published in the following paper (Note: commodepy's author is not directly associated with this publication, and commodepy was not used for this paper):
-
-* Koch, S., Kohrs, F., Lahmann, P., Bissinger, T., Wendschuh, S., Benndorf, D., ... & Klamt, S. (2019). RedCom: A strategy for reduced metabolic modeling of complex microbial communities and its application for analyzing experimental datasets from anaerobic digestion. *PLoS computational biology*, 15(2), e1006759. [doi:10.1371/journal.pcbi.1006759]( https://doi.org/10.1371/journal.pcbi.1006759)
-
-
-## Documentation
-
-A documentation of commodepy's features and functions can be found in the "docs" subfolder of this repository. The documentation's starting point is "index.html". The whole documentation was generated using [pdoc3](https://github.com/pdoc3/).
+The underlying methods for the generation and analysis of the community models is explained in more detail in ComModelPy's source code documentation.
 
+An exemplary usage of ComModelPy is given in its publiation (Bekiaris & Klamt, in submission).
 
 ## Installation procedure
 
 ### Option 1: As PyPI module
 
-You can install commodepy as Python module from [PyPI](https://pypi.org/project/autopacmen-Paulocracy/) using *pip*:
+You can install ComModelPy as Python module from [PyPI](https://pypi.org/project/commodelpy/) using *pip*:
 
 <pre>
-pip install commodepy-Paulocracy
+pip install commodelpy
 </pre>
 
-Afterwards, you can use commodepy just as any other Python module using *import* in your Python session/script:
+Afterwards, you can use ComModelPy just as any other Python module using *import* in your Python session/script:
 <pre>
-import commodepy
+import commodelpy
 </pre>
-
-You can also access commodepy's documentation using Python's help function after importing commodepy, e.g. for the whole module:
+In order to import ComModelPy's main script with all major dataclasses and functions and which is called "commodelpy.py", you can import it using
 <pre>
-help(commodepy)
+import commodelpy.commodelpy
 </pre>
 
-
 ### Option 2: Direct download
 
-If you don't want to use commodepy as PyPI module, you can also download this repository directly. commodepy's main script file is the commodepy Python script in the "commodepy" subfolder.
+If you don't want to use ComModelPy as PyPI module, you can also download this repository directly. The main script file is the commodelpy.py Python script in the "commodelpy" subfolder.
+
+## Repository structure
 
+* The actual commodelpy pip package can be found in the "commodelpy" subfolder, where "commodelpy.py" contains all relevant functions and dataclasses.
+* All Python scripts which were used in ComModelPy's publication, which use ComModelPy's function for community models without defined growth and with fixed species ratios, can be found in the "publication_runs" subfolder, which is in the "commodelpy" subfolder. The scripts in the local subfolder "toy_model" contain the script for the generation of the toy model shown in the publication. The scripts in the local subfolder "ecoli_models" contain the generation of dG0 data using the [Equilibrator API](https://gitlab.com/equilibrator/equilibrator-api) as well as the ComModelPy-assisted generation of iML1515 and EcoliCore2 single-species community models. A complete call of all E. coli model scripts in the right order is given by the "execute_publication_ecoli_model_scripts.py" script in the main folder, a call of the toy model scripts is given by the "execute_publication_toy_model_script.py" script in the main folder.
+* An exemplary usage of ComModelPy with its function with a defined fixed growth rate and free species ratios can be found in the "balanced_growth_example" subfolder. A call of the relevant script is given in the "execute_balanced_growth_example.py" script in the main folder.
 
-## Exemplary usage
+## Documentation
 
-Exemplary usage of commodepy can be found in the "puc" subfolder of the "commodepy" folder. It contains the scripts for the generation
-of the "shinjired" toy model, as well as community versions (i.e., a community of two times the respective model) of iJO1366 and
-EColiCore2. See the "example"'s folder <span>README.md</span> for the references of these examples.
+A documentation of ComModelPy's features and functions can be found in the "docs/commodelpy/" subfolder of this repository. The documentation's starting point is "index.html". The whole documentation was generated using [pdoc3](https://github.com/pdoc3/).
 
+You can also access ComModelPy's documentation using Python's help function after importing ComModelPy, e.g. for the whole module:
+<pre>
+help(commodelpy)
+</pre>
 
-## Source code test range
+## Publication
 
-A small test range for commodepy can be found in the "test" subfolder of the "commodepy" folder,
-it is contained in the "test_commodepy()" function of "test_commodepy.py". The test system works e.g. with
-[pytest](https://github.com/pytest-dev/pytest).
+ComModelPy is published in the following publication:
 
+* Bekiaris & Klamt, 2021, *in submission*
 
 ## License
-commodepy is free and open source, using the Apache License, Version 2
+
+ComModelPy is free and open source, using the Apache License, Version 2

balanced_growth_example/exemplary_run.py

@@ -0,0 +1,127 @@
+import cobra
+import copy
+from commodelpy.commodelpy import Community, SingleModel, create_community_model_with_balanced_growth
+from typing import Dict
+
+growth_rate = 0.4
+# ecolicore double model
+# with internal exchanges for everything in the periplasm
+ecoli_model = cobra.io.read_sbml_model(
+    "./publication_runs/ecoli_models/original_sbml_models/iML1515.xml")
+
+# Deactivate all C sources except of glucose
+ecoli_model.reactions.EX_succ_e.lower_bound = 0
+ecoli_model.reactions.EX_glyc_e.lower_bound = 0
+ecoli_model.reactions.EX_ac_e.lower_bound = 0
+
+# Test model with FBA
+with ecoli_model:
+    print("Single model FBA solution:")
+    fba_solution = ecoli_model.optimize()
+    print(ecoli_model.summary())
+    for reaction in ecoli_model.reactions:
+        if not reaction.id.startswith("EX_"):
+            continue
+        if fba_solution.fluxes[reaction.id] != 0:
+            print(f"{reaction.id}: {fba_solution.fluxes[reaction.id] }")
+    print("~~~")
+
+# Define essential and periplasmic metabolites (essential metabolites
+# were found by FBAs beforehand)
+essential_in_metabolites = [
+    "fe2_e",
+    "nh4_e",
+    "cu2_e",
+    "glc__D_e",
+    "o2_e",
+    "pi_e",
+    "so4_e",
+    "h_e",
+    "h2o_e",
+]
+essential_out_metabolites = [
+    "co2_e",
+    "meoh_e",
+    "ac_e",
+    "h_e",
+    "h2o_e",
+    "etoh_e",
+    "succ_e",
+    "lac__D_e",
+    "for_e",
+]
+all_essential_metabolites = list(
+    set(essential_in_metabolites+essential_out_metabolites))
+essential_metabolite_mapping: Dict[str, str] = {}
+for met in essential_in_metabolites+essential_out_metabolites:
+    essential_metabolite_mapping[met] = (met+"\b").replace("_e\b", "")
+
+periplasmic_metabolites = [
+    x for x in ecoli_model.metabolites if x.id.endswith("_p")]
+periplasmic_metabolites_cut = [(x.id+"\b").replace("_p\b", "")
+                               for x in periplasmic_metabolites]
+periplasmic_metabolites += [x for x in ecoli_model.metabolites
+                            if x.id.endswith("_c") and (((x.id+"\b").replace("_c\b", "") not in periplasmic_metabolites_cut))]
+periplasmic_metabolites = [x for x in periplasmic_metabolites
+                           if (((x.id+"\b").replace("_c\b", "_e") not in all_essential_metabolites)) and
+                              (((x.id+"\b").replace("_p\b", "_e") not in all_essential_metabolites))]
+all_input_metabolite_ids = []
+all_output_metabolite_ids = []
+all_inout_metabolite_ids_mapping: Dict[str, str] = {}
+for periplasmic_metabolite in periplasmic_metabolites:
+    metabolite_id = periplasmic_metabolite.id
+    all_input_metabolite_ids.append(metabolite_id)
+    all_output_metabolite_ids.append(metabolite_id)
+    all_inout_metabolite_ids_mapping[metabolite_id] = (
+        metabolite_id+"\b").replace("_p\b", "").replace("_c\b", "")
+
+combined_input_metabolite_ids = list(set(
+    all_input_metabolite_ids + essential_in_metabolites + essential_out_metabolites))
+combined_output_metabolite_ids = list(set(
+    all_output_metabolite_ids + essential_out_metabolites + essential_in_metabolites))
+combined_metabolite_ids_mapping = {
+    **all_inout_metabolite_ids_mapping, **essential_metabolite_mapping}
+
+# Define commodelpy SingleModel
+ecoli_1 = SingleModel(
+    cobra_model=ecoli_model,
+    species_abbreviation="ecoli1",
+    objective_reaction_id="BIOMASS_Ec_iML1515_core_75p37M",
+    exchange_reaction_id_prefix="EX_",
+    input_metabolite_ids=combined_input_metabolite_ids,
+    output_metabolite_ids=combined_output_metabolite_ids,
+    model_metabolite_to_exchange_id_mapping=combined_metabolite_ids_mapping,
+)
+# Double it :D
+ecoli_2 = copy.deepcopy(ecoli_1)
+ecoli_2.species_abbreviation = "ecoli2"
+
+# Create community model :D
+print("===\nGeneration of community model...")
+potential_product_metabolites = [x for x in periplasmic_metabolites]
+potential_product_metabolite_ids = [
+    (x.id+"\b").replace("_p\b", "").replace("_c\b", "") for x in potential_product_metabolites]
+
+community = Community(
+    single_models=[ecoli_1, ecoli_2],
+    exchange_compartment_id="exchg",
+    exchange_reaction_id_prefix="EX_C_",
+    input_metabolite_ids=[(x+"\b").replace("_e\b", "")
+                          for x in essential_in_metabolites],
+    output_metabolite_ids=[(x+"\b").replace("_e\b", "").replace("\b", "")
+                           for x in essential_out_metabolites+potential_product_metabolite_ids]
+)
+community_model = create_community_model_with_balanced_growth(
+    community, growth_rate)
+
+
+cobra.io.write_sbml_model(
+    community_model, "./balanced_growth_example/models/community_model.xml")
+
+with community_model:
+    community_model.optimize()
+    print(community_model.summary())
+
+
+def run():
+    pass