jbrowse-plugin-msaview 3.4.0 → 3.5.0

package/dist/MsaViewPanel/doLaunchBlast.js

@@ -1,116 +1,99 @@
-import { makeId, strip } from '../LaunchMsaView/components/util';
 import { cleanProteinSequence } from '../LaunchMsaView/util';
 import { saveBlastResult } from '../utils/blastCache';
-import { queryEbiBlast } from '../utils/ebiBlast';
-import { launchMSA, launchTree } from '../utils/msa';
-import { buildPhmmerMsa, buildRowMetadata } from '../utils/msaRows';
-import { queryPhmmer } from '../utils/phmmer';
+import { searchBackends } from '../utils/homologSearch';
+import { launchMSA } from '../utils/msa';
+import { buildSearchMsa } from '../utils/msaRows';
 import { fetchTaxonomyInfo } from '../utils/taxonomyNames';
-export async function doLaunchBlast({ self, }) {
-    // kept whole rather than destructured: the database's type depends on
-    // searchProgram, and pulling the two apart loses the link between them
-    const params = self.blastParams;
-    const { selectedTranscript } = params;
-    const cleanedSeq = cleanProteinSequence(params.proteinSequence);
-    const onProgress = (arg) => {
-        self.setProgress(arg);
-    };
-    // publish the job id before the first poll so the view can link out while the
-    // job is still running
-    const onRid = (r) => {
-        self.setRid(r);
-    };
-    const { msa, tree, treeMetadata, rid } = params.searchProgram === 'phmmer'
-        ? await runPhmmer({
-            query: cleanedSeq,
-            database: params.blastDatabase,
-            onProgress,
-            onRid,
-        })
-        : await runBlast({
-            query: cleanedSeq,
-            blastDatabase: params.blastDatabase,
-            msaAlgorithm: params.msaAlgorithm,
-            onProgress,
-            onRid,
-        });
-    const treeMetadataJson = JSON.stringify(treeMetadata);
-    await saveBlastResult({
-        proteinSequence: cleanedSeq,
-        blastDatabase: params.blastDatabase,
-        msaAlgorithm: params.msaAlgorithm,
-        searchProgram: params.searchProgram,
-        msa,
-        tree,
-        treeMetadata: treeMetadataJson,
-        rid,
-        geneId: selectedTranscript?.get('parentId'),
-        transcriptId: selectedTranscript?.id(),
-        transcriptName: selectedTranscript?.get('name') ?? selectedTranscript?.get('id'),
-        geneName: selectedTranscript?.get('gene_name') ??
-            selectedTranscript?.get('parentId'),
-    });
-    return { msa, tree, treeMetadata: treeMetadataJson };
+import { resolveUniProtEntry } from '../utils/unirefHomologs';
+import { transcriptFields, transcriptName } from './util';
+function asString(val) {
+    return typeof val === 'string' ? val : undefined;
 }
 /**
- * BLAST returns each hit already aligned to the query, but pairwise and one hit
- * at a time, so the alignments are stripped back off and every hit is realigned
- * together by a dedicated aligner.
+ * The query sequence, and what its row is called. The dialog hands over the
+ * translated transcript and the row stays `QUERY`; a spec naming a UniProt
+ * accession has the sequence fetched and the row named after the entry
+ * (`P53_HUMAN_query`), since a search of swissprot returns the entry itself
+ * as a hit and two rows called the same thing collapse into one.
  */
-async function runBlast({ query, blastDatabase, msaAlgorithm, onProgress, onRid, }) {
-    const { hits, rid } = await queryEbiBlast({
-        query,
-        blastDatabase,
-        onProgress,
-        onRid,
-    });
-    onProgress('Fetching species taxonomy info...');
-    const taxonomyInfo = await fetchTaxonomyInfo(hits
-        .map(h => h.description[0]?.taxid)
-        .filter((t) => t !== undefined));
-    const treeMetadata = {};
-    const sequences = hits.map(h => {
-        const desc = h.description[0] ?? {
-            accession: 'unknown',
-            id: 'unknown',
-            sciname: 'unknown',
+async function resolveQuery(self, scope) {
+    const params = self.blastParams;
+    if (params.proteinSequence) {
+        return {
+            sequence: cleanProteinSequence(params.proteinSequence),
+            name: self.querySeqName,
         };
-        const rowName = makeId(desc, taxonomyInfo);
-        treeMetadata[rowName] = buildRowMetadata(desc, taxonomyInfo);
-        return `>${rowName}\n${strip(h.hsps[0]?.hseq ?? '')}`;
-    });
-    const result = await launchMSA({
-        algorithm: msaAlgorithm,
-        sequence: [`>QUERY\n${query}`, ...sequences].join('\n'),
-        onProgress,
-    });
-    return { ...result, treeMetadata, rid };
+    }
+    if (params.accession) {
+        scope.onProgress(`Fetching ${params.accession} from UniProt...`);
+        const entry = await resolveUniProtEntry([params.accession], 0, scope.signal);
+        if (!entry) {
+            throw new Error(`UniProt has no entry ${params.accession}`);
+        }
+        const name = `${entry.id}_query`;
+        scope.act(() => {
+            self.setQuerySeqName(name);
+        });
+        return { sequence: entry.sequence, name };
+    }
+    throw new Error('No query: a search needs a proteinSequence, a UniProt accession, or a connectedTranscript to translate');
 }
 /**
- * phmmer aligns every hit to a profile of the query as it searches, so its own
- * output is the MSA and there is no realignment step — the hits keep the
- * placement HMMER gave them, and the query row is derived from the alignment's
- * match columns rather than being aligned back in afterwards. That leaves no
- * aligner run to take a tree from, so the tree is built from this alignment.
+ * A similarity search, then an alignment of what it found. The program is a
+ * backend behind one interface (utils/homologSearch.ts); what differs between
+ * them is settled by whether the result came back aligned. A program that
+ * aligns as it searches (phmmer) hands over the alignment and the tree is
+ * built from it in the browser; one that does not (blastp) hands over bare
+ * hits and the chosen aligner runs on them.
  */
-async function runPhmmer({ query, database, onProgress, onRid, }) {
-    const { rows, queryRow, rid } = await queryPhmmer({
+export async function doLaunchBlast({ self, scope, }) {
+    const params = self.blastParams;
+    const { selectedTranscript, maxHits, searchProgram = 'blastp' } = params;
+    const { sequence: query, name: querySeqName } = await resolveQuery(self, scope);
+    const { onProgress, onRid, signal } = scope;
+    const { hits, queryRow, rid } = await searchBackends[searchProgram]({
         query,
-        database,
+        database: params.blastDatabase,
+        maxHits,
         onProgress,
         onRid,
+        signal,
     });
+    if (hits.length === 0) {
+        throw new Error('No hits found');
+    }
     onProgress('Fetching species taxonomy info...');
-    const taxonomyInfo = await fetchTaxonomyInfo(rows.map(r => r.taxid).filter((t) => t !== undefined));
-    const { msa, treeMetadata } = buildPhmmerMsa({
-        rows,
+    const taxonomyInfo = await fetchTaxonomyInfo(hits.map(h => h.taxid).filter((t) => t !== undefined));
+    const { msa: fasta, treeMetadata } = buildSearchMsa({
+        hits,
+        query,
         queryRow,
         taxonomyInfo,
+        querySeqName,
     });
-    return {
+    const { msa, tree } = queryRow
+        ? { msa: fasta, tree: '' }
+        : await launchMSA({
+            algorithm: params.msaAlgorithm ?? 'browser',
+            sequence: fasta,
+            onProgress,
+            signal,
+        });
+    const transcript = transcriptFields(selectedTranscript);
+    const treeMetadataJson = JSON.stringify(treeMetadata);
+    await saveBlastResult({
+        proteinSequence: query,
+        blastDatabase: params.blastDatabase,
+        msaAlgorithm: params.msaAlgorithm,
+        searchProgram: params.searchProgram,
         msa,
-        tree: await launchTree({ alignment: msa, onProgress }),
-        treeMetadata,
-        rid,
-    };
+        tree,
+        treeMetadata: treeMetadataJson,
+        rid: rid ?? '',
+        geneId: asString(transcript.parentId),
+        transcriptId: asString(transcript.uniqueId),
+        transcriptName: transcriptName(selectedTranscript),
+        geneName: asString(transcript.gene_name) ?? asString(transcript.parentId),
+    });
+    return { msa, tree, treeMetadata: treeMetadataJson };
 }

package/dist/MsaViewPanel/doLaunchBlast.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/MsaViewPanel/doLaunchBlast.test.js

@@ -0,0 +1,158 @@
+import { beforeEach, expect, test, vi } from 'vitest';
+import { saveBlastResult } from '../utils/blastCache';
+import { searchBackends } from '../utils/homologSearch';
+import { launchMSA } from '../utils/msa';
+import { fetchTaxonomyInfo } from '../utils/taxonomyNames';
+import { resolveUniProtEntry } from '../utils/unirefHomologs';
+import { doLaunchBlast } from './doLaunchBlast';
+// Every network call is mocked: what is under test is how the launch turns a
+// request into a search and the search's answer into rows -- which backend it
+// asks, where the query comes from, and whether an aligner runs.
+vi.mock('../utils/homologSearch', () => ({
+    searchBackends: { blastp: vi.fn(), phmmer: vi.fn() },
+}));
+vi.mock('../utils/msa', () => ({ launchMSA: vi.fn() }));
+vi.mock('../utils/taxonomyNames', () => ({ fetchTaxonomyInfo: vi.fn() }));
+vi.mock('../utils/blastCache', () => ({ saveBlastResult: vi.fn() }));
+vi.mock('../utils/unirefHomologs', () => ({ resolveUniProtEntry: vi.fn() }));
+const blastp = vi.mocked(searchBackends.blastp);
+const phmmer = vi.mocked(searchBackends.phmmer);
+const mockLaunchMSA = vi.mocked(launchMSA);
+const setQuerySeqName = vi.fn();
+const HIT = { accession: 'P1', id: 'P1_MOUSE', sciname: 'Mus musculus' };
+function makeModel(blastParams) {
+    return {
+        blastParams,
+        querySeqName: 'QUERY',
+        setQuerySeqName,
+    };
+}
+function launch(self) {
+    return doLaunchBlast({
+        self,
+        scope: {
+            signal: new AbortController().signal,
+            act: fn => {
+                fn();
+            },
+            onProgress: () => { },
+            onRid: () => { },
+        },
+    });
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(fetchTaxonomyInfo).mockResolvedValue(new Map());
+    vi.mocked(saveBlastResult).mockResolvedValue(undefined);
+});
+test('bare hits go to the chosen aligner, with the query first', async () => {
+    blastp.mockResolvedValue({ rid: 'job', hits: [{ ...HIT, sequence: 'MKWV' }] });
+    mockLaunchMSA.mockResolvedValue({ msa: 'aligned', tree: 'tree' });
+    const result = await launch(makeModel({
+        searchProgram: 'blastp',
+        blastDatabase: 'uniprotkb_swissprot',
+        msaAlgorithm: 'clustalo',
+        maxHits: 20,
+        proteinSequence: 'MKWVTF*',
+    }));
+    expect(blastp).toHaveBeenCalledWith(expect.objectContaining({
+        query: 'MKWVTF',
+        database: 'uniprotkb_swissprot',
+        maxHits: 20,
+    }));
+    expect(mockLaunchMSA).toHaveBeenCalledWith(expect.objectContaining({
+        algorithm: 'clustalo',
+        sequence: '>QUERY\nMKWVTF\n>P1-Mus_musculus\nMKWV',
+    }));
+    expect(result.msa).toBe('aligned');
+    expect(result.tree).toBe('tree');
+});
+test('an aligned result skips the aligner and leaves the tree to the browser', async () => {
+    phmmer.mockResolvedValue({
+        rid: 'job',
+        queryRow: 'MKWV-TF',
+        hits: [{ ...HIT, sequence: 'MKWVSTF' }],
+    });
+    const result = await launch(makeModel({
+        searchProgram: 'phmmer',
+        blastDatabase: 'rp15',
+        proteinSequence: 'MKWVTF',
+    }));
+    expect(mockLaunchMSA).not.toHaveBeenCalled();
+    expect(result.msa).toBe('>QUERY\nMKWV-TF\n>P1-Mus_musculus\nMKWVSTF');
+    expect(result.tree).toBe('');
+});
+test('a UniProt accession supplies the query and names its row', async () => {
+    vi.mocked(resolveUniProtEntry).mockResolvedValue({
+        accession: 'P04637',
+        id: 'P53_HUMAN',
+        reviewed: true,
+        taxId: 9606,
+        scientificName: 'Homo sapiens',
+        sequence: 'MEEPQ',
+    });
+    phmmer.mockResolvedValue({
+        queryRow: 'MEEPQ',
+        hits: [{ ...HIT, sequence: 'MEEPQ' }],
+    });
+    const result = await launch(makeModel({
+        searchProgram: 'phmmer',
+        blastDatabase: 'swissprot',
+        accession: 'P04637',
+    }));
+    expect(resolveUniProtEntry).toHaveBeenCalledWith(['P04637'], 0, expect.any(AbortSignal));
+    expect(setQuerySeqName).toHaveBeenCalledWith('P53_HUMAN_query');
+    expect(result.msa.split('\n')[0]).toBe('>P53_HUMAN_query');
+});
+test('a request with no query at all is refused before any search runs', async () => {
+    await expect(launch(makeModel({ searchProgram: 'phmmer', blastDatabase: 'swissprot' }))).rejects.toThrow(/connectedTranscript/);
+    expect(phmmer).not.toHaveBeenCalled();
+});
+// blastParams is a frozen snapshot property, so the Feature the dialog put in
+// it comes back from a session reload as the plain JSON it serialized to. The
+// launch used to call .get() on that, minutes after the EBI job the reload
+// resubmitted had come back, and threw where nothing was catching.
+test('a transcript restored from a session snapshot still labels the cache row', async () => {
+    blastp.mockResolvedValue({ rid: 'job', hits: [{ ...HIT, sequence: 'MKWV' }] });
+    mockLaunchMSA.mockResolvedValue({ msa: 'aligned', tree: 'tree' });
+    await launch(makeModel({
+        searchProgram: 'blastp',
+        blastDatabase: 'uniprotkb_swissprot',
+        msaAlgorithm: 'clustalo',
+        proteinSequence: 'MKWV',
+        selectedTranscript: {
+            uniqueId: 'NM_000546.6',
+            name: 'TP53-201',
+            parentId: 'TP53',
+            gene_name: 'TP53',
+        },
+    }));
+    expect(saveBlastResult).toHaveBeenCalledWith(expect.objectContaining({
+        geneId: 'TP53',
+        transcriptId: 'NM_000546.6',
+        transcriptName: 'TP53-201',
+        geneName: 'TP53',
+    }));
+});
+test('a live Feature handed over in the same session labels it the same way', async () => {
+    blastp.mockResolvedValue({ rid: 'job', hits: [{ ...HIT, sequence: 'MKWV' }] });
+    mockLaunchMSA.mockResolvedValue({ msa: 'aligned', tree: 'tree' });
+    const json = {
+        uniqueId: 'NM_000546.6',
+        name: 'TP53-201',
+        parentId: 'TP53',
+    };
+    await launch(makeModel({
+        searchProgram: 'blastp',
+        blastDatabase: 'uniprotkb_swissprot',
+        msaAlgorithm: 'clustalo',
+        proteinSequence: 'MKWV',
+        selectedTranscript: { toJSON: () => json },
+    }));
+    expect(saveBlastResult).toHaveBeenCalledWith(expect.objectContaining({
+        geneId: 'TP53',
+        transcriptId: 'NM_000546.6',
+        transcriptName: 'TP53-201',
+        geneName: 'TP53',
+    }));
+});

package/dist/MsaViewPanel/doLaunchOrthologs.d.ts

@@ -1,4 +1,5 @@
 import type { JBrowsePluginMsaViewModel } from './model';
+import type { LaunchScope } from './runLaunch';
 /**
  * The no-search-job alternative to doLaunchBlast.
  *
@@ -16,8 +17,9 @@ import type { JBrowsePluginMsaViewModel } from './model';
  * would silently break the genome<->MSA linkage. The query species is therefore
  * excluded from the ortholog set rather than appearing twice.
  */
-export declare function doLaunchOrthologs({ self, }: {
+export declare function doLaunchOrthologs({ self, scope, }: {
     self: JBrowsePluginMsaViewModel;
+    scope: LaunchScope;
 }): Promise<{
     treeMetadata: string;
     msa: string;

package/dist/MsaViewPanel/doLaunchOrthologs.js

@@ -3,6 +3,8 @@ import { launchMSA } from '../utils/msa';
 import { dedupeLabels, fetchOrthologRows, fetchProteinForGene, resolveGeneId, } from '../utils/ncbiOrthologs';
 import { fetchPantherOrthologs } from '../utils/pantherOrthologs';
 import { fetchTaxonomyInfo } from '../utils/taxonomyNames';
+import { fetchUnirefHomologs } from '../utils/unirefHomologs';
+import { transcriptName } from './util';
 /**
  * The no-search-job alternative to doLaunchBlast.
  *
@@ -20,11 +22,9 @@ import { fetchTaxonomyInfo } from '../utils/taxonomyNames';
  * would silently break the genome<->MSA linkage. The query species is therefore
  * excluded from the ortholog set rather than appearing twice.
  */
-export async function doLaunchOrthologs({ self, }) {
-    const { taxId, taxa, maxSpecies, geneCandidates, msaAlgorithm, proteinSequence, source = 'ncbi', } = self.orthologParams;
-    const onProgress = (arg) => {
-        self.setProgress(arg);
-    };
+export async function doLaunchOrthologs({ self, scope, }) {
+    const { taxId, taxa, maxSpecies, geneCandidates, msaAlgorithm, proteinSequence, source = 'ncbi', identity, referenceProteomesOnly, } = self.orthologParams;
+    const { onProgress, act, signal } = scope;
     const request = {
         taxId,
         geneCandidates,
@@ -36,7 +36,14 @@ export async function doLaunchOrthologs({ self, }) {
     };
     const { geneId, representative, rows } = source === 'panther'
         ? await findPantherOrthologs(request)
-        : await findNcbiOrthologs(request);
+        : source === 'uniref'
+            ? await findUnirefHomologs({
+                ...request,
+                identity,
+                referenceProteomesOnly,
+                signal,
+            })
+            : await findNcbiOrthologs(request);
     // The query row. The dialog always supplies it — it is the user's OWN
     // selected transcript, which is what makes `connectedFeature` map genome
     // coordinates through this row. A launch that has no transcript to translate
@@ -48,7 +55,7 @@ export async function doLaunchOrthologs({ self, }) {
         ? cleanProteinSequence(proteinSequence)
         : representative?.sequence;
     if (!cleanedSeq) {
-        throw new Error(`No query protein: none was supplied and ${source === 'panther' ? 'PANTHER' : 'NCBI'} returned no representative protein for gene ${geneId}.`);
+        throw new Error(`No query protein: none was supplied and ${sourceNames[source]} returned no representative protein for gene ${geneId}.`);
     }
     // The query row is named for its species like every other row, with a suffix
     // marking it as the one the genome view is linked to. A bare `QUERY` among
@@ -62,7 +69,9 @@ export async function doLaunchOrthologs({ self, }) {
     // token, and a collision would silently point the coordinate mapping at
     // another animal's row.
     const queryLabel = await queryRowLabel(taxId, rows);
-    self.setQuerySeqName(queryLabel);
+    act(() => {
+        self.setQuerySeqName(queryLabel);
+    });
     const treeMetadata = {
         [queryLabel]: buildQueryMetadata(self, geneId, cleanedSeq, representative),
     };
@@ -76,6 +85,7 @@ export async function doLaunchOrthologs({ self, }) {
             ...rows.map(r => `>${r.label}\n${r.sequence}`),
         ].join('\n'),
         onProgress,
+        signal,
     });
     return {
         ...result,
@@ -102,6 +112,33 @@ async function findNcbiOrthologs({ taxId, geneCandidates, onProgress, ...rest })
     });
     return { geneId: resolved.geneId, representative, rows };
 }
+const sourceNames = {
+    ncbi: 'NCBI',
+    panther: 'PANTHER',
+    uniref: 'UniProt',
+};
+/**
+ * The query's own UniProt entry stands in for a representative protein: the
+ * entry the cluster was looked up from, whose sequence a spec-launched row
+ * takes and whose accession earns the CDD overlay when the two match.
+ */
+async function findUnirefHomologs({ geneCandidates, identity, referenceProteomesOnly, signal, ...rest }) {
+    const found = await fetchUnirefHomologs({
+        candidates: geneCandidates,
+        identity,
+        referenceProteomesOnly,
+        signal,
+        ...rest,
+    });
+    return {
+        geneId: found.query.id,
+        representative: {
+            accession: found.query.accession,
+            sequence: found.query.sequence,
+        },
+        rows: found.rows,
+    };
+}
 /**
  * One `matchortho` call resolves the gene, names its own UniProt entry and
  * lists an ortholog per genome, so the representative protein needs no second
@@ -161,9 +198,8 @@ async function fetchRepresentativeQueryProtein(geneId) {
  * protein as its query row passes that test by construction.
  */
 function buildQueryMetadata(self, geneId, proteinSequence, representative) {
-    const transcript = self.orthologParams?.selectedTranscript;
     const metadata = { 'Gene ID': geneId };
-    const name = transcript?.get('name') ?? transcript?.get('id');
+    const name = transcriptName(self.orthologParams?.selectedTranscript);
     if (name) {
         metadata.Transcript = name;
     }