imatpy 0.1.0__tar.gz

imatpy-0.1.0/PKG-INFO

@@ -0,0 +1,369 @@
+Metadata-Version: 2.1
+Name: imatpy
+Version: 0.1.0
+Summary: "Python implementation of the Integrative Metabolic Analysis Tool (iMAT) algorithm for context specific metabolic modeling."
+License: MIT
+Author: Braden Griebel
+Requires-Python: >3.9,<3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Provides-Extra: cplex
+Provides-Extra: gurobipy
+Requires-Dist: cobra (>=0.27.0,<0.28.0)
+Requires-Dist: cplex (==22.1.1.0) ; extra == "cplex"
+Requires-Dist: gurobipy (>=10.0.3,<11.0.0) ; extra == "gurobipy"
+Requires-Dist: numpy (>=1.26.0,<2.0.0)
+Requires-Dist: optlang (>=1.7.0,<2.0.0)
+Requires-Dist: pandas (>=1.0.0,<2.0.0)
+Requires-Dist: scipy (>=1.11.3,<2.0.0)
+Requires-Dist: sympy (>=1.12,<2.0)
+Description-Content-Type: text/markdown
+
+# Readme
+
+<img src="./imatpy_logo.png" height="60" alt="logo" />
+
+[![Documentation
+Status](https://readthedocs.org/projects/imatpy/badge/?version=latest.png)](https://imatpy.readthedocs.io/en/latest/?badge=latest)  
+![Tests](https://github.com/Braden-Griebel/imatpy/actions/workflows/tests.yml/badge.svg)
+
+## About
+
+iMATpy is a python package implementing the iMAT algorithm for
+integrating gene expression information with a genome scale metabolic
+model, described in [(Shlomi T, et al. Network-based prediction of human
+tissue-specific metabolism, Nat. Biotechnol., 2008, vol. 26 (pg.
+1003-1010))](https://www.nature.com/articles/nbt.1487).
+
+## Background
+
+The iMAT algorithm takes a genome scale metabolic model (GSM), and gene
+expression weights, then tries to find a feasible flux distribution
+which maximizes the sum of reactions with high expression which have a
+flux above `epsilon`, and reactions with low expression which have a
+flux below `threshold`.
+
+## Installation
+
+This package can be installed via pip
+
+``` python
+pip install imatpy
+```
+
+## Solvers
+
+In order to solve the optimization problems associated with iMAT, a
+LP/MILP solver is required. By default this package uses the
+[GLPK](https://www.gnu.org/software/glpk/) solver which is installed
+automatically by COBRApy, but [Gurobi](https://www.gurobi.com/) and
+[CPLEX](https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer).
+Both Gurobi and CPLEX have free academic licenses available.
+
+## Workflow
+
+The general workflow for using this package is as follows:
+
+1.  Normalize gene expression data for sequencing depth and gene length
+    (TPM or RPKM both work well)
+2.  Quantile normalize the gene expression data (for example with the
+    [`qnorm` package](https://pypi.org/project/qnorm/)) (This is
+    optional, but can help make the results less sensitive to
+    parameters)
+3.  Combine gene expression values accross samples, for example by
+    taking the mean or median
+4.  Convert the gene expression data into qualitative weights, of -1, 0,
+    or 1, where -1 represents low expression, 1 represents high
+    expression, and 0 represents all other genes. This can be done by
+    setting the bottom 15% of genes to -1, the top 15% of genes to 1,
+    and all other genes to 0. Other percentiles can be used, but 15% is
+    a decent starting point.
+5.  Using the `parse_gpr` submodule, specifically the
+    `gene_to_rxn_weights` function, convert the gene weights into
+    reaction weights using the GPR rules in the model.
+6.  Either generate a flux distribution with the iMAT algorithm, or
+    construct a new model with restrictions based on iMAT results.
+    - To generate a flux distribution, use the `imatpy.imat` submodule,
+      specifically the `imat` function. This function takes a model, and
+      a series of reaction weights, and returns a flux distribution
+      which maximizes the sum of reactions with high expression which
+      have a flux above `epsilon`, and reactions with low expression
+      which have a flux below `threshold`.  
+    - To generate a model with restrictions based on the iMAT results,
+      use the `model_creation` submodule. It includes a variety of
+      different methods for generating models based on iMAT, with a
+      wrapper function `generate_model` for convinience.
+
+## Parse GPR
+
+The `parse_gpr` submodule has functions for applying the
+gene-protien-reaction (GPR) rules in a model to gene weights in order to
+convert gene weights into reaction weights which can act as input to the
+iMAT algorithm.
+
+The input to this method is a pandas Series with the index being the
+gene identifiers, and the values being the gene weights. The output is a
+pandas Series with the index being the reaction identifiers, and the
+values being the reaction weights. This method only handles a single
+series, so the gene expression data must be processed into single
+weights (with -1 representing lowly expressed genes, 1 representing
+highly expressed genes, and 0 for all other genes).
+
+Here is an example of how to use this method:
+
+``` python
+# External imports
+import pandas as pd
+
+# iMATpy imports
+from imatpy.model_utils import read_model
+from imatpy.parse_gpr import gene_to_rxn_weights
+
+# Read in the model
+model = read_model("./tests/data/test_model.xml")
+
+# Create a pandas Series representing gene expression weights
+model_weights = pd.Series({
+            "g_A_imp": 1,
+            "g_B_imp": -1,
+            "g_C_imp": -1,
+            "g_F_exp": 0,
+            "g_G_exp": -1,
+            "g_H_exp": 0,
+            "g_A_B_D_E": 0,
+            "g_C_E_F": -1,
+            "g_C_H": 0,
+            "g_D_G": 1,
+        })
+
+# Convert the gene weights into reaction weights
+reaction_weights = gene_to_rxn_weights(model=model, gene_weights=model_weights)
+
+# Print the reaction weights
+print(reaction_weights)
+```
+
+    R_A_e_ex     0.0
+    R_B_e_ex     0.0
+    R_C_e_ex     0.0
+    R_F_e_ex     0.0
+    R_G_e_ex     0.0
+    R_H_e_ex     0.0
+    R_A_imp      1.0
+    R_B_imp     -1.0
+    R_C_imp     -1.0
+    R_F_exp      0.0
+    R_G_exp     -1.0
+    R_H_exp      0.0
+    r_A_B_D_E    0.0
+    r_C_E_F     -1.0
+    r_C_H        0.0
+    r_D_G        1.0
+    dtype: float64
+
+## iMAT Methods
+
+The `imat` submodule contains functions for running the iMAT algorithm.
+The main function is `imat`, which takes a model, and a series of
+reaction weights, and returns a flux distribution which maximizes the
+sum of reactions with high expression which have a flux above `epsilon`,
+and reactions with low expression which have a flux below `threshold`.
+
+Here is an example of how to use this method:
+
+``` python
+# External imports
+import pandas as pd
+
+# iMATpy imports
+from imatpy.model_utils import read_model
+from imatpy.imat import imat
+
+# Read in the model
+model = read_model("./tests/data/test_model.xml")
+
+# Read in the reaction weights
+rxn_weights = pd.read_csv("./tests/data/test_model_reaction_weights.csv", index_col=0).squeeze()
+
+# Run iMAT
+imat_results = imat(model=model, rxn_weights=rxn_weights, epsilon=1, threshold=0.01)
+
+# Print the imat objective
+print(f"iMAT Objective: {imat_results.objective_value}")
+
+# Print the imat flux distribution
+print(f"iMAT Flux Distribution: \n{imat_results.fluxes}")
+```
+
+    iMAT Objective: 3.0
+    iMAT Flux Distribution: 
+    R_A_e_ex    -1.0
+    R_B_e_ex    -1.0
+    R_C_e_ex    -1.0
+    R_F_e_ex     1.0
+    R_G_e_ex     1.0
+    R_H_e_ex    -0.0
+    R_A_imp      1.0
+    R_B_imp      1.0
+    R_C_imp      1.0
+    R_F_exp      1.0
+    R_G_exp      1.0
+    R_H_exp      0.0
+    r_A_B_D_E    1.0
+    r_C_E_F      1.0
+    r_C_H        0.0
+    r_D_G        1.0
+    Name: fluxes, dtype: float64
+
+## Model Creation
+
+The `model_creation` submodule contains functions for creating new
+models based on the results of iMAT. The main function is
+`generate_model`, which takes a model, and a series of reaction weights,
+and returns a new model with restrictions based on the iMAT results.
+
+The available methods for creating a model based on an iMAT flux
+distribution is:  
+- `imat_restrictions` Adds the binary variables and constraints used in
+the iMAT algorithm, as well as an additional constraint ensuring that
+the flux distribution is within tolerance of the optimal iMAT objective
+value. This method stays closest to the iMAT objective, but the included
+indicator (binary) variables mean that is unsuitable for sampling.
+
+- `simple_bounds` Adds bounds on the reactions found to be “on”, and
+  “off” in iMAT. For all the highly expressed reactions found to be
+  “on”, the flux is constrained to be at least `epsilon`. For all the
+  lowly expressed reactions found to be “off”, the flux is constrained
+  to be below `threshold`.
+
+- `subset` Removes reactions from the model which are found to be “off”.
+  For all the lowly expressed reactions found to be off, they are
+  constrained to have a flux below `threshold`.
+
+- `fva` Finds bounds using an FVA like approach. A temporary model is
+  created in a simmilar way to the
+
+- `imat_restrictions` method above, which includes the imat variables,
+  constraints, and which also constrains the flux distribution to be
+  near optimal for iMAT. The maximum and minimum fluxes allowed through
+  each reaction (while still maintaining the optimal iMAT objective) is
+  found. These values are used as the new reaction bounds. It should be
+  noted, that although the individual upper and lower bounds for the
+  reaction are achievable for each reation while being consistant with
+  the optimal iMAT objective, this doesn’t guarantee that the flux
+  distribution overall is consistant with the optimal iMAT objective.
+
+- `milp` Uses a set of mixed integer linear programs to find whether a
+  reaction should be forced off, forward, or reverse. Each reaction in
+  turn is forced to be off, active in the forward direction, and active
+  in the reverse direction, and the iMAT objective is maximized. Whether
+  a reaction should be forced off, or active in either the forward or
+  reverse direction is then determined by which direction maximizes the
+  iMAT objective. Again, it should be noted that this doesn’t guarantee
+  that the iMAT objective is overall maximized by solutions to this
+  model.
+
+Below is an example of how to generate a model with iMAT restrictions:
+
+``` python
+# External imports
+import pandas as pd
+
+# iMATpy imports
+from imatpy.model_utils import read_model
+from imatpy.model_creation import generate_model
+
+# Read in the model
+model = read_model("./tests/data/test_model.xml")
+
+# Read in the reaction weights
+rxn_weights = pd.read_csv("./tests/data/test_model_reaction_weights.csv", index_col=0).squeeze()
+
+# Generate a model with iMAT restrictions
+imat_model = generate_model(model=model, rxn_weights=rxn_weights, method="fva", epsilon=1, threshold=0.01)
+
+# This model can be used for sampling, finding optimal biomass generation, finding essential genes, etc.
+optimal_biomass = imat_model.slim_optimize()
+
+print(f"Optimal Biomass: {optimal_biomass}")
+```
+
+    Optimal Biomass: 50.0
+
+## Model Utils
+
+The `model_utils` submodule contains several utility functions for
+working with COBRApy models. Specifically, it contains functions for: -
+Reading and writing models in various formats with a single function,
+specifically `read_model`/`write_model`. - Determining if two models are
+equivalent, using `model_eq`.
+
+Here is an example of how to use the model IO methods:
+
+``` python
+# iMATpy imports
+from imatpy.model_utils import read_model, write_model, model_eq
+
+# You can read in a model from a file
+model = read_model("./tests/data/test_model.xml") # in SBML
+model = read_model("./tests/data/test_model.json") # in JSON
+model = read_model("./tests/data/test_model.yml") # in YAML
+model = read_model("./tests/data/test_model.mat") # in Matlab
+
+# You can also write a model to a file
+write_model(model, "./tests/data/test_model.xml") # in SBML
+write_model(model, "./tests/data/test_model.json") # in JSON
+write_model(model, "./tests/data/test_model.yml") # in YAML
+write_model(model, "./tests/data/test_model.mat") # in Matlab
+```
+
+Here is an example of using the model comparison method:
+
+``` python
+# iMATpy imports
+from imatpy.model_utils import read_model, model_eq
+
+# Read a model
+model = read_model("./tests/data/test_model.xml")
+
+# Create a copy of the model
+model_copy = model.copy()
+
+# Check that the models are equivalent
+print(f"Models are equivalent: {model_eq(model, model_copy)}")
+
+# Change the copy model
+model_copy.reactions.get_by_id("r_A_B_D_E").lower_bound = -314
+
+# Check that the models are no longer equivalent
+print(f"Models are equivalent: {model_eq(model, model_copy)}")
+```
+
+    Models are equivalent: True
+    Models are equivalent: False
+
+## License
+
+This package itself is relased under an MIT license. It makes use of
+several libraries which are listed below:  
+- COBRApy: Released under the LGPL-2.0-or-later license see
+[here](https://github.com/opencobra/cobrapy/blob/devel/LICENSE)  
+- Numpy: Released under the BSD-3-Clause license see
+[here](https://github.com/numpy/numpy/blob/main/LICENSE.txt)  
+- Optlang: Released under the Apache-2.0 lisence see
+[here](https://github.com/opencobra/optlang/blob/master/LICENSE)  
+- Pandas: Released under the BSD-3-Clause license see
+[here](https://github.com/pandas-dev/pandas/blob/main/LICENSE)  
+- Scipy: Released under the BSD-3-Clause license see
+[here](https://github.com/scipy/scipy/blob/main/LICENSE.txt)  
+- Sympy: Released under the BSD-3-Clause license see
+[here](https://github.com/sympy/sympy/blob/master/LICENSE)
+
+In addition, these libraries were used during developement:  
+- black: Used for autoformating  
+- jupyter: Used for rendering quarto documents - flake8: Used for
+linting - pytest: Used for running unittests  
+- Sphinx: Used for generating documentation  
+- sphinx-rtd-theme: Used for formating the documentation
+