jbrowse-plugin-msaview 3.2.0 → 3.3.0

package/dist/LaunchMsaView/components/OrthologQuery/OrthologPanel.js

@@ -2,10 +2,12 @@ import React, { useMemo, useState } from 'react';
 import { Typography } from '@mui/material';
 import { observer } from 'mobx-react';
 import { makeStyles } from 'tss-react/mui';
+import OrthologSourceSelect, { ORTHOLOG_SOURCE_STORAGE_KEY, } from './OrthologSourceSelect';
 import QuerySpeciesSelect from './QuerySpeciesSelect';
 import { orthologLaunchView } from './orthologLaunchView';
 import TextField2 from '../../../components/TextField2';
 import { defaultMaxSpecies } from '../../../utils/ncbiOrthologs';
+import { useLocalStorage } from '../../../utils/useLocalStorage';
 import { getGeneDisplayName, getGeneIdentifiers, getLinearGenomeView, getTranscriptDisplayName, } from '../../util';
 import MsaAlgorithmSelect from '../BlastQuery/MsaAlgorithmSelect';
 import LaunchPanelContent from '../LaunchPanelContent';
@@ -22,6 +24,7 @@ const OrthologPanel = observer(function ({ handleClose, feature, model, }) {
     const view = getLinearGenomeView(model);
     const [launchViewError, setLaunchViewError] = useState();
     const [taxId, setTaxId] = useState(9606);
+    const [source, setSource] = useLocalStorage(ORTHOLOG_SOURCE_STORAGE_KEY, 'ncbi');
     const [msaAlgorithm, setMsaAlgorithm] = useState('clustalo');
     const [maxSpecies, setMaxSpecies] = useState(String(defaultMaxSpecies));
     const geneCandidates = useMemo(() => getGeneIdentifiers(feature), [feature]);
@@ -32,13 +35,14 @@ const OrthologPanel = observer(function ({ handleClose, feature, model, }) {
     const rowCountValid = Number.isInteger(rowCount) && rowCount >= 2;
     return (React.createElement(React.Fragment, null,
         React.createElement(LaunchPanelContent, { error: e },
-            React.createElement(Typography, { variant: "body2" }, "NCBI's precomputed orthologs, one gene per species, looked up rather than searched for. No BLAST job to queue."),
+            React.createElement(Typography, { variant: "body2" }, "Precomputed orthologs, one gene per species, looked up rather than searched for. No BLAST job to queue."),
             React.createElement("div", null,
+                React.createElement(OrthologSourceSelect, { className: classes.selectField, value: source, onChange: setSource }),
                 React.createElement(QuerySpeciesSelect, { className: classes.selectField, value: taxId, assemblyName: view.assemblyNames[0], onChange: setTaxId }),
                 React.createElement(MsaAlgorithmSelect, { className: classes.selectField, value: msaAlgorithm, onChange: setMsaAlgorithm }),
                 React.createElement(TextField2, { variant: "outlined", label: "Rows to align", className: classes.selectField, type: "number", value: maxSpecies, onChange: event => {
                         setMaxSpecies(event.target.value);
-                    }, error: !rowCountValid, helperText: "the closest N species NCBI has" })),
+                    }, error: !rowCountValid, helperText: `the closest N species ${source === 'panther' ? 'PANTHER' : 'NCBI'} has` })),
             React.createElement(TranscriptSelector, { feature: feature, ...transcriptSelection })),
         React.createElement(SubmitCancelActions, { model: model, submitDisabled: !proteinSequence || !rowCountValid, onSubmit: () => {
                 try {
@@ -50,6 +54,7 @@ const OrthologPanel = observer(function ({ handleClose, feature, model, }) {
                             newViewTitle: `Orthologs - ${getGeneDisplayName(feature)} - ${getTranscriptDisplayName(selectedTranscript)}`,
                             orthologParams: {
                                 taxId,
+                                source,
                                 maxSpecies: rowCount,
                                 geneCandidates,
                                 msaAlgorithm,

package/dist/LaunchMsaView/components/OrthologQuery/OrthologSourceSelect.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { OrthologSource } from '../../../MsaViewPanel/model';
+export declare const ORTHOLOG_SOURCE_STORAGE_KEY = "msaview-ortholog-source";
+export declare const orthologSourceLabels: Record<OrthologSource, string>;
+export default function OrthologSourceSelect({ value, onChange, className, }: {
+    value: OrthologSource;
+    onChange: (val: OrthologSource) => void;
+    className?: string;
+}): React.JSX.Element;

package/dist/LaunchMsaView/components/OrthologQuery/OrthologSourceSelect.js

@@ -0,0 +1,20 @@
+import React from 'react';
+import { MenuItem } from '@mui/material';
+import TextField2 from '../../../components/TextField2';
+export const ORTHOLOG_SOURCE_STORAGE_KEY = 'msaview-ortholog-source';
+export const orthologSourceLabels = {
+    ncbi: 'NCBI orthologs',
+    panther: 'PANTHER',
+};
+// Which species a source can answer for, in the words a reader picking one
+// needs: NCBI's ortholog sets stop at vertebrates and insects, PANTHER's run
+// from human to yeast and Arabidopsis.
+const hints = {
+    ncbi: 'vertebrates and insects',
+    panther: 'also yeast, worm, fly and plants',
+};
+export default function OrthologSourceSelect({ value, onChange, className, }) {
+    return (React.createElement(TextField2, { variant: "outlined", label: "Source", className: className, select: true, value: value, helperText: hints[value], onChange: event => {
+            onChange(event.target.value);
+        } }, Object.keys(orthologSourceLabels).map(val => (React.createElement(MenuItem, { value: val, key: val }, orthologSourceLabels[val])))));
+}

package/dist/MsaViewPanel/doLaunchOrthologs.d.ts

@@ -3,12 +3,14 @@ import type { JBrowsePluginMsaViewModel } from './model';
  * The no-search-job alternative to doLaunchBlast.
  *
  * BLAST spends 10+ minutes answering "what looks like this sequence" and
- * returns a redundant, accession-labelled hit list. This asks NCBI the question
- * the alignment actually wants — "what is this gene's ortholog in each species"
- * — which NCBI has already computed, so the whole NCBI half returns in about a
- * second and only the EBI alignment (~10s) costs real time.
+ * returns a redundant, accession-labelled hit list. This asks the question the
+ * alignment actually wants — "what is this gene's ortholog in each species" —
+ * which NCBI and PANTHER have already computed, so the lookup returns in
+ * seconds and only the EBI alignment (~10s) costs real time. `source` picks
+ * which of the two answers: NCBI for vertebrates and insects, PANTHER for
+ * everything else (yeast, worm, plants, and a fly gene's vertebrate relatives).
  *
- * The query row is the user's OWN selected transcript, not NCBI's
+ * The query row is the user's OWN selected transcript, not the source's
  * representative protein for the query species, because `connectedFeature`
  * maps genome coordinates through that row — swapping in a different isoform
  * would silently break the genome<->MSA linkage. The query species is therefore

package/dist/MsaViewPanel/doLaunchOrthologs.js

@@ -1,57 +1,55 @@
 import { cleanProteinSequence } from '../LaunchMsaView/util';
 import { launchMSA } from '../utils/msa';
 import { dedupeLabels, fetchOrthologRows, fetchProteinForGene, resolveGeneId, } from '../utils/ncbiOrthologs';
+import { fetchPantherOrthologs } from '../utils/pantherOrthologs';
 import { fetchTaxonomyInfo } from '../utils/taxonomyNames';
 /**
  * The no-search-job alternative to doLaunchBlast.
  *
  * BLAST spends 10+ minutes answering "what looks like this sequence" and
- * returns a redundant, accession-labelled hit list. This asks NCBI the question
- * the alignment actually wants — "what is this gene's ortholog in each species"
- * — which NCBI has already computed, so the whole NCBI half returns in about a
- * second and only the EBI alignment (~10s) costs real time.
+ * returns a redundant, accession-labelled hit list. This asks the question the
+ * alignment actually wants — "what is this gene's ortholog in each species" —
+ * which NCBI and PANTHER have already computed, so the lookup returns in
+ * seconds and only the EBI alignment (~10s) costs real time. `source` picks
+ * which of the two answers: NCBI for vertebrates and insects, PANTHER for
+ * everything else (yeast, worm, plants, and a fly gene's vertebrate relatives).
  *
- * The query row is the user's OWN selected transcript, not NCBI's
+ * The query row is the user's OWN selected transcript, not the source's
  * representative protein for the query species, because `connectedFeature`
  * maps genome coordinates through that row — swapping in a different isoform
  * 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, } = self.orthologParams;
+    const { taxId, taxa, maxSpecies, geneCandidates, msaAlgorithm, proteinSequence, source = 'ncbi', } = self.orthologParams;
     const onProgress = (arg) => {
         self.setProgress(arg);
     };
-    onProgress('Resolving gene at NCBI...');
-    const resolved = await resolveGeneId(geneCandidates, taxId);
-    if (!resolved) {
-        throw new Error(`Could not resolve any of ${geneCandidates.join(', ')} to an NCBI gene in taxon ${taxId}. Try the NCBI BLAST tab, which needs no gene identifier.`);
-    }
+    const request = {
+        taxId,
+        geneCandidates,
+        taxa: taxa ? new Set(taxa) : undefined,
+        // the query species is represented by the query row below
+        exclude: taxId,
+        limit: maxSpecies,
+        onProgress,
+    };
+    const { geneId, representative, rows } = source === 'panther'
+        ? await findPantherOrthologs(request)
+        : 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
-    // (a session spec naming only a gene) falls back to NCBI's representative
-    // protein for the resolved gene, which is the same choice made for every
-    // other row, so the alignment is the one NCBI would build for that gene.
-    const representative = await fetchRepresentativeQueryProtein(resolved.geneId);
+    // (a session spec naming only a gene) falls back to the source's
+    // representative protein for the resolved gene, which is the same choice
+    // made for every other row, so the alignment is the one the source would
+    // build for that gene.
     const cleanedSeq = proteinSequence
         ? cleanProteinSequence(proteinSequence)
         : representative?.sequence;
     if (!cleanedSeq) {
-        throw new Error(`No query protein: none was supplied and NCBI returned no representative protein for gene ${resolved.geneId}.`);
+        throw new Error(`No query protein: none was supplied and ${source === 'panther' ? 'PANTHER' : 'NCBI'} returned no representative protein for gene ${geneId}.`);
     }
-    // Every species NCBI has an ortholog for, when a launch names none, capped at
-    // maxSpecies. A launch that wants specific species lists them; one that just
-    // wants "this gene across species" gets NCBI's own order, which leads with the
-    // reference organisms.
-    const rows = await fetchOrthologRows({
-        geneId: resolved.geneId,
-        taxa: taxa ? new Set(taxa) : undefined,
-        // the query species is represented by the query row above
-        exclude: taxId,
-        limit: maxSpecies,
-        onProgress,
-    });
     // 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
     // ninety-nine named species reads as a row whose species failed to resolve,
@@ -66,7 +64,7 @@ export async function doLaunchOrthologs({ self, }) {
     const queryLabel = await queryRowLabel(taxId, rows);
     self.setQuerySeqName(queryLabel);
     const treeMetadata = {
-        [queryLabel]: buildQueryMetadata(self, resolved.geneId, cleanedSeq, representative),
+        [queryLabel]: buildQueryMetadata(self, geneId, cleanedSeq, representative),
     };
     for (const row of rows) {
         treeMetadata[row.label] = buildRowMetadata(row);
@@ -84,6 +82,42 @@ export async function doLaunchOrthologs({ self, }) {
         treeMetadata: JSON.stringify(treeMetadata),
     };
 }
+/**
+ * Every species NCBI has an ortholog for, when a launch names none, capped at
+ * `limit`. A launch that wants specific species lists them; one that just
+ * wants "this gene across species" gets NCBI's own order, which leads with the
+ * reference organisms.
+ */
+async function findNcbiOrthologs({ taxId, geneCandidates, onProgress, ...rest }) {
+    onProgress('Resolving gene at NCBI...');
+    const resolved = await resolveGeneId(geneCandidates, taxId);
+    if (!resolved) {
+        throw new Error(`Could not resolve any of ${geneCandidates.join(', ')} to an NCBI gene in taxon ${taxId}. Try the NCBI BLAST tab, which needs no gene identifier.`);
+    }
+    const representative = await fetchRepresentativeQueryProtein(resolved.geneId);
+    const rows = await fetchOrthologRows({
+        geneId: resolved.geneId,
+        onProgress,
+        ...rest,
+    });
+    return { geneId: resolved.geneId, representative, 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
+ * lookup here.
+ */
+async function findPantherOrthologs({ geneCandidates, ...rest }) {
+    const found = await fetchPantherOrthologs({
+        candidates: geneCandidates,
+        ...rest,
+    });
+    return {
+        geneId: found.query?.geneRef ?? found.matched,
+        representative: found.query,
+        rows: found.rows,
+    };
+}
 /**
  * `<species>_query`, unique against the ortholog labels. Falls back to the bare
  * marker when NCBI cannot name the taxon, which is a naming failure and must not
@@ -120,7 +154,7 @@ async function fetchRepresentativeQueryProtein(geneId) {
 /**
  * The query row carries an Accession — which is what drives the automatic CDD
  * overlay (afterCreateAutoruns.autoLoadProteinDomains -> loadProteinDomains) —
- * ONLY when its sequence is byte-identical to the RefSeq protein that accession
+ * ONLY when its sequence is byte-identical to the protein that accession
  * names. Attaching it unconditionally would put every domain box at an offset
  * whenever the user picked a non-representative isoform, which is a silently
  * wrong figure rather than a missing one. A launch that took the representative

package/dist/MsaViewPanel/doLaunchOrthologs.test.js

@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, test, vi } from 'vitest';
 import { doLaunchOrthologs } from './doLaunchOrthologs';
 import { launchMSA } from '../utils/msa';
 import { defaultMaxSpecies, fetchOrthologRows, fetchProteinForGene, resolveGeneId, } from '../utils/ncbiOrthologs';
+import { fetchPantherOrthologs } from '../utils/pantherOrthologs';
 import { fetchTaxonomyInfo } from '../utils/taxonomyNames';
 // Every network call is mocked and nothing else is. What is under test is the
 // argument shaping either side of those calls -- which species get asked for,
@@ -14,11 +15,15 @@ vi.mock('../utils/ncbiOrthologs', async (importOriginal) => ({
     fetchProteinForGene: vi.fn(),
     fetchOrthologRows: vi.fn(),
 }));
+vi.mock('../utils/pantherOrthologs', () => ({
+    fetchPantherOrthologs: vi.fn(),
+}));
 vi.mock('../utils/msa', () => ({ launchMSA: vi.fn() }));
 vi.mock('../utils/taxonomyNames', () => ({ fetchTaxonomyInfo: vi.fn() }));
 const mockResolveGeneId = vi.mocked(resolveGeneId);
 const mockFetchProtein = vi.mocked(fetchProteinForGene);
 const mockFetchRows = vi.mocked(fetchOrthologRows);
+const mockFetchPanther = vi.mocked(fetchPantherOrthologs);
 const mockLaunchMSA = vi.mocked(launchMSA);
 const mockFetchTaxonomy = vi.mocked(fetchTaxonomyInfo);
 const HUMAN = 9606;
@@ -199,3 +204,103 @@ describe('the Accession that drives the domain overlay', () => {
         expect(queryMetadata(result).Accession).toBeUndefined();
     });
 });
+// The second source. What is under test is the dispatch and what the PANTHER
+// result becomes on the query row -- the rows themselves are shaped upstream,
+// and the tail of the launch (labels, aligner, metadata) is the same code the
+// NCBI tests above already cover.
+describe('the PANTHER source', () => {
+    const YEAST = 559292;
+    const found = {
+        matched: 'CDC28',
+        query: {
+            code: 'YEAST',
+            accession: 'P00546',
+            geneRef: 'SGD=S000000364',
+            sequence: 'MSGELANYKRLEKVGEGTYGVVYKA',
+        },
+        rows: [
+            {
+                taxId: HUMAN,
+                label: 'human',
+                scientificName: 'Homo sapiens',
+                commonName: 'human',
+                geneId: 'HGNC=1771',
+                protein: 'P24941',
+                sequence: 'MENFQKVEKIGEGTYGVVYKARNK',
+            },
+        ],
+    };
+    beforeEach(() => {
+        mockFetchPanther.mockResolvedValue(found);
+        mockFetchTaxonomy.mockResolvedValue(new Map([[YEAST, { sciname: 'Saccharomyces cerevisiae' }]]));
+    });
+    test('source omitted is NCBI, so an old launch never reaches PANTHER', async () => {
+        await doLaunchOrthologs({ self: makeModel(params()) });
+        expect(mockFetchPanther).not.toHaveBeenCalled();
+        expect(mockResolveGeneId).toHaveBeenCalled();
+    });
+    test('source panther asks PANTHER with the same species semantics, and skips NCBI', async () => {
+        await doLaunchOrthologs({
+            self: makeModel({
+                taxId: YEAST,
+                source: 'panther',
+                geneCandidates: ['CDC28'],
+                msaAlgorithm: 'clustalo',
+                taxa: [HUMAN, YEAST],
+                maxSpecies: 7,
+            }),
+        });
+        expect(mockResolveGeneId).not.toHaveBeenCalled();
+        expect(mockFetchRows).not.toHaveBeenCalled();
+        const { candidates, taxId, taxa, exclude, limit } = mockFetchPanther.mock.calls[0][0];
+        expect(candidates).toEqual(['CDC28']);
+        expect(taxId).toBe(YEAST);
+        expect([...taxa]).toEqual([HUMAN, YEAST]);
+        expect(exclude).toBe(YEAST);
+        expect(limit).toBe(7);
+    });
+    test("the query row is PANTHER's own entry for the gene when no sequence was supplied, and carries its UniProt accession for the domain overlay", async () => {
+        const result = await doLaunchOrthologs({
+            self: makeModel({
+                taxId: YEAST,
+                source: 'panther',
+                geneCandidates: ['CDC28'],
+                msaAlgorithm: 'clustalo',
+            }),
+        });
+        expect(queryRowName()).toBe('Saccharomyces_cerevisiae_query');
+        expect(queryRowSent()).toBe(found.query.sequence);
+        expect(queryMetadata(result)).toEqual({
+            'Gene ID': 'SGD=S000000364',
+            Accession: 'P00546',
+        });
+        expect(JSON.parse(result.treeMetadata).human).toMatchObject({
+            Accession: 'P24941',
+            'Gene ID': 'HGNC=1771',
+        });
+    });
+    test('a supplied sequence still wins, and a different isoform earns no Accession', async () => {
+        const result = await doLaunchOrthologs({
+            self: makeModel({
+                taxId: YEAST,
+                source: 'panther',
+                geneCandidates: ['CDC28'],
+                msaAlgorithm: 'clustalo',
+                proteinSequence: 'MDIFFERENTISOFORM',
+            }),
+        });
+        expect(queryRowSent()).toBe('MDIFFERENTISOFORM');
+        expect(queryMetadata(result).Accession).toBeUndefined();
+    });
+    test('names PANTHER when it has no protein for the query row', async () => {
+        mockFetchPanther.mockResolvedValue({ ...found, query: undefined });
+        await expect(doLaunchOrthologs({
+            self: makeModel({
+                taxId: YEAST,
+                source: 'panther',
+                geneCandidates: ['CDC28'],
+                msaAlgorithm: 'clustalo',
+            }),
+        })).rejects.toThrow(/PANTHER returned no representative protein/);
+    });
+});

package/dist/MsaViewPanel/model.d.ts

@@ -17,9 +17,18 @@ export interface BlastParams {
     selectedTranscript?: Feature;
     proteinSequence: string;
 }
+/**
+ * Where the ortholog set comes from. NCBI's sets cover vertebrates and
+ * insects; PANTHER's span its 144 reference proteomes, human to yeast to
+ * Arabidopsis, so a gene from outside NCBI's scope aligns only through it.
+ */
+export declare const orthologSources: readonly ["ncbi", "panther"];
+export type OrthologSource = (typeof orthologSources)[number];
 export interface OrthologParams {
     /** NCBI taxon id of the assembly the query gene came from */
     taxId: number;
+    /** `ncbi` when omitted, so every launch written before this key keeps its meaning */
+    source?: OrthologSource;
     /**
      * taxon ids to include as rows. The query taxon has its own row already, so
      * it is excluded from this set whether or not it is named.

package/dist/MsaViewPanel/model.js

@@ -6,6 +6,12 @@ import { autorun } from 'mobx';
 import { MSAModelF } from 'react-msaview';
 import { autoLoadProteinDomains, launchBlastIfNeeded, launchOrthologsIfNeeded, loadStoredData, observeProteinHighlights, processInit, runCleanup, storeDataToIndexedDB, syncGenomeHoverToMsaColumn, } from './afterCreateAutoruns';
 import { msaCoordToGenomeCoord, msaCoordToGenomeRegions, } from './msaCoordToGenomeCoord';
+/**
+ * Where the ortholog set comes from. NCBI's sets cover vertebrates and
+ * insects; PANTHER's span its 144 reference proteomes, human to yeast to
+ * Arabidopsis, so a gene from outside NCBI's scope aligns only through it.
+ */
+export const orthologSources = ['ncbi', 'panther'];
 /**
  * #stateModel MsaViewPlugin
  * extends