Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces a new “metaclonotype” abstraction (lightweight cluster membership tables over repertoires) and significantly extends the CDR3 motif-logo tooling toward V/J-matched OLGA-background “selection logos”, with supporting docs, notebooks, and tests to enable GIANA/iSMART/TCRdist-like comparative workflows.
Changes:
- Add
mir.common.metaclonotypecore APIs (definitions, builders, summaries, functional diversity/overlap utilities) and attach-metaclonotypes methods on repertoire objects. - Add shared clustering conversion utilities (
mir.utils.metaclonotype_clustering) plus convenience wrappers in embedding/graph/biomarker modules. - Extend
mir.biomarkers.motif_logowith selection-logo UX improvements and new background / terminal-anchored helpers, plus expanded unit tests and documentation.
Reviewed changes
Copilot reviewed 28 out of 29 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_motif_logo.py | Adds unit tests for new motif-logo backgrounds, plotting behavior, and terminal-anchored APIs. |
| tests/test_metaclonotype.py | Adds end-to-end tests for metaclonotype builders, summaries, diversity/overlap, and ALICE/TCRNET integration. |
| tests/test_metaclonotype_clustering_utils.py | Tests clustering-label/graph/search-scope conversion helpers and wrapper APIs. |
| skills/mirpy/SKILL.md | Documents metaclonotype workflows and expands motif-logo scientific/usage guidance. |
| README.md | Adds high-level “CDR3 Motif Logos” documentation and updates module description. |
| notebooks/metaclonotype_examples.ipynb | New notebook demonstrating metaclonotype usage patterns. |
| mir/utils/metaclonotype_clustering.py | New centralized helpers for converting clustering outputs into metaclonotype tables. |
| mir/utils/embedding_diagnostics.py | Docstring formatting update for parameter justification table. |
| mir/utils/init.py | Exposes new metaclonotype clustering utilities at the mir.utils package level. |
| mir/graph/token_graph.py | Adds metaclonotype builders for token/GLIPH clonotype graphs. |
| mir/graph/edit_distance_graph.py | Adds metaclonotype conversion helper for edit-distance graphs. |
| mir/graph/init.py | Exports new graph→metaclonotype helper APIs. |
| mir/embedding/tcremp.py | Adds label→metaclonotype wrappers for (paired) TCREmp clustering outputs. |
| mir/embedding/init.py | Exports the new TCREmp metaclonotype wrapper functions. |
| mir/common/single_cell.py | Adds PairedRepertoire.set_metaclonotypes() / .metaclonotypes attachment APIs. |
| mir/common/repertoire.py | Adds LocusRepertoire and SampleRepertoire metaclonotype attachment/get APIs. |
| mir/common/metaclonotype.py | New core metaclonotype definitions, builders, summaries, and functional diversity/overlap utilities. |
| mir/common/init.py | Re-exports metaclonotype APIs from mir.common. |
| mir/biomarkers/tcrnet.py | Adds metaclonotypes_from_tcrnet() convenience builder around significant clonotypes. |
| mir/biomarkers/motif_logo.py | Major expansion: selection-logo framing, new backgrounds, terminal-anchored logo/PWM, plotting tweaks, and batch builders. |
| mir/biomarkers/alice.py | Adds metaclonotypes_from_alice() convenience builder around significant clonotypes. |
| mir/biomarkers/init.py | Re-exports new motif-logo and metaclonotype builder APIs from mir.biomarkers. |
| docs/notebooks/metaclonotype_examples.ipynb | Documentation copy of the metaclonotype examples notebook. |
| docs/notebooks/index.rst | Adds metaclonotype notebook to docs index. |
| docs/mir.utils.rst | Adds API docs entry for mir.utils.metaclonotype_clustering. |
| docs/mir.common.rst | Adds API docs entry for mir.common.metaclonotype. |
| docs/mir.biomarkers.rst | Expands motif-logo documentation (selection logos, background regimes, key functions). |
| docs/getting-started.rst | Adds “Metaclonotype Workflows” getting-started documentation section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1025
to
+1026
| v_dom = str(dom[0][v_col][0]) | ||
| j_dom = str(dom[0][j_col][0]) |
Comment on lines
+1300
to
+1313
| # Axes formatting. | ||
| n_pos = len(positions) | ||
| ax.set_xlim(-0.1, n_pos + 0.1) | ||
| pad = max(0.05, (y_max - y_min) * 0.05) | ||
| ax.set_xlim(0, n_pos) | ||
| pad = max(0.05, (y_max - y_min) * 0.06) | ||
| ax.set_ylim(y_min - pad, y_max + pad) | ||
|
|
||
| if has_negatives: | ||
| ax.axhline(0, color="#333333", linewidth=0.6, zorder=0) | ||
|
|
||
| if show_xaxis: | ||
| ax.set_xticks(range(n_pos)) | ||
| ax.set_xticklabels([str(p + 1) for p in positions], fontsize=8) | ||
| # Ticks centred under each column bar (bars span pos to pos+1). | ||
| tick_positions = [p + 0.5 for p in range(n_pos)] | ||
| ax.set_xticks(tick_positions) | ||
|
|
Comment on lines
+563
to
+574
| lookup = paired_repertoire._materialize_clonotype_lookup() | ||
|
|
||
| def _find_clone(seq_id: str) -> Clonotype | None: | ||
| for by_id in lookup.values(): | ||
| if seq_id in by_id: | ||
| return by_id[seq_id] | ||
| return None | ||
|
|
||
| rows: list[dict] = [] | ||
| for row in metaclonotypes.table.iter_rows(named=True): | ||
| c1 = _find_clone(str(row["clonotype_id_1"])) | ||
| c2 = _find_clone(str(row["clonotype_id_2"])) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Metaclonotypes, functional diversity, preparing to implement GIANA/iSMART/TCRdist-like approaches for comparison