Phase 3: DuckDB backend for out-of-core TDC confidence estimation

[wsnoble]

Summary

• Adds backend='duckdb' parameter to PsmDataset.assign_confidence() and the module-level assign_confidence() — explicit opt-in, no behavior change for existing code
• New crema/backends/duckdb.py implements the full TDC pipeline (spectrum competition, peptide competition, protein aggregation, FDR + q-values) using DuckDB SQL window functions; handles datasets larger than RAM via out-of-core execution
• Q-value SQL uses the same tied-score-aware backward-monotone-minimum logic as qvalues.tdc() for numerical equivalence
• New DuckdbTdcConfidence class is a drop-in subclass of Confidence; to_txt() and _prettify_tables() work unchanged
• setup.cfg: adds [fast] (pyarrow) and [large] (duckdb≥0.8.0) optional dependency groups
• 18 new unit tests in tests/unit_tests/test_duckdb.py; all skipped automatically when duckdb is not installed

Limitations

• Only supports method='tdc'; backend='duckdb' with method='mixmax' raises ValueError
• Protein-group estimation is not implemented in the DuckDB backend (deferred)

Test plan

• pytest tests/unit_tests/ passes with 91 tests (duckdb tests skipped if package absent)
• pip install crema[large] installs duckdb; duckdb tests then run and pass
• psms.assign_confidence(score_column="score", backend="duckdb") produces same accept counts as pandas path
• to_txt() on a DuckdbTdcConfidence object writes valid output files

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added DuckDB backend support for TDC confidence scoring at PSM, peptide, and protein levels.
  • Introduced backend parameter to confidence assignment functions (default: "pandas").
  • New optional dependency group large for DuckDB support.

• Tests

  • Added comprehensive unit tests for the DuckDB backend with output validation and numerical accuracy checks.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6b8a6ab8-439d-44f5-849d-1af463dc146a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• ✅ Review completed - (🔄 Check again to review again)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch scale-phase-3

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crema/backends/duckdb.py`:
- Around line 50-64: The CREATE TABLE SQL statement in the con.execute call and
other code blocks in the file do not conform to Black's formatting standards,
causing linting failures. Run the Black code formatter on the
crema/backends/duckdb.py file to automatically apply the correct formatting to
the SQL query string and all other affected code blocks referenced in the
comment (lines 95-127, 236-244, 267-273, 284-295). This will ensure the code
passes the CI linting checks.
- Around line 49-60: Define a helper function _qid that takes a string name and
returns it wrapped in double quotes with any internal double quotes escaped by
doubling them (quote becomes two quotes). Then systematically replace all direct
identifier interpolations throughout the file that currently use the pattern
"{variable_name}" with _qid(variable_name) instead. This includes the partition
variable construction on line 49, all score_col variable references, target_col
references, pep_col references, prot_col references, and score_column references
across the various SQL query construction sections in the file. The goal is to
ensure that column names containing double quote characters are properly escaped
and do not cause SQL parse failures.

In `@crema/dataset.py`:
- Around line 218-233: The current code silently falls back to pandas when an
unrecognized backend value is provided (e.g., a typo like "duckbd"), which can
mask configuration mistakes. After the if statement that checks for backend ==
"duckdb", replace the else clause with explicit validation that either accepts
known backend values like "pandas" or raises a ValueError rejecting unknown
backends. This ensures invalid backend values are caught immediately with a
clear error message rather than silently executing with an unintended backend.

In `@tests/unit_tests/test_duckdb.py`:
- Line 12: Apply Black code formatting to the pytest.importorskip call on line
12. The line exceeds Black's default line length limit and needs to be
reformatted, likely by breaking the pytest.importorskip function call with the
"duckdb" argument and reason parameter across multiple lines to meet Black's
formatting standards and unblock the CI checks.
- Around line 181-201: The test test_duckdb_psm_qvalues_match_pandas is
comparing the score column "x" instead of the actual q-values. Replace the
assertion that currently compares p_df["x"] and d_df["x"] with a comparison of
the appropriate q-value column from both dataframes. The test should validate
that the q-values calculated by the DuckDB path match those from the pandas
path, not the original scores. Identify the correct q-value column name from the
confidence_estimates dictionary and update the pd.testing.assert_series_equal
call accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9c4e1a4e-45b5-4cca-9c10-ee6598ff06a9

📥 Commits

Reviewing files that changed from the base of the PR and between 1e6fb7c and 8c59b6c.

📒 Files selected for processing (7)

• crema/__init__.py
• crema/backends/__init__.py
• crema/backends/duckdb.py
• crema/confidence.py
• crema/dataset.py
• setup.cfg
• tests/unit_tests/test_duckdb.py

[Copilot]

Copilot reviewed 6 out of 7 changed files in this pull request and generated no comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.