pen-stack 7.1.4__tar.gz → 7.1.5__tar.gz

{pen_stack-7.1.4 → pen_stack-7.1.5}/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## [7.1.5] - 2026-06-29 - Chromosome field: validation, gene concordance, context
+
+### Added
+- The `chrom` design field was a free-text pass-through with no validation and no downstream effect. It is now
+  meaningful (`pen_stack/planner/chromosome.py`):
+  - **Validation** — the web form's Chromosome input is a controlled dropdown (chr1–chr22, chrX, chrY, chrM), so
+    an impossible value like `chrZZZ` can no longer be entered; `canonical_chromosome()` normalises/validates on
+    the backend (`chrX`/`X`/`x`, `chr1`/`1`, `chrM`/`chrMT`/`MT`, `23`→X, `24`→Y; rejects the rest).
+  - **Gene/chromosome concordance** — `verify()` now flags `chromosome_mismatch` when the entered chromosome does
+    not match the named gene's canonical location (e.g. *BRCA1 is on chr17, not chr1*), `chromosome_invalid` for a
+    non-standard value, and `chromosome_unverifiable` for an unknown gene. The web form shows the warning inline
+    with a one-click fix, driven by the new `GET /api/gene/location` endpoint. This closes the silent-mismatch gap.
+  - **Chromosome context** — `chromosome_context()` adds grounded, chromosome-driven advisories surfaced as scope
+    flags: **chrM** is not addressable by nuclear genome-writing tools (mtDNA needs DdCBE/TALED — out of scope),
+    **chrY** is male-specific with ampliconic repeats, **chrX** is hemizygous in 46,XY vs X-inactivated in 46,XX.
+- The Design Studio **cell-type dropdown now shows writability-atlas coverage** (from `/api/celltypes`): K562 /
+  HepG2 / HSPC are labelled measured (full / full / partial), while h1_hesc / iPSC / CD8 T / PBMC are labelled
+  "no atlas" — so a data-gated cell type is no longer silently indistinguishable from a measured one (the same
+  honest-field principle as the chromosome field). The 7 cell types are unchanged and already matched the backend.
+
+### Note (honest scoping)
+- The free-text chromosome does **not** move the scored locus: per-locus safety / durability / accessibility /
+  off-target are indexed by the gene's *resolved genomic coordinates* via the writability atlas, so a bare
+  chromosome string with no position cannot refine them. Rather than fabricate a per-chromosome score delta, the
+  field's grounded effect is validation + gene concordance (ensuring the score is read for the right locus, and
+  flagging when the entered chromosome disagrees with the gene) + the chromosome-context advisories above.
+
 ## [7.1.4] - 2026-06-29 - Germline-prohibition legality rule
 
 ### Added

{pen_stack-7.1.4 → pen_stack-7.1.5}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 7.1.4
+version: 7.1.5
 date-released: 2026-06-29
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-7.1.4 → pen_stack-7.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 7.1.4
+Version: 7.1.5
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT

{pen_stack-7.1.4 → pen_stack-7.1.5}/pen_stack/__init__.py

@@ -1,2 +1,2 @@
 """PEN-STACK v3.0 - open infrastructure for genome writing."""
-__version__ = "7.1.4"
+__version__ = "7.1.5"

pen_stack-7.1.5/pen_stack/planner/chromosome.py

@@ -0,0 +1,106 @@
+"""Chromosome validation, gene/chromosome concordance, and chromosome-context advisories (v7.1.5).
+
+The `chrom` field on a design was previously a free-text pass-through with no validation and no downstream
+effect. This module makes it meaningful WITHOUT fabricating a score: the engine's per-locus safety / durability /
+accessibility / off-target numbers are indexed by the GENE's resolved genomic coordinates via the writability
+atlas (`planner.optimize.gene_region`), not by a free-text chromosome string - a bare "chrX" with no position
+cannot index a specific locus value. So the honest, grounded use of the field is:
+
+  * `canonical_chromosome` - validate / normalise to a standard human chromosome (chr1-chr22, chrX, chrY, chrM);
+  * `gene_chromosome` - the gene's canonical chromosome from the gene-coordinate table;
+  * `chromosome_concordance` - flag when the entered chromosome does not match the named gene's real location
+    (the "BRCA1 is on chr17, not chr1" case), making explicit that scoring uses the gene's canonical locus;
+  * `chromosome_context` - chromosome-driven advisories that ARE grounded in biology: chrM is not addressable by
+    nuclear genome-writing tools (mtDNA needs DdCBE/TALED - out of scope), chrY is male-specific with ampliconic
+    repeats, chrX is hemizygous in 46,XY vs X-inactivated in 46,XX.
+"""
+from __future__ import annotations
+
+import re
+
+STANDARD_CHROMOSOMES = [f"chr{i}" for i in range(1, 23)] + ["chrX", "chrY", "chrM"]
+
+
+def canonical_chromosome(chrom: str | None) -> str | None:
+    """Normalise a chromosome string to canonical UCSC form (chr1..chr22, chrX, chrY, chrM), or None if it is not
+    a standard human chromosome. Accepts 'chrX'/'X'/'x', 'chr1'/'1', 'chrM'/'chrMT'/'MT', '23'->X, '24'->Y."""
+    if chrom is None:
+        return None
+    c = re.sub(r"\s+", "", str(chrom)).lower()
+    if not c:
+        return None
+    if c.startswith("chr"):
+        c = c[3:]
+    c = {"mt": "m", "23": "x", "24": "y", "25": "m"}.get(c, c)
+    if c in {"x", "y", "m"}:
+        return "chr" + c.upper()
+    if c.isdigit() and 1 <= int(c) <= 22:
+        return "chr" + c
+    return None
+
+
+def gene_chromosome(gene: str | None) -> str | None:
+    """The canonical chromosome of a gene (or safe-harbour locus nickname), from the gene-coordinate table; None
+    if the gene is unknown."""
+    if not gene:
+        return None
+    try:
+        from pen_stack.planner.optimize import gene_region
+        reg = gene_region(gene)
+    except Exception:  # noqa: BLE001 - coords table absent (bare checkout) -> cannot resolve, do not fabricate
+        return None
+    return canonical_chromosome(reg[0]) if reg else None
+
+
+def chromosome_concordance(gene: str | None, chrom: str | None) -> dict:
+    """Validate the entered chromosome and check it against the named gene's canonical location.
+
+    status is one of:
+      * 'invalid'  - the entered string is not a standard human chromosome;
+      * 'mismatch' - valid, but does not match the gene's canonical chromosome (the silent-mismatch case);
+      * 'match'    - matches the gene's canonical chromosome;
+      * 'unverifiable' - valid chromosome but the gene's location is unknown (cannot confirm);
+      * 'none'     - no chromosome supplied.
+    """
+    entered = canonical_chromosome(chrom)
+    gchrom = gene_chromosome(gene)
+    out = {"entered_raw": chrom, "entered": entered, "valid": entered is not None,
+           "gene": gene, "gene_chrom": gchrom}
+    if chrom in (None, "") or str(chrom).strip() == "":
+        out["status"] = "none"
+        out["message"] = None
+    elif entered is None:
+        out["status"] = "invalid"
+        out["message"] = (f"'{chrom}' is not a standard human chromosome. Use chr1-chr22, chrX, chrY, or chrM.")
+    elif gchrom and entered != gchrom:
+        out["status"] = "mismatch"
+        out["message"] = (f"{gene} is on {gchrom}, not {entered}. Locus scoring uses {gene}'s canonical location "
+                          f"({gchrom}); the entered chromosome does not move the locus.")
+    elif gchrom and entered == gchrom:
+        out["status"] = "match"
+        out["message"] = f"{entered} matches the canonical location of {gene}."
+    else:
+        out["status"] = "unverifiable"
+        out["message"] = (f"{entered} is a valid chromosome, but {gene or 'the gene'} is not in the coordinate "
+                          "table, so the gene/chromosome match cannot be confirmed.")
+    return out
+
+
+def chromosome_context(chrom: str | None) -> dict | None:
+    """A grounded, chromosome-driven advisory (or None for an autosome). These are real biological constraints
+    the chromosome identity alone implies; magnitudes remain locus/subject-dependent (not predicted here)."""
+    c = canonical_chromosome(chrom)
+    if c == "chrM":
+        return {"chrom": "chrM", "severity": "high",
+                "note": ("the mitochondrial genome is NOT addressable by nuclear genome-writing tools "
+                         "(integrases / recombinases / nuclear-targeted Cas9); mtDNA editing requires "
+                         "mitochondrially-targeted base editors (DdCBE / TALED) - out of scope for this tool.")}
+    if c == "chrY":
+        return {"chrom": "chrY", "severity": "medium",
+                "note": ("the Y chromosome is male-specific (absent in 46,XX) and rich in ampliconic / palindromic "
+                         "repeats, so confirm the target is single-copy before trusting a unique-site assumption.")}
+    if c == "chrX":
+        return {"chrom": "chrX", "severity": "low",
+                "note": ("the X chromosome is hemizygous in 46,XY (one copy) but subject to X-inactivation in "
+                         "46,XX (mosaic expression); dosage and durability are sex- and locus-dependent.")}
+    return None

{pen_stack-7.1.4 → pen_stack-7.1.5}/pen_stack/server/api.py

@@ -119,6 +119,23 @@ def crosslink_loci(request: Request, family: str, ct: str = "k562", cell_type: s
     return {"family": family, "ct": ct, "loci": _records(loci), "disclaimer": _DISCLAIMER}
 
 
+@app.get("/gene/location")
+def gene_location(gene: str):
+    """v7.1.5: the canonical chromosome of a gene (or safe-harbour locus nickname), for the UI's gene/chromosome
+    concordance check. found=False when the gene is not in the coordinate table (no fabrication)."""
+    from pen_stack.planner.chromosome import canonical_chromosome
+    from pen_stack.planner.optimize import gene_region, resolve_gene
+    try:
+        reg = gene_region(gene)
+    except Exception:  # noqa: BLE001 - coords table absent -> cannot resolve
+        reg = None
+    resolved = resolve_gene(gene)
+    if reg is None:
+        return {"gene": gene, "resolved": resolved, "found": False, "chrom": None}
+    return {"gene": gene, "resolved": resolved, "found": True, "chrom": canonical_chromosome(reg[0]),
+            "start": int(reg[1]), "end": int(reg[2])}
+
+
 @app.get("/writable")
 def writable(request: Request, gene: str, ct: str = "k562", cell_type: str | None = None,
              top: int = Query(20, le=200)):

{pen_stack-7.1.4 → pen_stack-7.1.5}/pen_stack/verify/service.py

@@ -98,6 +98,18 @@ def verify(design: Design | dict, question: str | None = None, *, actor: str = "
                   for r in results if r["kind"] == "scope_flag" and r["status"] == "scope"]
     scope_flags += rule_scope
 
+    # v7.1.5: chromosome validation + gene/chromosome concordance + chromosome-context advisory. The free-text
+    # chrom field does not move the scored locus (scoring is indexed by the gene's resolved coordinates), so a
+    # mismatch / invalid value / chromosome-context note is surfaced as a scope flag, never silently ignored.
+    from pen_stack.planner.chromosome import chromosome_concordance, chromosome_context
+    conc = chromosome_concordance(design.gene, getattr(design, "chrom", None))
+    if conc["status"] in ("invalid", "mismatch", "unverifiable"):
+        scope_flags.append({"kind": f"chromosome_{conc['status']}", "reason": conc["message"],
+                            "entered": conc["entered"], "gene_chrom": conc["gene_chrom"]})
+    ctx = chromosome_context(getattr(design, "chrom", None))
+    if ctx:
+        scope_flags.append({"kind": "chromosome_context", "chrom": ctx["chrom"], "reason": ctx["note"]})
+
     pc = _plan_confidence(design)
     verdict = classify(grounded=True, confidence=pc["confidence"], out_of_scope=oos_hit)
 

{pen_stack-7.1.4 → pen_stack-7.1.5}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 7.1.4
+Version: 7.1.5
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT

{pen_stack-7.1.4 → pen_stack-7.1.5}/pen_stack.egg-info/SOURCES.txt

@@ -252,6 +252,7 @@ pen_stack/planner/antipeg_oracle.py
 pen_stack/planner/capsid_epitope_oracle.py
 pen_stack/planner/cargo.py
 pen_stack/planner/cargo_polish.py
+pen_stack/planner/chromosome.py
 pen_stack/planner/delivery.py
 pen_stack/planner/delivery_constraints.py
 pen_stack/planner/delivery_immune.py

{pen_stack-7.1.4 → pen_stack-7.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pen-stack"
-version = "7.1.4"
+version = "7.1.5"
 description = "Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner."
 readme = "README.md"
 requires-python = ">=3.11"