Metadata-Version: 2.4
Name: MetaPont
Version: 0.1.0
Summary: Integrated analysis of metagenomic assembly, readmapping, Kraken2 and eggNOG-mapper outputs.
Author-email: Nicholas Dimonaco <nicholas@dimonaco.co.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/TheHuwsLab/MetaPont
Project-URL: Bug Tracker, https://github.com/TheHuwsLab/MetaPont/issues
Keywords: metagenomics,bioinformatics,genomics,Kraken2,eggNOG-mapper,readmapping
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: plots
Requires-Dist: matplotlib>=3.7; extra == "plots"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# MetaPont
**MetaPont**  - A tool to bridge the gap between the output of metagenomic tools and the analysis of the data

MetaPont is designed to work specifically with the output files generated by the HuwsLab Metagenome Workflow (github.com/TheHuwsLab/Metagenomic_Workflow) \
### Directory structure most follow the format generated by the workflow). 
```commandline
.
└── samples
    ├── E1.0
    │   ├── E1.0_eggnog_mapper
    │   │   ├── E1.0_eggnogmapper.success
    │   │   ├── E1.0_pyrodigal_eggnog_mapped.emapper.annotations
    │   │   ├── E1.0_pyrodigal_eggnog_mapped.emapper.annotations.xlsx
    │   │   ├── E1.0_pyrodigal_eggnog_mapped.emapper.decorated.gff
    │   │   ├── E1.0_pyrodigal_eggnog_mapped.emapper.hits
    │   │   └── E1.0_pyrodigal_eggnog_mapped.emapper.seed_orthologs
    │   ├── E1.0_kraken2
    │   │   ├── E1.0_kraken2_report_mpa.txt
    │   │   ├── E1.0_kraken2_report.txt
    │   │   └── E1.0_kraken2.txt
    │   └── E1.0_readmapped
    │       ├── E1.0_bowtie2_db.3.bt2
    │       ├── E1.0_readmapped_cds_summary.txt
    │       ├── E1.0_readmapped_cds_summary.txt_new
    │       └── E1.0_readmapped_contig_summary.txt
    ├── E2.0
    │   ├── E2.0_eggnog_mapper
    │   │   ├── E2.0_eggnogmapper.success
    │   │   ├── E2.0_pyrodigal_eggnog_mapped.emapper.annotations
    │   │   ├── E2.0_pyrodigal_eggnog_mapped.emapper.annotations.xlsx
    │   │   ├── E2.0_pyrodigal_eggnog_mapped.emapper.decorated.gff
    │   │   ├── E2.0_pyrodigal_eggnog_mapped.emapper.hits
    │   │   └── E2.0_pyrodigal_eggnog_mapped.emapper.seed_orthologs
    │   ├── E2.0_kraken2
    │   │   ├── E2.0_kraken2_report_mpa.txt
    │   │   ├── E2.0_kraken2_report.txt
    │   │   └── E2.0_kraken2.txt
    │   └── E2.0_readmapped
    │       ├── E2.0_bowtie2_db.3.bt2
    │       ├── E2.0_readmapped_cds_summary.txt
    │       └── E2.0_readmapped_contig_summary.txt
    ├── E3.0
    │   ├── E3.0_eggnog_mapper
    │   │   ├── E3.0_eggnogmapper.success
    │   │   ├── E3.0_pyrodigal_eggnog_mapped.emapper.annotations
    │   │   ├── E3.0_pyrodigal_eggnog_mapped.emapper.annotations.xlsx
    │   │   ├── E3.0_pyrodigal_eggnog_mapped.emapper.decorated.gff
    │   │   ├── E3.0_pyrodigal_eggnog_mapped.emapper.hits
    │   │   └── E3.0_pyrodigal_eggnog_mapped.emapper.seed_orthologs
    │   ├── E3.0_kraken2
    │   │   ├── E3.0_kraken2_report_mpa.txt
    │   │   ├── E3.0_kraken2_report.txt
    │   │   └── E3.0_kraken2.txt
    │   └── E3.0_readmapped
    │       ├── E3.0_readmapped_cds_summary.txt
    │       └── E3.0_readmapped_contig_summary.txt
    └── Per_Sample_Contig_Outputs
        ├── E1.0_Contigs.tsv
        ├── E2.0_Contigs.tsv
        └── E3.0_Contigs.tsv

```

## Features - These are the current aims of this project  - Still under development

- **Targeted Functional Analysis:** Search for specific functional IDs (e.g., GO terms) within the `_Final_Contig.tsv` files provided by the HuwsLab Metagenome Workflow (https://github.com/TheHuwsLab/Metagenome_Workflow) .
- **Taxonomic Breakdown:** Extract genus-level taxonomy information and calculate their proportions in the dataset.
- **Batch Processing:** Analyse all `_Contig.tsv` files in a specified directory.
- **Customisable Output:** Save results in a format suitable for downstream analysis.

---

## Installation

### Prerequisites

Ensure you have the following installed:

- Python ~3.10 or later

### Installation via pip

MetaPont is provided as a pip distribution. 

```bash
pip install MetaPont 
```

---

## Usage

--- 
### MetaPont-Combine (or metapont-combine) Aggregate results from emapper kraken and read mapping for each sample
```MetaPont-Combine -h```
```bash
usage: MetaPont_Combine.py [-h] -d PARENT_DIRECTORY_PATH [-p PREFIX]

MetaPont: Combine emapper-kraken-reads

options:
  -h, --help            show this help message and exit
  -d PARENT_DIRECTORY_PATH, --parent_directory_path PARENT_DIRECTORY_PATH
                        Directory containing sample directories to analyse.
  -p PREFIX, --prefix PREFIX
                        Default - 'PN': Default directory name prefix to
                        identify sample directories to analyse..
```
The output will be saved in a new directory called `Per_Sample_Contig_Outputs` within the specified parent directory. \
See [Per_Sample_Contig_Outputs](example_data/MetaPont_Combine/Per_Sample_Contig_Outputs) for example output files.

---
### Contig-Coverage-Summary: Generate contig coverage summary from read mapping outputs
```Contig-Coverage-Summary -h ```
```bash
usage: Contig_Coverage_Summary.py [-h] --root_dir ROOT_DIR --prefix PREFIX
                                  [--read-length READ_LENGTH]
                                  [--output OUTPUT]

MetaPont v0.0.9- Contig-Coverage-Summary: Aggregate readmapping contig
summaries and compute overview stats per sample.

options:
  -h, --help            show this help message and exit
  --root_dir ROOT_DIR, -d ROOT_DIR
                        Root directory containing sample folders (use
                        `root_dir` path).
  --prefix PREFIX, -p PREFIX
                        Comma-separated directory tags to search for (e.g.
                        E,L,P).
  --read-length READ_LENGTH, -r READ_LENGTH
                        Optional average read length to compute estimated
                        coverage.
  --output OUTPUT, -o OUTPUT
                        Output CSV path (default:
                        `root_dir/readmap_overview.csv`).

```
---
### Report-Contig-Lineage: Generate contig lineage report from kraken2 outputs
```Report-Contig-Lineage -h ```
```bash
usage: Report_Contig_Lineage.py [-h] -d DIR_PATH [--output OUTPUT]
                                [-s SEPARATE_TAXA] [-r REMOVE_TAXA]

MetaPont v0.0.9- Reporter-Contig-Lineage: Report contig lineage read counts
across samples, grouping by specified taxa substrings.

Required Arguments:
  -d DIR_PATH           Define the directory path containing the files

Optional Arguments:
  -s SEPARATE_TAXA, --separate-taxa SEPARATE_TAXA
                        Comma-separated list of taxa to separate (e.g.
                        d__Bacteria,d__Archaea). If omitted, defaults are
                        used.
  -r REMOVE_TAXA, --remove-taxa REMOVE_TAXA
                        Comma-separated list of taxa to remove. If omitted,
                        defaults are used.
```


### Extract-By-Function Command-line Arguments
```Extract-By-Function -h ``` 
```bash
usage: Extract_By_Function.py [-h] -d DIRECTORY -f FUNCTION_ID -o OUTPUT
                              [-m MIN_PROPORTION] [-top TOP_TAXA]

MetaPont v0.0.9: Extract-By-Function - Identify taxa contributing to a
specific function.

options:
  -h, --help            show this help message and exit
  -d DIRECTORY, --directory DIRECTORY
                        Directory containing TSV files to analyse.
  -f FUNCTION_ID, --function_id FUNCTION_ID
                        Specific function ID to search for (e.g.,
                        'GO:0016597').
  -o OUTPUT, --output OUTPUT
                        Output file to save results.
  -m MIN_PROPORTION, --min_proportion MIN_PROPORTION
                        Minimum proportion threshold for taxa to be included
                        in the output.
  -top TOP_TAXA, --top_taxa TOP_TAXA
                        Top n taxa to be included in the output.

```

The `Extract-By-Function` tool provides several command-line options: \
Note: Either -m or -top is required.

| Option                   | Description                                                | Required | Default |
|--------------------------|------------------------------------------------------------|----------|---------|
| `-d`, `--directory`      | Directory containing `_Final_Contig.tsv` files to analyse. | Yes      | None    |
| `-f`, `--function_id`    | Functional ID to search for (e.g., `GO:0016597`).          | Yes      | None    |
| `-m`, `--min_proportion` | Minimum proportion needed for reporting.                   | Yes/No   | None    |
| `-top`, `--top_taxa`     | Number of taxa to report.                                  | Yes/No   | None    |
| `-o`, `--output`         | Output file name to save results.                          | Yes      | None    |

### Example

To search for the functional ID `GO:0016597` in all `_Final_Contig.tsv` files within the `test_data/` directory:

```bash
Extract-By-Function -d .../test_data/Final_contig/ -f GO:0016597 -top 3 -o .../test_data/Final_Contig/Extract_By_Function_Out/results.tsv
```

---

## Output

The tool generates a tab-delimited output file with the following columns:

1. **Sample:** Name of the processed Sample.
2. **Taxa:** Genus-level taxonomic assignment extracted from the `Lineage` column.
3. **Reads Assigned (Function):** Number of reads assigned to contigs with the given functional ID.
3. **Proportion:** Proportion of reads assigned to contigs of stated Taxa with the given functional ID within the sample.
4. **Proportion (Total Reads):** Proportion of reads assigned to contigs of stated Taxa with the given functional ID within the total reads of the sample.

Example output:

```
Function ID: GO:0016597
Sample	Taxa	Reads Assigned (Function)	Proportion (Function)	Proportion (Total Reads)
PN0536_0001_S1_Final_Contig.tsv	Lactobacillus	111963	0.602	0.004
PN0536_0003_S83_Final_Contig.tsv	Lactobacillus	20072	0.457	0.001
PN0536_0002_S2_Final_Contig.tsv	Acutalibacter	145222	0.795	0.005
PN0536_0004_S3_Final_Contig.tsv	Lactobacillus	40076	0.404	0.002
```

---

# Extract-Function-By-Taxa:
```bash
usage: Extract_Function_By_Taxa.py [-h] -d DIRECTORY -t TAXON -f FUNCTION -o
                                   OUTPUT

MetaPont: Extract Reads Proportions for a Specific Taxon and Function

options:
  -h, --help            show this help message and exit
  -d DIRECTORY, --directory DIRECTORY
                        Directory containing TSV files to analyse.
  -t TAXON, --taxon TAXON
                        Target taxon to search for (e.g., 'g__Escherichia').
  -f FUNCTION, --function FUNCTION
                        Target function to extract (e.g., 'EC:2.7.11.1').
  -o OUTPUT, --output OUTPUT
                        Output file to save results.

```





### Workflow - unfinished

1. The script reads `_Final_Contig.tsv` files from the specified directory.
2. For each file, it searches for occurrences of the given functional ID within specific columns.
3. Matches are associated with genus-level taxonomic information extracted from the `Lineage` column.
4. Taxa proportions are calculated and saved to the output file.

---
## Extract-By-Taxa Command-line Arguments
```Extract-By-Taxa -h ``` 
```bash
usage: Extract_By_Taxa.py [-h] -d DIRECTORY -t TAXON -o OUTPUT -func
                          FUNCTIONAL_CLASSES [-top TOP_FUNCTIONS]

MetaPont: Extract Top Functions by Taxon

options:
  -h, --help            show this help message and exit
  -d DIRECTORY, --directory DIRECTORY
                        Directory containing TSV files to analyse.
  -t TAXON, --taxon TAXON
                        Target taxon to search for (e.g., 'g__Bacillus').
  -o OUTPUT, --output OUTPUT
                        Output file to save results.
  -func FUNCTIONAL_CLASSES, --functional_classes FUNCTIONAL_CLASSES
                        Which functional classes to report (e.g. GO,EC,KEGG
                        etc).
  -top TOP_FUNCTIONS, --top_functions TOP_FUNCTIONS
                        Top n functions to include in the output for each
                        sample (default: 3).

```

The `Extract-By-Taxa` tool provides several command-line options: 


| Option                            | Description                                                 | Required | Default |
|-----------------------------------|-------------------------------------------------------------|----------|---------|
| `-d`, `--directory`               | Directory containing `_Fincal_Contig.tsv` files to analyse. | Yes      | None    |
| `-t`, `--taxon`                   | Taxa to search for (e.g., `g__Bacillus`).                   | Yes      | None    |
| `-func`, `--functional_classes`   | Functional classes to report (e.g. GO,EC,KEGG etc).         | Yes      | None |
| `-top`, `--top_taxa`              | Number of functions to report (default 3).                  | No       | None    |
| `-o`, `--output`                  | Output file name to save results.                           | Yes      | None    |

### Example

To search for the top reported functions for taxon `g__Bacillus` in all `_Final_Contig.tsv` files within the `test_data/` directory:

```bash
Extract-By-Taxa -d .../test_data/Final_Contig -t g__Bacillus -o .../test_data/Final_Contig/Extract_By_Taxa/results.tsv  -func GO
```

---
## Output

The tool generates a tab-delimited output file with the following columns:

1. **Sample:** Name of the processed Sample.
2. **Function:** Reported 'top' function.
3. **Num of Assignments (Functions):** Number of times the function has been assigned across all contigs reported as chosen Taxon.

Example output:

```
Selected Taxon: g__Bacillus
Sample	Function	Num of Assignments
PN0536_0001_S1	GO:0008150	296
PN0536_0001_S1	GO:0003674	285
PN0536_0001_S1	GO:0005575	254
PN0536_0003_S83	GO:0005575	45
PN0536_0003_S83	GO:0008150	44
PN0536_0003_S83	GO:0003674	43
PN0536_0002_S2	GO:0005575	5
PN0536_0002_S2	GO:0008150	5
PN0536_0002_S2	GO:0005623	4
PN0536_0004_S3	GO:0008150	4
PN0536_0004_S3	GO:0003674	3
PN0536_0004_S3	GO:0005488	3

```

---

### Large File Handling (Might be a failure point)

The script uses `csv.field_size_limit` to handle exceptionally large `.tsv` files.

---


