epic: usability gaps surfaced by a real epitope-prediction project

[breimanntools]

Context

Usability gaps surfaced while building a real linear + conformational B-cell epitope-prediction
pipeline on aaanalysis master (__version__ still reads 1.0.3) — using CPP, aap.find_features,
EmbeddingPreprocessor, StructurePreprocessor, ShapModel, CPPPlot, dPULearn. Grouping the
findings here; the sub-issues below are the concrete, independently-shippable subtasks.

Already tracked (this project confirms the need in practice)

• Compositional baseline featurizers (scale, AAC, ACC, …) + baseline comparison in AAPred #335 compositional baseline featurizers (AAC/DPC/…) — the biggest source of glue code; had to
  hand-build a 20×20 one-hot identity scale set (Segment(1,1) = AAC) and a 400-token dipeptide
  alphabet for DPC. Not on master yet.
• feat: aa.eval_features — model + CV + metric feature-set scorer (incl. PU mask-CV) #309 aa.eval_features — re-implemented a cross_val_predict+metric wrapper in ~every script.
• feat: feature_matrix accepts df_seq + list_parts directly (drop the get_df_parts triple-call) #306 (closed) feature_matrix(df_seq=…) — confirmed present on master, resolved. 🎉
• CPP strategies guide: compositional vs positional features #86 / CPP strategy preset (compositional/positional) convenience #87 compositional-vs-positional guide — this project is a clean worked example (composition
  wins linear Z1; positional CPP + 3D structure wins conformational Z2).
• Add CPPStructurePlot.map_structure: paint CPP-SHAP feature impact onto a 3D protein structure (pro) #119 / Add CPPStructurePlot.interactive: live, feature-map-linked 3D structure explorer (pro) #280 / Add CPPStructurePlot.plot_combined: structure + feature_map side by side (static, pro) #284 / CPPStructurePlot: integrated-prediction linked explorer with selectable outputs (widget / self-contained HTML / static) #288 structure + feature-map linked explorer — exactly the app I hand-built.

New subtasks (not yet tracked)

• feat: NumericalFeature.feature_matrix for numeric CPP (run_num) outputs #337 — B1: NumericalFeature.feature_matrix for numeric CPP (run_num) outputs
• find_features / Pattern splits fail on free peptides (no flanks) #338 — B2: find_features / Pattern splits fail on free peptides (no flanks)
• CPP.run(n_jobs>1) crashes with multiprocessing.Manager() EOFError outside notebooks #339 — B3: CPP.run(n_jobs>1) mp.Manager() EOFError outside notebooks
• StructurePreprocessor: per-feature failure isolation + msms/backend routing #340 — B4: StructurePreprocessor per-feature failure isolation + msms/backend routing
• CPP filter blind to distributed (jointly-strong) signals #341 — B5: CPP filter blind to distributed (jointly-strong) signals

Minor

• __version__ stays 1.0.3 on master (unbumped) → master install is indistinguishable from the PyPI
  release; a .devN/git-hash suffix would disambiguate.
• Discoverability: re-implemented things that already exist (SequenceFeature.get_labels_quantile/ get_labels_tiered, prune_by_correlation/variance, get_df_parts_from_windows) — a task→method
  cookbook would help (docs epic epic: documentation architecture (Getting Started · Examples · API) #106).