isoform-dominance 2.0.0__tar.gz

isoform_dominance-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sangeon Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

isoform_dominance-2.0.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: isoform-dominance
+Version: 2.0.0
+Summary: Config-driven isoform-usage quantification and discrimination from bulk RNA-seq
+Author: Sangeon Kim
+License: MIT
+Project-URL: Homepage, https://github.com/charliekim97/isoform-dominance-pipeline
+Project-URL: Repository, https://github.com/charliekim97/isoform-dominance-pipeline
+Keywords: RNA-seq,alternative splicing,isoform quantification,Salmon,reproducible pipeline
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Dynamic: license-file
+
+# isoform-dominance
+
+[![CI](https://github.com/charliekim97/isoform-dominance-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/charliekim97/isoform-dominance-pipeline/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License: MIT](https://img.shields.io/badge/License-MIT-green)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20672052.svg)](https://doi.org/10.5281/zenodo.20672052)
+
+**Isoform-usage quantification *and discrimination* from bulk RNA-seq — one config away for any gene.**
+
+Most isoform analyses stumble on two things: deciding *which transcripts form a functional
+group*, and knowing whether short reads can even *tell the groups apart*. `isoform-dominance`
+handles both, then quantifies and tests the comparison end-to-end:
+
+```
+annotate  gene symbol      → proposed isoform groups        (Ensembl, by 3' terminal exon)
+identify  config           → are the groups distinguishable by short reads? (k-mer uniqueness)
+extract   Salmon quant.sf  → per-donor isoform-group TPM
+stats     per-donor TPM    → paired Wilcoxon, per cohort + combined, + figure
+qc        marker TPM       → contamination control (is the signal a cell-type artifact?)
+```
+
+![example output](docs/example_output.png)
+
+*Bundled self-test: short LEPR isoform (LepRa) predominates over the long isoform (LepRb) in
+control human choroid plexus across two independent cohorts; combined n = 11, P = 1×10⁻³.*
+
+---
+
+## Install
+
+```bash
+pip install -e ".[dev]"        # from a clone
+isoform-dominance --version
+```
+
+## Verify it works (no downloads, seconds)
+
+```bash
+isoform-dominance selftest
+# or: pytest -q
+```
+reproduces the published LEPR result (5/5, 6/6, combined n=11 P=9.8e-4) on a clean machine.
+
+## What makes it more than a quantifier
+
+**1. Auto isoform grouping (`annotate`).** Give a gene symbol; it pulls the gene's
+protein-coding transcripts from Ensembl, clusters them by their 3' terminal-exon splice
+acceptor (the alternative last exon that defines functional isoform classes), and proposes a
+comparison you review and rename.
+```bash
+isoform-dominance annotate --gene LEPR --out config.json
+#   iso_896aa : 7 transcripts   (short / LepRa)
+#   iso_1165aa: 2 transcripts   (long / LepRb, canonical)
+```
+
+**2. Identifiability guardrail (`identify`).** Short reads can only quantify an isoform group
+that has *unique* sequence. This checks per-group unique k-mers and **refuses to pretend** a
+group is measurable when it isn't.
+```bash
+isoform-dominance identifiability --config config.json
+#   [OK] iso_896aa : 3399 unique k-mers
+#   [OK] iso_1165aa: 5369 unique k-mers
+#   primary_comparison distinguishable by short reads: True
+```
+
+## Full workflow (real data)
+
+```bash
+# 0) build a decoy-aware index once (Salmon + GENCODE) — see scripts/01_salmon_quant.sbatch
+# 1) quantify on an HPC cluster:
+sbatch scripts/01_salmon_quant.sbatch                    # -> quant/<donor>/quant.sf
+# 2) extract per cohort:
+isoform-dominance extract --config config.json --quantdir quant \
+    --samplemap example/sample_map_GSE228458.csv --cohort GSE228458 --out perdonor_GSE228458.csv
+# 3) stats + figure:
+isoform-dominance stats --config config.json --condition control \
+    --perdonor GSE228458=perdonor_GSE228458.csv --perdonor GSE137619=perdonor_GSE137619.csv \
+    --out results/dominance
+# 4) optional contamination control:
+isoform-dominance qc --config config.json \
+    --markers GSE228458=markers_228.csv --target GSE228458=perdonor_GSE228458.csv --out results/qc
+```
+
+## Statistical notes
+
+- Donor-level two-sided **exact Wilcoxon signed-rank** (`scipy.stats.wilcoxon`), per cohort + combined.
+- **Small-n floor:** n = 5 cannot reach P < 0.05 in the exact two-sided test (floor 0.0625);
+  report exact P + direction (e.g. 5/5) and combine concordant cohorts for the summary statistic.
+- Effect size = median fold-change, reported alongside significance.
+
+## Layout
+
+```
+src/isoform_dominance/   annotate · identifiability · extract · stats · contamination · cli · _selftest
+tests/                   pytest (offline; reproduces the published result + unit tests)
+scripts/01_salmon_quant.sbatch
+example/                 config + sample maps
+.github/workflows/ci.yml docs/  pyproject.toml  CITATION.cff  LICENSE
+```
+
+## Citation
+
+Cite this repository (see `CITATION.cff`, DOI 10.5281/zenodo.20672052) and Salmon:
+Patro, R. et al. *Nat. Methods* **14**, 417–419 (2017). https://doi.org/10.1038/nmeth.4197
+
+## License
+
+MIT (see `LICENSE`).

isoform_dominance-2.0.0/README.md

@@ -0,0 +1,108 @@
+# isoform-dominance
+
+[![CI](https://github.com/charliekim97/isoform-dominance-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/charliekim97/isoform-dominance-pipeline/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License: MIT](https://img.shields.io/badge/License-MIT-green)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20672052.svg)](https://doi.org/10.5281/zenodo.20672052)
+
+**Isoform-usage quantification *and discrimination* from bulk RNA-seq — one config away for any gene.**
+
+Most isoform analyses stumble on two things: deciding *which transcripts form a functional
+group*, and knowing whether short reads can even *tell the groups apart*. `isoform-dominance`
+handles both, then quantifies and tests the comparison end-to-end:
+
+```
+annotate  gene symbol      → proposed isoform groups        (Ensembl, by 3' terminal exon)
+identify  config           → are the groups distinguishable by short reads? (k-mer uniqueness)
+extract   Salmon quant.sf  → per-donor isoform-group TPM
+stats     per-donor TPM    → paired Wilcoxon, per cohort + combined, + figure
+qc        marker TPM       → contamination control (is the signal a cell-type artifact?)
+```
+
+![example output](docs/example_output.png)
+
+*Bundled self-test: short LEPR isoform (LepRa) predominates over the long isoform (LepRb) in
+control human choroid plexus across two independent cohorts; combined n = 11, P = 1×10⁻³.*
+
+---
+
+## Install
+
+```bash
+pip install -e ".[dev]"        # from a clone
+isoform-dominance --version
+```
+
+## Verify it works (no downloads, seconds)
+
+```bash
+isoform-dominance selftest
+# or: pytest -q
+```
+reproduces the published LEPR result (5/5, 6/6, combined n=11 P=9.8e-4) on a clean machine.
+
+## What makes it more than a quantifier
+
+**1. Auto isoform grouping (`annotate`).** Give a gene symbol; it pulls the gene's
+protein-coding transcripts from Ensembl, clusters them by their 3' terminal-exon splice
+acceptor (the alternative last exon that defines functional isoform classes), and proposes a
+comparison you review and rename.
+```bash
+isoform-dominance annotate --gene LEPR --out config.json
+#   iso_896aa : 7 transcripts   (short / LepRa)
+#   iso_1165aa: 2 transcripts   (long / LepRb, canonical)
+```
+
+**2. Identifiability guardrail (`identify`).** Short reads can only quantify an isoform group
+that has *unique* sequence. This checks per-group unique k-mers and **refuses to pretend** a
+group is measurable when it isn't.
+```bash
+isoform-dominance identifiability --config config.json
+#   [OK] iso_896aa : 3399 unique k-mers
+#   [OK] iso_1165aa: 5369 unique k-mers
+#   primary_comparison distinguishable by short reads: True
+```
+
+## Full workflow (real data)
+
+```bash
+# 0) build a decoy-aware index once (Salmon + GENCODE) — see scripts/01_salmon_quant.sbatch
+# 1) quantify on an HPC cluster:
+sbatch scripts/01_salmon_quant.sbatch                    # -> quant/<donor>/quant.sf
+# 2) extract per cohort:
+isoform-dominance extract --config config.json --quantdir quant \
+    --samplemap example/sample_map_GSE228458.csv --cohort GSE228458 --out perdonor_GSE228458.csv
+# 3) stats + figure:
+isoform-dominance stats --config config.json --condition control \
+    --perdonor GSE228458=perdonor_GSE228458.csv --perdonor GSE137619=perdonor_GSE137619.csv \
+    --out results/dominance
+# 4) optional contamination control:
+isoform-dominance qc --config config.json \
+    --markers GSE228458=markers_228.csv --target GSE228458=perdonor_GSE228458.csv --out results/qc
+```
+
+## Statistical notes
+
+- Donor-level two-sided **exact Wilcoxon signed-rank** (`scipy.stats.wilcoxon`), per cohort + combined.
+- **Small-n floor:** n = 5 cannot reach P < 0.05 in the exact two-sided test (floor 0.0625);
+  report exact P + direction (e.g. 5/5) and combine concordant cohorts for the summary statistic.
+- Effect size = median fold-change, reported alongside significance.
+
+## Layout
+
+```
+src/isoform_dominance/   annotate · identifiability · extract · stats · contamination · cli · _selftest
+tests/                   pytest (offline; reproduces the published result + unit tests)
+scripts/01_salmon_quant.sbatch
+example/                 config + sample maps
+.github/workflows/ci.yml docs/  pyproject.toml  CITATION.cff  LICENSE
+```
+
+## Citation
+
+Cite this repository (see `CITATION.cff`, DOI 10.5281/zenodo.20672052) and Salmon:
+Patro, R. et al. *Nat. Methods* **14**, 417–419 (2017). https://doi.org/10.1038/nmeth.4197
+
+## License
+
+MIT (see `LICENSE`).

isoform_dominance-2.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "isoform-dominance"
+version = "2.0.0"
+description = "Config-driven isoform-usage quantification and discrimination from bulk RNA-seq"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Sangeon Kim" }]
+keywords = ["RNA-seq", "alternative splicing", "isoform quantification", "Salmon", "reproducible pipeline"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = ["numpy>=1.24", "scipy>=1.10", "matplotlib>=3.7"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov>=4"]
+
+[project.urls]
+Homepage = "https://github.com/charliekim97/isoform-dominance-pipeline"
+Repository = "https://github.com/charliekim97/isoform-dominance-pipeline"
+
+[project.scripts]
+isoform-dominance = "isoform_dominance.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

isoform_dominance-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

isoform_dominance-2.0.0/src/isoform_dominance/__init__.py

@@ -0,0 +1,12 @@
+"""isoform-dominance: config-driven isoform-usage quantification and discrimination
+from bulk RNA-seq.
+
+Modules
+-------
+annotate        gene symbol -> proposed isoform groups (Ensembl)
+identifiability are two isoform groups distinguishable by short reads?
+extract         Salmon quant.sf -> per-donor isoform-group TPM
+stats           paired Wilcoxon + figure
+contamination   marker-based contamination control
+"""
+__version__ = "2.0.0"

isoform_dominance-2.0.0/src/isoform_dominance/_selftest.py

@@ -0,0 +1,101 @@
+"""Download-free end-to-end self-test.
+
+Generates synthetic Salmon quant.sf files from the real per-transcript LEPR TPM values of
+the published analysis, runs extract + stats (+ contamination), and asserts the published
+result is reproduced: combined n=11, 11/11 short>long, paired Wilcoxon P ~= 9.77e-4.
+"""
+import tempfile, os, csv, shutil
+from . import extract, stats, contamination
+
+# donor: (ENST00000371060, ENST00000616738, ENST00000349533) TPM  (control choroid plexus)
+DATA = {
+    "GSE228458": [("ctrl1", 6.521574, 36.556954, 1.314808), ("ctrl2", 1.250224, 8.637422, 0.349876),
+                  ("ctrl3", 2.238854, 13.496253, 0.704219), ("ctrl4", 3.684999, 15.015936, 0.721059),
+                  ("ctrl5", 0.495420, 6.599920, 1.440164)],
+    "GSE137619": [("ctrl1", 9.130898, 9.898263, 0.351829), ("ctrl2", 5.896581, 5.928743, 0.216838),
+                  ("ctrl3", 7.516654, 20.317774, 1.033148), ("ctrl4", 1.804960, 3.059827, 0.143530),
+                  ("ctrl5", 3.730544, 2.848134, 0.203918), ("ctrl6", 2.582321, 4.337355, 0.166890)],
+}
+CONFIG = {
+    "gene": "LEPR",
+    "groups": {"short": ["ENST00000371060", "ENST00000616738"], "long": ["ENST00000349533"]},
+    "primary_comparison": ["short", "long"],
+    "contamination_qc": {"target_group": "long",
+                         "marker_panels": {"tissue": ["TTR", "FOLR1", "OTX2", "AQP1"],
+                                           "contaminant": ["RBFOX3", "SNAP25", "MAP2", "GAD1"]}},
+}
+EXPECT = {"GSE228458": (5, 5), "GSE137619": (6, 6), "COMBINED": (11, 11, 9.7656e-4)}
+
+
+def _write_quant(path, t1, t2, tl):
+    os.makedirs(path, exist_ok=True)
+    with open(os.path.join(path, "quant.sf"), "w") as f:
+        f.write("Name\tLength\tEffectiveLength\tTPM\tNumReads\n")
+        f.write("ENST00000371060.5\t3000\t2800\t%s\t100\n" % t1)
+        f.write("ENST00000616738.1\t3000\t2800\t%s\t100\n" % t2)
+        f.write("ENST00000349533.11\t4000\t3800\t%s\t10\n" % tl)
+
+
+def generate(base):
+    out = {}
+    for cohort, rows in DATA.items():
+        qd = os.path.join(base, "quant_%s" % cohort)
+        for donor, t1, t2, tl in rows:
+            _write_quant(os.path.join(qd, donor), t1, t2, tl)
+        sm = os.path.join(base, "sample_map_%s.csv" % cohort)
+        with open(sm, "w", newline="") as f:
+            w = csv.writer(f); w.writerow(["donor", "condition", "SRR"])
+            for donor, *_ in rows:
+                w.writerow([donor, "control", "SYNTHETIC"])
+        mk = os.path.join(base, "markers_%s.csv" % cohort)
+        with open(mk, "w", newline="") as f:
+            w = csv.writer(f)
+            w.writerow(["donor", "TTR", "FOLR1", "OTX2", "AQP1", "RBFOX3", "SNAP25", "MAP2", "GAD1"])
+            for i, (donor, *_rest) in enumerate(rows):
+                w.writerow([donor, 40000 + i * 3000, 1500 + i * 90, 800 + i * 40, 1200 + i * 70,
+                            round(0.05 + 0.01 * i, 3), round(0.30 + 0.03 * i, 3),
+                            round(0.10 + 0.02 * i, 3), round(0.02 + 0.01 * i, 3)])
+        out[cohort] = {"quantdir": qd, "samplemap": sm, "markers": mk}
+    return out
+
+
+def run(base):
+    """Run the pipeline on synthetic data under `base`. Returns (ok, messages)."""
+    info = generate(base)
+    perdonor = {}
+    for cohort, p in info.items():
+        out = os.path.join(base, "perdonor_%s.csv" % cohort)
+        extract.run(CONFIG, p["quantdir"], p["samplemap"], cohort, out)
+        perdonor[cohort] = out
+    res = stats.run(CONFIG, "control", perdonor, os.path.join(base, "result"))
+    msgs, ok = [], True
+    by = {r[0]: r for r in res["per_cohort"]}
+    for coh, (n, ngt) in [("GSE228458", EXPECT["GSE228458"]), ("GSE137619", EXPECT["GSE137619"])]:
+        gn, gng = by[coh][1], by[coh][2]
+        good = gn == n and gng == ngt; ok &= good
+        msgs.append("[%s] %s %d/%d short>long" % ("OK" if good else "FAIL", coh, gng, gn))
+    cn, cgt, cp, _ = res["combined"]
+    en, eng, ep = EXPECT["COMBINED"]
+    cgood = cn == en and cgt == eng and abs(cp - ep) < 1e-4; ok &= cgood
+    msgs.append("[%s] COMBINED %d/%d P=%.4g (expect %.4g)" % ("OK" if cgood else "FAIL", cgt, cn, cp, ep))
+    fig_ok = os.path.exists(os.path.join(base, "result.png")); ok &= fig_ok
+    msgs.append("[%s] dominance figure produced" % ("OK" if fig_ok else "FAIL"))
+    rows = contamination.run(CONFIG, {c: info[c]["markers"] for c in info},
+                             {c: perdonor[c] for c in info}, os.path.join(base, "qc"))
+    ratios = [r[4] for r in rows]
+    qc_ok = os.path.exists(os.path.join(base, "qc.png")) and all(x < 0.2 for x in ratios); ok &= qc_ok
+    msgs.append("[%s] contamination-QC purity ratios %s < 0.2"
+                % ("OK" if qc_ok else "FAIL", [round(x, 3) for x in ratios]))
+    return ok, msgs
+
+
+def main():
+    work = tempfile.mkdtemp(prefix="idp_selftest_")
+    try:
+        ok, msgs = run(work)
+        for m in msgs:
+            print("  " + m)
+        print("\n%s" % ("PASS - reproduces the published LEPR result." if ok else "FAIL"))
+        return 0 if ok else 1
+    finally:
+        shutil.rmtree(work, ignore_errors=True)

isoform_dominance-2.0.0/src/isoform_dominance/annotate.py

@@ -0,0 +1,99 @@
+"""Gene symbol -> proposed isoform groups via the Ensembl REST API.
+
+The hard part of isoform analysis is deciding which transcripts form a functional
+group. This module clusters a gene's protein-coding transcripts by their 3' terminal-exon
+splice acceptor — the alternative last exon that distinguishes functional isoform classes
+(e.g. a long signalling form vs a short truncated form) — and proposes a two-group
+comparison (canonical-isoform cluster vs the largest alternative cluster) that the user
+reviews and renames before use.
+"""
+import json
+import urllib.request
+
+ENSEMBL = "https://rest.ensembl.org"
+
+
+def _get(path, timeout=30):
+    req = urllib.request.Request(ENSEMBL + path, headers={"Content-Type": "application/json"})
+    return json.load(urllib.request.urlopen(req, timeout=timeout))
+
+
+def fetch_transcripts(gene, species="homo_sapiens"):
+    """Return {gene, species, strand, transcripts:[{id, protein_aa, terminal_acceptor, is_canonical}]}."""
+    g = _get("/lookup/symbol/%s/%s?expand=1" % (species, gene))
+    strand = g["strand"]
+    canonical = (g.get("canonical_transcript") or "").split(".")[0]
+    out = []
+    for t in g.get("Transcript", []):
+        if t.get("biotype") != "protein_coding":
+            continue
+        tl = t.get("Translation") or {}
+        plen = tl.get("length")
+        if not plen:
+            continue
+        exons = t["Exon"]
+        if strand == 1:
+            term = max(exons, key=lambda e: e["end"]); acc = term["start"]
+        else:
+            term = min(exons, key=lambda e: e["start"]); acc = term["end"]
+        tid = t["id"].split(".")[0]
+        out.append({"id": tid, "protein_aa": plen, "terminal_acceptor": acc,
+                    "is_canonical": (t.get("is_canonical", 0) == 1) or (tid == canonical)})
+    if not out:
+        raise ValueError("No protein-coding transcripts with a translation found for %s" % gene)
+    return {"gene": gene, "species": species, "strand": strand, "transcripts": out}
+
+
+def cluster_by_terminal_exon(info):
+    """Group transcripts by 3' terminal-exon acceptor coordinate."""
+    clusters = {}
+    for t in info["transcripts"]:
+        clusters.setdefault(t["terminal_acceptor"], []).append(t)
+    out = []
+    for acc, txs in clusters.items():
+        lens = sorted(x["protein_aa"] for x in txs)
+        out.append({"acceptor": acc, "rep_aa": lens[len(lens) // 2], "n": len(txs),
+                    "canonical": any(x["is_canonical"] for x in txs),
+                    "ids": sorted(x["id"] for x in txs)})
+    return sorted(out, key=lambda c: -c["n"])
+
+
+def propose_groups(info):
+    clusters = cluster_by_terminal_exon(info)
+    canon = next((c for c in clusters if c["canonical"]), None) or max(clusters, key=lambda c: c["rep_aa"])
+    others = sorted([c for c in clusters if c is not canon], key=lambda c: (-c["n"], -c["rep_aa"]))
+    alt = others[0] if others else None
+    lbl_canon = "iso_%daa" % canon["rep_aa"]
+    groups = {lbl_canon: canon["ids"]}
+    primary = [lbl_canon]
+    if alt:
+        lbl_alt = "iso_%daa" % alt["rep_aa"]
+        if lbl_alt == lbl_canon:
+            lbl_alt += "_alt"
+        groups[lbl_alt] = alt["ids"]
+        primary = [lbl_alt, lbl_canon]  # alternative (often shorter) first
+    return groups, primary, clusters
+
+
+def build_config(gene, species="homo_sapiens"):
+    """Build a reviewable config.json dict for `gene` from live Ensembl annotation."""
+    info = fetch_transcripts(gene, species)
+    groups, primary, clusters = propose_groups(info)
+    return {
+        "gene": gene, "species": species, "reference": "Ensembl REST (live annotation)",
+        "groups": groups, "primary_comparison": primary,
+        "_proposed": ("Auto-proposed by `isoform-dominance annotate`. Groups = protein-coding "
+                      "transcripts sharing a 3' terminal-exon splice acceptor (isoform-defining "
+                      "alternative last exon). REVIEW and rename to functional names "
+                      "(e.g. short/long) before use; smaller clusters are listed under _clusters."),
+        "_clusters": [{"terminal_acceptor": c["acceptor"], "rep_protein_aa": c["rep_aa"],
+                       "n_transcripts": c["n"], "contains_canonical": c["canonical"],
+                       "transcripts": c["ids"]} for c in clusters],
+    }
+
+
+def run(gene, out, species="homo_sapiens"):
+    cfg = build_config(gene, species)
+    with open(out, "w") as f:
+        json.dump(cfg, f, indent=2)
+    return cfg

isoform_dominance-2.0.0/src/isoform_dominance/cli.py

@@ -0,0 +1,118 @@
+"""Unified command-line interface: isoform-dominance <subcommand>."""
+import argparse, json, sys
+from urllib.error import URLError, HTTPError
+from . import __version__, io, extract, stats, contamination, annotate, identifiability
+
+
+def _kv(items):
+    return dict(s.split("=", 1) for s in (items or []))
+
+
+def _net_fail(e):
+    print("Ensembl request failed (%s). Check your network connection, the gene symbol, "
+          "and species, or supply sequences offline." % e, file=sys.stderr)
+    return 1
+
+
+def cmd_annotate(a):
+    try:
+        cfg = annotate.run(a.gene, a.out, species=a.species)
+    except (URLError, HTTPError) as e:
+        return _net_fail(e)
+    print("Proposed groups for %s -> %s" % (a.gene, a.out))
+    for g, ids in cfg["groups"].items():
+        print("  %s: %d transcripts" % (g, len(ids)))
+    print("  primary_comparison:", cfg["primary_comparison"])
+    print("  REVIEW _proposed/_clusters and rename groups before use.")
+
+
+def cmd_identifiability(a):
+    cfg = io.load_config(a.config)
+    seqs = json.load(open(a.sequences)) if a.sequences else None
+    try:
+        res = identifiability.analyze(cfg, k=a.k, sequences=seqs)
+    except (URLError, HTTPError) as e:
+        return _net_fail(e)
+    print("Identifiability (k=%d):" % res["k"])
+    for g, r in res["groups"].items():
+        flag = "OK" if r["distinguishable"] else "NOT DISTINGUISHABLE"
+        print("  [%s] %s: %d unique k-mers (%d transcripts)"
+              % (flag, g, r["n_unique_kmers"], r["n_transcripts"]))
+    print("  primary_comparison distinguishable by short reads:", res["primary_distinguishable"])
+    if not res["primary_distinguishable"]:
+        print("  WARNING: a primary group has no unique k-mers - short-read quantification "
+              "cannot resolve it. Reconsider the grouping or use long reads.", file=sys.stderr)
+        return 2
+    return 0
+
+
+def cmd_extract(a):
+    n = extract.run(io.load_config(a.config), a.quantdir, a.samplemap, a.cohort, a.out)
+    print("wrote %s (n=%d donors)" % (a.out, n))
+
+
+def cmd_stats(a):
+    res = stats.run(io.load_config(a.config), a.condition, _kv(a.perdonor), a.out)
+    for name, n, ngt, p, fold in res["per_cohort"]:
+        print("  %-12s n=%d  %d/%d  fold=%.1fx  P=%.4g" % (name, n, ngt, n, fold, p))
+    cn, cgt, cp, cfold = res["combined"]
+    print("  COMBINED     n=%d  %d/%d  fold=%.1fx  P=%.4g" % (cn, cgt, cn, cfold, cp))
+    print("wrote %s.{png,pdf,svg} + %s_stats.csv" % (a.out, a.out))
+
+
+def cmd_qc(a):
+    rows = contamination.run(io.load_config(a.config), _kv(a.markers), _kv(a.target), a.out)
+    for name, n, rho, p, ratio in rows:
+        print("  %-12s n=%d  rho=%+.3f  P=%.3f  contam/tissue=%.3f" % (name, n, rho, p, ratio))
+    print("wrote %s.{png,pdf,svg} + %s_scores.csv" % (a.out, a.out))
+
+
+def cmd_selftest(a):
+    from . import _selftest
+    return _selftest.main()
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="isoform-dominance",
+                                description="Isoform-usage quantification and discrimination from bulk RNA-seq.")
+    p.add_argument("--version", action="version", version="isoform-dominance %s" % __version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("annotate", help="gene symbol -> proposed isoform groups (Ensembl)")
+    s.add_argument("--gene", required=True); s.add_argument("--species", default="homo_sapiens")
+    s.add_argument("--out", required=True); s.set_defaults(func=cmd_annotate)
+
+    s = sub.add_parser("identifiability", aliases=["identify"],
+                       help="are the groups distinguishable by short reads?")
+    s.add_argument("--config", required=True); s.add_argument("--k", type=int, default=31)
+    s.add_argument("--sequences", help="optional JSON {transcript_id: cdna} (offline)")
+    s.set_defaults(func=cmd_identifiability)
+
+    s = sub.add_parser("extract", help="quant.sf -> per-donor isoform-group TPM")
+    for x in ("config", "quantdir", "samplemap", "cohort", "out"):
+        s.add_argument("--" + x, required=True)
+    s.set_defaults(func=cmd_extract)
+
+    s = sub.add_parser("stats", help="paired Wilcoxon + figure")
+    s.add_argument("--config", required=True); s.add_argument("--condition", default="control")
+    s.add_argument("--perdonor", action="append", required=True, help="NAME=perdonor.csv (repeatable)")
+    s.add_argument("--out", required=True); s.set_defaults(func=cmd_stats)
+
+    s = sub.add_parser("qc", help="contamination control")
+    s.add_argument("--config", required=True)
+    s.add_argument("--markers", action="append", required=True, help="NAME=marker_tpm.csv")
+    s.add_argument("--target", action="append", required=True, help="NAME=perdonor.csv")
+    s.add_argument("--out", required=True); s.set_defaults(func=cmd_qc)
+
+    s = sub.add_parser("selftest", help="run the download-free reproducibility test")
+    s.set_defaults(func=cmd_selftest)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    return args.func(args) or 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

isoform_dominance-2.0.0/src/isoform_dominance/contamination.py

@@ -0,0 +1,68 @@
+"""Contamination control: does a target isoform's signal track a contaminating cell type?"""
+import csv, os, math
+import numpy as np
+from scipy.stats import spearmanr
+import matplotlib as mpl; mpl.use("Agg")
+import matplotlib.pyplot as plt
+
+PALETTE = ["#4C72B0", "#DD8452", "#55A868", "#C44E52"]
+
+
+def _log2p1(x):
+    return math.log2(x + 1.0)
+
+
+def load_markers(path, tissue, contaminant):
+    out = {}
+    with open(path) as f:
+        for r in csv.DictReader(f):
+            t = np.mean([_log2p1(float(r[g])) for g in tissue if g in r])
+            c = np.mean([_log2p1(float(r[g])) for g in contaminant if g in r])
+            out[r["donor"]] = (t, c, (c / t if t > 0 else float("nan")))
+    return out
+
+
+def load_target(path, target_group):
+    col = "%s_TPM" % target_group
+    with open(path) as f:
+        return {r["donor"]: float(r[col]) for r in csv.DictReader(f)}
+
+
+def run(config, markers, targets, out):
+    """markers/targets: {cohort: path}. Writes <out>.{png,pdf,svg}+_scores.csv. Returns rows."""
+    qc = config["contamination_qc"]
+    tg = qc["target_group"]
+    tissue = qc["marker_panels"]["tissue"]; contam = qc["marker_panels"]["contaminant"]
+    names = list(markers)
+    mpl.rcParams.update({"font.family": "sans-serif", "font.sans-serif": ["Arial", "DejaVu Sans"],
+                         "font.size": 9, "pdf.fonttype": 42, "svg.fonttype": "none"})
+    os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+    fig, axes = plt.subplots(1, len(names), figsize=(3.6 * len(names), 3.4), squeeze=False)
+    srows = []
+    for i, name in enumerate(names):
+        m = load_markers(markers[name], tissue, contam)
+        t = load_target(targets[name], tg)
+        donors = [d for d in m if d in t]
+        cs = np.array([m[d][1] for d in donors])
+        ratio = np.array([m[d][2] for d in donors])
+        tv = np.array([t[d] for d in donors])
+        rho, p = spearmanr(cs, tv)
+        srows.append((name, len(donors), rho, p, float(np.nanmedian(ratio))))
+        ax = axes[0, i]; c = PALETTE[i % len(PALETTE)]
+        ax.scatter(cs, tv, s=36, c=c, edgecolor="white", lw=0.5, zorder=3)
+        ax.set_xlabel("contamination score\n[mean log2(TPM+1), contaminant]")
+        ax.set_ylabel("%s (%s) TPM" % (config.get("gene", "target"), tg))
+        ax.set_title("%s (n=%d)" % (name, len(donors)), fontsize=9.5)
+        ax.text(0.03, 0.97, "rho=%.2f\nP=%.2f" % (rho, p), transform=ax.transAxes, va="top",
+                fontsize=8, bbox=dict(boxstyle="round,pad=0.3", fc="white", ec="#ccc", lw=0.6))
+        ax.spines[["top", "right"]].set_visible(False)
+    fig.suptitle("%s (%s) vs contamination - no positive dependence = genuine signal"
+                 % (config.get("gene", "target"), tg), fontsize=10, fontweight="bold", y=1.04)
+    for ext in ("png", "pdf", "svg"):
+        fig.savefig("%s.%s" % (out, ext), dpi=300, bbox_inches="tight")
+    plt.close(fig)
+    with open(out + "_scores.csv", "w", newline="") as f:
+        w = csv.writer(f); w.writerow(["cohort", "n", "spearman_rho", "spearman_P", "median_contam_tissue_ratio"])
+        for r in srows:
+            w.writerow([r[0], r[1], "%.3f" % r[2], "%.4g" % r[3], "%.4f" % r[4]])
+    return srows

isoform_dominance-2.0.0/src/isoform_dominance/extract.py

@@ -0,0 +1,46 @@
+"""Extract per-donor isoform-group TPM from Salmon quant.sf (stdlib only)."""
+import csv, os, glob
+from .io import transcript_to_group, load_sample_map, primary_pair
+
+
+def extract(config, quantdir, samplemap, cohort):
+    """Return [(donor, condition, {group: tpm}), ...]. Reads quantdir/<donor>/quant.sf."""
+    groups = config["groups"]
+    tx2grp = transcript_to_group(groups)
+    cond = load_sample_map(samplemap)
+    rows = []
+    for q in sorted(glob.glob(os.path.join(quantdir, "*", "quant.sf"))):
+        donor = os.path.basename(os.path.dirname(q))
+        gt = {g: 0.0 for g in groups}
+        with open(q) as fh:
+            for row in csv.DictReader(fh, delimiter="\t"):
+                g = tx2grp.get(row["Name"].split(".")[0])
+                if g:
+                    gt[g] += float(row["TPM"])
+        rows.append((donor, cond.get(donor, "NA"), gt))
+    return rows
+
+
+def write_perdonor(config, rows, cohort, out):
+    groups = config["groups"]
+    a, b = primary_pair(config)
+    has_pair = len(config.get("primary_comparison", list(groups)[:2])) == 2
+    with open(out, "w", newline="") as f:
+        w = csv.writer(f)
+        head = ["cohort", "donor", "condition"] + ["%s_TPM" % g for g in groups]
+        if has_pair:
+            head.append("%s_fraction" % a)
+        w.writerow(head)
+        for donor, c, gt in rows:
+            line = [cohort, donor, c] + ["%.4f" % gt[g] for g in groups]
+            if has_pair:
+                s = gt[a] + gt[b]
+                line.append("%.4f" % (gt[a] / s) if s > 0 else "NA")
+            w.writerow(line)
+    return out
+
+
+def run(config, quantdir, samplemap, cohort, out):
+    rows = extract(config, quantdir, samplemap, cohort)
+    write_perdonor(config, rows, cohort, out)
+    return len(rows)

isoform_dominance-2.0.0/src/isoform_dominance/identifiability.py

@@ -0,0 +1,67 @@
+"""Are two isoform groups distinguishable by short reads?
+
+Short-read quantifiers (e.g. Salmon) can only apportion isoforms using sequence that is
+UNIQUE to one isoform group. If a group shares all of its sequence with another group, no
+short read can be assigned to it unambiguously and its abundance is not identifiable.
+
+This module fetches transcript cDNA (Ensembl, or supplied sequences), builds per-group
+k-mer sets, and reports each group's group-unique k-mer count. A group with zero unique
+k-mers is flagged as NOT distinguishable by short reads — an honest guardrail that most
+isoform analyses skip.
+"""
+import json
+import urllib.request
+
+ENSEMBL = "https://rest.ensembl.org"
+
+
+def _get_text(path, timeout=30):
+    req = urllib.request.Request(ENSEMBL + path, headers={"Content-Type": "text/plain"})
+    return urllib.request.urlopen(req, timeout=timeout).read().decode().strip()
+
+
+def fetch_cdna(transcript_id):
+    return _get_text("/sequence/id/%s?type=cdna" % transcript_id.split(".")[0])
+
+
+def kmers(seq, k):
+    seq = seq.upper()
+    return {seq[i:i + k] for i in range(len(seq) - k + 1)}
+
+
+def analyze(config, k=31, sequences=None):
+    """sequences: optional {transcript_id: cdna}. If None, fetched from Ensembl.
+    Returns {group: {n_unique_kmers, n_transcripts, distinguishable}} + summary."""
+    groups = config["groups"]
+    needed = {t.split(".")[0] for ids in groups.values() for t in ids}
+    seqs = dict(sequences or {})
+    for tid in needed:
+        if tid not in seqs:
+            seqs[tid] = fetch_cdna(tid)
+
+    group_kmers = {}
+    for g, ids in groups.items():
+        ks = set()
+        for t in ids:
+            ks |= kmers(seqs[t.split(".")[0]], k)
+        group_kmers[g] = ks
+
+    report = {}
+    for g, ks in group_kmers.items():
+        others = set()
+        for g2, ks2 in group_kmers.items():
+            if g2 != g:
+                others |= ks2
+        uniq = ks - others
+        report[g] = {"n_unique_kmers": len(uniq), "n_transcripts": len(groups[g]),
+                     "distinguishable": len(uniq) > 0}
+
+    pc = config.get("primary_comparison", list(groups)[:2])
+    primary_ok = all(report[g]["distinguishable"] for g in pc if g in report)
+    return {"k": k, "groups": report, "primary_comparison": pc,
+            "primary_distinguishable": primary_ok}
+
+
+def run(config, k=31, sequences=None):
+    res = analyze(config, k=k, sequences=sequences)
+    return res

isoform_dominance-2.0.0/src/isoform_dominance/io.py

@@ -0,0 +1,31 @@
+"""Shared IO helpers: config and sample-map loading."""
+import json, csv, os
+
+
+def load_config(path):
+    with open(path) as f:
+        return json.load(f)
+
+
+def transcript_to_group(groups):
+    """{group: [ENST,...]} -> {ENST(no version): group}."""
+    m = {}
+    for g, txs in groups.items():
+        for t in txs:
+            m[t.split(".")[0]] = g
+    return m
+
+
+def load_sample_map(path):
+    """CSV with columns donor,condition[,SRR] -> {donor: condition}."""
+    cond = {}
+    with open(path) as f:
+        for r in csv.DictReader(f):
+            cond[r["donor"]] = r.get("condition", "NA")
+    return cond
+
+
+def primary_pair(config):
+    groups = config["groups"]
+    pc = config.get("primary_comparison", list(groups)[:2])
+    return pc[0], pc[1]

isoform_dominance-2.0.0/src/isoform_dominance/stats.py

@@ -0,0 +1,68 @@
+"""Paired isoform-group statistics + figure."""
+import csv, os
+import numpy as np
+from scipy.stats import wilcoxon
+import matplotlib as mpl; mpl.use("Agg")
+import matplotlib.pyplot as plt
+from .io import primary_pair
+
+PALETTE = ["#4C72B0", "#DD8452", "#55A868", "#C44E52", "#8172B3", "#937860"]
+
+
+def load_perdonor(path, condition, gA, gB):
+    don, A, B = [], [], []
+    with open(path) as f:
+        for r in csv.DictReader(f):
+            if condition not in (None, "", "all") and r["condition"] != condition:
+                continue
+            don.append(r["donor"]); A.append(float(r["%s_TPM" % gA])); B.append(float(r["%s_TPM" % gB]))
+    return don, np.array(A), np.array(B)
+
+
+def paired_stat(A, B):
+    n = len(A); ngt = int(np.sum(A > B))
+    try:
+        p = wilcoxon(A, B, alternative="two-sided").pvalue
+    except Exception:
+        p = float("nan")
+    with np.errstate(divide="ignore", invalid="ignore"):
+        fold = float(np.median(A / B))
+    return n, ngt, p, fold
+
+
+def run(config, condition, cohorts, out):
+    """cohorts: {name: perdonor.csv}. Writes <out>.{png,pdf,svg} + <out>_stats.csv. Returns summary dict."""
+    gene = config.get("gene", "gene")
+    gA, gB = primary_pair(config)
+    mpl.rcParams.update({"font.family": "sans-serif", "font.sans-serif": ["Arial", "DejaVu Sans"],
+                         "font.size": 9, "pdf.fonttype": 42, "svg.fonttype": "none"})
+    os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+    names = list(cohorts)
+    fig, axes = plt.subplots(1, len(names), figsize=(3.6 * len(names), 3.6), squeeze=False)
+    allA, allB, statrows = [], [], []
+    for i, name in enumerate(names):
+        don, A, B = load_perdonor(cohorts[name], condition, gA, gB)
+        allA += list(A); allB += list(B)
+        n, ngt, p, fold = paired_stat(A, B); statrows.append((name, n, ngt, p, fold))
+        ax = axes[0, i]; c = PALETTE[i % len(PALETTE)]; fl = 1e-3
+        for k in range(n):
+            ax.plot([0, 1], [max(A[k], fl), max(B[k], fl)], color="#999", lw=0.8, zorder=1)
+        ax.scatter(np.zeros(n), np.clip(A, fl, None), s=34, c=c, edgecolor="white", lw=0.5, zorder=3)
+        ax.scatter(np.ones(n), np.clip(B, fl, None), s=34, c="#9aa0a6", edgecolor="white", lw=0.5, zorder=3)
+        ax.set_yscale("log"); ax.set_xlim(-0.4, 1.4); ax.set_xticks([0, 1]); ax.set_xticklabels([gA, gB])
+        ax.set_ylabel("%s TPM (log)" % gene); ax.set_title("%s (%s n=%d)" % (name, condition, n), fontsize=9.5)
+        ax.text(0.5, 1.16, "%d/%d  %.0fx  P=%.3f" % (ngt, n, fold, p), transform=ax.transAxes,
+                ha="center", va="top", fontsize=8, color="#333")
+        ax.spines[["top", "right"]].set_visible(False)
+    cn, cgt, cp, cfold = paired_stat(np.array(allA), np.array(allB))
+    fig.suptitle("%s: %s vs %s - combined %s n=%d, %d/%d, P=%.4g"
+                 % (gene, gA, gB, condition, cn, cgt, cn, cp), fontsize=10.5, fontweight="bold", y=1.04)
+    for ext in ("png", "pdf", "svg"):
+        fig.savefig("%s.%s" % (out, ext), dpi=300, bbox_inches="tight")
+    plt.close(fig)
+    with open(out + "_stats.csv", "w", newline="") as f:
+        w = csv.writer(f); w.writerow(["cohort", "n", "%s>%s" % (gA, gB), "median_fold", "paired_wilcoxon_P"])
+        for r in statrows:
+            w.writerow([r[0], r[1], "%d/%d" % (r[2], r[1]), "%.2f" % r[4], "%.4g" % r[3]])
+        w.writerow(["COMBINED", cn, "%d/%d" % (cgt, cn), "%.2f" % cfold, "%.4g" % cp])
+    return {"per_cohort": statrows, "combined": (cn, cgt, cp, cfold)}

isoform_dominance-2.0.0/src/isoform_dominance.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: isoform-dominance
+Version: 2.0.0
+Summary: Config-driven isoform-usage quantification and discrimination from bulk RNA-seq
+Author: Sangeon Kim
+License: MIT
+Project-URL: Homepage, https://github.com/charliekim97/isoform-dominance-pipeline
+Project-URL: Repository, https://github.com/charliekim97/isoform-dominance-pipeline
+Keywords: RNA-seq,alternative splicing,isoform quantification,Salmon,reproducible pipeline
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Dynamic: license-file
+
+# isoform-dominance
+
+[![CI](https://github.com/charliekim97/isoform-dominance-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/charliekim97/isoform-dominance-pipeline/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License: MIT](https://img.shields.io/badge/License-MIT-green)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20672052.svg)](https://doi.org/10.5281/zenodo.20672052)
+
+**Isoform-usage quantification *and discrimination* from bulk RNA-seq — one config away for any gene.**
+
+Most isoform analyses stumble on two things: deciding *which transcripts form a functional
+group*, and knowing whether short reads can even *tell the groups apart*. `isoform-dominance`
+handles both, then quantifies and tests the comparison end-to-end:
+
+```
+annotate  gene symbol      → proposed isoform groups        (Ensembl, by 3' terminal exon)
+identify  config           → are the groups distinguishable by short reads? (k-mer uniqueness)
+extract   Salmon quant.sf  → per-donor isoform-group TPM
+stats     per-donor TPM    → paired Wilcoxon, per cohort + combined, + figure
+qc        marker TPM       → contamination control (is the signal a cell-type artifact?)
+```
+
+![example output](docs/example_output.png)
+
+*Bundled self-test: short LEPR isoform (LepRa) predominates over the long isoform (LepRb) in
+control human choroid plexus across two independent cohorts; combined n = 11, P = 1×10⁻³.*
+
+---
+
+## Install
+
+```bash
+pip install -e ".[dev]"        # from a clone
+isoform-dominance --version
+```
+
+## Verify it works (no downloads, seconds)
+
+```bash
+isoform-dominance selftest
+# or: pytest -q
+```
+reproduces the published LEPR result (5/5, 6/6, combined n=11 P=9.8e-4) on a clean machine.
+
+## What makes it more than a quantifier
+
+**1. Auto isoform grouping (`annotate`).** Give a gene symbol; it pulls the gene's
+protein-coding transcripts from Ensembl, clusters them by their 3' terminal-exon splice
+acceptor (the alternative last exon that defines functional isoform classes), and proposes a
+comparison you review and rename.
+```bash
+isoform-dominance annotate --gene LEPR --out config.json
+#   iso_896aa : 7 transcripts   (short / LepRa)
+#   iso_1165aa: 2 transcripts   (long / LepRb, canonical)
+```
+
+**2. Identifiability guardrail (`identify`).** Short reads can only quantify an isoform group
+that has *unique* sequence. This checks per-group unique k-mers and **refuses to pretend** a
+group is measurable when it isn't.
+```bash
+isoform-dominance identifiability --config config.json
+#   [OK] iso_896aa : 3399 unique k-mers
+#   [OK] iso_1165aa: 5369 unique k-mers
+#   primary_comparison distinguishable by short reads: True
+```
+
+## Full workflow (real data)
+
+```bash
+# 0) build a decoy-aware index once (Salmon + GENCODE) — see scripts/01_salmon_quant.sbatch
+# 1) quantify on an HPC cluster:
+sbatch scripts/01_salmon_quant.sbatch                    # -> quant/<donor>/quant.sf
+# 2) extract per cohort:
+isoform-dominance extract --config config.json --quantdir quant \
+    --samplemap example/sample_map_GSE228458.csv --cohort GSE228458 --out perdonor_GSE228458.csv
+# 3) stats + figure:
+isoform-dominance stats --config config.json --condition control \
+    --perdonor GSE228458=perdonor_GSE228458.csv --perdonor GSE137619=perdonor_GSE137619.csv \
+    --out results/dominance
+# 4) optional contamination control:
+isoform-dominance qc --config config.json \
+    --markers GSE228458=markers_228.csv --target GSE228458=perdonor_GSE228458.csv --out results/qc
+```
+
+## Statistical notes
+
+- Donor-level two-sided **exact Wilcoxon signed-rank** (`scipy.stats.wilcoxon`), per cohort + combined.
+- **Small-n floor:** n = 5 cannot reach P < 0.05 in the exact two-sided test (floor 0.0625);
+  report exact P + direction (e.g. 5/5) and combine concordant cohorts for the summary statistic.
+- Effect size = median fold-change, reported alongside significance.
+
+## Layout
+
+```
+src/isoform_dominance/   annotate · identifiability · extract · stats · contamination · cli · _selftest
+tests/                   pytest (offline; reproduces the published result + unit tests)
+scripts/01_salmon_quant.sbatch
+example/                 config + sample maps
+.github/workflows/ci.yml docs/  pyproject.toml  CITATION.cff  LICENSE
+```
+
+## Citation
+
+Cite this repository (see `CITATION.cff`, DOI 10.5281/zenodo.20672052) and Salmon:
+Patro, R. et al. *Nat. Methods* **14**, 417–419 (2017). https://doi.org/10.1038/nmeth.4197
+
+## License
+
+MIT (see `LICENSE`).

isoform_dominance-2.0.0/src/isoform_dominance.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/isoform_dominance/__init__.py
+src/isoform_dominance/_selftest.py
+src/isoform_dominance/annotate.py
+src/isoform_dominance/cli.py
+src/isoform_dominance/contamination.py
+src/isoform_dominance/extract.py
+src/isoform_dominance/identifiability.py
+src/isoform_dominance/io.py
+src/isoform_dominance/stats.py
+src/isoform_dominance.egg-info/PKG-INFO
+src/isoform_dominance.egg-info/SOURCES.txt
+src/isoform_dominance.egg-info/dependency_links.txt
+src/isoform_dominance.egg-info/entry_points.txt
+src/isoform_dominance.egg-info/requires.txt
+src/isoform_dominance.egg-info/top_level.txt
+tests/test_annotate.py
+tests/test_identifiability.py
+tests/test_selftest.py

isoform_dominance-2.0.0/src/isoform_dominance.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

isoform_dominance-2.0.0/src/isoform_dominance.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+isoform-dominance = isoform_dominance.cli:main

isoform_dominance-2.0.0/src/isoform_dominance.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy>=1.24
+scipy>=1.10
+matplotlib>=3.7
+
+[dev]
+pytest>=7
+pytest-cov>=4

isoform_dominance-2.0.0/src/isoform_dominance.egg-info/top_level.txt

@@ -0,0 +1 @@
+isoform_dominance

isoform_dominance-2.0.0/tests/test_annotate.py

@@ -0,0 +1,27 @@
+"""Isoform-grouping logic (offline; no Ensembl call)."""
+from isoform_dominance import annotate
+
+
+def _info():
+    # canonical 1000aa (acceptor 100); two 900aa share acceptor 200; one 500aa acceptor 300
+    return {"gene": "X", "species": "homo_sapiens", "strand": 1, "transcripts": [
+        {"id": "T1", "protein_aa": 1000, "terminal_acceptor": 100, "is_canonical": True},
+        {"id": "T2", "protein_aa": 900, "terminal_acceptor": 200, "is_canonical": False},
+        {"id": "T3", "protein_aa": 900, "terminal_acceptor": 200, "is_canonical": False},
+        {"id": "T4", "protein_aa": 500, "terminal_acceptor": 300, "is_canonical": False},
+    ]}
+
+
+def test_clusters_by_terminal_exon():
+    clusters = annotate.cluster_by_terminal_exon(_info())
+    accs = {c["acceptor"]: c["n"] for c in clusters}
+    assert accs == {200: 2, 100: 1, 300: 1}
+
+
+def test_proposes_canonical_vs_largest_alt():
+    groups, primary, _ = annotate.propose_groups(_info())
+    # canonical cluster -> iso_1000aa; largest alternative (2 tx) -> iso_900aa
+    assert groups["iso_1000aa"] == ["T1"]
+    assert groups["iso_900aa"] == ["T2", "T3"]
+    # alternative group is listed first in the comparison
+    assert primary == ["iso_900aa", "iso_1000aa"]

isoform_dominance-2.0.0/tests/test_identifiability.py

@@ -0,0 +1,25 @@
+"""Short-read distinguishability (offline; supplied sequences)."""
+from isoform_dominance import identifiability
+
+SHARED = "ACGT" * 20  # 80 bp shared backbone
+
+
+def test_distinguishable_when_each_group_has_unique_region():
+    seqs = {"A1": SHARED + "GGGGGGGGCATCAT", "B1": SHARED + "TTTTTTTTAGAGAG"}
+    cfg = {"groups": {"A": ["A1"], "B": ["B1"]}, "primary_comparison": ["A", "B"]}
+    res = identifiability.analyze(cfg, k=8, sequences=seqs)
+    assert res["primary_distinguishable"] is True
+    assert res["groups"]["A"]["n_unique_kmers"] > 0
+    assert res["groups"]["B"]["n_unique_kmers"] > 0
+
+
+def test_flags_group_with_no_unique_sequence():
+    # 'sub' sequence is fully contained in 'super' -> sub has no unique k-mers
+    sub = SHARED + "GGGGGGGG"
+    sup = sub + "TTTTTTTTTT"
+    seqs = {"S1": sub, "P1": sup}
+    cfg = {"groups": {"sub": ["S1"], "super": ["P1"]}, "primary_comparison": ["sub", "super"]}
+    res = identifiability.analyze(cfg, k=8, sequences=seqs)
+    assert res["groups"]["sub"]["n_unique_kmers"] == 0
+    assert res["groups"]["sub"]["distinguishable"] is False
+    assert res["primary_distinguishable"] is False

isoform_dominance-2.0.0/tests/test_selftest.py

@@ -0,0 +1,21 @@
+"""End-to-end: synthetic data must reproduce the published LEPR result."""
+from isoform_dominance import _selftest
+
+
+def test_reproduces_published_result(tmp_path):
+    ok, msgs = _selftest.run(str(tmp_path))
+    assert ok, "self-test failed:\n" + "\n".join(msgs)
+
+
+def test_combined_pvalue(tmp_path):
+    info = _selftest.generate(str(tmp_path))
+    from isoform_dominance import extract, stats
+    perdonor = {}
+    for cohort, p in info.items():
+        out = str(tmp_path / ("pd_%s.csv" % cohort))
+        extract.run(_selftest.CONFIG, p["quantdir"], p["samplemap"], cohort, out)
+        perdonor[cohort] = out
+    res = stats.run(_selftest.CONFIG, "control", perdonor, str(tmp_path / "r"))
+    cn, cgt, cp, _ = res["combined"]
+    assert cn == 11 and cgt == 11
+    assert abs(cp - 9.7656e-4) < 1e-4