Skip to content

docs(tutorials): add the FASTA-to-scikit-learn upstream bridge recipe - #595

Open
breimanntools wants to merge 1 commit into
masterfrom
doc/555-adapter-notebooks
Open

breimanntools wants to merge 1 commit into
masterfrom
doc/555-adapter-notebooks

Conversation

@breimanntools

Copy link
Copy Markdown
Owner

The upstream adapters exist as code but none was documented as an end-to-end bridge. tutorials/tutorial8_upstream_bridge.ipynb takes a user from another tool's output to a fitted model.

FASTA in → read_fasta → get_df_parts → a genuine Pipeline([SequenceFeatureTransformer, StandardScaler, RandomForestClassifier]) under cross_val_score → get_feature_names_out showing the CPP feature ids survive into RF importances → a second unlabeled FASTA through transform / predict.

Zero library code touched — 3 files: the notebook, a gallery tile, and the tutorials.rst entry under a new Interoperability section.

Two judgement calls

  1. It uses SequenceFeatureTransformer, not aa_composition. Codex proposed the latter, which is a trivial pipeline that dodges the actual gap: the leak-free CPP-selection-inside-CV pipeline that today exists only in tests/integration/test_sklearn_pipeline_compat.py. The recipe is lifted out of that test — which is what the issue asks for, since it notes the only runnable pipeline lives in a test file.
  2. It exports the bundled DOM_GSEC (40 records) to a real FASTA rather than hand-writing six mock records, so the 5-fold CV is meaningful rather than decorative. Still offline, still no new dependency.

The one-bridge-versus-every-bridge contradiction in the issue is resolved in favour of one, matching its own Scope / non-goals line — and resolved inside the docs, so the next reader does not rediscover it: the notebook and the new section both say only the FASTA hand-off is covered and point at the embeddings/AlphaFold tutorial for the others.

Verification

Docs build before and after: 0 error · 167 critical both times, critical did not move, and the new page was confirmed built (41 KB RST, 85 KB HTML, 5 tables, the figure rendered). pytest --nbmake on the notebook: 1 passed in 64s — re-run independently here at 98s. 341 api_tests pass.

One open item

tutorials/ is not executed in CI at all — the notebook gate covers an examples/ subset plus all of protocols/. So this notebook has no blocking execution gate. Closing that is a one-line workflow addition (~65s to that job), left for you since .github/workflows/* is CONFIRM-FIRST.

Refs #555.

🤖 Generated with Claude Code

The upstream adapters ship as code, but no notebook carried another tool's
output end to end, and the only runnable scikit-learn pipeline lived inside
tests/integration/test_sklearn_pipeline_compat.py. Protocol 8 shows one too,
but only as an unexecuted fenced block in a markdown cell, so a reader could
not run it.

Adds tutorials/tutorial8_upstream_bridge.ipynb: a FASTA file from an upstream
tool through read_fasta, get_df_parts and SequenceFeatureTransformer into a
real sklearn Pipeline, cross-validated leak-free, with the CPP feature ids
preserved through get_feature_names_out and a second unlabeled delivery scored
end to end. Every public parameter of read_fasta, to_fasta and
SequenceFeatureTransformer (constructor plus fit / transform /
get_feature_names_out) is passed by name.

Runs offline on the bundled DOM_GSEC benchmark and adds no dependency
(scikit-learn is already core). Wired into docs/source/tutorials.rst under a
new Interoperability section, with a gallery thumbnail.

One bridge only, per the issue's scope note; the embedding and structure
bridges stay with the Embeddings & AlphaFold tutorial.

Gates: nbmake 1 passed in 64s (timeout 120); docs build 0 errors, critical at
baseline 167; tests/unit/api_tests 341 passed.

Refs #555

Co-Authored-By: Claude Fable 5.1 <[email protected]>
@codecov

codecov Bot commented Sep 18, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.39%. Comparing base (3c11c90) to head (0ddb4d0).
⚠️ Report is 10 commits behind head on master.

Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##           master     #595   +/-   ##
=======================================
  Coverage   95.39%   95.39%           
=======================================
  Files         222      222           
  Lines       23387    23387           
  Branches     4073     4073           
=======================================
  Hits        22309    22309           
  Misses        631      631           
  Partials      447      447           

see 2 files with indirect coverage changes

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

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