docs: explain formula-based reference levels for LFC shrinkage

[rastagan-git]

Reference Issue or PRs

Fixes #362. The underlying user example is in #361.

What does your PR implement? Be specific.

• Add an executable section to the existing synthetic-data tutorial that selects B as the reference with C(condition, contr.treatment(base='B')), fits a new dataset, prints its coefficient names, and shrinks the matching A-versus-B coefficient.
• Explain why changing a Wald contrast does not create a fitted coefficient for lfc_shrink, and why numeric category labels need C().
• Point the ignored ref_level argument's deprecation warning and documentation to the formula syntax.
• Clarify the lfc_shrink coefficient contract and link to the tutorial. Remove the misleading None default from its docstring; no signature changes.
• Test the three-level design and single-coefficient contrast for both string and numeric categories, plus the actionable warning and continued no-op behavior of ref_level.

This does not change model fitting, shrinkage, statistical thresholds, or the handling of invalid coefficient names (which already raises KeyError). The example creates and fits a new dataset rather than mutating a fitted design in place.

Validation

Windows / CPython 3.12.11; formulaic 1.2.2, formulaic-contrasts 1.0.0:

• New tests before warning change: 1 failed, 2 passed. After: 3 passed. The formula already worked; the red test checks the missing migration guidance, not a numerical bug.
• Full pytest -q: 68 passed.
• Project prek run --files ...: all applicable hooks passed, including Ruff, AST checks, private-key detection, and mypy.
• python -m sphinx -M html docs docs/_build -W --keep-going: passed, including execution of the updated tutorial and its fit/shrink calls. The first build caught a short heading underline; it was corrected and the strict build rerun successfully.
• git diff --check: passed.

The other two existing gallery examples also executed successfully during the first build; the final incremental build reused them. Used only the repository's synthetic example data, with no patient data or model service. The full Python 3.12/3.14/pre-release matrix was not run locally.

AI assistance was used for source analysis, editing, and tests. The commands above were actually executed; no independent human review or production-use experience is claimed.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.97%. Comparing base (2ca3b74) to head (d067028).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #475      +/-   ##
==========================================
- Coverage   86.05%   85.97%   -0.08%     
==========================================
  Files          15       15              
  Lines        1276     1276              
==========================================
- Hits         1098     1097       -1     
- Misses        178      179       +1     

Files with missing lines	Coverage Δ
src/pydeseq2/dds.py	87.42% <ø> (-0.20%)	⬇️
src/pydeseq2/ds.py	90.00% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.