Repository navigation
fix: deterministic read and output order (worker-count independent) - #22
Merged
Merged
Conversation
- run(): collect parse_barcodes chunk results in chunk order (not as_completed), so reads reach greedy clustering and POA in input-file order; process droplets in sorted barcode order and assemble metadata in that order; natural-sort annotated contigs by sequence_id; pair_well writes pairs naturally sorted by barcode. Applies in all modes, legacy included (documented in `legacy`). - pair-pooled: explicit tie-breaks (representative contig: UMIs then sequence_id; reciprocal-best candidates: confidence, well, sequence_id:0/1), fixed row order before the posterior sums, deterministic output order. - qc: sort (barcode, umi) before the seeded shuffle of the UMI null; failure table ties broken by mode. - run(): early exits of a well (no valid barcode, no metadata, <=1 consensus, empty file) now clean up temp chunks, close printers and advance the bar. - test_determinism: golden wells + a 2-chunk well, 1 vs 2 workers, byte-identical outputs and identical pair-pooled results. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bnemoz
marked this pull request as ready for review
November 18, 2026 09:21
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Two runs of the same code on the same input gave different outputs.
run()collectedparse_barcodeschunk results andprocess_dropletresults withas_completed, so read order within a well (and the row order of every output) depended on worker scheduling. Read order drives greedy-clustering tie-breaks and POA input order, so some equal-count clusters got a 1-nt different consensus or a different UMI count, andpair-pooledjittered by ±0.1 pt precision/recall and ±2 pairs. Benchmarks could not call neutral changes SAME.What
run(): chunk results are concatenated in chunk (= input file) order, so reads reach clustering/POA in input order. Droplets are submitted in sorted barcode order and metadata is assembled in that order (progress bar still updates on completion). Annotated contigs are natural-sorted bysequence_idafter abstar.pair_wellwrites pairs natural-sorted by barcode (both modes).pair-pooled: explicit tie-breaks. Representative contig per (species, well): most UMIs, then smallestsequence_id. Rows are put in a fixed order before the home-posterior log-sum-exp, so float sums always run in the same order. Reciprocal-best ranking breaks equal confidence by well, thensequence_id:0, thensequence_id:1. Output sorted by confidence, then barcode/well/ids. Only ties are affected.(barcode, umi)is sorted before the seeded shuffle of the UMI-error null (unique()order was random). The failure table breaks ties by mode.temp/.legacy=Trueincluded. There is no flag. v2-base's own order was random, so the fixed order is one valid v2-base outcome; thelegacydocstring says so. The golden test passes unchanged: its wells are single-chunk, and the input order is kept.Not changed (lane C finding (b)): the
cluster_fractiondenominator (partition_df.shape[0]) counts empty reads thatgreedy_clusteringskips. Fixing it would change legacy metadata whenever empty reads exist (e.g. all-G inserts underlstrip("G")), so this PR only reports it.Tests
pairplex/tests/test_determinism.py: golden wells plus a 1499-read, 2-chunk well, run withPAIRPLEX_MAX_WORKERS1 and 2. All files under metadata/consensus/annotated/pairs/qc are byte-identical, metadata rows are in natural order, andpair-pooledgives identical frames (also on a repeat). It fails on origin/main (20 files differ, pooled differs) and passes here.pytest pairplex: 146 passed, 1 skipped (annotation calls: abstar version mismatch; this skip predates the PR).Benchmark
D5-determinism-b vs D5-determinism-a (same commit b673d07, sims only)
Every output file of the two runs is byte-identical (
diff -rqoverpp/), pooled parquet included. Onlystage_run.jsonandpooled_pairs_run_info.jsondiffer, through their timestamps.D5-determinism-v1 vs main-91397e0 (all 4 datasets)
Sims:
Real data (per the public-repo rule: verdict and purity delta only):
Lineages: PASS on all six real sets, 0 lost lineages at ≥3/5/10; cells recovered ≥0.976. Runtime 18884 s → 18793 s (PASS).
On real data, emitted pair counts move by a handful (≤0.01%). That is expected: main's read order was random, so its clustering/POA tie-breaks were one random draw, and this PR fixes a single order. Sim per-well/pairs are exactly SAME.
OVERALL: PASS
🤖 Generated with Claude Code