Metadata-Version: 2.1
Name: AMON-bio
Version: 1.0.3
Summary: Annotation of Metabolite Origin via Networks: A tool for predicting putative metabolite origins formicrobes or between microbes and host with or without metabolomics data
Home-page: https://github.com/lozuponelab/AMON/
Download-URL: https://github.com/lozuponelab/AMON/tarball/1.0.3
Author: Michael Shaffer, Kumar Thurimella
Author-email: lozuponelab.dev@olucdenver.onmicrosoft.com
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scipy
Requires-Dist: biom-format
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: statsmodels
Requires-Dist: numpy
Requires-Dist: aiohttp
Requires-Dist: seaborn
Requires-Dist: matplotlib-venn
Requires-Dist: KEGG-parser

# AMON
[![PyPI](https://img.shields.io/pypi/v/KEGG-parser.svg?style=flat)](https://pypi.python.org/pypi/AMON-bio) ![Build Status](https://github.com/lozuponelab/AMON/actions/workflows/main.yml/badge.svg)

A command line tool for predicting the compounds produced by microbes and the host.

## Installation
It is recommended to install AMON in a conda environment. The environment can be created by first downloading the environment file.
```bash
wget https://raw.githubusercontent.com/shafferm/AMON/master/environment.yaml
```

Then create a new conda environment. Using the environment file and activate it.
```bash
conda env create -f environment.yaml -n AMON
conda activate AMON
```

Then it can be installed via pip.
```bash
pip install AMON-bio
```

### Alternative installation
Alternatively AMON can be installed from pip directly.
```bash
pip install AMON-bio
```

## Running AMON
AMON includes two scripts. `extract_ko_genome_from_organism.py` takes a KEGG organism flat file and makes a list of KOs present in that file. `AMON.py` predicts the metabolites that could be produced by the KOs used as input. This can be compared to the KOs present in the host or from some other gene set as well as to as set of KEGG metabolites.

### `extract_ko_genome_from_organism.py`
A simple script. Takes a download of an organism file from KEGG or a KEGG organism ID and outputs a new line separate list of KOs present in that file.
```
extract_ko_genome_from_organism.py --help
usage: extract_ko_genome_from_organism.py [-h] -i INPUT -o OUTPUT
                                          [--from_flat_file]

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        KEGG organism identifier or KEGG organism flat file
                        (default: None)
  -o OUTPUT, --output OUTPUT
                        Output file of new line separated list of KOs from
                        genome (default: None)
  --from_flat_file      Indicates that input is a flat flile to be parsered
                        directly (default: False)
```

### `AMON.py`
The full script to preform an analysis of possible metabolites originating from the list of KOs. From this as well as optional lists of compounds detected via metabolomics and lists of KOs present in a host or other environment a table of possible origin of compounds can be generated. From the list of compounds that could possibly be generated a pathway enrichment is also done with the hypergeometric test. Also if either of the other lists are included a Venn diagram will be generated representing the compounds which can be produced or where measured between the lists. If both the bacterial and host KOs are given a heatmap of pathway enrichments will be generated as well and in the enrichment test only compounds which are predicted to be uniquely generated by the bacteria or the host will be used.

#### Inputs

The `gene_set` parameter is a list that can be in the form of a plain text file that is a white space separated list of KO ids, a tsv or csv where the column labels are KO ids or a biom formatted file where the observation ids are KO ids. These are the KOs that will be used to determine the compounds that could be generated by the bacterial community. This and the output directory where all results will be written are the only required requirements. There are two other optional inputs: `detected_compounds` and `other_gene_set`. `detected_compounds` is a set of compounds that where detected in metabolomics of the sample and can come in any of the forms available for the input. `other_gene_set` is a set of KO ids that are encoded by the host or another set of genes that can be expressed as KO ids. This can also take any of the forms available to the  input parameter.

Two flags are available that will affect the Venn diagram made and the enrichment analysis that is done. `detected_only` will only include compounds that were detected as the background set of compounds for the hypergeometric test. This flag requires the `compound_detected` variable to be used. The `rn_compound_only` flag makes it so that only detected compounds which have a reaction associated with them in KEGG will be used for both the Venn diagram and the hypergeometric test.

Finally a set of locations for KEGG FTP downloaded files is avaliable. These inputs are optional and if they are not provided the KEGG API will be used to retrieve the records necessary. It is much faster to run with the KEGG FTP downloaded files if you have access to them.

**NOTE: the KEGG API has limits. It is currently past the limits of the KEGG API to require all inputs to be pulled from the KEGG API with a reasonably sized data set. This is something I am working on and if you have any suggestions for how to work within these limits please create an issue or pull request with a fix.**

#### Outputs

All outputs are written to the `output` directory. If only the `input` parameter is given then two files will be generated called origin_table.tsv, kegg_mapper.tsv and bacteria_enrichment.tsv. The origin_table.tsv has rows as the compounds that could be generated and the first column is true or false indicating if the bacterial KOs provided could generate this KO. If the `other_gene_set` input is provided an additional column will be generated in this table with true/false values indicating if this set of KOs could generate these compounds. If the `detected_compounds` parameter is given then an additional column with true/false values indicating whether or not this compound was generated is added.

To visualize the compounds predicted to be produced by microbiome as well as optionally the host and measured compounds the kegg_mapper.tsv file can used. This file can be used as input [here](https://www.genome.jp/kegg/tool/map_pathway2.html). This will color the detected compounds. Blue compounds are generated only by the microbiome and yellow are generated only by the host. Yellow compounds could have been generated by both. Compounds that were detected have an orange outline, with a light orange fill if that compound was not predicted to be produced by microbiome or host.

The bacteria_enrichment.tsv file, and the host_enrichment.tsv file if the `other_gene_set` parameter is given, gives the results of the pathway enrichment analysis from the compounds able to be produced by the KOs provided. When the `other_gene_set` parameter is given a heatmap is made to compare the significant pathways present from the bacteria and host KO lists.

When the `other_gene_set` and/or `detected_compounds` parameters are given a venn diagram will be made to see overlap in compounds possibly generated or detected.

#### Full help
```
amon.py --help
usage: amon.py [-h] -i GENE_SET -o OUTPUT_DIR
               [--detected_compounds DETECTED_COMPOUNDS]
               [--other_gene_set OTHER_GENE_SET] [--detected_only]
               [--rn_compound_only] [--ko_file_loc KO_FILE_LOC]
               [--rn_file_loc RN_FILE_LOC] [--co_file_loc CO_FILE_LOC]
               [--pathway_file_loc PATHWAY_FILE_LOC] [--save_entries]
               [--verbose]

optional arguments:
  -h, --help            show this help message and exit
  -i GENE_SET, --gene_set GENE_SET
                        KEGG KO's from bacterial community or organism of
                        interest in the form of a white space separated list,
                        a tsv or csv with KO ids as column names or a biom
                        file with KO ids as observations (default: None)
  -o OUTPUT_DIR, --output_dir OUTPUT_DIR
                        directory to store output (default: None)
  --detected_compounds DETECTED_COMPOUNDS
                        list of compounds detected via metabolomics (default:
                        None)
  --other_gene_set OTHER_GENE_SET
                        white space separated list of KEGG KO's from the host,
                        another organism or other environment (default: None)
  --detected_only       only use detected compounds in enrichment analysis
                        (default: False)
  --rn_compound_only    only use compounds with associated reactions (default:
                        False)
  --ko_file_loc KO_FILE_LOC
                        Location of ko file from KEGG FTP download (default:
                        None)
  --rn_file_loc RN_FILE_LOC
                        Location of reaction file from KEGG FTP download
                        (default: None)
  --co_file_loc CO_FILE_LOC
                        Location of compound file from KEGG FTP download
                        (default: None)
  --pathway_file_loc PATHWAY_FILE_LOC
                        Location of pathway file from KEGG FTP download
                        (default: None)
  --save_entries        Save json file of KEGG entries at all levels used in
                        analysis for deeper analysis (default: False)
  --verbose             verbose output (default: False)

```
