Skip to content

STATUS.md

Latest commit

 

History

History
49 lines (41 loc) · 4.09 KB

STATUS.md

File metadata and controls

49 lines (41 loc) · 4.09 KB
Raw

tcren — project status & TODO

Status of the Python re-implementation of TCRen (src/tcren/). The legacy R/Java pipeline is preserved (tag legacy-r-1.0) and serves as the numerical oracle. Current release: v2.2.0 (feature table + AF-orthogonal kit: recognize --full --scores, kit_score, forced_pose_score, interface mechanics, binder identification, configurable potentials, fast ΔΔG). See CHANGELOG.md for the authoritative per-release record, BENCHMARKS.md for achieved accuracy, and docs/ (features.rst, kit.rst) for the current API.

Note: the detailed "Done"/"TODO" sections below are historical (they predate v2.1+) and describe an earlier module layout — the native/ module is now orient/, FlexPepDock lives in refine/oracle_flexpep.py, and the standalone tcren mhc command was removed. Treat CHANGELOG.md + README.md + SKILL.md as the current source of truth.

Done

Area Module(s) Notes
Potentials potential/ classic + am (gap) variants, LOO; wide/long CSV loaders; MJ/Keskin bundled
Structure I/O structure/ biopython parse; import_structure (C-gene trim by default, keep_c_gene for MD)
TCR annotation annotation/ arda V(D)J → CDR/FR markup; αβ/γδ from C-gene (cgene)
Contacts contacts/, contactmap.py cKDTree 5 Å + Cα matrix; TCR/peptide/MHC interfaces
Scoring scoring.py substitution scoring; drop-in for run_TCRen.R; opt-in TCR framework regions (cdr/cdr+fr/all)
Configurable potentials pipeline.py per-interface potential override (Potential, bundled name, CSV, or None) on pipeline.run/CLI
Percentile rank scoring_rank.py native peptide energy vs. random pMHC background (tcren rank)
Fast ΔΔG ddg.py virtual-matrix point-mutation ΔΔG + alanine scan + neoantigen ΔΔG (tcren ddg)
Oracle facade oracle.py summarize_structure composes S1–S4 into one frame bundle for the paper notebooks
MHC mhc/ IMGT/HLA + mouse H-2 reference, mmseqs mapping, groove partitioning, linker-peptide split
Native DB native/ TCR3D download/version/manifest; ground-truth comparison; align-to-canonical; potential re-derivation
2D maps project2d/, viz/ groove-plane projection, canonical tables, metadata-rich SVG, py3Dmol pocket+CDR
Analysis analysis.py potential heatmaps/compare, contact distributions (per-structure/region/position)
CLI cli.py info/annotate/contacts/derive-potential/score/mhc/native …
Docs docs/ Sphinx + 3 tutorial notebooks (notebooks/); zero-warning build

TODO / pending

  • AI-model refinement (refine/): batch-refine predicted PDBs → canonical → score; QC (anchor RMSD, plDDT, completeness). Inputs in data/TCRpMHCmodels/, data/Bigot/, data/Bobisse/.
  • FlexPepDock (flexpep/, optional): peptide substitution + Rosetta relaxation; gated on a discovered Rosetta binary. Needs keep_c_gene=True.
  • Standalone orient/ module: generalise native/align.py (multi-structure overlay, canonical chain renumbering, write oriented PDBs).
  • Regenerate stale tcren_am/ outputs from the current contact data (see the spawned task).
  • MHC mapper speed: prebuild the mmseqs index (currently ~7 s/structure from per-call easy_search).
  • 2D map polish: optional "contacting residues only" mode for less cluttered overlays.
  • Mouse class-II MHC reference is sparse (TRGC3/4 skipped); extend if needed.

Known caveats

  • All bundled structure sets (data/PDB_structures/, TCR3D CIFs) are variable-domain-only; the C-gene classifier and full-complex geometry need full RCSB inputs (fixtures in tests/assets/cgene/).
  • TCR3D tcr_complexes_data.tsv mislabels some TRAV/DV J calls (e.g. 1bd2 TRDJ1); arda is correct (locus follows J). Locked by a test in arda dev.
  • arda is a runtime dependency, published to PyPI as arda-mapper>=2.0.1 (imports as arda); installed by pip install -e . / pip install tcren.