Metadata-Version: 2.4
Name: eccfp
Version: 1.1.3
Summary: ECCFP - EccDNA Caller based on Consecutive Full Pass
Home-page: 
Author: Li Wang, Zhang Tangxuan
Author-email: 
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0.0,>=1.21.0
Requires-Dist: pandas<3.0.0,>=2.0.0
Requires-Dist: pyfaidx>=0.6.0
Requires-Dist: pyfastx>=1.0.0
Requires-Dist: biopython>=1.79
Requires-Dist: rich>=12.0.0
Requires-Dist: numba>=0.58.0
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ECCFP - EccDNA Caller based on Consecutive Full Pass
A software package for identifying eccDNAs in the ONT sequencing data of RCA-amplified eccDNA
## Introduction
A new bioinformatics pipeline called ECCFP has been developed to improve the detection of extrachromosomal circular DNA (eccDNA) from long-read sequencing data. ECCFP uses all consecutive full passes from individual reads for candidate eccDNA identification and consolidates candidate eccDNAs to generate accurate unique eccDNA. To thoroughly evaluate the performance of ECCFP, 6 simulated datasets, 2 real sequencing datasets with spiked-in artificial synthesized eccDNAs and 29 publicly available real sequencing datasets, were applied. The results demonstrate that ECCFP markedly reduces the false positive rate, significantly increases the number of unique eccDNAs detection, achieves higher accuracy in identifying junction positions and circular consensus sequences, and also shortens the runtime, when compared to other three eccDNA analysis pipelines.  
[![ECCFP: ImetaOmics](https://img.shields.io/badge/DOI-10.1002/imo2.70080-blue)](https://doi.org/10.1002/imo2.70080)
[![ECCFP: Bio-protocol](https://img.shields.io/badge/DOI-10.2176/BioProtoc.5636-blue)](https://doi.org/10.21769/BioProtoc.5636)  
|![ECCFP](./images/Image.png)|
|:---------------------------------------:|
#### Reference
ECCFP is optimized from the [Flec](https://github.com/icebert/eccDNA_RCA_nanopore.git) software.
- [eccDNA_RCA_nanopore](https://github.com/icebert/eccDNA_RCA_nanopore.git)
- [minimap2](https://github.com/lh3/minimap2/)
#### Dependency (python packages)
- [numpy](https://numpy.org/)
- [pandas](https://pandas.pydata.org/)
- [pyfaidx](https://pypi.org/project/pyfaidx/)
- [pyfastx](https://pypi.org/project/pyfastx/)
- [Biopython](https://biopython.org)
## Installation
```
git clone https://github.com/WSG-Lab/ECCFP.git
cd ECCFP
conda env create --file environment.yml -y
conda activate ECCFP
pip install -e .

# Verify installation and display help message
eccfp --help
```
## Usage
#### simple usage
```
eccfp --fastq input.fastq --paf mapping.paf --reference ref.fa -o output
```
#### Parameter
```
usage: eccfp [-h] [-v] [--verbose] --fastq FASTQ --paf PAF --reference REFERENCE [--output OUTPUT] [--max-offset MAXOFFSET]
             [--min-map-qual MINMAPQUAL] [--fluctuate FLUCTUATE] [--min-fullpass NF] [--min-coverage COV] [--min-candidates NC]
             [--min-depth MINDP] [--min-allele-freq MINAF] [-t NUM_WORKERS] [--batch-size BATCH_SIZE]

ECCFP: EccDNA Caller based on Consecutive Full Pass

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  --verbose             Show detailed debug logs

Input files:
  --fastq FASTQ         Input FASTQ format reads file
  --paf PAF             Input PAF format alignment file
  --reference REFERENCE
                        Reference genome FASTA format file
  --output OUTPUT, -o OUTPUT
                        Output directory, default is current directory (default: .)

PAF filtering:
  --max-offset MAXOFFSET
                        Maximum offset between the start/end positions of two sub-reads (default: 20)
  --min-map-qual MINMAPQUAL
                        Minimum mapping quality of a sub-read (default: 30)

Candidate eccDNA refinement:
  --fluctuate FLUCTUATE
                        Maximum offset of candidate eccDNAs within the same group (default: 20)
  --min-fullpass NF, -nf NF
                        Minimum number of fullpass reads supporting a candidate eccDNA (default: 2)
  --min-coverage COV, -cov COV
                        Minimum fullpass count for merging candidate eccDNAs (default: 1)
  --min-candidates NC, -nc NC
                        Minimum number of candidate eccDNAs (default: 2)

Consensus sequence and variant detection:
  --min-depth MINDP, --minDP MINDP
                        Minimum depth for variant detection (default: 4)
  --min-allele-freq MINAF, --minAF MINAF
                        Minimum allele frequency for variant detection (default: 0.75)

Performance control:
  -t NUM_WORKERS, --threads NUM_WORKERS, --workers NUM_WORKERS
                        Number of parallel processes, 0 means auto-detect (cpu_count - 1, current machine: 31)
  --batch-size BATCH_SIZE
                        Phase 1 batch size, 0 means auto-calculate (recommended for current machine: 14000) (default: 0)

Examples:
  eccfp --fastq reads.fastq --paf mapping.paf --reference ref.fa -o output/
  
```
#### Example
```
cd example
minimap2 -cx map-ont ref.fa example.fastq --secondary=no -t 8 -o mapping.paf
eccfp --fastq example.fastq --paf mapping.paf --reference ref.fa -o output
```
## Output
Five files are generated following the completion of the pipeline: unit.txt and candidate_consolidated.txt(intermediate files), final_eccDNA.txt, consensus_sequence.fasta, and variant.txt (result files).   
|<div style="width: 150pt">file|<div style="width: 300pt">details|
|----|-------|  
|unit.txt|full pass alignment details for all candidate eccDNAs detected in reads|
|candidate_consolidated.txt|the consolidating steps used to derive accurate eccDNAs from the candidate eccDNAs|
|final_eccDNA.txt|accurate eccDNA information|
|consensus_sequence.fasta|the consensus sequences of accurate eccDNAs|
|variants.txt|variant profiles specific to these accurate eccDNAs|

###### Example final_eccDNA.txt file
|eccDNApos|Nfullpass|Nfragments|Nreads|refLength|seqLength|
|---------|---------|----------|------|---------|---------|
|chr16:757924-758274(+)|4|1|1|351|350|
|chr1:21828265-21828439(+)\|chr7:132167689-132167880(+)|24|2|2|367|367|

|<div style="width: 150pt">|<div style="width: 300pt">description|
|---------|---------------|
|eccDNApos|eccDNA position|
|Nfullpass|Number of consecutive full pass for this eccDNA covered by all reads|
|Nfragments|Number of fragment that form this eccDNA|
|Nreads|Number of reads identified for the eccDNA|
|refLength|The length of reference genome that this eccDNA |
|seqLength|The length of consensus sequence that this eccDNA |

###### variants.txt file
|<div style="width: 150pt">|<div style="width: 300pt">description|
|-------|-------|
|col1|chromsome|
|col2|position in the reference genome|
|col3|reference base|
|col4|variant|
|col5|supportive coverage depth|
|col6|total coverage depth|
|col7|type|
|col8|eccDNApos|

## Citation
- **Primary publication (iMetaOmics, 2026):** 
> Li, W., Miao, B., Zhang, J., Zeng, Q., Zhang, T., Wu, Z., Song, Y., Li, M., Guo, L., Luo, J., Xu, J., Liu, T., Chen, S., Gu, J. and Wan, S. (2026), ECCFP: A consecutive full pass-based bioinformatic analysis for eccDNA identification from long-read sequencing data. *iMetaOmics* e70080. https://doi.org/10.1002/imo2.70080
- **Protocol (Bio-protocol, 2026):**
> Li, W., Miao, B. and Wan, S. (2026). A Bioinformatics Workflow to Identify eccDNA Using ECCFP From Long-Read Nanopore Sequencing Data. *Bio-protocol* 16(6): e5636. DOI: 10.21769/BioProtoc.5636.
