AMON-bio 1.1.0
Annotation of Metabolite Origin via Networks: A tool for predicting putative
License: MIT

# AMON
[![PyPI](https://img.shields.io/pypi/v/AMON-bio.svg?style=flat)](https://pypi.python.org/pypi/AMON-bio) ![Build Status](https://github.com/lozuponelab/AMON/actions/workflows/main.yaml/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.

#### 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

```
usage: amon.py [-h] -i GENE_SET -o OUTPUT_DIR [--detected_compounds DETECTED_COMPOUNDS] [--other_gene_set OTHER_GENE_SET] [--gene_set_name GENE_SET_NAME]
               [--other_gene_set_name OTHER_GENE_SET_NAME] [--keep_separated] [--samples_are_columns] [--detected_only] [--rn_compound_only] [--unique_only] [--save_entries]
               [--force-download-kegg]

options:
  -h, --help            show this help message and exit
  -i, --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
                        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)
  --gene_set_name GENE_SET_NAME
                        Name to use for first gene set (should have no spaces, underscore separated) (default: None)
  --other_gene_set_name OTHER_GENE_SET_NAME
                        Name to use for second gene set (should have no spaces, underscore separated) (default: None)
  --keep_separated      If input in biom or tabular format keep samples separate for analysis (default: False)
  --samples_are_columns
                        If data is in tabular format, by default genes are columns and samples rows, to indicate that samples are columns and genes are rows use this flag (default: False)
  --detected_only       only use detected compounds in enrichment analysis (default: False)
  --rn_compound_only    only use compounds with associated reactions (default: False)
  --unique_only         only use compounds that are unique to a sample in enrichment (default: False)
  --save_entries        Save json file of KEGG entries at all levels used in analysis for deeper analysis (default: False)
  --force-download-kegg
                        Re-download KEGG flat files from cloud (default: False)
```