kompot 0.8.0

Kompot 0.8.0 aligns the statistics with the published method, adds pandas 3 / anndata 0.13 support, and makes every stored run self-describing.

Action required

Absolute values shift, so re-tune any hard-coded thresholds carried over from 0.7.0. The three changes reach very different distances — one is presentational, one moves your call rate, and one moves which genes are called at all.

• DE Mahalanobis distances are smaller by a factor of √2 (combined posterior covariance is now Σ_a + Σ_b, not (Σ_a + Σ_b)/2). Cosmetic by default: every distance divides by the same √2 and the empirical null rescales with it, so rankings, FDR and is_de calls are unchanged — only the printed magnitudes move. Exception: when sample variance is active, only the posterior term doubled, so the two variance components are reweighted and rankings can shift modestly.
• DA PTP is one-sided (Φ(−|z|) rather than 2Φ(−|z|)), so values are halved. More sensitive at an unchanged threshold: rankings hold, but more cells clear any fixed ptp_threshold — 1e-3 used to require |z| ≥ 3.29 and now requires only |z| ≥ 3.09. Halve your threshold to preserve the old call rate.
• use_empirical_variance now defaults to False in every entry point, matching kompot.de(). This is the one that changes results, not just their scale: it removes the per-gene, input-dependent noise surface from the denominator, so consistently noisy genes are no longer down-weighted and which genes are called genuinely differs. Runs are also faster and lighter. Pass use_empirical_variance=True to keep the old behavior.
• Renamed field: the DE posterior tail probability is now stored as -log10(PTP) in ..._neg_log10_ptp, so larger means more significant. volcano_de(y_axis_type="ptp") handles it for you; update any code reading the old _ptp column.

volcano_de no longer highlights a fallback when nothing is significant

Behaviour change. When no gene met the significance criteria, volcano_de used to highlight the top 10 genes by score, labelled "Top 10 genes (no genes at threshold)". On a volcano the coloured points read as "these are the hits" whatever the legend says, so a negative result was rendered as a hit list. The same applied when a stored is_de column marked nothing.

Both now highlight nothing and emit a warning naming the criteria that matched zero genes. Every gene still appears in the background colour, so the plot reads as the negative result it is.

The legitimate fallback is unchanged: with no significance criterion given, n_top_genes still highlights the top N by score, because ranking without a threshold claims nothing about significance. If you relied on the old behaviour to always get some highlighted genes, pass n_top_genes explicitly — that asks for the ranking the fallback was silently substituting.

Runs are now self-describing

Every run_history entry records kompot_version, kompot_git_sha and kompot_editable.

The sha and the editable flag are the load-bearing part: an editable install of v0.7.0-7-g4432d4f reports __version__ == "0.7.0", so a released version string alone does not identify the code that ran. Reconstructing it after the fact means crossing run timestamps against release dates — sound, but guesswork, and not something a reader could redo.

Resolution adds no dependency and reads the sha directly from .git, so no git binary is required. Fields are null when unresolvable rather than absent, because a present-but-null field is self-describing whereas a missing key is indistinguishable from an older store. A wheel install with no work tree reports a null sha rather than borrowing one from any surrounding repository.

Forward-only. It describes runs computed by 0.8.0 and later and does not retroactively describe existing stores, whose entries simply lack these keys and continue to load unchanged. Treat all three fields as optional when consuming run_history.

Compatibility

• pandas 3 and anndata 0.13. Grouping by a string column, passing a Series of indices as a group, colouring a volcano background by a categorical var column, and condition-label auto-detection in plot_smoothing all raised on the new majors. Dtype checks now go through pandas.api.types rather than numpy.issubdtype, which cannot interpret extension dtypes such as pandas 3's default StringDtype. Behaviour on pandas 2 / anndata 0.12 is unchanged, with one deliberate exception noted in the changelog.
• cell_filter= accepts nullable-integer index Series, which previously raised TypeError instead of selecting cells.
• matplotlib ≥ 3.9: no longer calls the removed matplotlib.cm.get_cmap.

Also new

kompot de --dry-run, kompot.plot.dotplot, kompot.plot.lollipop, custom background= for STRING enrichment, kompot.configure_logging(stream), and random_state on kompot.find_landmarks for reproducible landmark selection.

Full detail in CHANGELOG.md.