pdbe-molstar 3.4.0 → 3.6.0

package/lib/extensions/complexes/coloring.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colorComponents = colorComponents;
+exports.colorSubcomplex = colorSubcomplex;
+exports.colorSupercomplex = colorSupercomplex;
+const tslib_1 = require("tslib");
+const color_1 = require("molstar/lib/mol-util/color");
+const helpers_1 = require("../../helpers");
+const DEFAULT_CORE_COLOR = '#d8d8d8';
+const DEFAULT_UNMAPPED_COLOR = '#222222';
+const DEFAULT_COMPONENT_COLORS = [
+    '#1b9e77', '#d95f02', '#7570b3', '#e7298a', '#66a61e', '#e6ab02', '#a6761d', // Dark-2
+    '#7f3c8d', '#11a579', '#3969ac', '#f2b701', '#e73f74', '#80ba5a', '#e68310', '#008695', '#cf1c90', '#f97b72', // Bold
+    '#66c5cc', '#f6cf71', '#f89c74', '#dcb0f2', '#87c55f', '#9eb9f3', '#fe88b1', '#c9db74', '#8be0a4', '#b497e7', // Pastel
+    '#e5c494', '#66c2a5', '#fc8d62', '#8da0cb', '#e78ac3', '#a6d854', // Set-2
+];
+// TODO compare color variants:
+// http://127.0.0.1:1339/complexes-demo.html?complexId=PDB-CPX-159519&unmappedColor=%23222222
+// http://127.0.0.1:1339/complexes-demo.html?complexId=PDB-CPX-159519&unmappedColor=%23ff0000
+/** How much lighter/darker colors should be for the base/other complex */
+const COLOR_ADJUSTMENT_STRENGTH = 0.75;
+function colorComponents(viewer, params) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const { coreColor = DEFAULT_CORE_COLOR, componentColors = DEFAULT_COMPONENT_COLORS, components, mappings = {} } = params;
+        const colorData = [];
+        const tooltipData = [{ tooltip: '<b>Base complex</b>' }];
+        for (let i = 0; i < components.length; i++) {
+            const accession = components[i];
+            const color = componentColors[i % componentColors.length];
+            colorData.push(...selectorItems(accession, mappings[accession], { color: adjustForBase(color) }));
+            tooltipData.push(...selectorItems(accession, mappings[accession], { tooltip: `<b>component ${accession}</b>` }));
+        }
+        yield viewer.visual.select({ data: colorData, nonSelectedColor: adjustForBase(coreColor), structureId: params.structId });
+        yield viewer.visual.tooltips({ data: tooltipData, structureId: params.structId });
+    });
+}
+function colorSubcomplex(viewer, params) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const { coreColor = DEFAULT_CORE_COLOR, componentColors = DEFAULT_COMPONENT_COLORS, baseComponents, baseMappings = {}, otherMappings = {} } = params;
+        const subComponentsSet = new Set(params.otherComponents);
+        const baseColorData = [];
+        const baseTooltipData = [{ tooltip: '<b>Base complex</b>' }];
+        const subColorData = [];
+        const subTooltipData = [{ tooltip: '<b>Subcomplex</b>' }];
+        for (let i = 0; i < baseComponents.length; i++) {
+            const accession = baseComponents[i];
+            if (subComponentsSet.has(accession)) {
+                const color = componentColors[i % componentColors.length];
+                baseColorData.push(...selectorItems(accession, baseMappings[accession], { color: adjustForBase(color) }));
+                baseTooltipData.push(...selectorItems(accession, baseMappings[accession], { tooltip: `<b>common component ${accession}</b>` }));
+                subColorData.push(...selectorItems(accession, otherMappings[accession], { color: adjustForOther(color) }));
+                subTooltipData.push(...selectorItems(accession, otherMappings[accession], { tooltip: `<b>common component ${accession}</b>` }));
+            }
+            else {
+                baseTooltipData.push(...selectorItems(accession, baseMappings[accession], { tooltip: `<b>additional component ${accession}</b>` }));
+            }
+        }
+        if (params.baseStructId) {
+            yield viewer.visual.select({ data: baseColorData, nonSelectedColor: adjustForBase(coreColor), structureId: params.baseStructId });
+            yield viewer.visual.tooltips({ data: baseTooltipData, structureId: params.baseStructId });
+        }
+        if (params.otherStructId) {
+            yield viewer.visual.select({ data: subColorData, nonSelectedColor: adjustForOther(coreColor), structureId: params.otherStructId });
+            yield viewer.visual.tooltips({ data: subTooltipData, structureId: params.otherStructId });
+        }
+    });
+}
+function colorSupercomplex(viewer, params) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const { coreColor = DEFAULT_CORE_COLOR, unmappedColor = DEFAULT_UNMAPPED_COLOR, componentColors = DEFAULT_COMPONENT_COLORS, baseMappings = {}, otherMappings = {} } = params;
+        const baseComponentsSet = new Set(params.baseComponents);
+        const superComponents = params.baseComponents.concat(params.otherComponents.filter(acc => !baseComponentsSet.has(acc))); // reorder supercomplex accessions so that colors are consistent with the base
+        const baseColorData = [];
+        const baseTooltipData = [{ tooltip: '<b>Base complex</b>' }];
+        const superColorData = [];
+        const superTooltipData = [{ tooltip: '<b>Supercomplex</b>' }];
+        for (let i = 0; i < superComponents.length; i++) {
+            const accession = superComponents[i];
+            if (baseComponentsSet.has(accession)) {
+                baseColorData.push(...selectorItems(accession, baseMappings[accession], { color: adjustForBase(coreColor) }));
+                baseTooltipData.push(...selectorItems(accession, baseMappings[accession], { tooltip: `<b>common component ${accession}</b>` }));
+                superColorData.push(...selectorItems(accession, otherMappings[accession], { color: adjustForOther(coreColor) }));
+                superTooltipData.push(...selectorItems(accession, otherMappings[accession], { tooltip: `<b>common component ${accession}</b>` }));
+            }
+            else {
+                const color = componentColors[i % componentColors.length];
+                superColorData.push(...selectorItems(accession, otherMappings[accession], { color: adjustForOther(color) }));
+                superTooltipData.push(...selectorItems(accession, otherMappings[accession], { tooltip: `<b>additional component ${accession}</b>` }));
+            }
+        }
+        if (params.baseStructId) {
+            yield viewer.visual.select({ data: baseColorData, nonSelectedColor: adjustForBase(unmappedColor), structureId: params.baseStructId });
+            yield viewer.visual.tooltips({ data: baseTooltipData, structureId: params.baseStructId });
+        }
+        if (params.otherStructId) {
+            yield viewer.visual.select({ data: superColorData, nonSelectedColor: adjustForOther(unmappedColor), structureId: params.otherStructId });
+            yield viewer.visual.tooltips({ data: superTooltipData, structureId: params.otherStructId });
+        }
+    });
+}
+/** Adjust color for use on the base structure (slightly lighten) */
+function adjustForBase(color) {
+    return color_1.Color.toHexStyle(color_1.Color.lighten((0, helpers_1.normalizeColor)(color), COLOR_ADJUSTMENT_STRENGTH));
+}
+/** Adjust color for use on the subcomplex/supercomplex structure (slightly darken) */
+function adjustForOther(color) {
+    return color_1.Color.toHexStyle(color_1.Color.darken((0, helpers_1.normalizeColor)(color), COLOR_ADJUSTMENT_STRENGTH));
+}
+/** Create items for `.visual.select` or `.visual.tooltip`, preferrably based on `mappings`, or based on `uniprot_accession` if `mappings` not provided. */
+function selectorItems(uniprot_accession, mappings, extras) {
+    if (mappings) {
+        return mappings.map(m => (Object.assign(Object.assign({}, m), extras)));
+    }
+    else {
+        return [Object.assign({ uniprot_accession }, extras)];
+    }
+}
+;

package/lib/extensions/complexes/index.d.ts

@@ -0,0 +1,55 @@
+/** Helper functions to allow superposition of complexes */
+import { Structure } from 'molstar/lib/mol-model/structure';
+import { PDBeMolstarPlugin } from '../..';
+import { QueryParam } from '../../helpers';
+import { SuperpositionResult } from './superpose-by-biggest-chain';
+export * as Coloring from './coloring';
+export interface LoadComplexSuperpositionParams {
+    /** PDB identifier of complex structure */
+    pdbId: string;
+    /** Assembly identifier */
+    assemblyId: string;
+    /** Arbitrary string identifier to refer to the newly loaded structure later */
+    id?: string;
+    /** Duration of camera transition, in milliseconds. Default: 250. Do not use 0 (won't work because of bugs in Molstar), but you can use 1. */
+    animationDuration?: number;
+    /** Apply coloring to the base structure and newly loaded structure.
+     * 'subcomplex' = color the common components by unique entities (UniProt/Rfam accession); color remaining components by base color (gray).
+     * 'supercomplex' = color the common components by base color (gray); color additional components in the new structure (supercomplex) by unique entities. */
+    coloring?: 'subcomplex' | 'supercomplex' | undefined;
+    /** List of Uniprot/Rfam accessions in the base complex. Mandatory when `coloring` is not `undefined`. */
+    baseComponents?: string[];
+    /** List of Uniprot/Rfam accessions in the newly loaded complex. Mandatory when `coloring` is not `undefined`. */
+    otherComponents?: string[];
+    /** Base color for coloring "uninteresting" parts of structures (i.e. subcomplexes: additional components, supercomplexes: common components). Default: gray. */
+    coreColor?: string;
+    /** Color for coloring unmapped additional components for supercomplexes. */
+    unmappedColor?: string;
+    /** List of colors for coloring unique entities. */
+    componentColors?: string[];
+    /** Optional specification of which parts of the base complex structure belong to individual Uniprot/Rfam accessions (will be inferred from mmCIF atom_site if not provided) */
+    baseMappings?: {
+        [accession: string]: QueryParam[];
+    };
+    /** Optional specification of which parts of the other complex structure belong to individual Uniprot/Rfam accessions (will be inferred from mmCIF atom_site if not provided) */
+    otherMappings?: {
+        [accession: string]: QueryParam[];
+    };
+    /** Superposition method */
+    method?: 'biggest-matched-chain' | 'molstar-builtin';
+}
+/** Load a structure, superpose onto the main structure based on Uniprot residue numbers, and optionally apply coloring to show common/additional components. */
+export declare function loadComplexSuperposition(viewer: PDBeMolstarPlugin, params: LoadComplexSuperpositionParams): Promise<{
+    /** Structure identifier of the newly loaded complex structure, to refer to this structure later */
+    id: string;
+    /** Status of pairwise superposition ('success' / 'zero-overlap' / 'failed') */
+    status: "success" | "zero-overlap" | "failed";
+    /** Superposition RMSD and tranform (if status is 'success') */
+    superposition: (import("molstar/lib/mol-math/linear-algebra/3d/minimize-rmsd").MinimizeRmsd.Result & {
+        nAlignedElements: number;
+    }) | undefined;
+    /** Function that deletes the newly loaded complex structure */
+    delete: () => Promise<void>;
+}>;
+/** Superpose mobile structure onto static structure, based on Uniprot residue numbers. */
+export declare function superposeStructuresByMolstarDefault(staticStruct: Structure, mobileStruct: Structure): SuperpositionResult;

package/lib/extensions/complexes/index.js

@@ -0,0 +1,123 @@
+"use strict";
+/** Helper functions to allow superposition of complexes */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Coloring = void 0;
+exports.loadComplexSuperposition = loadComplexSuperposition;
+exports.superposeStructuresByMolstarDefault = superposeStructuresByMolstarDefault;
+const tslib_1 = require("tslib");
+const superposition_sifts_mapping_1 = require("molstar/lib/mol-model/structure/structure/util/superposition-sifts-mapping");
+const commands_1 = require("molstar/lib/mol-plugin/commands");
+const sleep_1 = require("molstar/lib/mol-util/sleep");
+const __1 = require("../..");
+const helpers_1 = require("../../helpers");
+const superposition_1 = require("../../superposition");
+const Coloring = tslib_1.__importStar(require("./coloring"));
+const superpose_by_biggest_chain_1 = require("./superpose-by-biggest-chain");
+exports.Coloring = tslib_1.__importStar(require("./coloring"));
+/** Load a structure, superpose onto the main structure based on Uniprot residue numbers, and optionally apply coloring to show common/additional components. */
+function loadComplexSuperposition(viewer, params) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const { pdbId, assemblyId, animationDuration = 250, coloring, baseComponents, otherComponents, baseMappings, otherMappings, coreColor, unmappedColor, componentColors, method = 'biggest-matched-chain' } = params;
+        const baseStructId = __1.PDBeMolstarPlugin.MAIN_STRUCTURE_ID;
+        const otherStructId = (_a = params.id) !== null && _a !== void 0 ? _a : `${pdbId}_${assemblyId}`;
+        // Apply coloring to base structure
+        if (coloring) {
+            if (!baseComponents)
+                throw new Error('`baseComponents` is required when `coloring` is not `undefined`');
+            if (!otherComponents)
+                throw new Error('`otherComponents` is required when `coloring` is not `undefined`');
+        }
+        if (coloring === 'subcomplex') {
+            yield Coloring.colorSubcomplex(viewer, { baseStructId, baseComponents: baseComponents, otherComponents: otherComponents, baseMappings, otherMappings, coreColor, componentColors });
+        }
+        if (coloring === 'supercomplex') {
+            yield Coloring.colorSupercomplex(viewer, { baseStructId, baseComponents: baseComponents, otherComponents: otherComponents, baseMappings, otherMappings, coreColor, unmappedColor, componentColors });
+        }
+        // Load other structure
+        const otherStructUrl = (0, helpers_1.getStructureUrl)(viewer.initParams, { pdbId, queryType: 'full' });
+        yield viewer.load({ url: otherStructUrl, isBinary: viewer.initParams.encoding === 'bcif', assemblyId, id: otherStructId }, false);
+        yield viewer.visual.structureVisibility(otherStructId, false); // hide structure until superposition complete, to avoid flickering
+        const baseStruct = (_c = (_b = viewer.getStructure(baseStructId)) === null || _b === void 0 ? void 0 : _b.cell.obj) === null || _c === void 0 ? void 0 : _c.data;
+        if (!baseStruct)
+            throw new Error('Static structure not loaded');
+        const otherStruct = (_e = (_d = viewer.getStructure(otherStructId)) === null || _d === void 0 ? void 0 : _d.cell.obj) === null || _e === void 0 ? void 0 : _e.data;
+        if (!otherStruct)
+            throw new Error('Mobile structure not loaded');
+        // Superpose other structure on base structure
+        const { status, superposition } = method === 'biggest-matched-chain' ?
+            (0, superpose_by_biggest_chain_1.superposeStructuresByBiggestCommonChain)(baseStruct, otherStruct, baseComponents, otherComponents)
+            : superposeStructuresByMolstarDefault(baseStruct, otherStruct);
+        if (superposition) {
+            yield (0, superposition_1.transform)(viewer.plugin, viewer.getStructure(otherStructId).cell, superposition.bTransform);
+        }
+        // Apply coloring to other structure
+        if (coloring === 'subcomplex') {
+            yield Coloring.colorSubcomplex(viewer, { otherStructId, baseComponents: baseComponents, otherComponents: otherComponents, baseMappings, otherMappings, coreColor, componentColors });
+        }
+        if (coloring === 'supercomplex') {
+            yield Coloring.colorSupercomplex(viewer, { otherStructId, baseComponents: baseComponents, otherComponents: otherComponents, baseMappings, otherMappings, coreColor, unmappedColor, componentColors });
+        }
+        // Adjust camera
+        const staticStructRef = viewer.getStructure(baseStructId);
+        const mobileStructRef = viewer.getStructure(otherStructId); // it is important to run this after superposition, to get correct coordinates for camera adjustment
+        // Wanted to use PluginCommands.Camera.Focus with viewer.plugin.canvas3d?.boundingSphere, but seems to not work properly, so using the following workaround:
+        yield commands_1.PluginCommands.Camera.FocusObject(viewer.plugin, {
+            targets: [
+                { targetRef: staticStructRef === null || staticStructRef === void 0 ? void 0 : staticStructRef.cell.transform.ref, extraRadius: 0.3 },
+                { targetRef: (_g = ((_f = mobileStructRef === null || mobileStructRef === void 0 ? void 0 : mobileStructRef.transform) !== null && _f !== void 0 ? _f : mobileStructRef)) === null || _g === void 0 ? void 0 : _g.cell.transform.ref, extraRadius: 0.3 },
+                // 0.3 is amount by which bounding sphere algorithm usually underestimates actual visible bounding sphere
+            ],
+            durationMs: animationDuration,
+        });
+        yield (0, sleep_1.sleep)(animationDuration); // wait until camera adjustment completed
+        // Reveal new structure
+        yield viewer.visual.structureVisibility(otherStructId, true);
+        return {
+            /** Structure identifier of the newly loaded complex structure, to refer to this structure later */
+            id: otherStructId,
+            /** Status of pairwise superposition ('success' / 'zero-overlap' / 'failed') */
+            status,
+            /** Superposition RMSD and tranform (if status is 'success') */
+            superposition,
+            /** Function that deletes the newly loaded complex structure */
+            delete: () => viewer.deleteStructure(otherStructId),
+        };
+    });
+}
+/** Superpose mobile structure onto static structure, based on Uniprot residue numbers. */
+function superposeStructuresByMolstarDefault(staticStruct, mobileStruct) {
+    var _a;
+    const aln = (0, superposition_sifts_mapping_1.alignAndSuperposeWithSIFTSMapping)([staticStruct, mobileStruct], { traceOnly: true });
+    const superposition = (_a = aln.entries.find(e => e.pivot === 0 && e.other === 1)) === null || _a === void 0 ? void 0 : _a.transform;
+    if (superposition) {
+        return { status: 'success', superposition: Object.assign(Object.assign({}, superposition), { nAlignedElements: Number.NaN }) };
+    }
+    else if (aln.zeroOverlapPairs.find(e => e[0] === 0 && e[1] === 1)) {
+        return { status: 'zero-overlap', superposition: undefined };
+    }
+    else {
+        return { status: 'failed', superposition: undefined };
+    }
+}
+/*
+Coloring - subcomplexes:
+- base common -> by entity, lighter
+- base additional -> gray, lighter
+- sub common -> by entity, darker
+- sub additional -> gray, darker (these are all unmapped components, includes antibodies and ligands)
+
+-> Colors can be assigned based on base complex and applied to subcomplex
+
+Coloring - supercomplexes:
+- base common -> gray, lighter
+- base additional -> unmapped color, lighter (these are all unmapped components, includes antibodies and ligands)
+- super common -> gray, darker
+- super additional mapped -> by entity, darker
+- super additional unmapped -> unmapped color, darker
+
+-> Colors can be assigned based on supercomplex complex, consistency between supercomplexes is probably not necessary
+
+-> For both subcomplexes and supercomplexes, colors could be assigned based on UniprotID hash -> database-wide consistency but complexes with similar-color components will occur
+
+*/

package/lib/extensions/complexes/superpose-by-biggest-chain.d.ts

@@ -0,0 +1,17 @@
+import { MinimizeRmsd } from 'molstar/lib/mol-math/linear-algebra/3d/minimize-rmsd';
+import { Structure } from 'molstar/lib/mol-model/structure';
+export type SuperpositionResult = {
+    status: 'success';
+    superposition: MinimizeRmsd.Result & {
+        nAlignedElements: number;
+    };
+} | {
+    status: 'zero-overlap';
+    superposition: undefined;
+} | {
+    status: 'failed';
+    superposition: undefined;
+};
+/** Status of pairwise superposition (success = superposed, zero-overlap = failed to superpose because the two structures have no matchable elements, failed = failed to superpose for other reasons) */
+export type SuperpositionStatus = SuperpositionResult['status'];
+export declare function superposeStructuresByBiggestCommonChain(structA: Structure, structB: Structure, allowedComponentsA: string[] | undefined, allowedComponentsB: string[] | undefined): SuperpositionResult;

package/lib/extensions/complexes/superpose-by-biggest-chain.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.superposeStructuresByBiggestCommonChain = superposeStructuresByBiggestCommonChain;
+const minimize_rmsd_1 = require("molstar/lib/mol-math/linear-algebra/3d/minimize-rmsd");
+const mmcif_1 = require("molstar/lib/mol-model-formats/structure/mmcif");
+function extractUniprotIndex(structure, allowedAccessions) {
+    var _a, _b, _c;
+    var _d, _e;
+    const allowedAccessionsSet = allowedAccessions ? new Set(allowedAccessions) : undefined;
+    const seenUnitInvariantIds = new Set();
+    const out = {};
+    for (const unit of structure.units) {
+        if (seenUnitInvariantIds.has(unit.invariantId))
+            continue;
+        else
+            seenUnitInvariantIds.add(unit.invariantId);
+        const src = structure.model.sourceData;
+        if (!mmcif_1.MmcifFormat.is(src))
+            throw new Error('Source data must be mmCIF/BCIF');
+        const h = unit.model.atomicHierarchy;
+        const { pdbx_sifts_xref_db_acc, pdbx_sifts_xref_db_name, pdbx_sifts_xref_db_num } = src.data.db.atom_site;
+        const atoms = unit.polymerElements;
+        const nAtoms = atoms.length;
+        for (let i = 0; i < nAtoms; i++) {
+            const iAtom = atoms[i];
+            const srcIAtom = h.atomSourceIndex.value(iAtom);
+            const dbName = pdbx_sifts_xref_db_name.value(srcIAtom);
+            if (dbName !== 'UNP')
+                continue;
+            const dbAcc = pdbx_sifts_xref_db_acc.value(srcIAtom);
+            if (allowedAccessionsSet && !allowedAccessionsSet.has(dbAcc))
+                continue;
+            const dbNum = pdbx_sifts_xref_db_num.value(srcIAtom);
+            const structMapping = (_a = out[dbAcc]) !== null && _a !== void 0 ? _a : (out[dbAcc] = {});
+            const chainMapping = (_b = structMapping[_d = unit.id]) !== null && _b !== void 0 ? _b : (structMapping[_d] = {
+                label_asym_id: h.chains.label_asym_id.value(h.chainAtomSegments.index[atoms[0]]),
+                auth_asym_id: h.chains.auth_asym_id.value(h.chainAtomSegments.index[atoms[0]]),
+                atomMap: {},
+            });
+            (_c = (_e = chainMapping.atomMap)[dbNum]) !== null && _c !== void 0 ? _c : (_e[dbNum] = iAtom);
+        }
+    }
+    return out;
+}
+function bestUniprotMatch(a, b) {
+    const sortedA = sortAccessionAndChains(a);
+    const sortedB = sortAccessionAndChains(b);
+    let bestMatch = undefined;
+    let bestScore = 0;
+    for (const accession of sortedA.accessions) {
+        const unitsA = sortedA.units[accession];
+        const unitsB = sortedB.units[accession];
+        if (!unitsB)
+            continue;
+        for (const ua of unitsA) {
+            if (ua.size <= bestScore)
+                break;
+            const unitA = a[accession][ua.unitId];
+            for (const ub of unitsB) {
+                if (ub.size <= bestScore || ua.size <= bestScore)
+                    break;
+                const unitB = b[accession][ub.unitId];
+                const score = objectKeyOverlap(unitA.atomMap, unitB.atomMap);
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestMatch = { accession, unitA: ua.unitId, unitB: ub.unitId, nMatchedElements: score };
+                }
+            }
+        }
+    }
+    return bestMatch;
+}
+/** Sort units for each accession by decreasing size and sort accessions by decreasing biggest unit size. */
+function sortAccessionAndChains(uniprotIndex) {
+    const unitsByAccession = {};
+    for (const accession in uniprotIndex) {
+        const unitIds = uniprotIndex[accession];
+        const units = [];
+        for (const unitId in unitIds) {
+            const size = Object.keys(unitIds[unitId].atomMap).length;
+            units.push({ unitId, size });
+        }
+        units.sort((a, b) => b.size - a.size);
+        unitsByAccession[accession] = units;
+    }
+    return {
+        /** Accessions sorted by decreasing biggest unit size */
+        accessions: Object.keys(unitsByAccession).sort((a, b) => unitsByAccession[b][0].size - unitsByAccession[a][0].size),
+        /** Units per accession, sorted by decreasing unit size */
+        units: unitsByAccession,
+    };
+}
+/** Return number of keys common to objects `a` and `b` */
+function objectKeyOverlap(a, b) {
+    let overlap = 0;
+    for (const key in a) {
+        if (key in b) {
+            overlap++;
+        }
+    }
+    return overlap;
+}
+function superposeStructuresByBiggestCommonChain(structA, structB, allowedComponentsA, allowedComponentsB) {
+    const indexA = extractUniprotIndex(structA, allowedComponentsA);
+    const indexB = extractUniprotIndex(structB, allowedComponentsB);
+    const bestMatch = bestUniprotMatch(indexA, indexB);
+    if (!bestMatch) {
+        return { status: 'zero-overlap', superposition: undefined };
+    }
+    const unitA = structA.unitMap.get(Number(bestMatch.unitA));
+    const unitB = structB.unitMap.get(Number(bestMatch.unitB));
+    const unitIndexA = indexA[bestMatch.accession][bestMatch.unitA];
+    const unitIndexB = indexB[bestMatch.accession][bestMatch.unitB];
+    const positionsA = minimize_rmsd_1.MinimizeRmsd.Positions.empty(bestMatch.nMatchedElements);
+    const positionsB = minimize_rmsd_1.MinimizeRmsd.Positions.empty(bestMatch.nMatchedElements);
+    let i = 0;
+    for (const unpNum in unitIndexA.atomMap) {
+        const iAtomB = unitIndexB.atomMap[unpNum];
+        if (iAtomB === undefined)
+            continue;
+        const iAtomA = unitIndexA.atomMap[unpNum];
+        positionsA.x[i] = unitA.conformation.coordinates.x[iAtomA];
+        positionsA.y[i] = unitA.conformation.coordinates.y[iAtomA];
+        positionsA.z[i] = unitA.conformation.coordinates.z[iAtomA];
+        positionsB.x[i] = unitB.conformation.coordinates.x[iAtomB];
+        positionsB.y[i] = unitB.conformation.coordinates.y[iAtomB];
+        positionsB.z[i] = unitB.conformation.coordinates.z[iAtomB];
+        i++;
+    }
+    const superposition = minimize_rmsd_1.MinimizeRmsd.compute({ a: positionsA, b: positionsB });
+    if (isNaN(superposition.rmsd)) {
+        return { status: 'failed', superposition: undefined };
+    }
+    return { status: 'success', superposition: Object.assign(Object.assign({}, superposition), { nAlignedElements: bestMatch.nMatchedElements }) };
+}

package/lib/extensions/foldseek/index.d.ts

@@ -1,6 +1,6 @@
 /** Helper functions to allow visualizing Foldseek results and superposing them on the query structure */
 import { Mat4 } from 'molstar/lib/mol-math/linear-algebra';
-import { type PDBeMolstarPlugin } from '../..';
+import { PDBeMolstarPlugin } from '../..';
 export interface FoldseekApiData {
     query: string;
     target: string;

package/lib/extensions/foldseek/index.js

@@ -1,18 +1,20 @@
 "use strict";
 /** Helper functions to allow visualizing Foldseek results and superposing them on the query structure */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.exportModels = exports.loadFoldseekSuperposition = void 0;
+exports.loadFoldseekSuperposition = loadFoldseekSuperposition;
+exports.exportModels = exportModels;
 const tslib_1 = require("tslib");
 const export_1 = require("molstar/lib/extensions/model-export/export");
 const minimize_rmsd_1 = require("molstar/lib/mol-math/linear-algebra/3d/minimize-rmsd");
+const __1 = require("../..");
 const helpers_1 = require("../../helpers");
 const superposition_1 = require("../../superposition");
 /** Load target structure as defined by `apiData`
  * and superpose it on the already loaded query structure. */
-function loadFoldseekSuperposition(viewer, targetStructId, apiData, targetColor = '#00ff00') {
-    var _a, _b, _c, _d;
-    return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        const Q_STRUCT_ID = 'main';
+function loadFoldseekSuperposition(viewer_1, targetStructId_1, apiData_1) {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (viewer, targetStructId, apiData, targetColor = '#00ff00') {
+        var _a, _b, _c, _d;
+        const Q_STRUCT_ID = __1.PDBeMolstarPlugin.MAIN_STRUCTURE_ID;
         // Retrieve target entry ID and chain ID
         let tEntryId;
         let tAuthAsymId;
@@ -69,7 +71,6 @@ function loadFoldseekSuperposition(viewer, targetStructId, apiData, targetColor
         return Object.assign(Object.assign({}, superposition), { nAligned: qCoords.x.length });
     });
 }
-exports.loadFoldseekSuperposition = loadFoldseekSuperposition;
 function getMatchedResidues(qstart, qaln, tstart, taln) {
     if (qaln.length !== taln.length) {
         throw new Error('Length of qaln and taln must be the same');
@@ -199,4 +200,3 @@ function discardMissingLocations(a, b) {
 function exportModels(viewer, format = 'cif') {
     return (0, export_1.exportHierarchy)(viewer.plugin, { format });
 }
-exports.exportModels = exportModels;

package/lib/extensions/interactions/index.d.ts

@@ -0,0 +1,36 @@
+/** Helper functions to allow showing custom atom interactions */
+import { PDBeMolstarPlugin } from '../..';
+import { QueryParam } from '../../helpers';
+export interface Interaction {
+    start: QueryParam;
+    end: QueryParam;
+    color?: string;
+    radius?: number;
+    dash_length?: number;
+    tooltip?: string;
+}
+export interface StateObjectHandle {
+    /** State transform reference */
+    ref: string;
+    /** Set state object visibility on/off */
+    setVisibility(visible: boolean): void;
+    /** Remove state object from state hierarchy */
+    delete: () => Promise<void>;
+}
+export declare function loadInteractions_example(viewer: PDBeMolstarPlugin, params?: {
+    opacity?: number;
+    color?: string;
+    radius?: number;
+    dash_length?: number;
+}): Promise<StateObjectHandle>;
+/** Show custom atom interactions */
+export declare function loadInteractions(viewer: PDBeMolstarPlugin, params: {
+    interactions: Interaction[];
+    structureId?: string;
+    opacity?: number;
+    color?: string;
+    radius?: number;
+    dash_length?: number;
+}): Promise<StateObjectHandle>;
+/** Remove any previously added interactions */
+export declare function clearInteractions(viewer: PDBeMolstarPlugin): Promise<void>;

package/lib/extensions/interactions/index.js

@@ -0,0 +1,112 @@
+"use strict";
+/** Helper functions to allow showing custom atom interactions */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadInteractions_example = loadInteractions_example;
+exports.loadInteractions = loadInteractions;
+exports.clearInteractions = clearInteractions;
+const tslib_1 = require("tslib");
+const primitives_1 = require("molstar/lib/extensions/mvs/components/primitives");
+const mvs_data_1 = require("molstar/lib/extensions/mvs/mvs-data");
+const representation_1 = require("molstar/lib/mol-plugin-state/transforms/representation");
+const state_1 = require("molstar/lib/mol-plugin/behavior/static/state");
+const __1 = require("../..");
+const helpers_1 = require("../../helpers");
+const plugin_custom_state_1 = require("../../plugin-custom-state");
+/** Name used when registering extension, custom state, etc. */
+const InteractionsExtensionName = 'pdbe-custom-interactions';
+const getExtensionCustomState = plugin_custom_state_1.ExtensionCustomState.getter(InteractionsExtensionName);
+const DEFAULT_COLOR = 'white';
+const DEFAULT_RADIUS = 0.075;
+const DEFAULT_DASH_LENGTH = 0.1;
+const DEFAULT_OPACITY = 1;
+function loadInteractions_example(viewer, params) {
+    return loadInteractions(viewer, Object.assign(Object.assign({}, params), { interactions: exampleData }));
+}
+/** Show custom atom interactions */
+function loadInteractions(viewer, params) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        var _c;
+        const structureId = (_a = params.structureId) !== null && _a !== void 0 ? _a : __1.PDBeMolstarPlugin.MAIN_STRUCTURE_ID;
+        const struct = viewer.getStructure(structureId);
+        if (!struct)
+            throw new Error(`Did not find structure with ID "${structureId}"`);
+        const primitivesMvsNode = interactionsToMvsPrimitiveData(params);
+        const update = viewer.plugin.build();
+        const data = update.to(struct.cell).apply(primitives_1.MVSInlinePrimitiveData, { node: primitivesMvsNode }, { tags: ['custom-interactions-data'] });
+        data.apply(primitives_1.MVSBuildPrimitiveShape, { kind: 'mesh' }).apply(representation_1.ShapeRepresentation3D, {}, { tags: ['custom-interactions-mesh'] });
+        data.apply(primitives_1.MVSBuildPrimitiveShape, { kind: 'lines' }).apply(representation_1.ShapeRepresentation3D, {}, { tags: ['custom-interactions-lines'] });
+        data.apply(primitives_1.MVSBuildPrimitiveShape, { kind: 'labels' }).apply(representation_1.ShapeRepresentation3D, {}, { tags: ['custom-interactions-labels'] });
+        yield update.commit();
+        const visual = {
+            ref: data.ref,
+            setVisibility: (visible) => (0, state_1.setSubtreeVisibility)(viewer.plugin.state.data, data.ref, !visible /* true means hidden */),
+            delete: () => viewer.plugin.build().delete(data.ref).commit(),
+        };
+        const visualsList = (_b = (_c = getExtensionCustomState(viewer.plugin)).visuals) !== null && _b !== void 0 ? _b : (_c.visuals = []);
+        visualsList.push(visual);
+        return visual;
+    });
+}
+/** Remove any previously added interactions */
+function clearInteractions(viewer) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const visuals = getExtensionCustomState(viewer.plugin).visuals;
+        if (!visuals)
+            return;
+        for (const visual of visuals) {
+            yield visual.delete();
+        }
+        visuals.length = 0;
+    });
+}
+function interactionsToMvsPrimitiveData(params) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const builder = mvs_data_1.MVSData.createBuilder();
+    const primitives = builder.primitives({
+        opacity: (_a = params.opacity) !== null && _a !== void 0 ? _a : DEFAULT_OPACITY,
+        color: (_b = params.color) !== null && _b !== void 0 ? _b : DEFAULT_COLOR,
+    });
+    for (const interaction of params.interactions) {
+        primitives.tube({
+            start: { expressions: (0, helpers_1.queryParamsToMvsComponentExpressions)([interaction.start]) },
+            end: { expressions: (0, helpers_1.queryParamsToMvsComponentExpressions)([interaction.end]) },
+            radius: (_d = (_c = interaction.radius) !== null && _c !== void 0 ? _c : params.radius) !== null && _d !== void 0 ? _d : DEFAULT_RADIUS,
+            dash_length: (_f = (_e = interaction.dash_length) !== null && _e !== void 0 ? _e : params.dash_length) !== null && _f !== void 0 ? _f : DEFAULT_DASH_LENGTH,
+            color: interaction.color,
+            tooltip: interaction.tooltip,
+        });
+    }
+    const state = builder.getState();
+    const primitivesNode = (_g = state.root.children) === null || _g === void 0 ? void 0 : _g.find(child => child.kind === 'primitives');
+    if (!primitivesNode)
+        throw new Error('AssertionError: Failed to create MVS "primitives" subtree.');
+    return primitivesNode;
+}
+/** Selected interactions from https://www.ebi.ac.uk/pdbe/graph-api/pdb/bound_ligand_interactions/1hda/C/143 */
+const exampleData = [
+    {
+        'start': { 'auth_asym_id': 'C', 'auth_seq_id': 143, 'atoms': ['CBC'] },
+        'end': { 'auth_asym_id': 'C', 'auth_seq_id': 32, 'atoms': ['CE'] },
+        'color': 'yellow',
+        'tooltip': '<strong>Hydrophobic interaction</strong><br>HEM 143 | CBC — MET 32 | CE',
+    },
+    {
+        'start': { 'auth_asym_id': 'C', 'auth_seq_id': 143, 'atoms': ['CBC'] },
+        'end': { 'auth_asym_id': 'C', 'auth_seq_id': 32, 'atoms': ['SD'] },
+        'color': 'yellow',
+        'tooltip': '<strong>Hydrophobic interaction</strong><br>HEM 143 | CBC — MET 32 | SD',
+    },
+    {
+        'start': { 'auth_asym_id': 'C', 'auth_seq_id': 143, 'atoms': ['CMD'] },
+        'end': { 'auth_asym_id': 'C', 'auth_seq_id': 42, 'atoms': ['O'] },
+        'color': 'gray',
+        'tooltip': '<strong>Mixed interaction</strong><br>Vdw, Weak polar<br>HEM 143 | CMD — TYR 42 | O',
+    },
+    {
+        'start': { 'auth_asym_id': 'C', 'auth_seq_id': 143, 'atoms': ['C1B', 'C2B', 'C3B', 'C4B', 'NB'] },
+        'end': { 'auth_asym_id': 'C', 'auth_seq_id': 136, 'atoms': ['CD1'] },
+        'color': 'magenta',
+        'tooltip': '<strong>CARBONPI interaction</strong><br>HEM 143 | C1B, C2B, C3B, C4B, NB — LEU 136 | CD1',
+    },
+];