@platforma-open/milaboratories.humanization-score.model 0.2.0 → 0.3.1

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@platforma-open/milaboratories.humanization-score.model",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Block model",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@platforma-sdk/model": "1.77.15",
-    "@milaboratories/helpers": "1.14.2"
+    "@platforma-sdk/model": "1.77.17",
+    "@milaboratories/helpers": "1.14.2",
+    "@milaboratories/graph-maker": "1.4.4"
   },
   "devDependencies": {
     "@milaboratories/ts-builder": "1.5.0",
     "@milaboratories/ts-configs": "1.2.3",
-    "@platforma-sdk/block-tools": "2.9.3",
+    "@platforma-sdk/block-tools": "2.10.0",
     "@platforma-sdk/eslint-config": "1.2.0",
     "eslint": "^9.25.1",
     "vitest": "^4.0.7",

package/src/index.ts

@@ -1,4 +1,7 @@
+import type { GraphMakerState } from '@milaboratories/graph-maker';
 import type {
+  PColumnIdAndSpec,
+  PFrameHandle,
   PlDataTableStateV2,
   PlRef,
 } from '@platforma-sdk/model';
@@ -6,6 +9,7 @@ import {
   ArrayColumnProvider,
   BlockModelV3,
   DataModelBuilder,
+  createPFrameForGraphs,
   createPlDataTableStateV2,
   createPlDataTableV3,
 } from '@platforma-sdk/model';
@@ -19,6 +23,7 @@ type OldArgs = {
 
 type OldUiState = {
   tableState: PlDataTableStateV2;
+  graphStateHistogram?: GraphMakerState;
 };
 
 export type BlockData = {
@@ -26,17 +31,54 @@ export type BlockData = {
   inputAnchor?: PlRef;
   mem?: number;
   tableState: PlDataTableStateV2;
+  // Distribution of the per-clonotype humanness score across the whole dataset.
+  graphStateHistogram: GraphMakerState;
 };
 
+// Humanness score column name emitted by `clonotype-process.tpl.tengo`.
+export const HUMANNESS_SCORE_COLUMN = 'pl7.app/humannessScore';
+
+export const defaultGraphStateHistogram = (): GraphMakerState => ({
+  title: 'Humanness Score Distribution',
+  template: 'bins',
+  currentTab: null,
+  axesSettings: {
+    other: { binsCount: 20 },
+  },
+  // Give the bars a solid fill instead of the default white — colour values
+  // taken from graph-maker's fixed palette ("Blue").
+  layersSettings: {
+    bins: { fillColor: '#2D93FA' },
+  },
+});
+
+// Selectors for the input dataset anchor — shared between `inputOptions`
+// (the dropdown) and `subtitle` (so the default label matches the dataset name).
+const inputSelectors = [{
+  axes: [
+    { name: 'pl7.app/sampleId' },
+    { name: 'pl7.app/vdj/clonotypeKey' },
+  ],
+  annotations: { 'pl7.app/isAnchor': 'true' },
+}, {
+  axes: [
+    { name: 'pl7.app/sampleId' },
+    { name: 'pl7.app/vdj/scClonotypeKey' },
+  ],
+  annotations: { 'pl7.app/isAnchor': 'true' },
+}];
+
 const dataModel = new DataModelBuilder()
   .from<BlockData>('v1')
   .upgradeLegacy<OldArgs, OldUiState>(({ args, uiState }) => ({
     ...args,
     tableState: uiState.tableState,
+    graphStateHistogram: uiState.graphStateHistogram ?? defaultGraphStateHistogram(),
   }))
   .init(() => ({
     customBlockLabel: '',
     tableState: createPlDataTableStateV2(),
+    graphStateHistogram: defaultGraphStateHistogram(),
   }));
 
 export const platforma = BlockModelV3.create(dataModel)
@@ -45,30 +87,20 @@ export const platforma = BlockModelV3.create(dataModel)
     if (!data.inputAnchor) throw new Error('Input anchor is required');
 
     return {
-      customBlockLabel: data.customBlockLabel || 'Humanness Score',
+      // Empty when unset; the workflow falls back to the input dataset name so
+      // the provenance trace label matches the block subtitle.
+      customBlockLabel: data.customBlockLabel || '',
       inputAnchor: data.inputAnchor,
       mem: data.mem,
     };
   })
 
   .output('inputOptions', (ctx) =>
-    ctx.resultPool.getOptions([{
-      axes: [
-        { name: 'pl7.app/sampleId' },
-        { name: 'pl7.app/vdj/clonotypeKey' },
-      ],
-      annotations: { 'pl7.app/isAnchor': 'true' },
-    }, {
-      axes: [
-        { name: 'pl7.app/sampleId' },
-        { name: 'pl7.app/vdj/scClonotypeKey' },
-      ],
-      annotations: { 'pl7.app/isAnchor': 'true' },
-    }]),
+    ctx.resultPool.getOptions(inputSelectors),
   )
 
   .outputWithStatus('pt', (ctx) => {
-    const pCols = ctx.outputs?.resolve('outputLiabilities')?.getPColumns();
+    const pCols = ctx.outputs?.resolve('outputHumanness')?.getPColumns();
     if (pCols === undefined) {
       return undefined;
     }
@@ -80,14 +112,37 @@ export const platforma = BlockModelV3.create(dataModel)
     });
   })
 
+  // --- Score distribution (histogram) ---------------------------------------
+  // One row per clonotype, so the histogram counts UNIQUE clonotypes by humanness
+  // score — it is deliberately NOT weighted by clonotype abundance. The question it
+  // answers is "how many distinct candidates sit below/above a humanness level"
+  // (i.e. how much humanization work is there), not "how human is the repertoire by
+  // read mass". No human-like threshold line is drawn: this score is a 9-mer
+  // fraction rescaled to 0..100, not a cutoff validated against therapeutic mAbs.
+  .outputWithStatus('histogramPf', (ctx): PFrameHandle | undefined => {
+    const pCols = ctx.outputs?.resolve('outputHumanness')?.getPColumns();
+    if (pCols === undefined) return undefined;
+    return createPFrameForGraphs(ctx, pCols);
+  })
+
+  .output('histogramPfPcols', (ctx): PColumnIdAndSpec[] | undefined => {
+    const pCols = ctx.outputs?.resolve('outputHumanness')?.getPColumns();
+    if (pCols === undefined || pCols.length === 0) return undefined;
+    return pCols.map((c) => ({ columnId: c.id, spec: c.spec }));
+  })
+
   .output('isRunning', (ctx) => ctx.outputs?.getIsReadyOrError() === false)
 
-  .title(() => 'Humanness Score')
+  .title(() => 'Humanization Score')
 
-  .subtitle((ctx) => ctx.data.customBlockLabel || 'Humanness Score')
+  .subtitle((ctx) => {
+    if (ctx.data.customBlockLabel) return ctx.data.customBlockLabel;
+    return 'Humanization Score';
+  })
 
   .sections((_) => [
     { type: 'link', href: '/', label: 'Table' },
+    { type: 'link', href: '/histogram', label: 'Score Distribution' },
   ])
 
   .done();