@platforma-open/milaboratories.clonotype-convergence 1.4.1 → 1.5.0

package/block-pack/description.md

@@ -1,11 +1,18 @@
 # Overview
 
-Detects antigen-driven clonotype convergence in B-cell receptor (BCR) repertoires using the fast-STAR statistic (Abbate et al. 2024). For each clonotype, the block counts how many other CDR3s in the same sample differ by exactly one amino acid — a per-clone neighbour density. High density signals independent B-cell lineages converging on the same CDR3 solution, a hallmark of antigen-driven selection. Outputs a Hit / Not hit flag from a configurable neighbour-frequency threshold plus the raw neighbour count and frequency, per chain. An optional cluster filter adds a stricter "binder" call: a clone is flagged when several similar CDR3s (one-edit distance) form a cluster of at least the user-set minimum size — matching the paper's headline definition.
+Detects antigen-driven clonotype convergence in B-cell receptor (BCR) repertoires. For each clonotype, the block counts how many other CDR3s in the same sample differ by exactly one amino acid — a per-clone neighbour density. High density signals independent B-cell lineages converging on the same CDR3 solution, a hallmark of antigen-driven selection.
 
-Inputs: clonotype-level VDJ data — CDR3 amino-acid sequence, CDR3 nucleotide sequence, and per-clonotype abundance. Accepts bulk Heavy, bulk Light, or single-cell BCR data; light-chain analysis on single-cell data is an explicit opt-in.
+Two convergence calls are produced side by side, from that same neighbour count:
+
+- **fast-STAR** — always computed. A configurable threshold on the normalised neighbour frequency (Abbate et al. 2024), calibrated for human IgH by default.
+- **full-STAR** — added automatically wherever a per-clonotype generation probability is available from the **Generation Probability** block. Each clone is tested against what V(D)J recombination alone would produce for *its own* CDR3: a Poisson test of the observed neighbour count against a Pgen-derived null, with Benjamini-Hochberg control at a user-set false-discovery rate. A rare CDR3 is flagged on a few neighbours where a common one needs many. Where it runs, full-STAR is the preferred signal — fast-STAR is a fixed threshold, blind to how likely a sequence was to arise by chance.
+
+A clonotype seen in several samples is collapsed to one value per clonotype, ready for downstream scoring and lead selection: for each call a **score**, a **Hit / Not hit** flag, and a **reproducibility** ratio — how broadly across the dataset the clone is a hit, on a scale that compares between clones. Per-sample values are kept for QC, alongside an optional cluster filter adding a stricter "binder" call matching the paper's headline definition.
+
+Inputs: clonotype-level VDJ data — CDR3 amino-acid sequence, CDR3 nucleotide sequence, and per-clonotype abundance. Accepts bulk Heavy, bulk Light, or single-cell BCR data; light-chain analysis on single-cell data is an explicit opt-in. Generation Probability is optional — without it the block reports fast-STAR alone.
 
 **Designed for in-vivo BCR repertoires only.** In-vitro data — scFv libraries, phage / yeast display, panning-enriched repertoires — produces uninterpretable results. The algorithm runs and emits numbers, but the signal it was built to detect (germinal-center convergence under antigen-driven selection) is absent in vitro.
 
-The fast-STAR algorithm is from the Statistical Biophysics group's STAR tool. For more information, please see: [https://github.com/statbiophys/STAR](https://github.com/statbiophys/STAR) and cite the following publication if used in your research:
+Both statistics are from the Statistical Biophysics group's STAR tool. For more information, please see: [https://github.com/statbiophys/STAR](https://github.com/statbiophys/STAR) and cite the following publication if used in your research:
 
 > Abbate A. et al. Computational detection of antigen-specific B cell receptors following immunization. _PNAS_ 121(35):e2401058121 (2024). [https://doi.org/10.1073/pnas.2401058121](https://doi.org/10.1073/pnas.2401058121)

package/block-pack/manifest.json

@@ -1 +1 @@
-{"schema":"v2","description":{"id":{"organization":"milaboratories","name":"clonotype-convergence","version":"1.4.1"},"components":{"workflow":{"type":"workflow-v1","main":{"type":"relative","path":"main.plj.gz"}},"model":{"type":"relative","path":"model.json"},"ui":{"type":"relative","path":"ui.tgz"}},"meta":{"title":"Clonotype Convergence","description":"Detect antigen-driven clonotype convergence in a single BCR repertoire (fast-STAR).","longDescription":{"type":"relative","path":"description.md"},"changelog":{"type":"relative","path":"CHANGELOG.md"},"logo":{"type":"relative","path":"block-logo.png"},"url":"https://github.com/platforma-open/clonotype-convergence","support":"mailto:support@milaboratories.com","tags":["downstream","VDJ","BCR"],"organization":{"name":"MiLaboratories Inc","url":"https://milaboratories.com/","logo":{"type":"relative","path":"organization-logo.png"}}},"featureFlags":{"supportsLazyState":true,"supportsPframeQueryRanking":true,"requiresUIAPIVersion":3,"requiresModelAPIVersion":2,"requiresCreatePTable":2,"requiresPFramesVersion":1001031,"requiresPFrameSpec":true,"requiresPFrame":true,"requiresDialog":true,"requiresColumnsCollection":true},"kind":"@platforma-open/milaboratories.clonotype-convergence.kind@1.0.0"},"timestamp":1790335654261,"files":[{"name":"main.plj.gz","size":862475,"sha256":"8B920DD33776A2B6748930B134F6797BB60EBC5BCB8FFFB014A15F96CEAB84CA"},{"name":"model.json","size":563521,"sha256":"81476F96D152AFA6767F0D2BC2EAE9725D42AFBBC3031E19727D42A0D9D92570"},{"name":"ui.tgz","size":6398176,"sha256":"62E868CC8EDA72764489A93B2864B7B3EA575AB0F80A57FFBFB9BAAAE70B8C57"},{"name":"organization-logo.png","size":24439,"sha256":"FA71390C77C91E4B7FAAE5640D00F92F1E3F2869296F68B6040DD7CC549A50B5"},{"name":"description.md","size":1816,"sha256":"78776990C88A950FA0CD0602EFB75E00EE48E4F4D197AE17EF6A6A1D40E2D72D"},{"name":"CHANGELOG.md","size":27,"sha256":"3E1D1DA422E5D609FCDE7F996A81F7635011F3CA297923598DB36D924C4A0DAE"},{"name":"block-logo.png","size":37048,"sha256":"9C5C3FB48F044AC6C94551C303EFEAB5F1AE83F87117ADA794C8F87655FEB317"}]}
+{"schema":"v2","description":{"id":{"organization":"milaboratories","name":"clonotype-convergence","version":"1.5.0"},"components":{"workflow":{"type":"workflow-v1","main":{"type":"relative","path":"main.plj.gz"}},"model":{"type":"relative","path":"model.json"},"ui":{"type":"relative","path":"ui.tgz"}},"meta":{"title":"Clonotype Convergence","description":"Detect antigen-driven clonotype convergence in BCR repertoires: fast-STAR always, plus the FDR-controlled full-STAR where generation probability is available.","longDescription":{"type":"relative","path":"description.md"},"changelog":{"type":"relative","path":"CHANGELOG.md"},"logo":{"type":"relative","path":"block-logo.png"},"url":"https://github.com/platforma-open/clonotype-convergence","support":"mailto:support@milaboratories.com","tags":["downstream","VDJ","BCR"],"organization":{"name":"MiLaboratories Inc","url":"https://milaboratories.com/","logo":{"type":"relative","path":"organization-logo.png"}}},"featureFlags":{"supportsLazyState":true,"supportsPframeQueryRanking":true,"requiresUIAPIVersion":3,"requiresModelAPIVersion":2,"requiresCreatePTable":2,"requiresPFramesVersion":1001031,"requiresPFrameSpec":true,"requiresPFrame":true,"requiresDialog":true,"requiresColumnsCollection":true},"kind":"@platforma-open/milaboratories.clonotype-convergence.kind@1.1.0"},"timestamp":1790681445737,"files":[{"name":"main.plj.gz","size":863284,"sha256":"A695ADCF5091B51B2D6E9D2F44918A2D2E5D1866DC560DF4D898D33BD17F0B30"},{"name":"model.json","size":567078,"sha256":"54534A39BA969AEBE7D7776D2F37AB3D79AD8A465245DA2B128A80B687B41EFF"},{"name":"ui.tgz","size":6565833,"sha256":"AE5EE5483ADA03824ED4AA5A0802CA1EA90685DD0A6DDF6AB770632F0B8D2482"},{"name":"organization-logo.png","size":24439,"sha256":"FA71390C77C91E4B7FAAE5640D00F92F1E3F2869296F68B6040DD7CC549A50B5"},{"name":"description.md","size":2778,"sha256":"CF776A90E8683CDC0EEF317B2277D704999B9002E93D2A7400DEA4A3431F31E7"},{"name":"CHANGELOG.md","size":27,"sha256":"3E1D1DA422E5D609FCDE7F996A81F7635011F3CA297923598DB36D924C4A0DAE"},{"name":"block-logo.png","size":37048,"sha256":"9C5C3FB48F044AC6C94551C303EFEAB5F1AE83F87117ADA794C8F87655FEB317"}]}