p2s_mapper 2.0.0 → 2.1.0

package/src/coordinates.ts

@@ -8,16 +8,15 @@ import { invertMap } from './invertMap.ts'
 import type { PairwiseAlignment } from './mappings.ts'
 
 /**
- * Branded coordinate spaces. Every position in this plugin is a bare `number`,
- * but the *meaning* differs: a structure residue index is not interchangeable
- * with a transcript residue index or an alignment column, and mixing them is
- * the root cause of the off-by-one class of bugs. Branding makes the compiler
- * reject cross-space mixing; construct values with the helpers below at the
- * boundaries where raw numbers enter (molstar picks, hover events, features).
+ * Branded coordinate spaces. Every position is a plain `number` at runtime, but
+ * a structure residue index, a transcript residue index and an alignment column
+ * mean different things, and mixing them causes off-by-one bugs. The brands
+ * make the compiler reject mixing; wrap a raw number with the helpers below
+ * where it enters, such as a molstar pick, a hover event or a feature.
  *
- * Conventions: all are 0-based. StructurePos indexes the ungapped structure
- * sequence; TranscriptPos the ungapped transcript sequence; AlignmentCol a
- * column of the pairwise alignment (gaps included).
+ * All are 0-based. StructurePos indexes the ungapped structure sequence,
+ * TranscriptPos the ungapped transcript sequence, and AlignmentCol a column of
+ * the pairwise alignment, gaps included.
  */
 export type StructurePos = number & { readonly __brand: 'StructurePos' }
 export type TranscriptPos = number & { readonly __brand: 'TranscriptPos' }
@@ -44,10 +43,9 @@ export interface CoordinateMapper {
   transcriptToAlignment: (p: TranscriptPos) => AlignmentCol | undefined
   alignmentToTranscript: (c: AlignmentCol) => TranscriptPos | undefined
   /**
-   * Raw lookup tables, for consumers that iterate the whole map rather than
-   * convert a single position (e.g. per-residue track rendering, selection of
-   * all aligned residues). Plain numbers — prefer the typed methods above for
-   * point conversions.
+   * The lookup tables as plain numbers, for code that iterates a whole map,
+   * such as drawing a per-residue track or selecting every aligned residue.
+   * Use the typed methods above to convert one position.
    */
   readonly maps: CoordinateMaps
 }

package/src/extractStructureSequences.ts

@@ -1,42 +1,35 @@
 /** A polymer entity of a loaded structure: its mmCIF entity id, its one-letter
- * sequence, and the molstar `label_seq_id` of each of those residues.
+ * sequence, and the molstar `label_seq_id` of each residue.
  *
- * The entity id is what lets every downstream step talk about "the gene's
- * protein" by identity instead of by the fragile entity-[0] position.
+ * Structure positions are 0-based indices into `seq`, and molstar selects
+ * residues by `label_seq_id`. The two differ by 1 only when the entity's
+ * sequence covers every residue from 1, which holds for any mmCIF with an
+ * `entity_poly_seq` category (all of RCSB and AlphaFold) and for a PDB file
+ * with SEQRES records, from which molstar builds that category.
  *
- * `seqIds` is what lets it talk about a *residue* by identity. Structure
- * positions in this plugin are 0-based indices into `seq`; molstar addresses
- * residues by `label_seq_id`. Those are related by `+1` only when the entity's
- * sequence covers every residue from 1 — true for any mmCIF with an
- * `entity_poly_seq` category (all of RCSB and AlphaFold) and for PDB files
- * carrying SEQRES records, because molstar synthesizes the category from them.
- *
- * A PDB-format file with no SEQRES has no such category, so molstar falls back
- * to `StructureSequence.fromHierarchy` and takes `label_seq_id` straight from
- * the observed residues' author numbering: a chain whose coordinates start at
- * residue 94 yields seqIds 94.., and an unobserved loop leaves a hole. Deriving
- * the id arithmetically there is off by the whole offset, in both directions —
- * every hover reads the wrong residue and every highlight paints the wrong one.
- * So carry the real ids and convert through them.
+ * For a PDB file without SEQRES, molstar falls back to
+ * `StructureSequence.fromHierarchy` and takes `label_seq_id` from the observed
+ * residues' author numbering: a chain whose coordinates start at residue 94 has
+ * seqIds 94.., and an unobserved loop leaves a gap. Adding 1 there is off by the
+ * whole offset, in both directions, so convert through `seqIds`.
  */
 export interface Entity {
-  /** mmCIF entity id, molstar's own bookkeeping */
+  /** mmCIF entity id */
   entityId: string
   /** one letter per residue, observed or not */
   seq: string
   /** molstar `label_seq_id` per position of `seq` */
   seqIds: number[]
-  /** author chain ids carrying this entity, e.g. ['A', 'B'] for a homodimer:
-   * what a user recognises from the PDB entry page */
+  /** author chain ids of this entity, e.g. ['A', 'B'] for a homodimer, as
+   * the PDB entry page lists them */
   chains: string[]
-  /** DNA, RNA or a hybrid, by molstar's entity subtype. Its letters spell
-   * amino acids too (A, C, G, T, U), so it is kept out of the alignment
-   * rather than left to score low. */
+  /** DNA, RNA or a hybrid, by molstar's entity subtype. A, C, G, T and U
+   * are amino-acid letters too, so chooseMappedEntity skips these. */
   nucleicAcid?: boolean
   /** `auth_seq_id` per position: the depositors' numbering, which papers cite
-   * (1TUP's position 154 is R248) and Mol*'s hover shows. Display only;
-   * address Mol* through `seqIds`. Absent when the model has no atomic
-   * hierarchy. See `residueNumber`. */
+   * (1TUP's position 154 is R248) and Mol*'s hover shows. For display only;
+   * use `seqIds` to select residues in Mol*. Absent when the model has no
+   * atomic hierarchy. See `residueNumber`. */
   authSeqIds?: number[]
 }
 
@@ -284,8 +277,8 @@ export function entityLabel(entity: Entity) {
   return `${chains} (${entity.seq.length} ${entity.nucleicAcid ? 'nt' : 'aa'})`
 }
 
-/** The protein chains' sequences, for the launch dialog's isoform matching,
- * which has no use for a DNA strand that happens to align. */
+/** The protein chains' sequences, for ranking isoforms against a structure.
+ * DNA chains are left out, because their letters align as amino acids. */
 export function extractStructureSequences(
   model: StructureModel,
 ): string[] | undefined {

package/src/fetchUtils.ts

@@ -36,9 +36,9 @@ export function isDefinitiveFailure(e: unknown) {
 }
 
 /**
- * The error a failed response deserves: status and host, plus at most the first
- * line of the body. A whole body is an HTML error page or a megabyte of JSON,
- * and pasting it into the dialog buries the one line that says what went wrong.
+ * The error for a failed response: status and host, plus at most the first line
+ * of the body. A whole body is an HTML error page or a megabyte of JSON, which
+ * hides the line that says what went wrong.
  */
 export async function httpError(response: Response, url: string) {
   const detail = firstLine(await response.text().catch(() => ''))
@@ -127,10 +127,10 @@ export async function jsonfetch<T = unknown>(
 }
 
 /**
- * An AbortSignal's reason as a real Error. `signal.reason` is `any` — usually a
- * DOMException, but a caller can abort with anything at all — and throwing a
- * non-Error loses the stack and breaks `instanceof Error` checks in the UI's
- * error rendering. Normalize at every throw site.
+ * An AbortSignal's reason as a real Error. `signal.reason` is `any`, usually a
+ * DOMException, but a caller can abort with any value, and throwing a non-Error
+ * loses the stack and breaks `instanceof Error` checks. Use it at every throw
+ * site.
  */
 export function abortError(signal: AbortSignal) {
   return signal.reason instanceof Error

package/src/isoformRanking.ts

@@ -17,7 +17,7 @@ export interface RankedIsoform {
   /** identical residues against the structure, for an isoform that does not
    * match it exactly; undefined with no structure to compare to */
   identical?: number
-  /** that alignment's score, which is what ranks non-matching isoforms */
+  /** that alignment's score, which ranks the non-matching isoforms */
   score?: number
 }
 

package/src/mappings.ts

@@ -6,13 +6,11 @@ export interface AlignmentRow {
 }
 
 /**
- * A two-row alignment whose ROW ORDER IS A CONTRACT: row 0 is the transcript,
- * row 1 is the structure. Every producer honors it — runLocalAlignment is
- * always called as (transcript, structure), and the manual-import dialog tells
- * the user to paste them in that order — and every consumer depends on it, but
- * nothing in the type can enforce it, and swapping the two silently inverts
- * every coordinate map. Read the rows through the accessors below rather than
- * indexing, so a call site states which sequence it means.
+ * A two-row alignment: row 0 is the transcript and row 1 is the structure.
+ * alignSequences takes them in that order and every consumer depends on it,
+ * but the type cannot enforce it, and swapped rows invert every coordinate map
+ * without an error. Read the rows with the accessors below, so a call site
+ * names the sequence it means.
  */
 export interface PairwiseAlignment {
   consensus: string
@@ -28,11 +26,10 @@ export const alignmentLength = (pa: PairwiseAlignment) =>
   transcriptAlignedSeq(pa).length
 
 /**
- * Why a pairwise alignment can't be used, or undefined if it's usable. The two
- * rows must be the same non-zero length — every coordinate map walks them in
- * lockstep, so a ragged pair would map positions to nonsense. Callers that
- * accept alignments from outside (the manual-import dialog) check this and
- * report it; the internal map builders assert on it.
+ * Why a pairwise alignment can't be used, or undefined if it's usable. Both
+ * rows must have the same non-zero length, because every coordinate map walks
+ * them in step. Check an alignment from outside the package with this; the
+ * internal map builders throw on it.
  */
 export function pairwiseAlignmentProblem(pa: PairwiseAlignment) {
   const transcript = transcriptAlignedSeq(pa)

package/src/pairwiseAlignment.ts

@@ -393,14 +393,14 @@ export function selfScore(seq: string) {
 }
 
 export function scoredAlignment(
-  seq1: string,
-  seq2: string,
+  transcript: string,
+  structure: string,
   algorithm: AlignmentAlgorithm,
 ): { alignment: PairwiseAlignment; score: number } {
   const { alignedSeq1, alignedSeq2, score } =
     algorithm === 'smith_waterman'
-      ? smithWaterman(seq1, seq2)
-      : needlemanWunsch(seq1, seq2)
+      ? smithWaterman(transcript, structure)
+      : needlemanWunsch(transcript, structure)
 
   return {
     alignment: {
@@ -414,10 +414,13 @@ export function scoredAlignment(
   }
 }
 
-export function runLocalAlignment(
-  seq1: string,
-  seq2: string,
+export function alignSequences(
+  transcript: string,
+  structure: string,
   algorithm: AlignmentAlgorithm,
 ): PairwiseAlignment {
-  return scoredAlignment(seq1, seq2, algorithm).alignment
+  return scoredAlignment(transcript, structure, algorithm).alignment
 }
+
+/** @deprecated renamed to `alignSequences`, which runs either algorithm */
+export const runLocalAlignment = alignSequences

package/src/pdbUniProtMapping.ts

@@ -70,12 +70,11 @@ function segmentsForEntity(
 }
 
 /**
- * Picks the UniProt entry that describes a given entity, with its segments
- * narrowed to that entity. Only the entity the plugin has mapped to the
- * transcript is relevant — a heteromer maps each of its chains to a different
- * accession, and using the wrong one would silently annotate the wrong protein.
- * When several accessions cover the same entity (a chimeric construct) the one
- * contributing the most residues wins.
+ * Picks the UniProt entry for a given entity, with its segments narrowed to
+ * that entity. Pass the entity mapped to the transcript: a heteromer's chains
+ * align to different accessions, and the wrong one would annotate the wrong
+ * protein. When several accessions cover one entity (a chimeric construct), the
+ * one covering the most residues wins.
  */
 export function chooseUniProtMappingForEntity(
   mappings: UniProtStructureMapping[],

package/src/structureFormat.ts

@@ -1,19 +1,14 @@
 /**
  * Which molstar trajectory parser a structure needs.
  *
- * Getting this wrong is not a graceful failure in either direction: parsing a
- * PDB file as mmCIF throws ("Unexpected token. Expected data_, loop_, or data
- * name"), and — worse — parsing an mmCIF as PDB *succeeds* and yields a model
- * with zero polymer entities and thousands of misread atoms, so the view loads
- * with no sequence, no alignment and no genome mapping, and nothing reports an
- * error.
+ * A wrong choice fails either way. Parsing a PDB file as mmCIF throws
+ * ("Unexpected token. Expected data_, loop_, or data name"). Parsing an mmCIF
+ * as PDB succeeds and yields a model with zero polymer entities and thousands of
+ * misread atoms, so the structure loads with no sequence, no alignment and no
+ * genome mapping, and with no error.
  *
- * So detection lives here and is applied as the default at every entry point,
- * rather than at one of them.
- *
- * The two names are the subset of molstar's `BuiltInTrajectoryFormat` a
- * structure loaded from a file or a url can be, spelled out rather than
- * imported so nothing here depends on molstar.
+ * The two names are the subset of molstar's `BuiltInTrajectoryFormat` that a
+ * structure file or URL can be, written out so nothing here imports molstar.
  */
 export type StructureFormat = 'pdb' | 'mmcif'
 
@@ -35,8 +30,7 @@ export function structureFileExtension(nameOrUrl: string) {
 
 /**
  * Format for a filename or URL. Unknown extensions fall back to mmCIF, which is
- * what every URL this plugin generates itself serves (AlphaFold and RCSB both
- * hand out `.cif`).
+ * what AlphaFold and RCSB serve (`.cif`).
  */
 export function structureFormatFromName(nameOrUrl: string): StructureFormat {
   return PDB_EXTENSIONS.has(structureFileExtension(nameOrUrl)) ? 'pdb' : 'mmcif'
@@ -49,10 +43,9 @@ export function isBinaryStructureUrl(url: string) {
 }
 
 /**
- * Format for structure text that arrived without a filename — an inline `data`
- * snapshot, a pasted file, or the PDB the plugin synthesizes from Foldseek Cα
- * coordinates. Sniffs the content, which is strictly more reliable than a name
- * and is the only signal available here.
+ * Format for structure text with no filename, such as inline data, a pasted
+ * file, or a PDB built by `caCoordsToPdb`. The content is more reliable than a
+ * name, and here it is the only signal.
  *
  * mmCIF is line-oriented and its first meaningful line is a `data_` block
  * header (comments and blank lines may precede it); PDB has none.

package/src/structureSources.ts

@@ -24,7 +24,7 @@ export interface ExperimentalStructure {
   end: number
   /** fraction of the UniProt sequence the entry covers, 0..1 */
   coverage: number
-  /** author chain ids carrying the protein */
+  /** author chain ids of the protein */
   chains: string[]
 }
 

package/src/structureUrls.ts

@@ -1,13 +1,9 @@
-// Pure structure-URL builders and target parsers. Kept dependency-free so both
-// the launch flow and the ProteinView model (e.g. resolving a `uniprotId`/`pdbId`
-// shorthand at hydration) can import them without pulling in heavy launch code.
+// Structure URL builders and target parsers, with no dependencies.
 
 const ALPHAFOLD_VERSION = 'v6'
 
-// UniProt endpoints. rest.* is the machine API (the GFF the feature tracks and
-// the alignment's annotation rows both read, the FASTA the temporary protein
-// assembly is built from); www.*/entry is the human-facing entry page the UI
-// links to. Centralized so a path change is one edit rather than a grep.
+// UniProt endpoints. rest.* is the machine API, serving the features as GFF
+// and the sequence as FASTA; www.*/entry is the entry page for people.
 export function uniprotGffUrl(uniprotId: string) {
   return `https://rest.uniprot.org/uniprotkb/${uniprotId}.gff`
 }
@@ -49,20 +45,15 @@ export function rcsbEntryUrl(pdbId: string) {
 }
 
 /**
- * Resolve the `{ pdbId }` shorthand to a concrete structure URL, so a
- * hand-authored snapshot or a short launch URL doesn't have to know RCSB's
- * filename format. An explicit `url` (or inline `data`) always wins.
- * Idempotent: re-resolving an already-resolved spec returns the same url.
+ * Resolve the `{ pdbId }` shorthand to a structure URL, so a hand-written config
+ * or a short launch URL needs no RCSB filename. An explicit `url` (or inline
+ * `data`) always wins, and resolving an already-resolved spec returns the same
+ * url.
  *
- * `uniprotId` deliberately resolves to no url here, and still outranks a
- * `pdbId`. An accession's files are whatever AlphaFold DB currently holds — an
- * isoform model, several fragments, a new model version — so the structure
- * keeps the accession and the structure loader asks the prediction API which
- * file to open.
- *
- * Shared by the Structure model's snapshot preprocessor and the
- * LaunchView-ProteinView extension point, which would otherwise each carry
- * their own copy of the same precedence rule.
+ * `uniprotId` resolves to no url and still outranks a `pdbId`. AlphaFold DB's
+ * files for an accession change (an isoform model, several fragments, a new
+ * model version), so the caller keeps the accession and asks
+ * `fetchAlphaFoldModels` which file to open.
  */
 export function resolveStructureUrl({
   url,
@@ -149,9 +140,9 @@ export function getConfidenceUrlFromTarget(target: string) {
 }
 
 /**
- * What a structure is called in the UI: its PDB id, its AlphaFold accession,
- * else the file's name. Shared by the view title, the alignment panel heading
- * and the hover readout, so one structure reads the same everywhere.
+ * The name to show for a structure: its PDB id, its AlphaFold accession, else
+ * the file's name. Use it wherever a structure is named, so each place shows
+ * the same name.
  */
 export function structureDisplayLabel({
   url,

package/src/types.ts

@@ -12,11 +12,8 @@ export const ALIGNMENT_ALGORITHM_VALUES: AlignmentAlgorithm[] = [
   'smith_waterman',
 ]
 
-/**
- * Parses an untrusted algorithm name (a URL session-spec param) into the union.
- * The only place a coercion is needed: the model property is an enumeration, so
- * everything downstream of hydration is already typed.
- */
+/** Parses an untrusted algorithm name, such as a URL parameter, falling back
+ * to Smith-Waterman. */
 export function coerceAlignmentAlgorithm(value: string): AlignmentAlgorithm {
   return (
     ALIGNMENT_ALGORITHM_VALUES.find(v => v === value) ??

package/src/uniProtSearch.ts

@@ -111,7 +111,6 @@ async function searchByXref(
   try {
     return { entries: await searchUniProt(query, 10, opts), error: undefined }
   } catch (e) {
-    console.error(`xref search failed for ${id}:`, e)
     return { entries: [], error: e }
   }
 }
@@ -132,22 +131,18 @@ async function searchByGeneName(
     // are 284812. The descendants are asked only on a miss, because for a
     // species with reviewed subspecies entries (human and Neanderthal) they
     // turn one answer into two.
-    // The taxon itself has answered, so the wider question failing leaves
-    // that answer standing rather than turning an empty result into an error.
+    // When the descendant search fails, the taxon's own empty result stands
+    // rather than becoming an error.
     const entries =
       exact.length === 0 && organismId
         ? await searchUniProt(
             buildGeneNameQuery(geneName, organismId, 'taxonomy_id'),
             5,
             opts,
-          ).catch((e: unknown) => {
-            console.error(`descendant-taxon search failed for ${geneName}:`, e)
-            return exact
-          })
+          ).catch(() => exact)
         : exact
     return { entries, error: undefined }
   } catch (e) {
-    console.error(`gene name search failed for ${geneName}:`, e)
     return { entries: [], error: e }
   }
 }