release: 3.4.0 — mir CLI, uv dev setup, docs overhaul, correct_batch#48
Merged
Conversation
…/repertoire Robustness (degenerate-input -> silent NaN/0/inf, now a clear error): - repertoire: unbiased MMD raises at n_eff<=1 (was /0 on singleton samples); empty / all-zero-count repertoires raise via _sample_weights (was NaN Phi/n_eff). - prototypes: load_prototypes rejects n<=0 (df.head(-k) silently changed the prototype set + its hash, breaking embedding comparability). - density: calibrate_radius raises on a non-positive radius (short/identical junctions -> empty balls); neighbor_enrichment raises on empty obs/bg and pseudocount<=0; backend error message now lists kdtree. Optimization: - density: default backend 'exact'->'kdtree' (also exact, multithreaded, 5-9x; bit-identical at fixed radius, +-1 at balloon boundary -- re-verify analysis balloon baselines); fit_density_space auto-chunks above 500k pooled rows. - repertoire: fit_repertoire_space samples frame rows before embedding (bit- identical, no full raw matrix); hla_stratified_mmd O(S^2) loop -> indicator matmul; class_witness gains a precomputed witness= fast-path. Tests: singleton/empty/zero-count guards, negative-n, calibrate rejection, empty/pseudocount guards, multi-allele HLA, precomputed-witness parity. Full suite 127 passed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…DMAP Phase 1 of the 'vdjtools at the embedding level' roadmap: promote the cohort/clinical glue that lived in the analysis repo into first-class library API. - mir/cohort.py (NEW): the digital donor. fit_donor_embeddings/DonorCohort fuse per-chain identity(kernel-mean, cross-sample PCA) + diversity + coverage across loci through ONE explain.ChannelBuilder, with an extra_channels hook for the analysis's tissue/clinical blocks. Comparability bites twice (per-locus prototype_hash + stored identity PCA): save/load verify every hash, transform is the only held-out path. Plus residualize (batch cookbook), cluster_samples (MMD->precomputed cluster), incidence_biomarkers (subject-incidence Fisher, delegating to vdjtools). Generalizes _tcga_embedding.build_embedding. - mir/bench/eval.py (NEW): the scorers channel_report consumes, kept out of explain.py so it stays scorer-free — cv_auc/held_out_auc (classification), cv_cindex/km_logrank (Cox survival, [bench]), kmer_matrix (baseline). - mir/repertoire.py: fit_repertoire_spaces (one basis per locus) + centroid_atypicality (Phi-geometry op for the atypicality channel). - ROADMAP.md (NEW): durable audit + phased plan (three verbs make/measure/ generate); README + CLAUDE.md updated (module table, layout, open loops). Tests: test_cohort (fusion, missing-chain impute, transform parity, hash-verified save/load, residualize, cluster_samples) + test_eval + centroid_atypicality. Full suite 137 passed. No new deps. Analysis-repo follow-up: refactor build_embedding onto fit_donor_embeddings and re-verify pan-cancer ΔC. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Feature release; no public Python API removed. - CLI: `mir embed clonotypes` (per-clonotype table) / `mir embed repertoires` (per-sample-per-chain Φ(S), optional --mmd). argparse/stdlib, reads via vdjtools.io. [project.scripts] mir=mir.cli:main. tests/test_cli.py. - Dev: conda → repo-local .venv via uv. setup.sh rewritten (bash/zsh; --dev-parents / --docs / --tests); environment.yml removed. Runtime unchanged (py3-none-any). - Deps: vdjtools>=3.0.0; pynndescent split out of [bench] into a new [ann] extra so [bench] resolves cleanly (no numba/llvmlite). - Docs: use-case-driven user guide, both CLI commands, examples page, logo + sample-embedding schematic + real depth-robustness figure, mir.cohort / mir.bench.eval added to the API ref. Zero-warning Sphinx build. - correct_batch: mir.repertoire.correct_batch — Harmony-like cluster-aware batch correction (reduces to cohort.residualize at n_clusters=1/theta=0), aligning the library with the manuscript's prop:batch claim. Test in test_repertoire.py. - Cleanup (audit): DEFAULT_GAP_POSITIONS defined once in distances.junction and imported (was 3 copies); cluster_samples/AntigenMetric/bench.__init__ docstrings; drop an unused rng in cohort._demo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
1 participant
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.
Release 3.4.0. Feature release — no public Python API removed. Brings
master(3.3.0) up to 3.4.0; also folds in the already-pushed Phase 0/1 cohort-tier commits.Highlights
mir embed clonotypes(per-clonotype table) /mir embed repertoires(per-sample-per-chain Φ(S),--mmd). argparse/stdlib, reads viavdjtools.io;[project.scripts] mir=mir.cli:main. Tests intests/test_cli.py..venv;setup.shrewritten (bash/zsh,--dev-parents/--docs/--tests);environment.ymlremoved. Runtime unchanged (py3-none-any).vdjtools>=3.0.0;pynndescentsplit from[bench]into a new[ann]extra so[bench]resolves cleanly (no numba/llvmlite).mir.cohort/mir.bench.evaladded to the API ref. Zero-warning Sphinx build.mir.repertoire.correct_batch— Harmony-like cluster-aware batch correction (reduces tocohort.residualizeatn_clusters=1/theta=0), aligning the library with the manuscript'sprop:batchclaim; test intests/test_repertoire.py.DEFAULT_GAP_POSITIONSdefined once indistances.junction(was 3 copies); docstring fixes; drop an unused local.Verification
.venv): 131 passed, 6 skipped (torch + pynndescent, correctly absent from the base install).make html.py3-none-any,twine checkPASSED,mir 3.4.0works from a fresh isolated install.To finish the release (after merge)
v3.4.0onmaster.v3.4.0→ triggerspublish.yml→ PyPI. (The publish is intentionally left as a manual step.)🤖 Generated with Claude Code