Preserve mixed Boltz token confidence through native viewer transport

Author: MolBioFreak

platform/api/services/boltz_scientific_consumer.py

@@ -238,7 +238,9 @@ def retained_cp_metric(design, job, metric, params=None):
                 values = z['plddt']
             if values.shape != (n,) or not np.isfinite(values).all() or np.any(values < 0) or np.any(values > 1):
                 raise ValueError('invalid_native_confidence_vector')
-            return ScientificResidueMetric.model_validate(dict(payload, axis=axis, native_positions=list(range(n)),
+            return ScientificResidueMetric.model_validate(dict(payload,
+                metric='token_plddt' if any('label_atom_id' in r for r in axis['residues']) else 'residue_plddt',
+                axis=axis, native_positions=list(range(n)),
                 artifact_sha256=selected['artifacts']['plddt']['sha256'], units='fraction', values=values.tolist()))
         if metric == 'chain_metrics':
             confidence = json.loads(selected['snapshots']['metrics'])
@@ -309,6 +311,7 @@ async def compute_persisted_native_metric(design, metric, session, *, selected=N
             with np.load(BytesIO(selected['snapshots']['plddt']), allow_pickle=False) as data:
                 values = data['plddt'].tolist()
             payload.update(artifact_sha256=native['vectors'][0]['artifact_sha256'], units='fraction', values=values)
+            payload['metric'] = 'token_plddt' if any('label_atom_id' in r for r in payload['axis']['residues']) else 'residue_plddt'
             result = ScientificResidueMetric.model_validate(payload)
         elif metric == 'chain_metrics':
             confidence = json.loads(selected['snapshots']['metrics'])

platform/api/services/scientific_viewer_contract.py

@@ -119,7 +119,8 @@ def source_binding(self):
 
 
 class ScientificResidueMetric(NativeMetricBase):
-    metric: Literal['residue_plddt']
+    # Boltz tokens may bind polymer residues or exact non-polymer atoms.
+    metric: Literal['residue_plddt', 'token_plddt']
     units: Literal['fraction']
     values: list[float]
 

platform/frontend/src/components/StructurePredictionResults.tsx

@@ -67,6 +67,7 @@ export function confidenceProfile(raw: unknown, design: Design): { chains: Recor
         if (native.status !== 'ok') return { chains: {}, description: 'Native confidence', reason: native.reason };
         const chains: Record<string, ConfidenceChainMetric> = {};
         native.residues.forEach((ref, i) => {
+            if (native.metric === 'token_plddt' && (ref.labelAtomId || ref.authAtomId)) return;
             if (native.metric === 'atom_plddt' && ((ref.labelAtomId ?? ref.authAtomId) !== 'CA' || !protein.has(ref.componentId ?? ''))) return;
             const id = chainId(ref), position = ref.authSeqId ?? ref.labelSeqId;
             if (position == null) return;
@@ -78,7 +79,7 @@ export function confidenceProfile(raw: unknown, design: Design): { chains: Recor
             chain.length++;
         });
         for (const chain of Object.values(chains)) chain.avg_plddt = chain.plddt.reduce((a, b) => a + b, 0) / chain.length;
-        return { chains, description: native.metric === 'atom_plddt' ? 'Protein Cα-only confidence profile (0–100); no atom averaging. Native atom and non-protein evidence is available in Structure → Metrics & tools.' : 'Confidence by residue. Higher is better.' };
+        return { chains, description: native.metric === 'token_plddt' ? 'Native polymer-residue token confidence (0–100). Exact atom-token confidence remains separately available in Structure → Metrics & tools; no atom averaging.' : native.metric === 'atom_plddt' ? 'Protein Cα-only confidence profile (0–100); no atom averaging. Native atom and non-protein evidence is available in Structure → Metrics & tools.' : 'Confidence by residue. Higher is better.' };
     }
     return { chains: {}, description: 'Legacy per-chain confidence' };
 }

platform/frontend/src/components/StructureViewerPane.tsx

@@ -592,7 +592,7 @@ export default function StructureViewerPane({
     const nativeResidue = useMemo(()=>parseScientificNativeMetric(residueQuery.data,nativeDocument,'residue_plddt',selectedDesignId ?? undefined),[residueQuery.data,nativeDocument,selectedDesignId]);
     const nativeChains = useMemo(()=>parseScientificNativeMetric(chainQuery.data,nativeDocument,'chain_metrics',selectedDesignId ?? undefined),[chainQuery.data,nativeDocument,selectedDesignId]);
     const nativeResidueLayer = useMemo<MetricLayer | null>(()=>nativeResidue.status !== 'ok' ? null : ({
-        descriptor:{id:'native-plddt',label:nativeResidue.metric === 'atom_plddt' ? 'Native atom pLDDT' : 'Native residue pLDDT',dimension:nativeResidue.metric === 'atom_plddt' ? 'atom-scalar' : 'residue-scalar',units:'fraction',direction:'higher_is_better',valueRange:[0,1],projectionPolicy:'direct',normalization:'none',
+        descriptor:{id:'native-plddt',label:nativeResidue.metric === 'atom_plddt' ? 'Native atom pLDDT' : nativeResidue.metric === 'token_plddt' ? 'Native polymer-residue pLDDT' : 'Native residue pLDDT',dimension:nativeResidue.metric === 'atom_plddt' ? 'atom-scalar' : 'residue-scalar',units:'fraction',direction:'higher_is_better',valueRange:[0,1],projectionPolicy:'direct',normalization:'none',
             categories: {
                 veryHigh: {label: '≥90', color: '#3b82f6'},
                 confident: {label: '70–<90', color: '#22d3ee'},
@@ -601,8 +601,14 @@ export default function StructureViewerPane({
             },
             provenance:{source:'Verified native confidence vector',artifactSha256:nativeResidue.artifactSha256}},
         // Reuse the established confidence bands for display only; retain native fractions.
-        values:nativeResidue.residues.map((identity,index)=>({identity,value:nativeResidue.values[index],displayColor:plddtColor(nativeResidue.values[index]! * 100)})),
+        values:nativeResidue.residues.map((identity,index)=>({identity,value:nativeResidue.values[index],displayColor:plddtColor(nativeResidue.values[index]! * 100)})).filter(entry => nativeResidue.metric !== 'token_plddt' || !(entry.identity.labelAtomId || entry.identity.authAtomId)),
     } as MetricLayer),[nativeResidue]);
+    const nativeTokenAtomLayer = useMemo<MetricLayer | null>(() => {
+        if (nativeResidue.status !== 'ok' || nativeResidue.metric !== 'token_plddt' || !nativeResidueLayer) return null;
+        return { descriptor: { ...nativeResidueLayer.descriptor, id: 'native-plddt-atoms', label: 'Native atom-token pLDDT', dimension: 'atom-scalar' },
+            values: nativeResidue.residues.flatMap((identity, index) => identity.labelAtomId || identity.authAtomId
+                ? [{ identity, value: nativeResidue.values[index], displayColor: plddtColor(nativeResidue.values[index]! * 100) }] : []) };
+    }, [nativeResidue, nativeResidueLayer]);
     const chainMetrics = useMemo(() => requiresBoundMetrics ? {} : viewerAnalyses?.chainMetrics ?? {}, [requiresBoundMetrics, viewerAnalyses?.chainMetrics]);
     const chainMetricsBusy = viewerAnalyses?.chainMetricsBusy ?? false;
     const onRunChainMetrics = viewerAnalyses?.onRunChainMetrics;
@@ -1469,12 +1475,13 @@ export default function StructureViewerPane({
     const allMetricLayers = useMemo<readonly MetricLayer[]>(
         () => [
             ...(nativeResidueLayer ? [nativeResidueLayer] : []),
+            ...(nativeTokenAtomLayer ? [nativeTokenAtomLayer] : []),
             ...structureScalarMetricLayers,
             ...(subunitMeanPlddtLayer ? [subunitMeanPlddtLayer] : []),
             ...pairMetricLayers,
             ...interfaceMetricLayers,
         ],
-        [nativeResidueLayer, interfaceMetricLayers, pairMetricLayers, structureScalarMetricLayers, subunitMeanPlddtLayer],
+        [nativeResidueLayer, nativeTokenAtomLayer, interfaceMetricLayers, pairMetricLayers, structureScalarMetricLayers, subunitMeanPlddtLayer],
     );
 
 
@@ -3080,7 +3087,7 @@ export default function StructureViewerPane({
                                 structureDocumentId={nativeDocument?.documentId ?? governedWorkbenchContext?.structureDocumentId}
                                 structureContentSha256={nativeDocument?.contentSha256}
                                 derivedComponents={derivedComponents}
-                                activeMetricId={overlayView === 'pae' ? 'pae' : residueMetricLayer?.descriptor.id}
+                                activeMetricId={overlayView === 'pae' ? 'pae' : nativeResidueLayer?.descriptor.id ?? residueMetricLayer?.descriptor.id}
                                 showMetricWorkbench={!shapeMetrics && metricWorkbenchOpen}
                                 metricDetails={selectedDesign && nativeChains.status === 'ok' ? (
                                     <details className="rounded border border-slate-700 bg-slate-900/95 p-2 text-xs">

platform/frontend/src/lib/scientificViewerIdentity.ts

@@ -96,7 +96,7 @@ function sampled(value: unknown, count: number): number[] {
 }
 
 export type ScientificNativeMetric = { status: 'unavailable'; reason: string } | {
-    status: 'ok'; reason: null; metric: 'residue_plddt' | 'atom_plddt' | 'chain_metrics';
+    status: 'ok'; reason: null; metric: 'residue_plddt' | 'atom_plddt' | 'token_plddt' | 'chain_metrics';
     document: StructureDocumentRef; artifactSha256: string; residues: AtomRef[];
     confidenceSource?: { producerVersion: string; scope: 'collapsed_residue'; storedUnits: 'percent' };
     values: number[]; chains: { providerIndex: string; chainId: string; residues: AtomRef[]; ptm: number }[];
@@ -112,7 +112,7 @@ export function parseScientificNativeMetric(raw: unknown, expected: StructureDoc
     try {
         if (raw == null) return {status:'unavailable',reason:'Native metric not loaded'};
         const initial = record(raw);
-        const actualMetric: 'residue_plddt' | 'atom_plddt' | 'chain_metrics' = metric === 'residue_plddt' && initial.metric === 'atom_plddt' ? 'atom_plddt' : metric;
+        const actualMetric: 'residue_plddt' | 'atom_plddt' | 'token_plddt' | 'chain_metrics' = metric === 'residue_plddt' && (initial.metric === 'atom_plddt' || initial.metric === 'token_plddt') ? initial.metric : metric;
         const p = exact(raw, initial.status === 'unavailable' ? envelopeKeys : [...nativeBaseKeys,
             ...(metric === 'residue_plddt' ? ['units','values'] : ['chain_index_map','chains_ptm','pair_chains_iptm','role_assignment','role_reason'])]);
         if (p.schema_name !== 'core_protein_viewer_metric' || p.schema_version !== 1 || p.contract_revision !== 1 || p.metric !== actualMetric) throw Error('unsupported native metric schema');

platform/frontend/src/structureViewer/StructureViewerHost.tsx

@@ -490,7 +490,7 @@ export default function StructureViewerHost({
                         </details>
                     )}
                     {showMetricWorkbench && activeLayer && <MetricLegendPanel layer={activeLayer} visible={layerVisible} opacity={layerOpacity} onVisibilityChange={setLayerVisible} onOpacityChange={setLayerOpacity} onReset={() => { setLayerVisible(true); setLayerOpacity(1); setFilters(DEFAULT_FILTERS); }} />}
-                    {showMetricWorkbench && !(pairLayer && 'dataset' in pairLayer && pairLayer.dataset?.matrixDirection === 'directed') && <FilterPanel value={filters} availableChains={chains} metricRange={activeLayer?.descriptor.valueRange} metricUnits={activeLayer?.descriptor.units ?? undefined} metricDisplayScale={activeLayer?.descriptor.id === 'native-plddt' && ['fraction', 'fractional'].includes(activeLayer.descriptor.units ?? '') ? 100 : 1} onChange={setFilters} />}
+                    {showMetricWorkbench && !(pairLayer && 'dataset' in pairLayer && pairLayer.dataset?.matrixDirection === 'directed') && <FilterPanel value={filters} availableChains={chains} metricRange={activeLayer?.descriptor.valueRange} metricUnits={activeLayer?.descriptor.units ?? undefined} metricDisplayScale={['native-plddt', 'native-plddt-atoms'].includes(activeLayer?.descriptor.id ?? '') && ['fraction', 'fractional'].includes(activeLayer.descriptor.units ?? '') ? 100 : 1} onChange={setFilters} />}
                     {showLinkedSequence && residueLayer && <SequenceTrackExtension
                         key={residueLayer.descriptor.id}
                         metricId={residueLayer.descriptor.id}
@@ -501,7 +501,7 @@ export default function StructureViewerHost({
                             value: typeof entry.value === 'number' ? entry.value : null,
                             missingness: entry.missingness,
                             // Display only: the registry, palette and export keep native fractions.
-                            displayValue: residueLayer.descriptor.id === 'native-plddt' && ['fraction', 'fractional'].includes(residueLayer.descriptor.units ?? '') && typeof entry.value === 'number'
+                            displayValue: ['native-plddt', 'native-plddt-atoms'].includes(residueLayer.descriptor.id ?? '') && ['fraction', 'fractional'].includes(residueLayer.descriptor.units ?? '') && typeof entry.value === 'number'
                                 ? `${(entry.value * 100).toFixed(1)} / 100` : undefined,
                         }))}
                         selectedKeys={selectedResidueKeys}

platform/frontend/src/structureViewer/extensions/metrics/MetricLegendPanel.tsx

@@ -1,6 +1,6 @@
 import type { MetricDescriptor, MetricLayer } from '../../metrics/metricContracts.js';
 
-const formatRange = (descriptor: MetricDescriptor): string => descriptor.id === 'native-plddt' && ['fraction', 'fractional'].includes(descriptor.units ?? '') ? '0–100 display (native fraction × 100)' : descriptor.valueRange
+const formatRange = (descriptor: MetricDescriptor): string => ['native-plddt', 'native-plddt-atoms'].includes(descriptor.id ?? '') && ['fraction', 'fractional'].includes(descriptor.units ?? '') ? '0–100 display (native fraction × 100)' : descriptor.valueRange
     ? `${descriptor.valueRange[0]}–${descriptor.valueRange[1]}${descriptor.units ? ` ${descriptor.units}` : ''}`
     : descriptor.units ?? 'unitless';
 

platform/frontend/src/structureViewer/metrics/metricProjection.ts

@@ -32,7 +32,7 @@ const finiteValues = (values: readonly MetricValue<ResidueRef>[]): number[] => v
 
 /** Display precision only: native values and provenance remain in the metric layer. */
 const metricTooltip = (layer: MetricLayer, value: number, identity: ResidueRef | AtomRef): string => {
-    const nativePlddt = layer.descriptor.id === 'native-plddt' && layer.descriptor.units === 'fraction';
+    const nativePlddt = ['native-plddt', 'native-plddt-atoms'].includes(layer.descriptor.id ?? '') && layer.descriptor.units === 'fraction';
     const rendered = nativePlddt ? `${(value * 100).toFixed(1)} /100`
         : `${Number(value.toPrecision(4))}${layer.descriptor.units ? ` ${layer.descriptor.units}` : ''}`;
     const author = identity.authAsymId !== undefined && identity.authSeqId !== undefined;