pyPGA2

中文

pyPGA2 is a cross-platform Python implementation of PGA v2 for reference-based plastid genome annotation. It uses BLAST+ for similarity searches and implements input parsing, hit filtering, inverted-repeat detection, feature reconstruction, GenBank writing, and Perl/Python semantic comparison in Python.

The installed command is pga2.

Install

Requirements:

• Python 3.12 or newer
• uv
• BLAST+ executables: makeblastdb, blastn, and tblastn

uv sync
uv run pga2 --help

For an installed release, install the distribution with your preferred Python package manager and run the pga2 command directly:

uv tool install pyPGA2
pga2 --help

BLAST+ is not bundled with pyPGA2. Install it for your operating system, then either expose its executables through PATH or provide their directory with --blast-dir.

Reference Choice

-r accepts either a directory of reference GenBank files or one of two bundled aliases. Each alias selects one concrete plastome reference; neither is a general database of all plants in that group.

-r value	Bundled file	Organism	Accession	Length
ang	src/reference/angiosperms/Amborella_trichopoda.gb	Amborella trichopoda	AJ506156.2	162,686 bp
gym	src/reference/gymnosperms/Zamia_furfuracea.gb	Zamia furfuracea	JX416857.1	164,953 bp

Use a custom reference directory whenever a taxonomically closer plastome is available:

uv run pga2 -r path/to/reference_genbank -t path/to/targets

The aliases are useful starting points when running from this project source tree:

uv run pga2 -r ang -t targets
uv run pga2 -r gym -t targets

Target Input

-t accepts a directory containing FASTA or GenBank files. Extensions are case-insensitive.

Input	Processing
FASTA (.fa, .fas, .fasta, .fsa)	One target per file. For compatibility with PGA v2, a multi-record FASTA uses its final record.
GenBank (.gb, .gbf, .gbk, .genbank)	Every record is reannotated independently. Its sequence, meaningful record metadata, and source qualifiers are retained; its old feature table is replaced.

For GenBank reannotation, pyPGA2 transfers non-empty description, accession/version, keywords, source, organism, taxonomy, references, comments, database links, and source qualifiers. The new output topology is always controlled by --form.

BLAST Configuration

Executables are resolved independently in this order:

1. --blast-dir
2. PATH

For example:

export PATH="/opt/ncbi-blast/bin:$PATH"
uv run pga2 -r ang -t targets --preflight

$env:Path = "C:\Program Files\NCBI\blast-2.17.0+\bin;$env:Path"
uv run pga2 -r ang -t targets --preflight

uv run pga2 -r ang -t targets --blast-dir "C:\Program Files\NCBI\blast-2.17.0+\bin"

--blast-dir accepts both Windows .exe names and POSIX extensionless executable names.

Run

Validate reference, targets, and BLAST discovery without running searches:

uv run pga2 -r ang -t targets --preflight

Annotate and write GenBank results:

uv run pga2 -r ang -t targets -o results

An existing output directory is announced in the Rich terminal UI, then replaced atomically only after all target records complete successfully. A failed run leaves the old output untouched.

Parallel Execution

Parallel execution is a pyPGA2 innovation; PGA v2's Perl workflow processes these searches serially. pyPGA2 preserves the annotation and output semantics while exposing independent BLAST work safely.

At startup, pyPGA2 detects the number of logical processors. With at least four processors, every active target receives a fixed allocation of four BLAST slots: its four reference query groups and inverted-repeat self-search are scheduled through those slots, never exceeding four concurrent BLAST processes for that target. Target database construction remains a prerequisite, and annotation reconstruction and final writing remain ordered, so output is deterministic. On systems with fewer than four logical processors, a target remains serial.

--threads (-j) is the requested number of complete targets to annotate at once, not a BLAST thread count. pyPGA2 automatically clamps the request so that each active target keeps its four-process allocation. This is not an error or a warning: the terminal prints one INFO line when a request is reduced.

Logical processors	Requested --threads	Effective target concurrency	Per-target BLAST concurrency
12	3	3	4
10	3	2	4
4	2	1	4
3	3	3	serial

For example, on a 12-logical-processor machine, use three concurrent targets:

uv run pga2 -r ang -t targets -o results --threads 3

Measured Improvement

On a 12-logical-processor Windows machine, 12 FASTA targets were selected at equal intervals from a 79-sample plastome QC set and annotated with the bundled angiosperm reference. Pure serial execution took 173.43 s. The fixed four-slot design with --threads 3 took 61.40 s, a 2.82x speedup and a 64.6% reduction in elapsed time.

The two runs produced 12/12 GenBank files with zero semantic differences, identical SHA-256 hashes for every GenBank file, and an identical warning.log. The speedup therefore does not trade away PGA-compatible output.

pga2 annotate ... remains accepted for compatibility, but annotate is unnecessary.

Options

Option	Default	Meaning
-r, --reference	required	Reference GenBank directory, ang, or gym
-t, --target	required	Target FASTA or GenBank directory
-i, --ir	1000	Minimum inverted-repeat length in bp
-p, --pidentity	40	Legacy TBLASTN protein identity setting
-l, --link	Y	Link rps12 exons
-d, --redundancy	N	Retain redundant or pseudogene CDS candidates
-q, --qcoverage	0.5,2.0	Query-coverage warning and filtering range
-o, --out	gb	Output directory
-j, --threads	1	Requested concurrent target annotations; automatically capped to processor capacity
-f, --form	circular	Output topology
-w, --warning	warning	Warning-log prefix
--blast-dir	automatic	BLAST+ directory
--preflight	off	Validate and summarize without BLAST searches

For PGA v2 compatibility, --pidentity accepts a value but the effective threshold remains the Perl implementation's historical value of 40.

Development Validation

uv run pytest -q
uv run ruff check src tests

The optional Perl/Python parity runner compares GenBank semantics and warning logs using reference and target directories supplied by the caller:

uv run python tests/parity_runner.py --reference reference --target targets --matrix

Set PGA2_PERL_EXE to select a system Perl executable when it is not available on PATH.

Layout

src/          Production modules and bundled reference GenBank records
tests/        Self-contained unit and integration tests
validation/   Optional local BLAST, Perl, and comparison assets

License

pyPGA2 retains the GPL-3.0 license and credits the PGA v2.0 implementation by Xiao-Jian Qu.