Metadata-Version: 2.4
Name: ampliqc
Version: 0.1.0
Summary: ampliQC: Context-aware Quality Control (QC) engine specialized for Amplicon sequencing data (16S, 18S, ITS, functional amplicons - Short & Long Reads)
Author-email: Fabiano Menegidio <labiomics@bioinformatica.com.br>
Maintainer-email: Fabiano Menegidio <labiomics@bioinformatica.com.br>
License-Expression: MIT
Project-URL: Homepage, https://github.com/LaBiOmicS/ampliQC
Project-URL: Documentation, https://github.com/LaBiOmicS/ampliQC#readme
Project-URL: Repository, https://github.com/LaBiOmicS/ampliQC.git
Project-URL: Issues, https://github.com/LaBiOmicS/ampliQC/issues
Keywords: amplicon,ampliQC,quality-control,QC,16S,18S,ITS,microbiome,metabarcoding,DADA2,Cutadapt,Illumina,Nanopore,PacBio,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dnaio>=1.2.0
Requires-Dist: xopen>=2.0.0
Requires-Dist: pyfastx>=2.3.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: plotly>=5.14.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# ampliQC 🧬

**ampliQC** is a context-aware Quality Control (QC) engine specialized for **Amplicon Sequencing Data** (16S, 18S, ITS, and functional marker genes) across both **Short-Read (Illumina / MGI / Element)** and **Long-Read (PacBio HiFi / Oxford Nanopore)** platforms.

Unlike generic QC tools like FastQC or Falco—which evaluate amplicon reads against genome sequencing assumptions and trigger false warnings for high duplication rates or initial primer nucleotide composition—**ampliQC** evaluates sequencing quality **within the biological and technical context of amplicon libraries**.

---

## Key Features

- 🎯 **Amplicon-Aware Biological Evaluation**:
  - **16S / 18S / ITS & Custom Target Profiling**: Detects target regions (V1-V3, V3-V4, V4, V9, ITS1, ITS2, or Full-Length ~1.5kb).
  - **Primer Detection & Trimming Status**: Scans 5' and 3' ends for degenerate PCR primers (IUPAC codes) and assesses trimming state.
  - **Context-Aware Duplication Rate**: Distinguishes expected biological locus amplification from library bottleneck errors.
  - **Conserved Base Bias vs Body Composition**: Separates expected primer binding site bias from target sequence quality drops.
  - **Short vs Long-Read Profiling**: Supports Illumina (150-300bp) and PacBio HiFi / ONT Full-Length amplicons.
- ✂️ **Automatic Trimming & DADA2 Parameters**:
  - Generates ready-to-copy **Cutadapt** and **Chopper** CLI commands.
  - Calculates optimal **DADA2 / QIIME 2 truncation lengths** based on Phred quality decay and amplicon target overlap.
- 🚀 **Multi-Sample Parallel Batch Processing**:
  - Process an entire directory of FASTQ files in parallel via `ampliqc run-batch`.
  - Generates consolidated Multi-Sample **TSV summary matrices** and native **MultiQC JSON** files (`_ampliqc_mqc.json`).
- 🛠️ **Custom Primer Database Support**:
  - Load custom lab primer panels via `--primer-db custom_primers.yaml` or default `~/.config/ampliqc/primers.yaml`.

---

## Installation

```bash
pip install -e .
```

## Quick Start

```bash
# Analyze a 16S amplicon dataset (Paired-End Illumina V3-V4)
ampliqc run -1 sample_R1.fastq.gz -2 sample_R2.fastq.gz --context amplicon_16s -o qc_output/

# Analyze a Full-Length 16S dataset (PacBio HiFi / Oxford Nanopore Long-Read)
ampliqc run -1 sample_longreads.fastq.gz --context auto -o qc_output/

# Run multi-sample batch QC across a directory in parallel (4 threads)
ampliqc run-batch -i /path/to/fastq_dir/ -o batch_qc_output/ -t 4

# Specify custom forward and reverse primers or custom YAML database
ampliqc run -1 sample.fastq.gz --primer-f GTGYCAGCMGCCGCGGTAA --primer-r GGACTACNVGGGTWTCTAAT -o qc_output/
ampliqc run -1 sample.fastq.gz --primer-db lab_primers.yaml -o qc_output/
```
