Skip to content

CellReads.stats values as STARsolo writes them - #379

Open
iandriver wants to merge 1 commit into
scverse:mainfrom
iandriver:fix/cellreads-stats-as-star
Open

iandriver wants to merge 1 commit into
scverse:mainfrom
iandriver:fix/cellreads-stats-as-star

Conversation

@iandriver

Copy link
Copy Markdown
Contributor

What changed

Solo.out/<feature>/CellReads.stats now carries the values STARsolo writes (SoloReadFeature_record.cpp, SoloReadFeature_inputRecords.cpp, SoloFeature_statsOutput.cpp).

  • Options. --soloCellReadStats takes STAR's value, Standard. CB, which rustar-aligner took before, stays as a deprecated alias. --genomeChrSetMitochondrial defaults to STAR's chrM M MT instead of naming nothing.
  • One table per feature. Gene and GeneFull no longer print the same rows.
  • Region columns come from the feature's own overlap type (exonic for a Gene read with a gene, none for GeneFull), not from CellRanger's positional regions.
  • cbMatch counts every read, including those whose barcode or UMI was rejected.
  • Barcode resolution. One-mismatch corrections and 1MM_multi barcodes are resolved with the run's exact counts, as the matrix resolves them, so cbMMunique, cbMMmultiple and the rows match.
  • Columns that were empty. featureM and countedM are now filled, and nUMImulti/nGenesMulti come from the first --soloMultiMappers matrix.
  • Determinism. Each read's entry is folded in input order by the in-order consumer of the alignment loop, so the file no longer depends on thread timing.

Evidence

  • cargo test: 821 passed, 0 failed. cargo clippy --all-targets and cargo fmt --check are clean. New tests are in tests/solo_cell_read_stats.rs.
  • Data: CellRanger's tiny 10x data (tinygex_S1_L001, 230,610 reads), whitelist 3M-february-2018, --soloFeatures Gene GeneFull.
  • Comparison: against STARsolo 2.7.11b on the same index and options, at 1 and at 8 threads.
  • Result: all 6,983 rows are present on both sides, with identical headers. Every value in every column, for both features, matches.
  • Exception: 3 barcodes differ, holding the 3 reads rustar-aligner maps and STAR leaves unmapped (genomeU +2, genomeM +1, and in GeneFull featureM +2).

Known divergence: row order

The row order still differs from STAR's. STAR writes these rows by iterating a std::unordered_map keyed by whitelist index. rustar-aligner writes them in reverse order of each barcode's first appearance, which agrees with STAR only on the first rows of this data.

STAR's order was the same at 1 and 8 threads. A model of a libc++ hash-table walk did not reproduce it, so what sets STAR's order is not settled. DIVERGENCE.md §3.2, which previously claimed the orders matched, now records what was measured.

The values are the content of the file. Read it by barcode, and sort both files by barcode before comparing them with STAR's.

For reviewers

  • CHANGELOG.md, DIVERGENCE.md and the CLI parameter docs are updated.
  • --soloCellReadStats CB still works, as an alias, for anyone already passing it.

🤖 Generated with Claude Code

--soloCellReadStats takes STAR's value, Standard (CB stays as a deprecated
alias), and --genomeChrSetMitochondrial defaults to STAR's chrM M MT. Each
feature keeps its own table; region columns come from the feature's own
overlap type; every read is counted under cbMatch; one-mismatch and
1MM_multi barcodes are resolved with the run's exact counts, as the matrix
resolves them; featureM, countedM, nUMImulti and nGenesMulti are filled.
Rows are folded in input order by the in-order consumer.

On CellRanger's tiny 10x data every value matches STARsolo 2.7.11b except
on the 3 barcodes of 3 reads rustar-aligner maps and STAR leaves unmapped.
Row order still differs from STAR's (which was the same at 1 and 8
threads); DIVERGENCE.md 3.2 now says what was measured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant