jbrowse-plugin-msaview 2.5.0 → 2.5.1

package/dist/utils/domainCache.d.ts

@@ -0,0 +1,8 @@
+import type { DomainMatch } from './ncbiDomains';
+interface CachedDomain {
+    accession: string;
+    matches: DomainMatch[];
+}
+export declare function getCachedDomains(accessions: string[]): Promise<(CachedDomain | undefined)[]>;
+export declare function saveDomains(entries: CachedDomain[]): Promise<void>;
+export {};

package/dist/utils/domainCache.js

@@ -0,0 +1,28 @@
+import { openDB } from 'idb';
+const DB_NAME = 'jbrowse-msaview-domain-cache';
+const STORE_NAME = 'domains';
+const DB_VERSION = 1;
+async function getDB() {
+    return openDB(DB_NAME, DB_VERSION, {
+        upgrade(db) {
+            if (!db.objectStoreNames.contains(STORE_NAME)) {
+                db.createObjectStore(STORE_NAME, { keyPath: 'accession' });
+            }
+        },
+    });
+}
+export async function getCachedDomains(accessions) {
+    const db = await getDB();
+    const tx = db.transaction(STORE_NAME, 'readonly');
+    const results = await Promise.all(accessions.map(accession => tx.store.get(accession)));
+    await tx.done;
+    return results;
+}
+export async function saveDomains(entries) {
+    const db = await getDB();
+    const tx = db.transaction(STORE_NAME, 'readwrite');
+    for (const entry of entries) {
+        await tx.store.put(entry);
+    }
+    await tx.done;
+}

package/dist/utils/eutils.d.ts

@@ -0,0 +1,3 @@
+export declare const NCBI_TOOL = "jbrowse-plugin-msaview";
+export declare const NCBI_EMAIL = "colin.diesh@gmail.com";
+export declare function efetchUrl(params: Record<string, string>): string;

package/dist/utils/eutils.js

@@ -0,0 +1,14 @@
+// NCBI asks that programmatic E-utilities requests identify themselves with a
+// tool name and contact email so they can reach out before throttling, rather
+// than silently rate-limiting. https://www.ncbi.nlm.nih.gov/books/NBK25497/
+export const NCBI_TOOL = 'jbrowse-plugin-msaview';
+export const NCBI_EMAIL = 'colin.diesh@gmail.com';
+const EUTILS = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils';
+export function efetchUrl(params) {
+    const search = new URLSearchParams({
+        ...params,
+        tool: NCBI_TOOL,
+        email: NCBI_EMAIL,
+    });
+    return `${EUTILS}/efetch.fcgi?${search.toString()}`;
+}

package/dist/utils/msa.js

@@ -1,4 +1,5 @@
-import { textfetch, timeout } from './fetch';
+import { textfetch } from './fetch';
+import { pollLoop } from './poll';
 const base = `https://www.ebi.ac.uk/Tools/services/rest`;
 const email = 'colin.diesh@gmail.com';
 const algorithms = {
@@ -24,20 +25,22 @@ const algorithms = {
     },
 };
 async function wait({ onProgress, jobId, algorithm, }) {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    while (true) {
-        const result = await textfetch(`${base}/${algorithm}/status/${jobId}`);
-        if (result === 'FINISHED') {
-            break;
-        }
-        else if (result.includes('FAILURE')) {
-            throw new Error(`Failed to run: jobId ${jobId}`);
-        }
-        for (let i = 0; i < 10; i++) {
-            onProgress(`Re-checking MSA status in... ${10 - i}`);
-            await timeout(1000);
-        }
-    }
+    await pollLoop({
+        intervalSeconds: 10,
+        onCountdown: s => {
+            onProgress(`Re-checking MSA status in... ${s}`);
+        },
+        check: async () => {
+            const result = await textfetch(`${base}/${algorithm}/status/${jobId}`);
+            if (result.includes('FINISHED')) {
+                return true;
+            }
+            if (result.includes('FAILURE')) {
+                throw new Error(`Failed to run: jobId ${jobId}`);
+            }
+            return false;
+        },
+    });
 }
 export async function launchMSA({ algorithm, sequence, onProgress, }) {
     const config = algorithms[algorithm];

package/dist/utils/ncbiBlast.js

@@ -1,4 +1,5 @@
-import { jsonfetch, textfetch, timeout } from './fetch';
+import { jsonfetch, textfetch } from './fetch';
+import { pollLoop } from './poll';
 export async function queryBlastFromRid({ rid, baseUrl, onProgress, }) {
     onProgress(`Checking BLAST status for RID: ${rid}...`);
     await waitForRid({
@@ -56,31 +57,28 @@ async function initialQuery({ query, blastProgram, blastDatabase, baseUrl, }) {
     };
 }
 async function waitForRid({ rid, onProgress, baseUrl, }) {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    while (true) {
-        const res = await textfetch(`${baseUrl}?CMD=Get&FORMAT_OBJECT=SearchInfo&RID=${rid}`);
-        const statusMatch = /\s+Status=(\S+)/m.exec(res);
-        const status = statusMatch?.[1];
-        const hasHits = /\s+ThereAreHits=yes/m.test(res);
-        if (status === 'WAITING') {
-            const iter = 20;
-            for (let i = 0; i < iter; i++) {
-                onProgress(`Re-checking BLAST status in... ${iter - i}`);
-                await timeout(1000);
+    await pollLoop({
+        intervalSeconds: 20,
+        onCountdown: s => {
+            onProgress(`Re-checking BLAST status in... ${s}`);
+        },
+        check: async () => {
+            const res = await textfetch(`${baseUrl}?CMD=Get&FORMAT_OBJECT=SearchInfo&RID=${rid}`);
+            const status = /\s+Status=(\S+)/m.exec(res)?.[1];
+            const hasHits = /\s+ThereAreHits=yes/m.test(res);
+            if (status === 'WAITING') {
+                return false;
             }
-            continue;
-        }
-        if (status === 'FAILED') {
-            throw new Error(`BLAST ${rid} failed`);
-        }
-        if (status === 'READY') {
-            if (hasHits) {
-                return true;
+            if (status === 'FAILED') {
+                throw new Error(`BLAST ${rid} failed`);
             }
-            else {
+            if (status === 'READY') {
+                if (hasHits) {
+                    return true;
+                }
                 throw new Error('No hits found');
             }
-        }
-        throw new Error(`BLAST ${rid} returned unexpected status: ${status ?? 'unknown'}`);
-    }
+            throw new Error(`BLAST ${rid} returned unexpected status: ${status ?? 'unknown'}`);
+        },
+    });
 }

package/dist/utils/ncbiDomains.d.ts

@@ -0,0 +1,39 @@
+import type { InterProScanResults } from 'react-msaview';
+export type DomainMatch = InterProScanResults['matches'][number];
+/**
+ * Parse a GenPept (efetch db=protein&rettype=gp&retmode=xml) document into CDD
+ * domain and site annotations, keyed by both the versioned and primary
+ * accession so callers can look up by whichever NCBI returned.
+ */
+export declare function parseCddDomains(xml: string): Map<string, {
+    signature: {
+        entry?: {
+            name: string;
+            description: string;
+            accession: string;
+        };
+    };
+    locations: {
+        start: number;
+        end: number;
+    }[];
+}[]>;
+/**
+ * Fetch pre-computed CDD domain and site annotations for NCBI protein
+ * accessions. These come baked into the GenPept records, so a single batched
+ * efetch returns them with no job submission or polling. Results are cached in
+ * IndexedDB so reopening a view doesn't refetch.
+ */
+export declare function fetchProteinDomains(accessions: string[]): Promise<Map<string, {
+    signature: {
+        entry?: {
+            name: string;
+            description: string;
+            accession: string;
+        };
+    };
+    locations: {
+        start: number;
+        end: number;
+    }[];
+}[]>>;

package/dist/utils/ncbiDomains.js

@@ -0,0 +1,154 @@
+import { getCachedDomains, saveDomains } from './domainCache';
+import { efetchUrl } from './eutils';
+import { textfetch } from './fetch';
+function field(xml, tag) {
+    return new RegExp(`<${tag}>(.*?)</${tag}>`, 's').exec(xml)?.[1];
+}
+function parseQualifiers(featureXml) {
+    const quals = {};
+    const re = /<GBQualifier>([\s\S]*?)<\/GBQualifier>/g;
+    let m;
+    while ((m = re.exec(featureXml)) !== null) {
+        const name = field(m[1], 'GBQualifier_name');
+        const value = field(m[1], 'GBQualifier_value');
+        // keep the first occurrence: NCBI lists the canonical value first
+        if (name && value !== undefined && quals[name] === undefined) {
+            quals[name] = value;
+        }
+    }
+    return quals;
+}
+// A feature can span several intervals: domains are usually one contiguous
+// range, but CDD Sites (e.g. an active site) are a set of scattered residues
+// expressed as multiple GBInterval ranges and single GBInterval_point residues.
+// We collapse those to a single bounding span so a site renders as one box
+// rather than a spray of 1px specks.
+function parseBoundingSpan(featureXml) {
+    const starts = [];
+    const ends = [];
+    const re = /<GBInterval>([\s\S]*?)<\/GBInterval>/g;
+    let m;
+    while ((m = re.exec(featureXml)) !== null) {
+        const block = m[1];
+        const from = field(block, 'GBInterval_from');
+        const to = field(block, 'GBInterval_to');
+        const point = field(block, 'GBInterval_point');
+        if (from && to) {
+            starts.push(Number(from));
+            ends.push(Number(to));
+        }
+        else if (point) {
+            starts.push(Number(point));
+            ends.push(Number(point));
+        }
+    }
+    return starts.length > 0
+        ? { start: Math.min(...starts), end: Math.max(...ends) }
+        : undefined;
+}
+// Drop single-residue specks (acetylation/phospho points) but keep every
+// genuine domain and functional site; react-msaview draws longest-first, so
+// smaller features (binding sites, loops) layer on top of the domain they sit
+// inside.
+const MIN_FEATURE_LENGTH = 2;
+function parseFeature(featureXml) {
+    const key = field(featureXml, 'GBFeature_key');
+    const quals = parseQualifiers(featureXml);
+    const xref = quals.db_xref;
+    const span = parseBoundingSpan(featureXml);
+    // only CDD-backed Regions/Sites are conserved-domain annotations; Regions and
+    // Sites without a CDD xref are UniProt-propagated point motifs we don't want
+    if ((key === 'Region' || key === 'Site') &&
+        xref?.startsWith('CDD:') &&
+        span &&
+        span.end - span.start + 1 >= MIN_FEATURE_LENGTH) {
+        const cddId = xref.replace('CDD:', '');
+        const isDomain = key === 'Region';
+        // a site's note (e.g. "ATP binding site [chemical binding]") is more
+        // specific than its generic site_type ("other"), so prefer it for the name
+        // — that gives each functional site its own color/legend/filter entry
+        const noteName = quals.note?.split(/[[(]/)[0]?.trim();
+        const name = isDomain
+            ? (quals.region_name ?? cddId)
+            : noteName || quals.site_type || 'site';
+        const accession = isDomain ? cddId : `${cddId}:${name}`;
+        return {
+            signature: { entry: { name, description: quals.note ?? name, accession } },
+            locations: [span],
+        };
+    }
+    return undefined;
+}
+/**
+ * Parse a GenPept (efetch db=protein&rettype=gp&retmode=xml) document into CDD
+ * domain and site annotations, keyed by both the versioned and primary
+ * accession so callers can look up by whichever NCBI returned.
+ */
+export function parseCddDomains(xml) {
+    const byAccession = new Map();
+    const seqRe = /<GBSeq>([\s\S]*?)<\/GBSeq>/g;
+    let seqMatch;
+    while ((seqMatch = seqRe.exec(xml)) !== null) {
+        const seqXml = seqMatch[1];
+        const matches = [];
+        const featRe = /<GBFeature>([\s\S]*?)<\/GBFeature>/g;
+        let featMatch;
+        while ((featMatch = featRe.exec(seqXml)) !== null) {
+            const match = parseFeature(featMatch[1]);
+            if (match) {
+                matches.push(match);
+            }
+        }
+        for (const acc of [
+            field(seqXml, 'GBSeq_accession-version'),
+            field(seqXml, 'GBSeq_primary-accession'),
+        ]) {
+            if (acc) {
+                byAccession.set(acc, matches);
+            }
+        }
+    }
+    return byAccession;
+}
+/**
+ * Fetch pre-computed CDD domain and site annotations for NCBI protein
+ * accessions. These come baked into the GenPept records, so a single batched
+ * efetch returns them with no job submission or polling. Results are cached in
+ * IndexedDB so reopening a view doesn't refetch.
+ */
+export async function fetchProteinDomains(accessions) {
+    const unique = [...new Set(accessions)].filter(Boolean);
+    const byAccession = new Map();
+    const cached = await getCachedDomains(unique);
+    const uncached = [];
+    unique.forEach((acc, i) => {
+        const hit = cached[i];
+        if (hit) {
+            byAccession.set(acc, hit.matches);
+        }
+        else {
+            uncached.push(acc);
+        }
+    });
+    const toCache = [];
+    const batchSize = 100;
+    for (let i = 0; i < uncached.length; i += batchSize) {
+        const batch = uncached.slice(i, i + batchSize);
+        const xml = await textfetch(efetchUrl({
+            db: 'protein',
+            id: batch.join(','),
+            rettype: 'gp',
+            retmode: 'xml',
+        }));
+        const parsed = parseCddDomains(xml);
+        for (const acc of batch) {
+            const matches = parsed.get(acc) ?? [];
+            byAccession.set(acc, matches);
+            toCache.push({ accession: acc, matches });
+        }
+    }
+    if (toCache.length > 0) {
+        await saveDomains(toCache);
+    }
+    return byAccession;
+}

package/dist/utils/poll.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Poll a remote job until it reports done. `check` returns true when finished,
+ * false when still pending, and throws on failure. Between checks it counts down
+ * `intervalSeconds`, calling `onCountdown` each second so the UI can show
+ * progress.
+ */
+export declare function pollLoop({ check, intervalSeconds, onCountdown, }: {
+    check: () => Promise<boolean>;
+    intervalSeconds: number;
+    onCountdown: (secondsRemaining: number) => void;
+}): Promise<void>;

package/dist/utils/poll.js

@@ -0,0 +1,19 @@
+import { timeout } from './fetch';
+/**
+ * Poll a remote job until it reports done. `check` returns true when finished,
+ * false when still pending, and throws on failure. Between checks it counts down
+ * `intervalSeconds`, calling `onCountdown` each second so the UI can show
+ * progress.
+ */
+export async function pollLoop({ check, intervalSeconds, onCountdown, }) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+        if (await check()) {
+            return;
+        }
+        for (let i = intervalSeconds; i > 0; i--) {
+            onCountdown(i);
+            await timeout(1000);
+        }
+    }
+}

package/dist/utils/taxonomyNames.js

@@ -1,4 +1,5 @@
 import { openDB } from 'idb';
+import { efetchUrl } from './eutils';
 const DB_NAME = 'jbrowse-msaview-taxonomy-cache';
 const STORE_NAME = 'common-names';
 const DB_VERSION = 2;
@@ -53,7 +54,7 @@ export async function fetchTaxonomyInfo(taxids) {
         const batch = uncachedTaxids.slice(i, i + batchSize);
         const idsParam = batch.join(',');
         try {
-            const response = await fetch(`https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=taxonomy&id=${idsParam}&retmode=xml`);
+            const response = await fetch(efetchUrl({ db: 'taxonomy', id: idsParam, retmode: 'xml' }));
             const text = await response.text();
             // Build a map of taxid -> taxon block by finding Taxon elements.
             // Prefer entries with <LineageEx> (full top-level entries) over nested

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.5.0";
+export declare const version = "2.5.1";

package/dist/version.js

@@ -1 +1 @@
-export const version = '2.5.0';
+export const version = '2.5.1';

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.5.0",
+  "version": "2.5.1",
   "license": "MIT",
   "name": "jbrowse-plugin-msaview",
   "repository": {
@@ -20,7 +20,7 @@
     "g2p_mapper": "^2.1.5",
     "idb": "^8.0.3",
     "pako-esm2": "^2.0.2",
-    "react-msaview": "^5.1.1",
+    "react-msaview": "^5.4.1",
     "swr": "^2.4.1"
   },
   "devDependencies": {
@@ -28,36 +28,39 @@
     "@eslint/js": "^10.0.1",
     "@fal-works/esbuild-plugin-global-externals": "^2.1.2",
     "@jbrowse/core": "^4.3.0",
-    "@jbrowse/mobx-state-tree": "^5.10.2",
+    "@jbrowse/mobx-state-tree": "^5.10.8",
     "@jbrowse/plugin-linear-genome-view": "^4.3.0",
     "@mui/icons-material": "^7.3.11",
     "@mui/material": "^7.3.11",
     "@mui/system": "^7.3.11",
     "@mui/x-data-grid": "^8.28.7",
     "@types/node": "^25.9.1",
-    "@types/react": "^19.2.15",
-    "@typescript-eslint/eslint-plugin": "^8.60.0",
-    "@typescript-eslint/parser": "^8.60.0",
+    "@types/react": "^19.2.16",
+    "@typescript-eslint/eslint-plugin": "^8.60.1",
+    "@typescript-eslint/parser": "^8.60.1",
     "esbuild": "^0.28.0",
-    "eslint": "^10.4.0",
+    "eslint": "^10.4.1",
     "eslint-plugin-import-x": "^4.16.2",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-unicorn": "^64.0.0",
     "mobx": "^6.15.4",
     "mobx-react": "^9.2.2",
+    "msa-parsers": "5.4.1",
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0",
     "prettier": "^3.8.3",
     "pretty-bytes": "^7.1.0",
     "puppeteer": "^25.1.0",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "rimraf": "^6.1.3",
     "rxjs": "^7.8.2",
     "serve": "^14.2.6",
     "tss-react": "^4.9.21",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.60.0",
-    "vitest": "^4.1.7"
+    "typescript-eslint": "^8.60.1",
+    "vitest": "^4.1.8"
   },
   "scripts": {
     "clean": "rimraf dist",

package/src/LaunchMsaViewExtensionPoint/index.ts

@@ -24,6 +24,7 @@ export default function LaunchMsaViewExtensionPointF(
       labelsAlignRight,
       showBranchLen,
       querySeqName,
+      highlightColumns,
     }: {
       session: AbstractSessionModel
       data?: { msa: string; tree?: string }
@@ -41,6 +42,7 @@ export default function LaunchMsaViewExtensionPointF(
       labelsAlignRight?: boolean
       showBranchLen?: boolean
       querySeqName?: string
+      highlightColumns?: number[]
     }) => {
       if (!data && !msaFileLocation) {
         throw new Error(
@@ -61,6 +63,7 @@ export default function LaunchMsaViewExtensionPointF(
         drawNodeBubbles,
         labelsAlignRight,
         showBranchLen,
+        highlightColumns,
         init: {
           msaData: data?.msa,
           treeData: data?.tree,

package/src/MsaViewPanel/afterCreateAutoruns.ts

@@ -2,6 +2,7 @@ import { getSession } from '@jbrowse/core/util'
 
 import { doLaunchBlast } from './doLaunchBlast'
 import { genomeToMSA } from './genomeToMSA'
+import { loadProteinDomains } from './loadProteinDomains'
 import {
   cleanupOldData,
   generateDataStoreId,
@@ -30,6 +31,9 @@ export function loadStoredData(self: JBrowsePluginMsaViewModel) {
           if (storedData.tree) {
             self.setTree(storedData.tree)
           }
+          if (storedData.treeMetadata) {
+            self.setTreeMetadata(storedData.treeMetadata)
+          }
         }
       } catch (e) {
         console.error('Failed to load MSA data from IndexedDB:', e)
@@ -95,6 +99,34 @@ export function launchBlastIfNeeded(self: JBrowsePluginMsaViewModel) {
   }
 }
 
+/**
+ * Once an accession-bearing alignment is present (fresh from BLAST or restored
+ * from cache), fetch NCBI CDD domains for those accessions and overlay them.
+ * Runs once per view; the domainsRequested guard prevents refiring when NCBI
+ * returns no domains (which leaves interProAnnotations undefined).
+ */
+export function autoLoadProteinDomains(self: JBrowsePluginMsaViewModel) {
+  const { rows, domainsRequested, interProAnnotations } = self
+  const hasAccessions = self.data.treeMetadata?.includes('"Accession"') ?? false
+  if (
+    rows.length > 0 &&
+    hasAccessions &&
+    !interProAnnotations &&
+    !domainsRequested
+  ) {
+    self.setDomainsRequested(true)
+    void (async () => {
+      try {
+        await loadProteinDomains(self)
+      } catch (e) {
+        console.error('[msaview-domains] auto-load failed:', e)
+      } finally {
+        self.setProgress('')
+      }
+    })()
+  }
+}
+
 export function processInit(self: JBrowsePluginMsaViewModel) {
   const { init } = self
   if (init) {

package/src/MsaViewPanel/loadProteinDomains.ts

@@ -0,0 +1,57 @@
+import { fetchProteinDomains } from '../utils/ncbiDomains'
+
+import type { InterProScanResults } from 'react-msaview'
+
+// structural subset of the MSA model: the full model type can't be used here
+// because it references this very action, creating a self-referential cycle
+interface DomainModel {
+  data: { treeMetadata?: string }
+  setProgress: (arg: string) => void
+  setDomains: (data: Record<string, InterProScanResults>) => void
+}
+
+/**
+ * Overlay protein domains on the alignment using NCBI's pre-computed CDD
+ * annotations. The BLAST workflow stores each hit's accession in treeMetadata,
+ * so we look those up via efetch and key the results by MSA row name (which is
+ * what react-msaview matches domains against).
+ */
+export async function loadProteinDomains(self: DomainModel) {
+  const metadataJson = self.data.treeMetadata
+  if (!metadataJson) {
+    throw new Error('No sequence metadata available to look up domains')
+  }
+  const metadata = JSON.parse(metadataJson) as Record<
+    string,
+    Record<string, string>
+  >
+
+  const rowAccessions = Object.entries(metadata)
+    .map(([rowName, meta]) => ({ rowName, accession: meta.Accession }))
+    .filter((r): r is { rowName: string; accession: string } => !!r.accession)
+
+  if (rowAccessions.length === 0) {
+    throw new Error('No NCBI accessions found in alignment rows')
+  }
+
+  self.setProgress(
+    `Fetching protein domains from NCBI for ${rowAccessions.length} sequences...`,
+  )
+  const byAccession = await fetchProteinDomains(
+    rowAccessions.map(r => r.accession),
+  )
+
+  const annotations: Record<string, InterProScanResults> = {}
+  for (const { rowName, accession } of rowAccessions) {
+    const matches = byAccession.get(accession)
+    if (matches && matches.length > 0) {
+      annotations[rowName] = { matches, xref: [{ id: rowName }] }
+    }
+  }
+
+  if (Object.keys(annotations).length === 0) {
+    throw new Error('No CDD domain annotations found for these proteins')
+  }
+
+  self.setDomains(annotations)
+}