- The paper introduces PyPeakRankR, a deterministic and extensible tool that decouples feature extraction from ranking in regulatory genomics.
- The paper details a modular, table-first pipeline that integrates BigWig summaries, GC content, evolutionary conservation, statistical moments, and cell-type specificity scores.
- The paper demonstrates enhanced cross-species and cell-type specificity, achieving on-target efficacy above 70% and supporting robust enhancer discovery.
PyPeakRankR: Standardized, Deterministic Feature Extraction for Regulatory Element Ranking
Motivation and Problem Statement
High-throughput chromatin accessibility assays such as ATAC-seq generate vast collections of candidate regulatory elements, but prioritization of these peaks for experimental validation remains technically fragmented. Existing pipelines are commonly ad hoc, lack reproducibility, and impede systematic benchmarking across laboratories or projects due to non-standardized feature definitions, inconsistent aggregation logic, and limited extensibility. Most established tools, including MACS2, ArchR, and GREAT, only address isolated facets of the peak ranking workflow, lacking a unified and portable framework for reproducible peak-level feature extraction. This gap impacts large-scale functional genomics, single-cell ATAC-seq analyses, and enhancer discovery pipelines, particularly in multiplexed or cross-species settings.
PyPeakRankR: Design Principles and Methodology
PyPeakRankR is introduced as a highly modular, open-source Python package enabling reproducible assembly of peak-level feature matrices for regulatory genomics applications (2606.18179). The tool implements a "table-first" pipeline, emphasizing deterministic augmentation of a core peak-by-feature TSV matrix. Each processing step appends new feature columns without modifying peak coordinates or prior columns, while supporting user-defined extensions and incremental analysis. This architecture ensures that the extraction of quantitative features is fully decoupled and reproducible, facilitating downstream benchmarking and transparent ranking protocol development.
A central design feature is the strict separation of deterministic feature extraction from all ranking logic. This makes feature tables portable and agnostic with respect to ranking criteria, enabling rigorous comparative evaluation of prioritization algorithms on fixed input matrices. The ranking subcommand reproduces the cell-type specificity score previously validated in community benchmarks, normalizing the ratio of target group to mean background signal into [0, 1].
Both a command-line interface and a Python API are provided, with full parity, ensuring integration in heterogeneous computing environments including shell pipelines and interactive Python notebooks.
Feature Set and Biological Rationale
PyPeakRankR aggregates and quantifies several biologically salient features at the peak level:
- BigWig signal summaries: Quantitative signal across each peak extracted from BigWig files.
- GC content: Base composition, reflecting nucleosome occupancy, with known functional differences between enhancers and other genomic elements.
- PhyloP conservation: Measures of evolutionary constraint across species, capturing regulatory elements under purifying selection.
- Distribution moments (kurtosis, skewness, bimodality): Higher-order statistics of peak signal distribution, enabling discrimination of enhancers from promoters beyond simple intensity metrics, motivated by shape-driven models as in DELTA.
- Cell-type specificity rankings: Ratio-based specificity metric, validated in cross-study settings, for selecting cell-type-restricted elements.
- Cross-assembly scoring: Integration with liftOver enables direct comparison across genome assemblies and species, supporting translational and comparative genomics.
The table-first architecture provides direct extensibility to additional columns, such as sequence model importance scores from deep learning models (e.g., Borzoi, Enformer) or spatially-resolved epigenomic scores, allowing rapid incorporation of emerging modalities.
Implementation Details
The package is implemented in Python (≥3.9), leveraging pandas for tabular data manipulations, NumPy for numerical operations, pyBigWig for fast signal extraction, pyfaidx for efficient sequence access, and SciPy for statistical moments. It is distributed under the MIT license and is installable via pip from a public GitHub repository, with comprehensive unit testing and example datasets.
Every API subcommand is mirrored as a public Python function, ensuring feature parity and prohibiting logic divergence between CLI and programmatic usage.
Validation and Empirical Results
PyPeakRankR generalizes and extends the PeakRankR package (R implementation), which was independently validated as one of the top three peak prioritization strategies (out of sixteen evaluated) in the BICCN community challenge for cell-type-specific enhancer prediction in the mammalian cortex. Notably, the PeakRankR approach provided robust performance using only a minimal feature set, while PyPeakRankR broadens the feature landscape and integrates seamlessly in Python-centric genomics workflows.
In cross-species applications, integration into the Cross-species Enhancer Ranking Pipeline (CERP) enabled systematic enhancer-AAV tool design for basal ganglia cell types in both mouse and macaque. The toolkit outperformed conventional fold-change-based ranking, achieving on-target cell-type specificity exceeding 70% — with select elements above 90% — directly supporting the experimental efficacy of the approach.
Practical and Theoretical Implications
PyPeakRankR provides an essential step toward standardizing reproducible, deterministic, and extensible feature extraction for regulatory genomics, removing the bottleneck of inconsistent peak-level feature engineering. The orthogonality of extraction and ranking empowers the genomics community to benchmark and refine prioritization strategies transparently, while the extensibility to cell-type, species, and model-derived sequence features enables integration with rapidly evolving computational genomics models.
On the theoretical front, this modularization structurally decouples feature space definition from performance benchmarking, consolidating regulatory candidate ranking protocols. Practically, it has direct impact on the design and experimental evaluation of enhancer-driven tools, such as enhancer-AAV constructs in cell-type-targeted neuroscience, and supports methods development for both bulk and single-cell epigenome datasets in diverse organisms.
Future extensions could include more advanced sequence-based models, spatial genomics features, and integration with graph-based representations of chromatin interactions.
Conclusion
PyPeakRankR is a robust, reproducible, and extensible Python package for standardized feature extraction and peak-level ranking in regulatory genomics. By unifying signal-based, evolutionary, sequence, and statistical features in a well-engineered table-first framework, it establishes a reproducible substrate for downstream benchmarking and integration with modern genomics and gene regulation toolchains. Its demonstrated empirical efficacy and flexible architecture uniquely position it to facilitate ongoing advances in regulatory element discovery and functional genomics.