jbrowse-plugin-msaview 3.4.1 → 3.5.0

package/README.md

@@ -29,6 +29,13 @@ https://jbrowse.org/code/jb2/main/index.html?config=https://unpkg.com/jbrowse-pl
 - Can share sessions with other users which will send relevant settings and
   links to files to automatically open your results
 - The tree or the MSA panel can be loaded separately from each other
+- Builds a cross-species alignment for any gene from the genome view's
+  right-click menu: precomputed orthologs (NCBI, PANTHER), the gene's UniRef
+  cluster across all of UniProtKB, or a phmmer/blastp search at EBI
+- Aligns and builds trees in the browser, so a UniRef launch needs no job at any
+  external service; EBI's aligners remain an option
+- Every launch is also a session-spec URL (`orthologParams`, `searchParams`,
+  `connectedTranscript`), see [DEVELOPERS.md](DEVELOPERS.md)
 
 ## File format supports
 

package/dist/LaunchMsaView/components/BlastQuery/BlastAutomaticPanel.js

@@ -12,7 +12,7 @@ import { useTranscriptSelection } from '../useTranscriptSelection';
 import CachedBlastResults from './CachedBlastResults';
 import MsaAlgorithmSelect from './MsaAlgorithmSelect';
 import { blastLaunchView } from './blastLaunchView';
-import { databaseOptionsFor, defaultSearchFor, searchPrograms } from './consts';
+import { databaseOptionsFor, defaultMaxHits, defaultSearchFor, searchPrograms, } from './consts';
 import { useStoredMsaAlgorithm, useStoredSearchChoice, } from './searchChoiceStorage';
 import { useCachedBlastResults } from './useCachedBlastResults';
 const useStyles = makeStyles()({
@@ -41,6 +41,9 @@ const BlastAutomaticPanel = observer(function ({ handleClose, feature, model, ch
     // would let them drift into that
     const [search, setSearch] = useStoredSearchChoice();
     const [selectedMsaAlgorithm, setSelectedMsaAlgorithm] = useStoredMsaAlgorithm();
+    const [maxHits, setMaxHits] = useState(String(defaultMaxHits));
+    const hitCount = Number(maxHits);
+    const hitCountValid = Number.isInteger(hitCount) && hitCount >= 1;
     const isPhmmer = search.program === 'phmmer';
     const geneIds = useMemo(() => getGeneIdentifiers(feature), [feature]);
     const { results: cachedResults, error: cachedResultsError } = useCachedBlastResults(geneIds);
@@ -63,28 +66,31 @@ const BlastAutomaticPanel = observer(function ({ handleClose, feature, model, ch
                     });
                 } }, databaseOptionsFor(search.program).map(val => (React.createElement(MenuItem, { value: val, key: val }, val)))),
             isPhmmer ? null : (React.createElement(MsaAlgorithmSelect, { className: classes.selectField, value: selectedMsaAlgorithm, onChange: setSelectedMsaAlgorithm })),
+            React.createElement(TextField2, { variant: "outlined", label: "Hits", className: classes.selectField, type: "number", value: maxHits, onChange: event => {
+                    setMaxHits(event.target.value);
+                }, error: !hitCountValid, helperText: "best-scoring sequences to keep" }),
             React.createElement(TranscriptSelector, { feature: feature, ...transcriptSelection }),
             React.createElement(Typography, { className: classes.infoText },
                 isPhmmer
                     ? `phmmer searches UniProtKB with a profile HMM built from the query,
                so it aligns the hits as it finds them and that alignment is used
                directly — nothing is realigned afterwards. The tree is then built
-               from it by neighbour-joining. A hit matching the query in more
-               than one place appears once per matched region.`
+               from it in the browser. A hit matching the query in more than one
+               place appears once per matched region. rp15 spreads the hits
+               across all of life; swissprot keeps to the curated set.`
                     : `This panel will automatically submit a blastp query to EBI, which
-               searches UniProtKB. Searches usually finish in under a minute, and
-               swissprot returns curated sequences that align more cleanly than
-               the many near-identical entries a TrEMBL search brings back. After
-               completion, all the hits will be run through a multiple sequence
-               alignment.`,
+               searches UniProtKB. swissprot returns curated sequences that align
+               more cleanly than the many near-identical entries a TrEMBL search
+               brings back. After completion, all the hits will be run through
+               the chosen aligner; "in browser" needs no second EBI job.`,
                 ' ',
-                "Searching NCBI's nr needs the manual approach: NCBI no longer lets a browser read responses from Blast.cgi."),
+                "EBI's queue is the wait, and it varies from seconds to many minutes. For a homolog panel with no job at all, the Orthologs tab's UniRef source is a lookup. Searching NCBI's nr needs the manual approach: NCBI no longer lets a browser read responses from Blast.cgi."),
             cachedResults.length > 0 ? (React.createElement(Accordion, { className: classes.cachedResultsAccordion },
                 React.createElement(AccordionSummary, { expandIcon: React.createElement(ExpandMoreIcon, null) },
                     React.createElement(Typography, null, "Previous BLAST Results")),
                 React.createElement(AccordionDetails, null,
                     React.createElement(CachedBlastResults, { model: model, handleClose: handleClose, feature: feature })))) : null),
-        React.createElement(SubmitCancelActions, { model: model, submitDisabled: !proteinSequence, onSubmit: () => {
+        React.createElement(SubmitCancelActions, { model: model, submitDisabled: !proteinSequence || !hitCountValid, onSubmit: () => {
                 try {
                     if (selectedTranscript) {
                         setLaunchViewError(undefined);
@@ -96,14 +102,16 @@ const BlastAutomaticPanel = observer(function ({ handleClose, feature, model, ch
                                 ? {
                                     searchProgram: 'phmmer',
                                     blastDatabase: search.database,
-                                    selectedTranscript,
+                                    maxHits: hitCount,
+                                    selectedTranscript: selectedTranscript.toJSON(),
                                     proteinSequence,
                                 }
                                 : {
                                     searchProgram: 'blastp',
                                     blastDatabase: search.database,
                                     msaAlgorithm: selectedMsaAlgorithm,
-                                    selectedTranscript,
+                                    maxHits: hitCount,
+                                    selectedTranscript: selectedTranscript.toJSON(),
                                     proteinSequence,
                                 },
                         });

package/dist/LaunchMsaView/components/BlastQuery/BlastManualPanel.js

@@ -88,6 +88,7 @@ const BlastManualPanel = observer(function ({ handleClose, feature, model, child
                             view,
                             feature: selectedTranscript,
                             querySeqName: queryRow.querySeqName,
+                            querySeqOffset: queryRow.querySeqOffset,
                             data: { msa: msaText, tree: treeText },
                         });
                         handleClose();

package/dist/LaunchMsaView/components/BlastQuery/MsaAlgorithmSelect.js

@@ -1,9 +1,11 @@
 import React from 'react';
 import { MenuItem } from '@mui/material';
 import TextField2 from '../../../components/TextField2';
-import { msaAlgorithms } from './consts';
+import { msaAlgorithmLabels, msaAlgorithms } from './consts';
 export default function MsaAlgorithmSelect({ value, onChange, className, }) {
-    return (React.createElement(TextField2, { variant: "outlined", label: "MSA Algorithm", className: className, select: true, value: value, onChange: event => {
+    return (React.createElement(TextField2, { variant: "outlined", label: "MSA Algorithm", className: className, select: true, value: value, helperText: value === 'browser'
+            ? 'no EBI job; rows aligned to the query'
+            : undefined, onChange: event => {
             onChange(event.target.value);
-        } }, msaAlgorithms.map(val => (React.createElement(MenuItem, { value: val, key: val }, val)))));
+        } }, msaAlgorithms.map(val => (React.createElement(MenuItem, { value: val, key: val }, msaAlgorithmLabels[val])))));
 }

package/dist/LaunchMsaView/components/BlastQuery/consts.d.ts

@@ -5,8 +5,20 @@
  * cannot read a response from it at all. See docs/blast.md.
  */
 export declare const BASE_BLAST_URL = "https://blast.ncbi.nlm.nih.gov/Blast.cgi";
-export declare const msaAlgorithms: readonly ["clustalo", "muscle", "kalign", "mafft"];
+/** The aligners EBI's Job Dispatcher runs, each a tool name at their REST api. */
+export declare const ebiMsaAlgorithms: readonly ["clustalo", "muscle", "kalign", "mafft"];
+export type EbiMsaAlgorithm = (typeof ebiMsaAlgorithms)[number];
+/**
+ * `browser` is no job at all: each sequence is aligned to the query in the
+ * page and the rows merged on the query (utils/browserAlign.ts), with the tree
+ * built by react-msaview's neighbour joining. It is the aligner for a launch
+ * that must not depend on EBI, and for one that wants to be quick -- a
+ * hundred rows take a second or two against a Job Dispatcher queue that has
+ * been measured at anything from ten seconds to fifteen minutes.
+ */
+export declare const msaAlgorithms: readonly ["clustalo", "muscle", "kalign", "mafft", "browser"];
 export type MsaAlgorithm = (typeof msaAlgorithms)[number];
+export declare const msaAlgorithmLabels: Record<MsaAlgorithm, string>;
 /**
  * EBI rejects a submission naming a database outside its own list with a 400,
  * so every value here has to appear in
@@ -21,13 +33,21 @@ export declare const searchPrograms: readonly ["blastp", "phmmer"];
 export type SearchProgram = (typeof searchPrograms)[number];
 /**
  * phmmer offers PDB, AlphaFold, Ensembl Genomes, MEROPS and ChEMBL too, but
- * targets outside UniProt carry no OS=/OX= in their description, so those rows
+ * targets outside UniProt carry no species in their description, so those rows
  * would lose their species and common name. Only the databases that label their
  * hits are offered.
+ *
+ * rp15..rp75 are the Representative Proteomes: UniProt's reference proteomes
+ * thinned so that no two are more than 15% (35%, 55%, 75%) similar, which is
+ * the widest taxonomic spread per hit that any of these databases gives. rp15
+ * is the one to reach for when the question is "what is this like across all
+ * of life"; swissprot when it is "what is this like in the curated set".
  */
-export declare const phmmerDatabaseOptions: readonly ["swissprot", "uniprotkb", "uniprotrefprot"];
+export declare const phmmerDatabaseOptions: readonly ["swissprot", "uniprotkb", "uniprotrefprot", "rp75", "rp55", "rp35", "rp15"];
 export type PhmmerDatabase = (typeof phmmerDatabaseOptions)[number];
 export declare const defaultPhmmerDatabase: PhmmerDatabase;
+export declare const defaultMaxHits = 100;
+export declare function snapBlastHitCount(maxHits: number): number;
 /**
  * A program together with a database that program actually has.
  *
@@ -44,4 +64,4 @@ export type SearchChoice = {
     database: PhmmerDatabase;
 };
 export declare function defaultSearchFor(program: SearchProgram): SearchChoice;
-export declare function databaseOptionsFor(program: SearchProgram): readonly ["uniprotkb_swissprot", "uniprotkb", "pan_proteomes", "uniprotkb_trembl"] | readonly ["swissprot", "uniprotkb", "uniprotrefprot"];
+export declare function databaseOptionsFor(program: SearchProgram): readonly ["uniprotkb_swissprot", "uniprotkb", "pan_proteomes", "uniprotkb_trembl"] | readonly ["swissprot", "uniprotkb", "uniprotrefprot", "rp75", "rp55", "rp35", "rp15"];

package/dist/LaunchMsaView/components/BlastQuery/consts.js

@@ -5,7 +5,29 @@
  * cannot read a response from it at all. See docs/blast.md.
  */
 export const BASE_BLAST_URL = 'https://blast.ncbi.nlm.nih.gov/Blast.cgi';
-export const msaAlgorithms = ['clustalo', 'muscle', 'kalign', 'mafft'];
+/** The aligners EBI's Job Dispatcher runs, each a tool name at their REST api. */
+export const ebiMsaAlgorithms = [
+    'clustalo',
+    'muscle',
+    'kalign',
+    'mafft',
+];
+/**
+ * `browser` is no job at all: each sequence is aligned to the query in the
+ * page and the rows merged on the query (utils/browserAlign.ts), with the tree
+ * built by react-msaview's neighbour joining. It is the aligner for a launch
+ * that must not depend on EBI, and for one that wants to be quick -- a
+ * hundred rows take a second or two against a Job Dispatcher queue that has
+ * been measured at anything from ten seconds to fifteen minutes.
+ */
+export const msaAlgorithms = [...ebiMsaAlgorithms, 'browser'];
+export const msaAlgorithmLabels = {
+    clustalo: 'clustalo (EBI)',
+    muscle: 'muscle (EBI)',
+    kalign: 'kalign (EBI)',
+    mafft: 'mafft (EBI)',
+    browser: 'in browser, query-anchored',
+};
 /**
  * EBI rejects a submission naming a database outside its own list with a 400,
  * so every value here has to appear in
@@ -25,16 +47,36 @@ export const defaultBlastDatabase = 'uniprotkb_swissprot';
 export const searchPrograms = ['blastp', 'phmmer'];
 /**
  * phmmer offers PDB, AlphaFold, Ensembl Genomes, MEROPS and ChEMBL too, but
- * targets outside UniProt carry no OS=/OX= in their description, so those rows
+ * targets outside UniProt carry no species in their description, so those rows
  * would lose their species and common name. Only the databases that label their
  * hits are offered.
+ *
+ * rp15..rp75 are the Representative Proteomes: UniProt's reference proteomes
+ * thinned so that no two are more than 15% (35%, 55%, 75%) similar, which is
+ * the widest taxonomic spread per hit that any of these databases gives. rp15
+ * is the one to reach for when the question is "what is this like across all
+ * of life"; swissprot when it is "what is this like in the curated set".
  */
 export const phmmerDatabaseOptions = [
     'swissprot',
     'uniprotkb',
     'uniprotrefprot',
+    'rp75',
+    'rp55',
+    'rp35',
+    'rp15',
 ];
 export const defaultPhmmerDatabase = 'swissprot';
+/**
+ * The hit counts EBI's ncbiblast accepts for `alignments` and `scores`. A value
+ * off this list is a 400 at submit time, so a request is rounded up to the next
+ * one on it.
+ */
+const blastHitCounts = [5, 10, 20, 50, 100, 150, 200, 250, 500, 750, 1000];
+export const defaultMaxHits = 100;
+export function snapBlastHitCount(maxHits) {
+    return blastHitCounts.find(n => n >= maxHits) ?? blastHitCounts.at(-1);
+}
 export function defaultSearchFor(program) {
     return program === 'phmmer'
         ? { program, database: defaultPhmmerDatabase }

package/dist/LaunchMsaView/components/BlastQuery/searchChoiceStorage.d.ts

@@ -4,4 +4,4 @@ export declare const MSA_ALGORITHM_STORAGE_KEY = "msaView-msaAlgorithm";
 export declare function validSearchChoice(stored: unknown): SearchChoice;
 export declare function validMsaAlgorithm(stored: unknown): MsaAlgorithm;
 export declare function useStoredSearchChoice(): readonly [SearchChoice, (choice: SearchChoice) => void];
-export declare function useStoredMsaAlgorithm(): readonly ["clustalo" | "muscle" | "kalign" | "mafft", (algorithm: MsaAlgorithm) => void];
+export declare function useStoredMsaAlgorithm(): readonly ["clustalo" | "muscle" | "kalign" | "mafft" | "browser", (algorithm: MsaAlgorithm) => void];

package/dist/LaunchMsaView/components/ManualMSALoader/ManualMSALoader.js

@@ -69,6 +69,7 @@ const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handle
                             view,
                             feature: selectedTranscript,
                             querySeqName: queryRow.querySeqName,
+                            querySeqOffset: queryRow.querySeqOffset,
                             ...(inputMethod === 'file'
                                 ? {
                                     msaFilehandle: msaFileLocation,

package/dist/LaunchMsaView/components/ManualMSALoader/launchView.d.ts

@@ -1,12 +1,14 @@
 import type { Feature, FileLocation } from '@jbrowse/core/util';
 import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view';
-export declare function launchView({ newViewTitle, view, feature, msaFilehandle, treeFilehandle, querySeqName, data, }: {
+export declare function launchView({ newViewTitle, view, feature, msaFilehandle, treeFilehandle, querySeqName, querySeqOffset, data, }: {
     newViewTitle: string;
     view: LinearGenomeViewModel;
     feature: Feature;
     msaFilehandle?: FileLocation;
     treeFilehandle?: FileLocation;
     querySeqName?: string;
+    /** transcript residues before the query row's first residue */
+    querySeqOffset?: number;
     data?: {
         msa: string;
         tree?: string;

package/dist/LaunchMsaView/components/ManualMSALoader/launchView.js

@@ -1,7 +1,7 @@
 import { getSession } from '@jbrowse/core/util';
 import { launchMsaView } from '../../../utils/launchMsaView';
 import { readLaunchPlacement } from '../../../utils/workspaces';
-export function launchView({ newViewTitle, view, feature, msaFilehandle, treeFilehandle, querySeqName, data, }) {
+export function launchView({ newViewTitle, view, feature, msaFilehandle, treeFilehandle, querySeqName, querySeqOffset, data, }) {
     launchMsaView(getSession(view), {
         placement: readLaunchPlacement(),
         displayName: newViewTitle,
@@ -10,6 +10,7 @@ export function launchView({ newViewTitle, view, feature, msaFilehandle, treeFil
         msaFilehandle,
         treeFilehandle,
         querySeqName,
+        querySeqOffset,
         data,
     });
 }

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

@@ -20,6 +20,11 @@ const useStyles = makeStyles()({
         width: 180,
     },
 });
+const rowsHint = {
+    ncbi: 'the closest N species NCBI has',
+    panther: 'the closest N species PANTHER has',
+    uniref: 'one per species, reviewed entries first',
+};
 const OrthologPanel = observer(function ({ handleClose, feature, model, }) {
     const { classes } = useStyles();
     const view = getLinearGenomeView(model);
@@ -36,14 +41,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" }, "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, and with the in-browser aligner no job at all."),
             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 ${source === 'panther' ? 'PANTHER' : 'NCBI'} has` })),
+                    }, error: !rowCountValid, helperText: rowsHint[source] })),
             React.createElement(TranscriptSelector, { feature: feature, ...transcriptSelection })),
         React.createElement(SubmitCancelActions, { model: model, submitDisabled: !proteinSequence || !rowCountValid, onSubmit: () => {
                 try {
@@ -59,7 +64,7 @@ const OrthologPanel = observer(function ({ handleClose, feature, model, }) {
                                 maxSpecies: rowCount,
                                 geneCandidates,
                                 msaAlgorithm,
-                                selectedTranscript,
+                                selectedTranscript: selectedTranscript.toJSON(),
                                 proteinSequence,
                             },
                         });

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

@@ -5,13 +5,16 @@ export const ORTHOLOG_SOURCE_STORAGE_KEY = 'msaview-ortholog-source';
 export const orthologSourceLabels = {
     ncbi: 'NCBI orthologs',
     panther: 'PANTHER',
+    uniref: 'UniRef cluster',
 };
 // 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.
+// from human to yeast and Arabidopsis, and a UniRef cluster is every UniProtKB
+// entry within 50% identity of the query, whatever it came from.
 const hints = {
     ncbi: 'vertebrates and insects',
     panther: 'also yeast, worm, fly and plants',
+    uniref: 'all of UniProtKB within 50% identity',
 };
 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 => {

package/dist/LaunchMsaView/components/QueryRowSelector.js

@@ -10,6 +10,19 @@ const useStyles = makeStyles()({
         marginTop: 10,
     },
 });
+/**
+ * Where a trimmed row sits in the protein. The offset is what the view maps
+ * through, so the alert says it rather than leaving the user to wonder why the
+ * row is shorter than their transcript.
+ */
+function partialCoverage({ identity, offset, }) {
+    const covering = `, covering ${Math.round(identity * 100)}% of it`;
+    return offset > 0
+        ? `${covering} from residue ${offset + 1}`
+        : offset < 0
+            ? `${covering} and running ${-offset} residues past its start`
+            : covering;
+}
 /**
  * Which MSA row corresponds to the selected transcript. Clicking and hovering in
  * the alignment reach the genome only through this name, and a wrong one fails
@@ -27,12 +40,15 @@ export default function QueryRowSelector({ names, detected, querySeqName, setQue
             detected?.name === name ? ' — matches your protein' : ''))))) : (React.createElement(TextField2, { variant: "outlined", label: "MSA row matching the selected transcript", fullWidth: true, className: classes.field, helperText: "Paste an alignment above and this fills in on its own", value: querySeqName, onChange: event => {
                 setQuerySeqName(event.target.value);
             } })),
-        isAutoDetected && detected ? (React.createElement(Alert, { severity: "success", className: classes.alert },
+        isAutoDetected && detected ? (detected.quality === 'similar' ? (React.createElement(Alert, { severity: "warning", className: classes.alert },
+            React.createElement("strong", null, detected.name),
+            " is",
+            ' ',
+            Math.round(detected.identity * 100),
+            "% identical to your protein but is not the same sequence. Clicking the alignment navigates the genome view, approximately: wherever the two differ by an insertion or a deletion, every residue after it lands one codon off.")) : (React.createElement(Alert, { severity: "success", className: classes.alert },
             "Matched ",
             React.createElement("strong", null, detected.name),
             " to your protein sequence",
-            detected.quality === 'exact'
-                ? ''
-                : `, covering ${Math.round(detected.identity * 100)}% of it`,
-            ". Clicking the alignment will navigate the genome view.")) : names.length > 0 && !querySeqName ? (React.createElement(Alert, { severity: "warning", className: classes.alert }, "No row matched your protein sequence \u2014 pick the one for your gene above. Without it the alignment still renders, but clicking it will not navigate the genome view.")) : null));
+            detected.quality === 'exact' ? '' : partialCoverage(detected),
+            ". Clicking the alignment will navigate the genome view."))) : names.length > 0 && !querySeqName ? (React.createElement(Alert, { severity: "warning", className: classes.alert }, "No row matched your protein sequence \u2014 pick the one for your gene above. Without it the alignment still renders, but clicking it will not navigate the genome view.")) : null));
 }

package/dist/LaunchMsaView/detectQueryRow.d.ts

@@ -18,6 +18,17 @@ export interface QueryRowMatch {
     quality: MatchQuality;
     /** identity over the compared region, 0-1 */
     identity: number;
+    /**
+     * Transcript residues before the row's first residue, so transcript position
+     * = row position + offset. BLAST reports the aligned region, so a row is
+     * often the query with its termini trimmed, and mapping its first residue to
+     * the transcript's first residue would put every navigation off by the
+     * trimmed amount. Negative when the row is the longer of the two.
+     *
+     * Zero for a `similar` match, which is the one arm this cannot measure: the
+     * row is not the query, so where it starts is a guess.
+     */
+    offset: number;
 }
 export interface MsaQueryRow {
     /** every row name, in file order, for the picker to offer */

package/dist/LaunchMsaView/detectQueryRow.js

@@ -70,20 +70,27 @@ function bestMatch(parsed, names, query) {
         }
         if (row === query) {
             // nothing beats an exact match, and a second one would be a duplicate row
-            return { name, quality: 'exact', identity: 1 };
+            return { name, quality: 'exact', identity: 1, offset: 0 };
         }
         // BLAST reports the aligned region, so the row is often the query trimmed
         // at one or both ends rather than the whole protein
-        if (query.includes(row) || row.includes(query)) {
+        const contained = query.indexOf(row);
+        const containing = row.indexOf(query);
+        if (contained !== -1 || containing !== -1) {
             const coverage = Math.min(row.length, query.length) / Math.max(row.length, query.length);
             if (coverage >= PARTIAL_COVERAGE_FLOOR) {
-                candidates.push({ name, quality: 'partial', identity: coverage });
+                candidates.push({
+                    name,
+                    quality: 'partial',
+                    identity: coverage,
+                    offset: contained === -1 ? -containing : contained,
+                });
             }
             continue;
         }
         const identity = identityOverOverlap(row, query);
         if (identity >= SIMILARITY_FLOOR) {
-            candidates.push({ name, quality: 'similar', identity });
+            candidates.push({ name, quality: 'similar', identity, offset: 0 });
         }
     }
     // an exact match returns above, so only these two can be here

package/dist/LaunchMsaView/detectQueryRow.test.js

@@ -33,6 +33,36 @@ describe('findQueryRow', () => {
             quality: 'partial',
         });
     });
+    // the offset is what the view maps genome coordinates through: without it an
+    // N-terminally trimmed row puts every click five codons off, silently
+    test('says how far into the protein a trimmed row starts', () => {
+        const trimmed = `>aligned_query\n${protein.slice(5, 40)}\n>hit_one\nWRONGWRONGWRONGWRONG\n`;
+        expect(findQueryRow(trimmed, protein).match).toMatchObject({
+            name: 'aligned_query',
+            quality: 'partial',
+            offset: 5,
+        });
+    });
+    test('an exact match starts where the protein does', () => {
+        expect(findQueryRow(clustal, protein).match?.offset).toBe(0);
+    });
+    test('a row running past the protein gets a negative offset', () => {
+        const extended = `>longer_row\nMMM${protein}\n`;
+        expect(findQueryRow(extended, protein).match).toMatchObject({
+            name: 'longer_row',
+            quality: 'partial',
+            offset: -3,
+        });
+    });
+    // the one arm with nothing to measure: a 90%-identical row is not the query,
+    // so QueryRowSelector warns rather than claiming a match
+    test('a merely similar row claims no offset', () => {
+        const similar = protein.slice(0, 30) + 'W' + protein.slice(31);
+        expect(findQueryRow(`>near\n${similar}\n`, protein).match).toMatchObject({
+            quality: 'similar',
+            offset: 0,
+        });
+    });
     // the failure that matters: silently wiring the view to a homolog would look
     // like it worked, and every navigation afterwards would land in the wrong place
     test('returns nothing when only diverged homologs are present', () => {

package/dist/LaunchMsaView/useQueryRowName.d.ts

@@ -10,6 +10,7 @@ export declare function useQueryRowName(msaText: string, proteinSequence: string
     detected: import("./detectQueryRow").QueryRowMatch | undefined;
     names: string[];
     querySeqName: string;
+    querySeqOffset: number;
     setQuerySeqName: import("react").Dispatch<import("react").SetStateAction<string | undefined>>;
     isAutoDetected: boolean;
 };

package/dist/LaunchMsaView/useQueryRowName.js

@@ -13,10 +13,14 @@ export function useQueryRowName(msaText, proteinSequence) {
     // parsing runs on every keystroke in the paste box otherwise, and an
     // alignment of a few hundred rows is not free
     const { names, match } = useMemo(() => findQueryRow(msaText, proteinSequence), [msaText, proteinSequence]);
+    const querySeqName = override ?? match?.name ?? '';
     return {
         detected: match,
         names,
-        querySeqName: override ?? match?.name ?? '',
+        querySeqName,
+        // only the detected row's offset is known; a row the user picked instead is
+        // taken at face value, residue 1 to residue 1
+        querySeqOffset: querySeqName === match?.name ? match.offset : 0,
         setQuerySeqName: setOverride,
         isAutoDetected: override === undefined && !!match,
     };

package/dist/LaunchMsaView/useQueryRowName.test.js

@@ -0,0 +1,23 @@
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { useQueryRowName } from './useQueryRowName';
+const protein = 'MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD';
+const trimmed = `>aligned_query\n${protein.slice(5, 45)}\n>other\nWRONGWRONGWRONGWRONGWRONGWRONGWRONGWRONG\n`;
+describe('useQueryRowName', () => {
+    test('carries the detected row and where it starts', () => {
+        const { result } = renderHook(() => useQueryRowName(trimmed, protein));
+        expect(result.current.querySeqName).toBe('aligned_query');
+        expect(result.current.querySeqOffset).toBe(5);
+    });
+    // the offset was measured against the detected row; another row is a row the
+    // user vouched for, and nothing here knows where in the protein it sits
+    test('a row the user picks instead is taken at face value', () => {
+        const { result } = renderHook(() => useQueryRowName(trimmed, protein));
+        act(() => {
+            result.current.setQuerySeqName('other');
+        });
+        expect(result.current.querySeqName).toBe('other');
+        expect(result.current.querySeqOffset).toBe(0);
+    });
+});

package/dist/LaunchMsaViewExtensionPoint/index.js

@@ -1,15 +1,16 @@
 import { launchMsaView } from '../utils/launchMsaView';
 export default function LaunchMsaViewExtensionPointF(pluginManager) {
     pluginManager.addToExtensionPoint('LaunchView-MsaView', (args) => {
-        const { session, data, msaFileLocation, msaIndexedLocation, msaName, treeFileLocation, querySeqName, ...rest } = args;
-        // `orthologParams` is a fourth source, and unlike the other three it names
-        // no alignment at all — the view builds one from NCBI at launch, which is
-        // the dialog's Orthologs tab reached declaratively.
+        const { session, data, msaFileLocation, msaIndexedLocation, msaName, treeFileLocation, querySeqName, searchParams, ...rest } = args;
+        // `orthologParams` and `searchParams` name no alignment at all — the
+        // view builds one at launch, which is the dialog's Orthologs and BLAST
+        // tabs reached declaratively.
         if (!data &&
             !msaFileLocation &&
             !msaIndexedLocation &&
-            !rest.orthologParams) {
-            throw new Error('No MSA data, file location or orthologParams provided when launching MSA view');
+            !rest.orthologParams &&
+            !searchParams) {
+            throw new Error('No MSA data, file location, orthologParams or searchParams provided when launching MSA view');
         }
         // inline data and the tree URL are native react-msaview snapshot props, set
         // directly, and so is orthologParams (the model's own autorun picks it up).
@@ -27,6 +28,7 @@ export default function LaunchMsaViewExtensionPointF(pluginManager) {
         };
         launchMsaView(session, {
             ...rest,
+            ...(searchParams ? { blastParams: searchParams } : {}),
             data,
             ...(treeFileLocation
                 ? {

package/dist/LaunchMsaViewExtensionPoint/index.test.js

@@ -32,6 +32,27 @@ test('a file location travels through init', () => {
         querySeqName: undefined,
     });
 });
+test('searchParams is a source, stored under the name the dialog uses', () => {
+    const snapshot = launch({
+        searchParams: {
+            searchProgram: 'phmmer',
+            blastDatabase: 'rp15',
+            accession: 'P04637',
+        },
+        connectedViewId: 'lgv1',
+        connectedTranscript: 'NM_000546.6',
+    });
+    expect(snapshot.blastParams).toEqual({
+        searchProgram: 'phmmer',
+        blastDatabase: 'rp15',
+        accession: 'P04637',
+    });
+    expect('searchParams' in snapshot).toBe(false);
+    expect(snapshot.connectedTranscript).toBe('NM_000546.6');
+});
+test('a launch naming no source at all is refused', () => {
+    expect(() => launch({ connectedViewId: 'lgv1' })).toThrow(/searchParams/);
+});
 test('one field set is enough to need init', () => {
     const snapshot = launch({ data: { msa: '>a\nMEEP' }, querySeqName: 'QUERY' });
     expect(snapshot.init).toEqual({

package/dist/MsaViewPanel/afterCreateAutoruns.d.ts

@@ -12,8 +12,9 @@ export declare function loadStoredData(self: JBrowsePluginMsaViewModel): void;
  * it is recorded whether or not the write succeeded, so a browser refusing
  * IndexedDB (private mode) fails once rather than in a loop.
  *
- * A view whose data comes from a filehandle stores nothing at all: the file is
- * the source of truth and react-msaview refetches it at startup.
+ * A view whose data comes from a filehandle -- or from the indexed block its
+ * kept `init` names -- stores nothing at all: the file is the source of truth
+ * and it is refetched at startup.
  */
 export declare function storeDataToIndexedDB(self: JBrowsePluginMsaViewModel): void;
 /**