@platforma-open/milaboratories.sequence-properties.workflow 1.1.1 → 1.2.0

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
  WARN  Issue while reading "/home/runner/work/sequence-properties/sequence-properties/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @platforma-open/milaboratories.sequence-properties.workflow@1.1.1 build /home/runner/work/sequence-properties/sequence-properties/workflow
+> @platforma-open/milaboratories.sequence-properties.workflow@1.2.0 build /home/runner/work/sequence-properties/sequence-properties/workflow
 > shx rm -rf dist && pl-tengo check && pl-tengo build
 
   info: Skipping unknown file type: wf.test.ts

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @platforma-open/MiLaboratories.sequence-properties.workflow
 
+## 1.2.0
+
+### Minor Changes
+
+- a3eaf4b: Add ΔCharge (pH 7.4 → 6.0) metric — `pl7.app/chargeShift` — emitted at peptide, CDR3 (per chain), and Fv scopes. Captures pH-switching capacity (FcRn recycling, endosomal release); negative values mean the molecule gains positive charge on acidification, the productive direction for histidine-driven pH switching. Histidine dominates the metric (~−0.46 per His; pKa ~6.0 sits in the window). Domain carries the pH endpoints (`pl7.app/pH/from`, `pl7.app/pH/to`) so additional pH pairs can land later without breaking the v1 column identity. Default-visible alongside the static charge column at each scope; not marked `isScore` (interpretive, not a Lead Selection ranking criterion).
+
+  Performance: cache per-sequence `_prepare`, `ProteinAnalysis`, and `IsoelectricPoint` via a `SequenceContext` so each sequence does the BioPython setup work once instead of per-property. Pipeline reuses the full-chain context for the Fv pass (one `IsoelectricPoint(IPC2_PROTEIN, include_cys=False)` shared between `charge_at_pH(7.0)` and pI bisection per chain). DataFrames are built columnarly (dict-of-lists) instead of via list-of-dicts. Output is byte-identical to pre-refactor on the corpus tests; ~1.7× faster on per-property micro-bench, end-to-end ~40k peptides/s and ~10k antibody-clones/s with full-chain + Fv. CDR3 chain-mode byte-stability tests added.
+
+### Patch Changes
+
+- Updated dependencies [a3eaf4b]
+  - @platforma-open/milaboratories.sequence-properties.software@1.2.0
+
+## 1.1.2
+
+### Patch Changes
+
+- 9d628d9: **Workflow (SD-008):** Derive receptor from `pl7.app/vdj/chain` when `pl7.app/vdj/receptor` is absent. Bulk MiXCR axes carry the chain key (`IGHeavy`, `IGLight`, `TCRAlpha`, `TCRBeta`, `TCRGamma`, `TCRDelta`) without the receptor key, which previously fired R13b's "Receptor type not detected" warning on every bulk run. Detection precedence now: axis receptor → axis chain → per-column receptor → per-column chain → IG default + warning. Inputs that carry receptor explicitly are unaffected.
+
+  **Model:** Default-visible single upstream amino-acid sequence column matching the analysed coverage tier — peptide (`pl7.app/sequence`, feature=peptide) for peptide mode; full-chain VDJRegion (`pl7.app/vdj/sequence`, feature=VDJRegion or VDJRegionInFrame, chain A) for `full_chain` tier; CDR3 (`pl7.app/vdj/sequence`, feature=CDR3, chain A) for `cdr3_only` and `partial` tiers. Chain B (light / beta / delta) and secondary alleles stay available via the column picker.
+
+  **UI:** Move the "Input dataset" picker into a Settings slide-out drawer (matches the convention used by clonotype-clustering and other sibling blocks). Drawer auto-opens on first load when no input is selected, auto-closes when the workflow starts running.
+
+  **Software:** Switch the Python runenv from `runenv-python-3:3.12.10` to `runenv-python-3:3.12.10-scientific-slim`. The scientific-slim image now ships biopython, so the per-block dependency install is faster and matches the convention used by sibling python blocks (e.g. `titeseq-analysis`).
+
+- Updated dependencies [9d628d9]
+  - @platforma-open/milaboratories.sequence-properties.software@1.1.1
+
 ## 1.1.1
 
 ### Patch Changes

package/dist/tengo/lib/messages.lib.tengo

@@ -47,6 +47,12 @@ vhh := func() {
 		"disregard these thresholds for nanobody libraries."
 }
 
+
+
+peptidesShortInstability := func() {
+	return "Instability Index applies only to peptides ≥10 aa; shorter peptides show blank values."
+}
+
 export ll.toStrict({
 	partialChainMissingFullChain: partialChainMissingFullChain,
 	partialChainNoCdr3: partialChainNoCdr3,
@@ -54,5 +60,6 @@ export ll.toStrict({
 	cdr3OnlyInput: cdr3OnlyInput,
 	gammaDeltaTcr: gammaDeltaTcr,
 	receptorNotDetected: receptorNotDetected,
-	vhh: vhh
+	vhh: vhh,
+	peptidesShortInstability: peptidesShortInstability
 })

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@platforma-open/milaboratories.sequence-properties.workflow",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Block Workflow",
   "type": "module",
   "dependencies": {
     "@platforma-sdk/workflow-tengo": "5.16.0",
-    "@platforma-open/milaboratories.sequence-properties.software": "1.1.0"
+    "@platforma-open/milaboratories.sequence-properties.software": "1.2.0"
   },
   "devDependencies": {
     "@platforma-sdk/tengo-builder": "2.5.17",

package/src/main.tpl.tengo

@@ -58,6 +58,44 @@ contains := func(arr, x) {
 	return false
 }
 
+// Spec deviation SD-008 — see docs/spec-deviations.md.
+// Bulk MiXCR axes carry `pl7.app/vdj/chain` without the spec-required
+// `pl7.app/vdj/receptor`. The chain enum maps unambiguously to a receptor —
+// derive it when receptor is absent. Returns "" for unrecognised input;
+// caller falls through to the IG default + R13b warning, which still fires
+// for genuinely unknown datasets.
+CHAIN_TO_RECEPTOR := {
+	IGHeavy: "IG",
+	IGLight: "IG",
+	IGKappa: "IG",
+	IGLambda: "IG",
+	TCRAlpha: "TCRAB",
+	TCRBeta: "TCRAB",
+	TCRGamma: "TCRGD",
+	TCRDelta: "TCRGD"
+}
+
+chainToReceptor := func(chain) {
+	if chain == undefined { return "" }
+	r := CHAIN_TO_RECEPTOR[chain]
+	if r == undefined { return "" }
+	return r
+}
+
+// Resolve receptor from a (receptor, chain) domain pair. Explicit receptor
+// wins; chain-derived receptor is the fallback. Returns { value, seen };
+// `seen` false when neither key resolves.
+resolveReceptor := func(receptorVal, chainVal) {
+	if receptorVal == "IG" || receptorVal == "TCRAB" || receptorVal == "TCRGD" {
+		return { value: receptorVal, seen: true }
+	}
+	derived := chainToReceptor(chainVal)
+	if derived != "" {
+		return { value: derived, seen: true }
+	}
+	return { value: "", seen: false }
+}
+
 wf.prepare(func(args) {
 	bb := wf.createPBundleBuilder()
 	bb.ignoreMissingDomains()
@@ -132,10 +170,17 @@ wf.body(func(args) {
 	// anchor's secondary axis), not on per-region sequence column domains. Read
 	// from the axis first; the per-column check inside the loop stays as a
 	// fallback for non-MiXCR producers.
+	//
+	// Spec deviation SD-008 — bulk MiXCR axes lack `pl7.app/vdj/receptor` but
+	// carry `pl7.app/vdj/chain`; derive receptor from chain when receptor is
+	// absent. See docs/spec-deviations.md.
 	if keyAxisSpec.domain != undefined {
-		axisR := keyAxisSpec.domain["pl7.app/vdj/receptor"]
-		if axisR == "IG" || axisR == "TCRAB" || axisR == "TCRGD" {
-			receptor = axisR
+		r := resolveReceptor(
+			keyAxisSpec.domain["pl7.app/vdj/receptor"],
+			keyAxisSpec.domain["pl7.app/vdj/chain"]
+		)
+		if r.seen {
+			receptor = r.value
 			receptorSeen = true
 		}
 	}
@@ -192,9 +237,10 @@ wf.body(func(args) {
 			}
 
 			// Same receptor value is expected on every input column; last seen wins.
-			r := d["pl7.app/vdj/receptor"]
-			if r == "IG" || r == "TCRAB" || r == "TCRGD" {
-				receptor = r
+			// SD-008: derive from chain when explicit receptor key is absent.
+			rec := resolveReceptor(d["pl7.app/vdj/receptor"], d["pl7.app/vdj/chain"])
+			if rec.seen {
+				receptor = rec.value
 				receptorSeen = true
 			}
 

package/src/messages.lib.tengo

@@ -47,6 +47,12 @@ vhh := func() {
 		"disregard these thresholds for nanobody libraries."
 }
 
+// R9 — Guruprasad instability index is undefined for sequences shorter than
+// 10 residues; emitted in peptide mode whenever any peptide falls below the floor.
+peptidesShortInstability := func() {
+	return "Instability Index applies only to peptides ≥10 aa; shorter peptides show blank values."
+}
+
 export ll.toStrict({
 	partialChainMissingFullChain: partialChainMissingFullChain,
 	partialChainNoCdr3: partialChainNoCdr3,
@@ -54,5 +60,6 @@ export ll.toStrict({
 	cdr3OnlyInput: cdr3OnlyInput,
 	gammaDeltaTcr: gammaDeltaTcr,
 	receptorNotDetected: receptorNotDetected,
-	vhh: vhh
+	vhh: vhh,
+	peptidesShortInstability: peptidesShortInstability
 })

package/src/process.tpl.tengo

@@ -14,6 +14,17 @@ messages := import(":messages")
 
 self.defineOutputs("propertiesPf", "exportPframe", "info")
 
+// ΔCharge (pH 7.4 → 6.0) endpoints — fixed in v1 per spec; schema accepts
+// additional pH pairs without breaking existing column identities.
+CHARGE_SHIFT_PH_FROM := "7.4"
+CHARGE_SHIFT_PH_TO := "6.0"
+
+// Spec R6b — same description on every chargeShift column (peptide / CDR3 / Fv).
+// Trimmed to ~30 words for the column-header tooltip; PlAgDataTableV2 clips the
+// top edge against the page header. Magnitude rule and scope-exclusion caveats
+// live in pcolumn-spec.md / the spec, not in the tooltip.
+CHARGE_SHIFT_DESC := "Net charge change from pH 7.4 (blood) to pH 6.0 (endosome). Negative values mean the molecule gains positive charge on acidification — the productive direction for histidine-driven pH switching. Histidine dominates (~−0.46 per His)."
+
 // Receptor + chain → human label fragments (CDR3 / full-chain).
 // Spec R13a: PColumn name and chain domain are unchanged; only the label varies.
 labelFragments := func(receptor, chain) {
@@ -81,6 +92,13 @@ self.body(func(args) {
 		}
 	}
 
+	// R9 — Instability Index is NA for peptides shorter than 10 aa. Surface a
+	// banner in peptide mode whenever any row falls below the floor so the
+	// user understands why the Instability Index column is blank.
+	if mode == "peptide" && stats.hasPeptideBelowInstabilityFloor == true {
+		infoMessages += [messages.peptidesShortInstability()]
+	}
+
 	infoBlob := smart.createValueResource(constants.RTYPE_JSON, canonical.encode({
 		mode: mode,
 		receptor: receptor,
@@ -106,6 +124,18 @@ self.body(func(args) {
 				"pl7.app/table/orderPriority": "70000"
 			})]
 
+		columns += [makeCol("chargeShift_peptide", "pl7.app/chargeShift", "Double",
+			"Peptide ΔCharge (pH 7.4 → 6.0)", {
+				"pl7.app/feature": "peptide",
+				"pl7.app/pH/from": CHARGE_SHIFT_PH_FROM,
+				"pl7.app/pH/to": CHARGE_SHIFT_PH_TO
+			}, {
+				"pl7.app/format": ".2f",
+				"pl7.app/description": CHARGE_SHIFT_DESC,
+				"pl7.app/table/visibility": "default",
+				"pl7.app/table/orderPriority": "69950"
+			})]
+
 		columns += [makeCol("gravy_peptide", "pl7.app/hydrophobicity", "Double",
 			"Hydrophobicity (GRAVY)", dom, {
 				"pl7.app/format": ".3f",
@@ -206,6 +236,18 @@ self.body(func(args) {
 					"pl7.app/table/visibility": "default",
 					"pl7.app/table/orderPriority": string(chargeOrder)
 				})]
+			columns += [makeCol("chargeShift_" + chain + "_CDR3", "pl7.app/chargeShift", "Double",
+				frag.cdr3 + " ΔCharge (pH 7.4 → 6.0)", {
+					"pl7.app/feature": "CDR3",
+					"pl7.app/vdj/scClonotypeChain": chain,
+					"pl7.app/pH/from": CHARGE_SHIFT_PH_FROM,
+					"pl7.app/pH/to": CHARGE_SHIFT_PH_TO
+				}, {
+					"pl7.app/format": ".2f",
+					"pl7.app/description": CHARGE_SHIFT_DESC,
+					"pl7.app/table/visibility": "default",
+					"pl7.app/table/orderPriority": string(chargeOrder - 50)
+				})]
 			columns += [makeCol("gravy_" + chain + "_CDR3", "pl7.app/hydrophobicity", "Double",
 				frag.cdr3 + " Hydrophobicity (GRAVY)", cdr3Dom, {
 					"pl7.app/format": ".3f",
@@ -308,6 +350,17 @@ self.body(func(args) {
 					"pl7.app/table/visibility": "default",
 					"pl7.app/table/orderPriority": "65100"
 				})]
+			columns += [makeCol("chargeShift_Fv", "pl7.app/chargeShift", "Double",
+				"Fv ΔCharge (pH 7.4 → 6.0)", {
+					"pl7.app/feature": "Fv",
+					"pl7.app/pH/from": CHARGE_SHIFT_PH_FROM,
+					"pl7.app/pH/to": CHARGE_SHIFT_PH_TO
+				}, {
+					"pl7.app/format": ".2f",
+					"pl7.app/description": CHARGE_SHIFT_DESC,
+					"pl7.app/table/visibility": "default",
+					"pl7.app/table/orderPriority": "65050"
+				})]
 			columns += [makeCol("pi_Fv", "pl7.app/isoelectricPoint", "Double",
 				"Fv Isoelectric Point (pI)", fvDom, {
 					"pl7.app/format": ".2f",