PyFgsea: GSEA in Python and Rust

Abstract

PyFgsea 0.2.0 Release date: 2026-09-02. PyFgsea 0.2.0 updates the statistical core used by the high-level Python API and narrows the trajectory interface to functions that are implemented and tested. The paper remains reproducible with its original software pair; current comparisons use a separate, newer reference pair. Highlights mode="aligned" and score_type="std" are the high-level defaults. Aligned mode uses exact pathway sizes (bin_width=0). Gene-ID ordering makes tied ranks deterministic. Unresolved and failed pathways remain visible in the result table. Results include tail-depth, error, termination, approximation, pathway-size, ranking, and algorithm-revision fields. The supported trajectory API is run_trajectory_gsea; unfinished public helpers and the incomplete trajectory CLI have been removed. DPT computation requires an explicit root and preserves root identity when cells are filtered or subsetted. The low-level build_tail_curve and query_tail_curve helpers remain available but are deprecated. They implement the approximate legacy-empirical-tail-v1 method, not the aligned estimator. Reference comparisons The two reference lanes answer different questions and should not be pooled: | Lane | PyFgsea | R | Bioconductor | fgsea | Purpose | | --- | --- | --- | --- | --- | --- | | publication | 0.1.4 | 4.4.3 | 3.20 | 1.32.2 | reproduce the comparison reported in the paper | | current | 0.2.0 | 4.6.0 | 3.23 | 1.38.0 | evaluate the current implementation | On the 100-pathway publication input, the publication lane reproduced the reported values after rounding: ES RMSE 3.84e-16; NES Pearson 0.999967, Spearman 0.999676, and RMSE 0.01333; transformed-p Pearson 0.997199, Spearman 0.988318, and RMSE 0.16960. On the same input, the current lane gave ES RMSE 3.21e-16; NES Pearson 0.999952, Spearman 0.999652, and RMSE 0.01567; transformed-p Pearson 0.999069, Spearman 0.996628, and RMSE 0.11826. A separate 60-pathway tie-heavy case exposes a 0.1.4 limitation. Its legacy NES RMSE was 0.29868; the current implementation reduced it to 0.01558 while restoring machine-precision ES agreement. This sensitivity case was not the publication input. Across 20 fixed score-permutation replicates, the current installed package returned all 2,000 planned null pathways. The pooled mean and median nominal p-values were 0.4991 and 0.5010; the proportions below 0.01, 0.05, and 0.10 were 0.0065, 0.0430, and 0.0935. These are descriptive summaries, not a fitted acceptance threshold. The original speed and memory values are not carried forward because the current run did not measure all tools under one matched scope. Figure 2 scope The accepted trajectory parameters are window_size=500, step=50, nperm_nes=2000, score_type="std", exact pathway sizes, bin_width=0, and NES caching off. The reassembled figure uses a processed 3,576-cell erythroid subset from GSE155254 with precomputed UMAP coordinates and DPT. Panel D ranks genes from scaled adata.X; the frozen object has no separate raw or named log1p layer. Public assignment tables match 2,097 control and 816 gata307mut cells, while 663 cells remain unmatched. The figure pools these groups and is descriptive, not a control-versus-mutant comparison. Benjamini-Hochberg adjustment is performed across pathways within each window and is not trajectory-wide error control. Migration from 0.1.4 The defaults intentionally differ: | Setting | 0.1.4 | 0.2.0 | | --- | --- | --- | | high-level score type | two_sided_abs | std | | estimator | implicit legacy behavior | mode="aligned" | | pathway-size binning | None | 0 (exact size) | | trajectory step | 100 | 50 | | trajectory NES permutations | 100 | 2000 | | trajectory NES cache | on | off | For new analyses, state the numerical contract explicitly: result = pyfgsea.run_gsea( data=ranks, gmt=pathways, gene_col="gene", score_col="score", mode="aligned", score_type="std", bin_width=0, seed=42, ) Install trajectory dependencies with: python -m pip install "pyfgsea[trajectory]" score_type="two_sided_abs" remains available for a bounded legacy-like calculation, but it is approximate and is not equivalent to fgseaMultilevel(scoreType="std"). The Python API does not accept an n_threads keyword. Packaging and paper impact Cargo.toml is the single version source for the Rust crate and Python distribution. Release packages are built as source distribution and platform wheels, installed into fresh environments, and tested through the installed Python package and native core. The two R reference images are also started and checked at runtime. The manuscript review is classified as a numerical and methods correction whose central software-concordance conclusion remains intact. The detailed decision note and claim matrix identify the text and values to keep, qualify, update, or remove. Limits The formal comparison covers the publication input and one predeclared tie-heavy sensitivity case; it is not a universal equivalence claim. Correlation and pathway overlap do not establish algorithmic identity or biological correctness. The Figure 1 run does not provide matched current benchmarks against GSEApy or BlitzGSEA. Runtime and peak memory remain hardware- and scope-dependent. Fast mode and the legacy empirical-tail helpers are approximate.