PoreSignalExtractor

PoreSignalExtractor is a modular Python pipeline designed to extract raw picoampere (pA) signal from Oxford Nanopore Technologies (ONT) POD5 files and map it to genomic coordinates.

Supported Alignment Engines

Supports 4 different extraction modes, depending on the upstream mapping/basecalling tool used:

1. moves: Uses Dorado's implicit alignment (via mv and ts tags in the BAM file).
2. unc-ref: Uses uncalled4 convert --eventalign-out TSV mapping after ref-based resquiggling.
3. unc-self: Uses uncalled4 convert --eventalign-out TSV mapping after self resquiggling.
4. f5c-self: Uses f5c resquiggle TSV mapping after self resquiggling.

---

Usage

The pipeline is executed via the run_extract.py entry point, followed by the desired extraction subcommand.

1. Dorado Moves Extraction (moves)

Extracts signal using Dorado basecaller's implicit alignment via mv and ts tags. Parallelizes across genomic chunks.

python run_extract.py moves \
    --bam mapped_reads.bam \
    --pod5 /path/to/pod5_dir/ \
    --output out_moves.tsv \
    --ref genome.fasta \
    --threads 16 \
    --bed target_regions.bed

2. Uncalled4 Reference Eventalign (unc-ref)

Extracts signal using the TSV generated by uncalled4 convert --eventalign-out after reference-based resquiggling.

python run_extract.py unc-ref \
    --map uncalled4_eventalign.tsv \
    --pod5 /path/to/pod5_dir/ \
    --output out_uncref.tsv \
    --threads 16 \
    --bed target_regions.bed

3. Uncalled4 Self Alignment (unc-self)

Extracts signal using the TSV generated by uncalled4 convert --eventalign-out after read-based resquiggling.

python run_extract.py unc-self \
    --bam uncalled4_self.bam \
    --self-tsv uncalled_eventalign_self.tsv \
    --pod5 /path/to/pod5_dir/ \
    --output out_uncself.tsv \
    --bed target_regions.bed \
    --threads 16

4. F5C Event Alignment (f5c-self)

Extracts signal using the TSV file generated by f5c resquiggle.

python run_extract.py f5c-self \
    --bam f5c_mapped.bam \
    --fasta genome.fasta \
    --pod5 /path/to/pod5_dir/ \
    --output out_f5c.tsv \
    --bed target_regions.bed \
    --threads 16

Output Format

All modules output a standardized TSV file. The structure is designed to be easily parsed.

The output columns are as follows:

Column	Description
read_id	The unique UUID of the Nanopore read.
contig	Reference chromosome or contig (e.g., chr1).
position	0-based genomic coordinate of the aligned signal.
ref_kmer	Reference sequence context (K-mer) at this position. Will be N or . if not applicable.
read_kmer	Read sequence context (K-mer) at this position. Will be N or . if not applicable.
samples_pA	Comma-separated list of calibrated raw signal samples (in picoamperes).