gffkit 0.3.1

Region-aware GFF annotation integration toolkit

gffkit

gffkit is a lightweight toolkit for region-aware GFF/GTF annotation integration. It combines three utilities:

1. detect-bridge: detect suspicious merged-gene artifacts caused by bridge transcripts.
2. complement: complement/merge annotations, with optional region-swap mode.
3. add-utr: reconstruct five_prime_UTR and three_prime_UTR features from exon/CDS coordinates.

Installation

pip install gffkit

Quick start

Full integration pipeline

gffkit integrate \
  --annotation-a EviAnn.gff3 \
  --annotation-b ANNEVO.gff3 \
  --outdir gffkit_out \
  --prefix sample \
  -t 8

Outputs:

• gffkit_out/sample.suspicious.tsv
• gffkit_out/sample.merged.gff3
• gffkit_out/sample.final.withUTR.gff3

Step-by-step usage

# 1. Detect suspicious merged genes in Annotation A
gffkit detect-bridge -i EviAnn.gff3 -o suspicious.tsv -t 8

# 2. Use A as the global reference, but switch to B in suspicious regions
gffkit complement \
  --ref EviAnn.gff3 \
  --add ANNEVO.gff3 \
  --swap_region_tsv suspicious.tsv \
  --swap_region_flank 100 \
  --output merged.gff3 \
  -t 8

# 3. Add UTR features
gffkit add-utr -i merged.gff3 -o final.annotation.withUTR.gff3

Merge three or more annotations

Use repeated --add arguments. Files are merged in the order provided.

gffkit complement \
  --ref EviAnn.gff3 \
  --add ANNEVO.gff3 \
  --add Helixer.gff3 \
  --add PASA.gff3 \
  --output merged.multi.gff3 \
  -t 8

Command overview

gffkit --help
gffkit detect-bridge --help
gffkit complement --help
gffkit add-utr --help
gffkit integrate --help

Threads

Version 0.3 and later add -t/--threads.

• detect-bridge analyzes genes in parallel.
• complement pre-parses multiple --add files in parallel, then merges them in the original command-line order.
• integrate passes the thread count to the detect and complement steps.

Example:

gffkit integrate --annotation-a EviAnn.gff3 --annotation-b ANNEVO.gff3 -t 16

Annotation integration strategy

• Annotation A, for example EviAnn/RNA-seq-supported GFF, is used as the global primary reference.
• Annotation B, for example ANNEVO/deep-learning GFF, is used as the local primary reference only in suspicious merged-gene regions.
• UTR features are reconstructed after merging using an exon-minus-CDS strategy.
• When multiple tools annotate the same gene locus, the GFF source column is combined with |, for example EviAnn|ANNEVO.

Maintainer notes

When command-line options or behavior changes, update this README.md in the versioned package directory before building and uploading to PyPI.

License

MIT License.