Metadata-Version: 2.4
Name: kegganog
Version: 1.6.2
Summary: A tool for generating KEGG heatmaps from eggNOG-mapper outputs.
Author-email: Ilia Popov <iljapopov17@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Ilia Popov
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/iliapopov17/KEGGaNOG
Requires-Python: <=3.16,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.9.0
Requires-Dist: matplotlib<=3.10.8,>=3.10.0
Requires-Dist: numpy<=2.4.0,>=2.2.0
Requires-Dist: pandas<=2.3.3,>=2.2.3
Requires-Dist: plotly<=6.5.0,>=5.24.1
Requires-Dist: pyparsing<=3.3.1,>=3.2.0
Requires-Dist: scipy<=1.16.3,>=1.14.1
Requires-Dist: seaborn<=0.13.2,>=0.13.2
Requires-Dist: tanglegram<=0.2.0,>=0.2.0
Requires-Dist: tqdm<=4.67.1,>=4.67.1
Requires-Dist: networkx<=3.6.1,>=3.4.2
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: requests<3,>=2.28.0
Requires-Dist: typer<1,>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Dynamic: license-file

# KEGGaNOG

![Python3](https://img.shields.io/badge/Language-Python3-steelblue)
![KEGG-Decoder](https://img.shields.io/badge/Dependecy-KEGG_Decoder-steelblue)
![License](https://img.shields.io/badge/License-MIT-steelblue)
[![codecov](https://codecov.io/gh/iliapopov17/KEGGaNOG/graph/badge.svg)](https://codecov.io/gh/iliapopov17/KEGGaNOG)

![Linux](https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black)
![macOS](https://img.shields.io/badge/mac%20os-000000?style=for-the-badge&logo=macos&logoColor=F0F0F0)

<br>
<br>

## Motivation

[**`eggNOG-mapper`**](https://github.com/eggnogdb/eggnog-mapper) 🤝 [**`KEGG-Decoder`**](https://github.com/bjtully/BioData/blob/master/KEGGDecoder/README.md)

- `eggNOG-mapper` is a comprehensive tool for fast functional annotation of novel sequences. Yet it does not provide any visualization functions.
- `KEGG-Decoder` is a perfect tool for visualizing KEGG Pathways. But it only takes `KEGG-Koala` outputs as an input (including blastKOALA, ghostKOALA, KOFAMSCAN).
- `KEGG-Koala` is a web-tool which can work for more than 24 hours. `eggNOG-mapper` can be installed locally on your PC / server and work faster.
- This tool `KEGGaNOG` makes `eggNOG-mapper` meet `KEGG-Decoder`! It parses `eggNOG-mapper` output, make it fit for the input to `KEGG-Decoder` and then visualize KEGG Pathways as the heatmap!
- **Pro-tip:** `eggNOG-mapper` and `KEGGaNOG` could be wrapped into 🐍 `Snakemake` pipeline making metabolic profiling a "one-click" process!

## Installation

```bash
# Linux / WSL / macOS
conda create -n kegganog pip -y
conda activate kegganog
pip install kegganog
```

## Usage Guide

### Command-line mode

```
Usage: KEGGaNOG [OPTIONS]                                                      
                                                                                
 KEGGaNOG: Link eggNOG-mapper and KEGG-Decoder for pathway visualization.       
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --input      -i              TEXT     Path to eggNOG-mapper annotation file. │
│ --output     -o              TEXT     Output folder to save results.         │
│ --multi      -M                       Run KEGGaNOG in multi mode with        │
│                                       multiple eggNOG-mapper annotation      │
│                                       files.                                 │
│ --overwrite  -overwrite               Overwrite the output directory if it   │
│                                       already exists.                        │
│ --dpi        -dpi            INTEGER  DPI for the output image.              │
│                                       [default: 300]                         │
│ --color      -c              TEXT     Cmap for seaborn heatmap.              │
│                                       [default: Blues]                       │
│ --name       -n              TEXT     Sample name for labeling.              │
│                                       [default: SAMPLE]                      │
│ --group      -g                       Group the heatmap based on predefined  │
│                                       categories.                            │
│ --web                                 Launch local web UI in browser at      │
│                                       http://localhost:8000.                 │
│ --version    -V                       Show version and exit.                 │
│ --help       -h                       Show this message and exit.            │
╰──────────────────────────────────────────────────────────────────────────────╯
```

🔗 Please visit [KEGGaNOG wiki](https://github.com/iliapopov17/KEGGaNOG/wiki) page


### Web interface mode

For an interactive, browser-based experience with live preview and advanced visualization options:

```bash
KEGGaNOG --web
```

Then open `http://localhost:8000` in your browser.

**Features:**
- **Live preview** — visualize plots in real-time as you adjust parameters
- **Interactive settings** — no command-line arguments needed; drop files, tweak colors and dimensions through an intuitive UI
- **Multi-sample analysis** — compare samples using heatmaps, radarplots, correlation networks, stacked bars, and streamgraphs
- **Re-render on the fly** — modify plot parameters without re-running the full analysis (multi mode only)
- **Download results** — export individual plots or the complete results ZIP

## Output examples gallery

**Default visualization**

|Single mode|Multi mode|
|-----------|----------|
|![heatmap_figure](https://github.com/user-attachments/assets/2b50518d-1fff-46d6-8bfc-6a5b8c31356d)|![heatmap_figure](https://github.com/user-attachments/assets/484077b9-8212-4aa2-8a3e-1a831afba26f)|

These figures are generated using functional groupping mode (`-g`/`--group`) and `Greens` colormap

**User APIs visualization**

|[Barplot](https://github.com/iliapopov17/KEGGaNOG/wiki/Barplot-API)|[Boxplot](https://github.com/iliapopov17/KEGGaNOG/wiki/Boxplot-API)|[Radarplot](https://github.com/iliapopov17/KEGGaNOG/wiki/Radarplot-API)|[Correlation Network](https://github.com/iliapopov17/KEGGaNOG/wiki/Correlation-Network-API)|
|-------|-------|---------|-------------------|
|![image](https://github.com/user-attachments/assets/81d69bef-f69c-4960-b2d3-73e348e3853a)|![image](https://github.com/user-attachments/assets/f98fd993-20b7-4b00-b203-83b40fe35f9c)|![image](https://github.com/user-attachments/assets/dd75e5d8-e3c8-4eaa-b009-02c042534a53)|![image](https://github.com/user-attachments/assets/e76057b9-bcfd-4ba9-a4cf-cb7b4269441a)|

|[Stacked Barplot](https://github.com/iliapopov17/KEGGaNOG/wiki/Stacked-Barplot-API)|[Streamgraph](https://github.com/iliapopov17/KEGGaNOG/wiki/Streamgraph-API)|[Stacked Barplot + Streamgraph](https://github.com/iliapopov17/KEGGaNOG/wiki/Combined-Stacked-Barplot-&-Streamgraph)|
|-------|-------|-------|
|![kgnstbar_OLD](https://github.com/user-attachments/assets/11e9e265-52c7-41b7-a284-64f3181caac3)|![kgnstream_OLD](https://github.com/user-attachments/assets/e82654fc-478a-4233-8478-f2c69ee4a1a6)|![combined_white_OLD](https://github.com/user-attachments/assets/6059da3c-4b74-47a2-af1c-427180f44845)|

## Advantages

1. **Seemless Access to KEGG Annotations:** Provides KEGG Ortholog (KO) annotations without requiring a KEGG license.
2. **High-Throughput Capability:** Optimized for rapid KO assignment in large-scale datasets, ideal for metagenomics and genomics projects.
3. **Broad Functional Coverage:** Leverages the extensive eggNOG database to annotate genes across a wide range of taxa.

## Limitation

1. **Indirect KO Mapping:** `eggNOG-mapper` doesn’t directly use the KEGG database, its KO term assignments are inferred through orthologous groups (eggNOG entries). This can sometimes result in less precise annotations.

## Tool name background

`KEGGaNOG` stands for “KEGG out of NOG”, highlighting its purpose: extracting KEGG Ortholog annotations from eggNOG’s Non-supervised Orthologous Groups.

## Contributing
Contributions are welcome! If you have any ideas, bug fixes, or enhancements, feel free to open an issue or submit a pull request.

## Contact
For any inquiries or support, feel free to contact me via [email](mailto:iljapopov17@gmail.com)

Happy functional annotation! 💻🧬

## Citation

If you use `KEGGaNOG` in your research, please cite:

[Popov, I.V., Chikindas, M.L., Venema, K., Ermakov, A.M. and Popov, I.V., 2025. 
KEGGaNOG: A Lightweight Tool for KEGG Module Profiling From Orthology-Based Annotations. 
Molecular Nutrition & Food Research, p.e70269.
doi.org/10.1002/mnfr.70269](https://onlinelibrary.wiley.com/share/author/QAEWYFJAQ6TAZGDW6FJZ?target=10.1002/mnfr.70269)

## Acknowledgements

For now `KEGGaNOG` uses [**`KEGG-Decoder`**](https://github.com/bjtully/BioData/blob/master/KEGGDecoder/KEGG_decoder.py) as a main dependecy. I greatly thank [**`KEGG-Decoder`**](https://github.com/bjtully/BioData/blob/master/KEGGDecoder/KEGG_decoder.py)'s developers.
