pymgpipe 0.16.10
Community level microbiome metabolic modeling in Python
License: Apache-2.0
Requires Python: >=3

## [pymgpipe](https://korem-lab.github.io/pymgpipe/) | [![DOI](https://zenodo.org/badge/525586335.svg)](https://zenodo.org/badge/latestdoi/525586335) [![status](https://joss.theoj.org/papers/3f284f37987438428fd09ad3d5bd4871/status.svg)](https://joss.theoj.org/papers/3f284f37987438428fd09ad3d5bd4871) [![Python package](https://github.com/korem-lab/pymgpipe/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/korem-lab/pymgpipe/actions/workflows/python-package.yml) [![Tests](https://github.com/korem-lab/pymgpipe/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/korem-lab/pymgpipe/actions/workflows/tests.yml) [![Docs](https://github.com/korem-lab/pymgpipe/actions/workflows/docs.yml/badge.svg)](https://github.com/korem-lab/pymgpipe/actions/workflows/docs.yml) [![PyPI version](https://badge.fury.io/py/pymgpipe.svg)](https://badge.fury.io/py/pymgpipe)  
<!-- Pytest Coverage Comment:Begin -->
<a href="https://github.com/korem-lab/pymgpipe/blob/main/README.md"><img alt="Coverage" src="https://img.shields.io/badge/Coverage-77%25-yellow.svg" /></a><details><summary>Coverage Report </summary><table><tr><th>File</th><th>Stmts</th><th>Miss</th><th>Cover</th><th>Missing</th></tr><tbody><tr><td colspan="5"><b>pymgpipe</b></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/coupling.py">coupling.py</a></td><td>39</td><td>6</td><td>85%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/coupling.py#L20">20</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/coupling.py#L43">43</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/coupling.py#L46-L47">46&ndash;47</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/coupling.py#L52">52</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/coupling.py#L67">67</a></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py">diet.py</a></td><td>103</td><td>19</td><td>82%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L16">16</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L22">22</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L396-L397">396&ndash;397</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L437-L453">437&ndash;453</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L466-L477">466&ndash;477</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L482-L485">482&ndash;485</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L494">494</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L496">496</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/diet.py#L525">525</a></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py">fva.py</a></td><td>144</td><td>59</td><td>59%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L32">32</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L36">36</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L88-L92">88&ndash;92</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L98">98</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L107-L113">107&ndash;113</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L116-L117">116&ndash;117</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L120-L121">120&ndash;121</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L139-L149">139&ndash;149</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L165">165</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L174-L235">174&ndash;235</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/fva.py#L244">244</a></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py">io.py</a></td><td>106</td><td>37</td><td>65%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L17">17</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L55">55</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L61-L66">61&ndash;66</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L80-L81">80&ndash;81</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L95-L96">95&ndash;96</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L108">108</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L111">111</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L117-L120">117&ndash;120</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L125-L133">125&ndash;133</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L142">142</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L146-L147">146&ndash;147</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L152-L157">152&ndash;157</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L161-L167">161&ndash;167</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/io.py#L176-L177">176&ndash;177</a></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py">main.py</a></td><td>148</td><td>44</td><td>70%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py#L112">112</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py#L115">115</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py#L167">167</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py#L210-L212">210&ndash;212</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py#L243-L297">243&ndash;297</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py#L304">304</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py#L309-L310">309&ndash;310</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/main.py#L323">323</a></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/metrics.py">metrics.py</a></td><td>24</td><td>21</td><td>12%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/metrics.py#L5-L35">5&ndash;35</a></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/modeling.py">modeling.py</a></td><td>145</td><td>7</td><td>95%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/modeling.py#L36">36</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/modeling.py#L39">39</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/modeling.py#L54-L57">54&ndash;57</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/modeling.py#L129">129</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/modeling.py#L131">131</a></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/nmpc.py">nmpc.py</a></td><td>64</td><td>5</td><td>92%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/nmpc.py#L95">95</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/nmpc.py#L132-L134">132&ndash;134</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/nmpc.py#L136">136</a></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py">utils.py</a></td><td>235</td><td>107</td><td>54%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L45-L46">45&ndash;46</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L49">49</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L52">52</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L67">67</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L73">73</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L83">83</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L87">87</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L102-L105">102&ndash;105</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L111">111</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L115-L117">115&ndash;117</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L120-L138">120&ndash;138</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L142-L152">142&ndash;152</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L160">160</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L173-L174">173&ndash;174</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L176-L177">176&ndash;177</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L199-L200">199&ndash;200</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L205-L207">205&ndash;207</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L245-L248">245&ndash;248</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L250-L264">250&ndash;264</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L270">270</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L281-L286">281&ndash;286</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L289-L293">289&ndash;293</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L313-L314">313&ndash;314</a>, <a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/utils.py#L325-L367">325&ndash;367</a></td></tr><tr><td colspan="5"><b>pymgpipe/tests</b></td></tr><tr><td>&nbsp; &nbsp;<a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/tests/test_e2e.py">test_e2e.py</a></td><td>90</td><td>1</td><td>99%</td><td><a href="https://github.com/korem-lab/pymgpipe/blob/main/pymgpipe/tests/test_e2e.py#L197">197</a></td></tr><tr><td><b>TOTAL</b></td><td><b>1309</b></td><td><b>306</b></td><td><b>77%</b></td><td>&nbsp;</td></tr></tbody></table></details>
<!-- Pytest Coverage Comment:End -->

### API Docs
https://korem-lab.github.io/pymgpipe/

### Installation
**pympgipe** has been built and tested with python 3.10+. To install and use our PyPi package, run `pip install pymgpipe`

### Additional Dependencies
Need at least one of the following solvers (requirements.txt includes **gurobi**)-

-  [cplex](<https://www-01.ibm.com/software/commerce/optimization/cplex-optimizer/>)
-  [gurobipy](<http://www.gurobi.com>)

In order to install the solver interfaces in python, you can use `pip install cplex` or `pip install gurobipy`. This does not actually create a license, it just installs the python interface to interact with these solvers. Both gurobipy and cplex offer free academic licenses. To install the licenses themselves, refer to the links provided above.

### Inputs
To create multi-species community models with **pymgpipe**, you need two things to start-

-  Folder with individual taxa models (either in `.mat` or `.xml` format)
-  Relative abundance matrix (as a `.csv`) with samples as **columns** and taxa as **rows**. Taxa names should correspond to file names within taxa folder (excluding extension)

Examples of both can be found in the `examples/` folder. Individual models for thousands of bacteria can be found and downloaded [here](<https://www.vmh.life/#microbes/search>).

### Outputs
The exact location and names of output files will vary depending on the parameters you pass into each function. However, the default output for pymgpipe's **build_models** function will look something like this-

```

* pymgpipe input*
.
├── taxaModels/
│   ├── taxa1.xml
│   ├── taxa2.xml
│   └── ...
├── abundances.csv

# pymgpipe output*
.
├── out/
    ├── reaction_content.csv
    ├── reaction_abundance.csv
    ├── sample_label_conversion.csv
    ├── metabolic_diversity.png
    ├── problems/
    │   ├── mc1.mps.gz
    │   ├── mc2.mps.gz
    │   └── ...
    └── models/
        ├── mc1.xml.gz
        ├── mc2.xml.gz
        └── ...
```

Here is a breakdown of each output files/directory and their descriptions-

| File | Type | Description |  
|---|---|---|
| reaction_content | CSV | Matrix showing binary presence/absence of all reactions within each sample | 
| reaction_abundance | CSV | Matrix showing scaled abundance (between 0 and 1) of all reactions within each sample  |  
| sample_label_conversion | CSV | Dictionary with conversion between original sample names and model names (default `sample_prefix` is 'mc') | 
| metabolic_diversity | PNG | Plot depicting # of unique reactions & taxa present within each sample | 
| problems | dir | Directory containing LP problems (default format is .mps, with `compressed` set to True) |  
| models | dir | Directory containing COBRA moddels (default format is .xml, with `compressed` set to True) | 

### Examples
Clone and run through `workflow.ipynb` in the **examples/** folder (see below)

### Attribution

When using pymgpipe please cite-

Baldini, F., Heinken, A., Heirendt, L., Magnusdottir, S., Fleming, R. M. T., & Thiele, I. (2019). *The Microbiome Modeling Toolbox: from microbial interactions to personalized microbial communities.* Bioinformatics (Oxford, England), 35(13), 2332–2334. https://doi.org/10.1093/bioinformatics/bty941

### Contributing

We warmly welcome and appreciate contributions from everyone. There are several ways you can contribute:

- Reporting Bugs: If you find a bug, please create a new issue on our GitHub page. Be sure to include as much information as possible so we can reproduce and fix the bug. The more detail you provide, the better.
- Code Contributions: If you'd like to contribute code, great! Please fork this repository, make your changes in a separate branch, and then submit a pull request. We'll review your changes and discuss any necessary modifications or improvements before merging.

Here are some general guidelines for code contributions:

1. Fork the repo and create your branch from the master.
2. If you've added code, add tests.
3. Ensure the test suite passes.
4. Issue that pull request!

### Reporting Issues

Issues should be reported using the [GitHub issue tracker](https://github.com/korem-lab/pymgpipe/issues). Please check the existing issues to avoid duplicates. When reporting an issue, please provide as much detail as possible about how to reproduce the problem, including the following information:

- Operating system and version
- Details of the problem, including any error messages and screenshots if possible

Thank you for your contributions!

Copyright 2023 The Trustees of Columbia University in the City of New York. See [LICENSE](https://github.com/korem-lab/pymgpipe/blob/main/LICENSE) for additional details.