Skip to content

doc(use-cases): add Use Cases guide + UC1 γ-secretase reproduction#277

Merged
breimanntools merged 2 commits into
masterfrom
doc/use-case1-gsec
Jun 26, 2026
Merged

doc(use-cases): add Use Cases guide + UC1 γ-secretase reproduction#277
breimanntools merged 2 commits into
masterfrom
doc/use-case1-gsec

Conversation

@breimanntools

Copy link
Copy Markdown
Owner

What

Introduces Use Cases as a third subchapter under the GUIDES nav (alongside Tutorials and Protocols) and ships the first one. A use case reproduces a published study end to end from bundled data only — distinct from Tutorials (one tool) and Protocols (one minimal-code workflow).

Note on nav placement: issue #109's original text says "Examples umbrella caption", but the live nav uses the GUIDES caption (Tutorials · Protocols), so per direction this lands as GUIDES → Use Cases. Same use_cases/ folder + create_notebooks_docs.py wiring the issue specifies.

First use case — use_case1_gamma_secretase.ipynb

Reproduces the key results of Breimann et al., Charting γ-secretase substrates by explainable AI, Nat. Commun. 16, 5428 (2025) — the paper AAanalysis was built to support — on the bundled, balanced DOM_GSEC set (63 substrates + 63 non-substrates), no downloads:

  • CPP signature — feature map + profile (cf. Fig 2b/2c), concentrated in the TMD_C_JMD_C cleavage region, Conformation dominant (matches the paper's biology).
  • Benchmark (cf. Fig 3a) — CPP 84.9% vs scale-average baseline 75.4% balanced accuracy (5-fold CV, same tree model). Matches the paper's 84% headline; the narrower baseline gap vs the paper's ~50% is expected on this balanced, proteome-free set and is called out in the notebook.
  • Simplifications documented in-notebook: balanced bundled set (not the imbalanced proteome), one tree ensemble (not the 10-model LOO sweep), single bundled TMD annotation (not the UniProt/TMHMM/Phobius comparison). Scaling up = the Protocols.

Wiring

  • export_use_case_notebooks_to_rst() in create_notebooks_docs.py + call in conf.py
  • new docs/source/use_cases.rst toctree; added to the GUIDES caption in index.rst
  • landing-page routing line updated (was "coming soon") + release note

Local gates

  • pytest --nbmake on the notebook: 1 passed
  • cd docs && make html: use_cases.html + RST + 3 figures render, zero net-new Sphinx warnings

Scope

Docs-only; no public API change. Advances #109 (does not close it — the first milestone also wants one case per prediction level; this delivers the infrastructure + the γ-secretase flagship). Part of epic #106.

Introduce "Use Cases" as a third subchapter under the GUIDES nav (alongside
Tutorials and Protocols): a use case reproduces a published study end to end
from bundled data only.

First use case (use_case1_gamma_secretase) reproduces the key results of
Breimann et al., "Charting gamma-secretase substrates by explainable AI",
Nat. Commun. 16, 5428 (2025) on the bundled DOM_GSEC set (63 substrates + 63
non-substrates): the CPP signature (feature map + profile, cf. Fig. 2b/2c) and
the CPP-vs-scale-based benchmark (~85% vs ~75% balanced accuracy, cf. Fig. 3a),
with the cleavage-region / conformational feature breakdown the paper reports.

Wire the new use_cases/ notebook folder into the docs: export_use_case_
notebooks_to_rst() (conf.py + create_notebooks_docs.py), a use_cases.rst
toctree, the GUIDES caption, the landing-page routing line (was "coming soon"),
and a release note.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@breimanntools breimanntools left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure how good the notebook will be. I check it after it is pusehd

Review follow-up: three docs pages enumerated the guide pillars
(Tutorials/Protocols) but omitted the new Use Cases subchapter — the
Introduction guides overview, the Getting Started dev note, and the
prediction-tasks "Where to go next". Add Use Cases to each for nav consistency.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@breimanntools breimanntools marked this pull request as ready for review June 26, 2026 02:57
@codecov

codecov Bot commented Jun 26, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.16%. Comparing base (ae64fe2) to head (b1764dc).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##           master     #277      +/-   ##
==========================================
+ Coverage   96.13%   96.16%   +0.03%     
==========================================
  Files         176      176              
  Lines       16827    16856      +29     
  Branches     2877     2882       +5     
==========================================
+ Hits        16176    16210      +34     
+ Misses        366      359       -7     
- Partials      285      287       +2     

see 3 files with indirect coverage changes

Components Coverage Δ
cpp_core 94.95% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@breimanntools breimanntools merged commit 7b4fc12 into master Jun 26, 2026
16 checks passed
@breimanntools breimanntools deleted the doc/use-case1-gsec branch June 26, 2026 04:23
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