p2s_mapper 1.4.0 → 2.1.0

package/README.md

@@ -1,28 +1,17 @@
 # p2s_mapper
 
-Map a transcript's translation onto a protein structure.
-
-- **Align** the transcript to the structure's sequence (Smith-Waterman or
-  Needleman-Wunsch, BLOSUM62)
-- **Convert coordinates** both ways between transcript, alignment, structure,
-  Mol\* and UniProt numbering
-- **Choose the chain** that best matches the gene's protein
-- **Use SIFTS** to place UniProt annotations and drop fusion-partner residues
-- **Find structures** through AlphaFold, 3D-Beacons, PDBe and UniProt
-
-## Works with g2p_mapper
-
-p2s_mapper covers **protein ↔ structure**. The other half, **genome ↔ protein**,
-is [g2p_mapper](https://github.com/GMOD/g2p_mapper): it turns a transcript's CDS
-into per-codon genome positions, on either strand and across exon boundaries. It
-is p2s_mapper's only runtime dependency, and chaining the two takes you from a
-genome coordinate to a residue in 3D and back.
-
-Extracted from
-[jbrowse-plugin-protein3d](https://github.com/GMOD/jbrowse-plugin-protein3d),
-where we made the measurements behind the scoring rules. The package has no
-React, JBrowse or Mol\* dependency: a loaded Mol\* model reaches it through
-narrow structural interfaces.
+Lines up a protein sequence with its 3D structure, residue by residue.
+
+- **In:** a protein sequence, and an AlphaFold or PDB structure
+- **Out:** which 3D residue each amino acid is, and back
+- Picks the right chain and flags a poor match
+- Finds structures for a gene
+- Places UniProt annotations on a PDB entry
+- With [g2p_mapper](https://github.com/GMOD/g2p_mapper): genome position ↔ 3D
+  residue
+- No React, JBrowse or Mol\* dependency
+- Used by
+  [jbrowse-plugin-protein3d](https://github.com/GMOD/jbrowse-plugin-protein3d)
 
 ## Install
 
@@ -30,28 +19,220 @@ narrow structural interfaces.
 npm install p2s_mapper
 ```
 
-## How it fits together
+## Usage
+
+### Map a transcript onto a structure
+
+Pass the transcript's translation and the structure's chain sequences.
+`chooseMappedEntity` picks the chain, `isLowSimilarity` checks the match is not
+chance, and `makeCoordinateMapper` converts positions both ways.
+
+```ts
+import {
+  alignmentQuality,
+  chooseMappedEntity,
+  describeAlignmentQuality,
+  isLowSimilarity,
+  makeCoordinateMapper,
+  structurePos,
+  transcriptPos,
+} from 'p2s_mapper'
+
+// p53's N-terminus, and a structure holding a DNA strand and a tagged fragment
+const transcript = 'MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDP*'
+const chains = [
+  { seq: 'TTTCCTAGACTTGCCCAATTA', nucleicAcid: true },
+  { seq: 'GSHMSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQW' },
+]
+
+const picked = chooseMappedEntity(transcript, chains, 'smith_waterman')
+if (picked) {
+  picked.index // 1: the protein chain
+
+  const quality = alignmentQuality(picked.alignment)
+  isLowSimilarity(quality) // false
+  describeAlignmentQuality(quality)
+  // '98% identity over 40 of 43 structure residues'
+
+  const mapper = makeCoordinateMapper(picked.alignment)
+  mapper.transcriptToStructure(transcriptPos(16)) // 6
+  mapper.structureToTranscript(structurePos(6)) // 16
+  mapper.structureToTranscript(structurePos(0)) // undefined: the GSH tag
+}
+```
+
+Every position is 0-based. Structure and transcript positions are separate
+types, so passing one where the other belongs is a compile error.
+
+### From a genome position to a residue, and back
+
+g2p_mapper maps genome positions to protein positions. p2s_mapper maps a protein
+position to a structure position, and that to the `label_seq_id` Mol\* uses to
+select a residue.
+
+```ts
+import { genomeToTranscriptSeqMapping } from 'g2p_mapper'
+import {
+  chooseMappedEntity,
+  codonGenomeSpan,
+  makeCoordinateMapper,
+  makeLabelSeqIdIndex,
+  residueNumber,
+  structurePos,
+  toLabelSeqIds,
+  transcriptPos,
+} from 'p2s_mapper'
+import type { Entity } from 'p2s_mapper'
+
+const transcript = 'MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDP*'
+const { g2p, p2gCodon } = genomeToTranscriptSeqMapping({
+  refName: 'chr17',
+  start: 1000,
+  end: 2117,
+  strand: 1,
+  subfeatures: [
+    { refName: 'chr17', start: 1000, end: 1060, type: 'CDS', phase: 0 },
+    { refName: 'chr17', start: 2000, end: 2117, type: 'CDS' },
+  ],
+})
+
+// normally from extractEntities(model); here the author numbering starts at 12
+const entity: Entity = {
+  entityId: '1',
+  seq: 'GSHMSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQW',
+  seqIds: Array.from({ length: 43 }, (_, i) => i + 1),
+  authSeqIds: Array.from({ length: 43 }, (_, i) => i + 12),
+  chains: ['A'],
+}
+const picked = chooseMappedEntity(transcript, [entity], 'smith_waterman')!
+const mapper = makeCoordinateMapper(picked.alignment)
+
+// genome -> structure
+const proteinPos = g2p[2000] // 20
+if (proteinPos !== undefined) {
+  const pos = mapper.transcriptToStructure(transcriptPos(proteinPos)) // 10
+  if (pos !== undefined) {
+    toLabelSeqIds(entity, [pos]) // [11]: what to highlight in Mol*
+    residueNumber(entity, pos) // 22: what to show the user
+  }
+}
+
+// a Mol* hover on label_seq_id 15 -> genome
+const hovered = makeLabelSeqIdIndex(entity).get(15) // 14
+if (hovered !== undefined) {
+  const t = mapper.structureToTranscript(structurePos(hovered)) // 24
+  if (t !== undefined) {
+    codonGenomeSpan(p2gCodon, t) // [2012, 2015]
+  }
+}
+```
+
+### With a structure loaded in Mol\*
+
+`extractEntities` reads each chain's sequence, residue ids and numbering from a
+loaded Mol\* model. `StructureModel` lists the fields it reads, so the package
+needs no Mol\* import.
+
+```ts
+import {
+  chooseMappedEntity,
+  extractEntities,
+  rangeToLabelSeqIds,
+} from 'p2s_mapper'
+import type { StructureModel } from 'p2s_mapper'
+
+// e.g. what plugin.builders.structure.createModel resolves to
+declare const model: StructureModel
+declare const transcript: string
+
+const entities = extractEntities(model) ?? []
+const picked = chooseMappedEntity(transcript, entities, 'smith_waterman')
+const entity = picked ? entities[picked.index] : undefined
+
+// the label_seq_ids of structure positions 10-19, for a Mol* selection
+rangeToLabelSeqIds(entity, { start: 10, end: 20 })
+```
+
+### Find a structure for a gene
+
+```ts
+import {
+  fetchAlphaFoldModels,
+  fetchExperimentalStructures,
+  getPdbStructureUrl,
+  pickAlphaFoldModel,
+  searchUniProtEntries,
+} from 'p2s_mapper'
+
+declare const translation: string
+
+const { entries } = await searchUniProtEntries({
+  recognizedIds: ['GeneID:7157', 'ENST00000269305'],
+  geneName: 'TP53',
+  organismId: 9606,
+})
+const accession = entries[0]?.accession // 'P04637'
+
+if (accession) {
+  // predicted: the model folded from this exact translation, else the canonical one
+  const models = await fetchAlphaFoldModels(accession)
+  const predicted = pickAlphaFoldModel(models, { tx1: { seq: translation } })
+
+  // experimental: PDB entries, best coverage first
+  const [best] = await fetchExperimentalStructures(accession)
+  const url = predicted?.url ?? (best && getPdbStructureUrl(best.pdbId))
+}
+```
+
+Every network function takes `{ fetch?, signal? }` last, defaulting to
+`globalThis.fetch`, so the caller can pass a custom fetch and an `AbortSignal`.
+
+### Place UniProt annotations on a PDB entry
+
+A PDB construct is usually a fragment, numbered differently from UniProt.
+`fetchUniProtStructureMappings` reads the entry's alignment to UniProt from
+RCSB.
+
+```ts
+import {
+  chooseUniProtMappingForEntity,
+  fetchUniProtStructureMappings,
+  makeUniProtPositionMap,
+} from 'p2s_mapper'
+
+const mappings = await fetchUniProtStructureMappings('1tup')
+const mapping = chooseUniProtMappingForEntity(mappings, {
+  entityId: '3',
+  chains: ['A', 'B', 'C'],
+})
+const toStructure = makeUniProtPositionMap(mapping?.segments ?? [])
+toStructure(248) // 154: UniProt residue 248 is structure position 154
+```
+
+## Pipeline
 
 ![From a gene on the genome to a residue in 3D, and back](docs/img/pipeline.svg)
 
 ## Docs
 
-- [faq.md](docs/faq.md) — can I trust the mapping? What the package checks, and
-  what it leaves to you
-- [pipeline.md](docs/pipeline.md) — the flow above, step by step, and why chain
+- [api.md](docs/api.md): every export, with its signature, types and an example
+- [pipeline.md](docs/pipeline.md): the flow above, step by step, and why chain
   choice divides by the shorter sequence
-- [coordinates.md](docs/coordinates.md) — the four numberings of a residue and
-  the one route between each
-- [api.md](docs/api.md) — every export, grouped by job
-
-## Things to know first
-
-- Every coordinate in the API is **0-based**, branded by space so the compiler
-  rejects mixing them. See [coordinates.md](docs/coordinates.md).
-- A `PairwiseAlignment` has **row 0 = transcript, row 1 = structure**. Use the
-  accessors, not indexes.
-- Network functions take `{ fetch?, signal? }` and default to
-  `globalThis.fetch`.
+- [coordinates.md](docs/coordinates.md): the four ways a residue is numbered,
+  and which function converts between them
+- [faq.md](docs/faq.md): can I trust the mapping? What the package checks, and
+  what it leaves to you
+
+## Pitfalls
+
+- Positions are **0-based**, except UniProt positions and author residue
+  numbers, which are 1-based. See [coordinates.md](docs/coordinates.md).
+- A `PairwiseAlignment` has **row 0 = transcript, row 1 = structure**. Read the
+  rows with `transcriptAlignedSeq` and `structureAlignedSeq`.
+- `chooseMappedEntity` returns the best-matching chain even when the match is
+  poor. Check it with `isLowSimilarity` before trusting the mapping.
+- Get Mol\*'s `label_seq_id` from `toLabelSeqIds`, which reads `Entity.seqIds`.
+  Adding 1 to the position gives the wrong residue in a PDB file without SEQRES.
 
 ## License
 

package/dist/alignmentQuality.d.ts

@@ -1,20 +1,20 @@
 import type { PairwiseAlignment } from './mappings.ts';
 export interface AlignmentQuality {
-    /** columns carrying a residue on both rows, i.e. mapped positions */
+    /** columns with a residue in both rows, i.e. mapped positions */
     aligned: number;
     identical: number;
     transcriptLength: number;
     structureLength: number;
     /** identical over aligned; 0 when nothing aligned */
     identity: number;
-    /** identical over the shorter of the two sequences: the statistic that
-     * separates a real match from a chance local alignment, see below */
+    /** identical over the shorter of the two sequences, which separates a
+     * real match from a chance local alignment (see LOW_IDENTITY_OVER_SHORTER) */
     identityOverShorter: number;
     /** aligned over the structure's length */
     structureCoverage: number;
     /** first and last transcript residue the alignment covers, 1-based
-     * inclusive; 0 when nothing aligned. A structure is usually a fragment, and
-     * which part of the protein it holds is the reader's first question. */
+     * inclusive; 0 when nothing aligned. A structure is usually a fragment, so
+     * these show which part of the protein it contains. */
     transcriptStart: number;
     transcriptEnd: number;
 }

package/dist/alphaFoldModels.d.ts

@@ -22,11 +22,11 @@ export declare function parseAlphaFoldModels(json: unknown): AlphaFoldModel[];
 export declare function fetchAlphaFoldModels(uniprotId: string, opts?: FetchOptions): Promise<AlphaFoldModel[]>;
 /**
  * The model to open for a gene's transcripts: one folded from exactly a
- * transcript's translation, canonical first, so the view maps it as an
- * identity; else the canonical model; else the longest isoform model.
+ * transcript's translation, canonical first, so every residue maps to itself;
+ * else the canonical model; else the longest isoform model.
  *
- * Takes any record of sequences, since the structure loader knows one
- * translation rather than a gene's isoforms.
+ * Takes any record of sequences, since a caller may know one translation rather
+ * than a gene's isoforms.
  */
 export declare function pickAlphaFoldModel(models: AlphaFoldModel[], isoformSequences: Record<string, {
     seq: string;

package/dist/alphaFoldModels.js

@@ -48,11 +48,11 @@ async function fetchAlphaFoldModels(uniprotId, opts) {
 }
 /**
  * The model to open for a gene's transcripts: one folded from exactly a
- * transcript's translation, canonical first, so the view maps it as an
- * identity; else the canonical model; else the longest isoform model.
+ * transcript's translation, canonical first, so every residue maps to itself;
+ * else the canonical model; else the longest isoform model.
  *
- * Takes any record of sequences, since the structure loader knows one
- * translation rather than a gene's isoforms.
+ * Takes any record of sequences, since a caller may know one translation rather
+ * than a gene's isoforms.
  */
 function pickAlphaFoldModel(models, isoformSequences) {
     const translations = new Set(Object.values(isoformSequences ?? {}).map(v => (0, stripStopCodon_ts_1.stripStopCodon)(v.seq)));

package/dist/chooseMappedEntity.d.ts

@@ -9,12 +9,12 @@ import type { AlignmentAlgorithm } from './types.ts';
  */
 export declare function interactionMatchesMappedEntity(entityId: string, mappedEntityId: string | undefined): boolean;
 export interface EntitySelection extends ScoredAlignment {
-    /** index into the candidate array of the entity that is the transcript's */
+    /** index of the chosen entity in the candidate array */
     index: number;
 }
 export interface ScoredAlignment {
-    /** alignment of the transcript against the entity (stop codons stripped on
-     * both sides, matching the rest of the mapping pipeline) */
+    /** alignment of the transcript against the entity, with stop codons
+     * stripped from both */
     alignment: PairwiseAlignment;
     /** identical aligned residues */
     matches: number;
@@ -39,17 +39,15 @@ export declare function explainedFraction(matches: number, transcriptLength: num
  */
 export declare function alignTranscriptToEntity(transcript: string, entitySeq: string, algorithm: AlignmentAlgorithm): ScoredAlignment | undefined;
 /**
- * Pick which polymer entity of a structure corresponds to the transcript.
+ * Pick the polymer entity of a structure that is the transcript's protein.
  *
- * The plugin historically hardcoded entity `[0]`, which silently mis-maps every
- * heteromeric / protein-DNA / processed-peptide structure where the protein of
- * interest is some other chain. Selecting by alignment makes the structure self-
- * describe which entity is the gene's protein: an exact sequence match wins
- * outright, otherwise the entity with the highest identity over the shorter
- * sequence (see `explainedFraction`). Nucleic-acid entities are never
- * candidates.
+ * Taking entity `[0]` mis-maps every heteromeric, protein-DNA or
+ * processed-peptide structure where the protein is another chain. An exact
+ * sequence match wins outright; otherwise the entity with the highest identity
+ * over the shorter sequence wins (see `explainedFraction`). Nucleic-acid
+ * entities are never candidates.
  *
- * Returns `undefined` only when there is nothing to map (no transcript or no
- * protein entities) — never a silent fallback to the wrong entity.
+ * Returns `undefined` only when there is nothing to map: no transcript, or no
+ * protein entity. It never falls back to another entity.
  */
 export declare function chooseMappedEntity(transcript: string, entities: readonly (string | EntityCandidate)[], algorithm: AlignmentAlgorithm): EntitySelection | undefined;

package/dist/chooseMappedEntity.js

@@ -25,8 +25,7 @@ function interactionMatchesMappedEntity(entityId, mappedEntityId) {
  * usually is: on 1H26 the 11-residue p53 peptide matches 11 while CDK2 accrues
  * 58 scattered identities, and on 4ZZJ SIRT1 beats the 7-residue p53 peptide
  * 63 to 6. The Smith-Waterman score is no better there (56 vs 58). Dividing
- * by length asks the question the picker actually has, which chain *is* this
- * gene's product: the peptide scores 0.69 and 0.50, the partners 0.19 and
+ * by the shorter length identifies the chain that *is* this gene's product: the peptide scores 0.69 and 0.50, the partners 0.19 and
  * 0.17, and across a ribosome's 55 chains no decoy passes 0.29.
  *
  * Dividing by the *entity's* length alone penalised a fusion construct: a
@@ -91,18 +90,16 @@ function alignTranscriptToEntity(transcript, entitySeq, algorithm) {
     };
 }
 /**
- * Pick which polymer entity of a structure corresponds to the transcript.
+ * Pick the polymer entity of a structure that is the transcript's protein.
  *
- * The plugin historically hardcoded entity `[0]`, which silently mis-maps every
- * heteromeric / protein-DNA / processed-peptide structure where the protein of
- * interest is some other chain. Selecting by alignment makes the structure self-
- * describe which entity is the gene's protein: an exact sequence match wins
- * outright, otherwise the entity with the highest identity over the shorter
- * sequence (see `explainedFraction`). Nucleic-acid entities are never
- * candidates.
+ * Taking entity `[0]` mis-maps every heteromeric, protein-DNA or
+ * processed-peptide structure where the protein is another chain. An exact
+ * sequence match wins outright; otherwise the entity with the highest identity
+ * over the shorter sequence wins (see `explainedFraction`). Nucleic-acid
+ * entities are never candidates.
  *
- * Returns `undefined` only when there is nothing to map (no transcript or no
- * protein entities) — never a silent fallback to the wrong entity.
+ * Returns `undefined` only when there is nothing to map: no transcript, or no
+ * protein entity. It never falls back to another entity.
  */
 function chooseMappedEntity(transcript, entities, algorithm) {
     const t = (0, stripStopCodon_ts_1.stripStopCodon)(transcript);

package/dist/chooseMappedEntity.js.map

@@ -1 +1 @@
-{"version":3,"file":"chooseMappedEntity.js","sourceRoot":"","sources":["../src/chooseMappedEntity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chooseMappedEntity.js","sourceRoot":"","sources":["../src/chooseMappedEntity.ts"],"names":[],"mappings":"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"}

package/dist/coordinates.d.ts

@@ -1,22 +1,24 @@
 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.
  */
-type Branded<B extends string> = number & {
-    readonly __brand: B;
+export type StructurePos = number & {
+    readonly __brand: 'StructurePos';
+};
+export type TranscriptPos = number & {
+    readonly __brand: 'TranscriptPos';
+};
+export type AlignmentCol = number & {
+    readonly __brand: 'AlignmentCol';
 };
-export type StructurePos = Branded<'StructurePos'>;
-export type TranscriptPos = Branded<'TranscriptPos'>;
-export type AlignmentCol = Branded<'AlignmentCol'>;
 export declare const structurePos: (n: number) => StructurePos;
 export declare const transcriptPos: (n: number) => TranscriptPos;
 export declare const alignmentCol: (n: number) => AlignmentCol;
@@ -36,10 +38,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;
 }
@@ -63,4 +64,3 @@ export declare function transcriptRangeToStructureRange(mapper: CoordinateMapper
     start: number;
     end: number;
 } | undefined;
-export {};

package/dist/coordinates.js.map

@@ -1 +1 @@
-{"version":3,"file":"coordinates.js","sourceRoot":"","sources":["../src/coordinates.ts"],"names":[],"mappings":";;;AA4DA,oDAiCC;AASD,0EAgBC;AAtHD,+CAIsB;AACtB,iDAA0C;AAqBnC,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAiB,CAAA;AAA/C,QAAA,YAAY,gBAAmC;AACrD,MAAM,aAAa,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAkB,CAAA;AAAjD,QAAA,aAAa,iBAAoC;AACvD,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAiB,CAAA;AAA/C,QAAA,YAAY,gBAAmC;AA2B5D;;;;GAIG;AACH,SAAgB,oBAAoB,CAClC,iBAAoC;IAEpC,MAAM,EACJ,mCAAmC,EACnC,mCAAmC,GACpC,GAAG,IAAA,4CAA8B,EAAC,iBAAiB,CAAC,CAAA;IACrD,MAAM,KAAK,GAAG,IAAA,6CAA+B,EAAC,iBAAiB,CAAC,CAAA;IAChE,MAAM,KAAK,GAAG,IAAA,8CAAgC,EAAC,iBAAiB,CAAC,CAAA;IACjE,MAAM,KAAK,GAAG,IAAA,wBAAS,EAAC,KAAK,CAAC,CAAA;IAC9B,MAAM,KAAK,GAAG,IAAA,wBAAS,EAAC,KAAK,CAAC,CAAA;IAE9B,uEAAuE;IACvE,6EAA6E;IAC7E,sEAAsE;IACtE,OAAO;QACL,qBAAqB,EAAE,CAAC,CAAC,EAAE,CACzB,mCAAmC,CAAC,CAAC,CAA8B;QACrE,qBAAqB,EAAE,CAAC,CAAC,EAAE,CACzB,mCAAmC,CAAC,CAAC,CAA6B;QACpE,oBAAoB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAC/D,oBAAoB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAC/D,qBAAqB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAChE,qBAAqB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA8B;QACjE,IAAI,EAAE;YACJ,mCAAmC;YACnC,mCAAmC;YACnC,+BAA+B,EAAE,KAAK;YACtC,gCAAgC,EAAE,KAAK;YACvC,4BAA4B,EAAE,KAAK;YACnC,6BAA6B,EAAE,KAAK;SACrC;KACF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,+BAA+B,CAC7C,MAAwB,EACxB,KAAqC;IAErC,IAAI,KAAyB,CAAA;IAC7B,IAAI,IAAwB,CAAA;IAC5B,KAAK,IAAI,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;QAChE,MAAM,GAAG,GAAG,MAAM,CAAC,qBAAqB,CAAC,IAAA,qBAAa,EAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;QACpE,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YACxD,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QACvD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS;QAC9C,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,GAAG,CAAC,EAAE,CAAA;AACrC,CAAC"}
+{"version":3,"file":"coordinates.js","sourceRoot":"","sources":["../src/coordinates.ts"],"names":[],"mappings":";;;AAyDA,oDAiCC;AASD,0EAgBC;AAnHD,+CAIsB;AACtB,iDAA0C;AAmBnC,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAiB,CAAA;AAA/C,QAAA,YAAY,gBAAmC;AACrD,MAAM,aAAa,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAkB,CAAA;AAAjD,QAAA,aAAa,iBAAoC;AACvD,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAiB,CAAA;AAA/C,QAAA,YAAY,gBAAmC;AA0B5D;;;;GAIG;AACH,SAAgB,oBAAoB,CAClC,iBAAoC;IAEpC,MAAM,EACJ,mCAAmC,EACnC,mCAAmC,GACpC,GAAG,IAAA,4CAA8B,EAAC,iBAAiB,CAAC,CAAA;IACrD,MAAM,KAAK,GAAG,IAAA,6CAA+B,EAAC,iBAAiB,CAAC,CAAA;IAChE,MAAM,KAAK,GAAG,IAAA,8CAAgC,EAAC,iBAAiB,CAAC,CAAA;IACjE,MAAM,KAAK,GAAG,IAAA,wBAAS,EAAC,KAAK,CAAC,CAAA;IAC9B,MAAM,KAAK,GAAG,IAAA,wBAAS,EAAC,KAAK,CAAC,CAAA;IAE9B,uEAAuE;IACvE,6EAA6E;IAC7E,sEAAsE;IACtE,OAAO;QACL,qBAAqB,EAAE,CAAC,CAAC,EAAE,CACzB,mCAAmC,CAAC,CAAC,CAA8B;QACrE,qBAAqB,EAAE,CAAC,CAAC,EAAE,CACzB,mCAAmC,CAAC,CAAC,CAA6B;QACpE,oBAAoB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAC/D,oBAAoB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAC/D,qBAAqB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA6B;QAChE,qBAAqB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAA8B;QACjE,IAAI,EAAE;YACJ,mCAAmC;YACnC,mCAAmC;YACnC,+BAA+B,EAAE,KAAK;YACtC,gCAAgC,EAAE,KAAK;YACvC,4BAA4B,EAAE,KAAK;YACnC,6BAA6B,EAAE,KAAK;SACrC;KACF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,+BAA+B,CAC7C,MAAwB,EACxB,KAAqC;IAErC,IAAI,KAAyB,CAAA;IAC7B,IAAI,IAAwB,CAAA;IAC5B,KAAK,IAAI,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;QAChE,MAAM,GAAG,GAAG,MAAM,CAAC,qBAAqB,CAAC,IAAA,qBAAa,EAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;QACpE,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YACxD,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QACvD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS;QAC9C,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,GAAG,CAAC,EAAE,CAAA;AACrC,CAAC"}

package/dist/dbIds.d.ts

@@ -1,4 +1,4 @@
-type DbType = 'ensembl' | 'refseq' | 'ccds' | 'hgnc' | 'geneid';
+export type DbType = 'ensembl' | 'refseq' | 'ccds' | 'hgnc' | 'geneid';
 export declare function matchDbIdPattern(id: string): {
     db: DbType;
     pattern: RegExp;
@@ -13,4 +13,3 @@ export declare function getDbIdLabel(id: string): string;
  * "xref:ensembl-ENST00000123". HGNC strips its redundant "HGNC:" prefix. */
 export declare function buildUniProtXrefQuery(id: string): string | undefined;
 export declare function stripTrailingVersion(s?: string): string | undefined;
-export {};

package/dist/extractPerResidueConfidence.d.ts

@@ -1,4 +1,4 @@
-interface ConfidenceModel {
+export interface ConfidenceModel {
     obj?: {
         data: {
             atomicConformation: {
@@ -46,4 +46,3 @@ export declare function extractPerResidueConfidence(model: ConfidenceModel): Ent
  * indicate the track wouldn't be meaningful as confidence.
  */
 export declare function looksLikePlddt(values: number[] | undefined): values is number[];
-export {};

package/dist/extractStructureSequences.d.ts

@@ -1,49 +1,42 @@
 /** 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 */
     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, where the entity id is
-     * molstar's own bookkeeping */
+    /** 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 one-letter
-     * sequence spells amino acids too (A, C, G, T, U), so it has to be kept
-     * out of the transcript alignment rather than merely scoring 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 numbering the depositors chose, which
-     * for an RCSB entry is the one papers and UniProt cite (1TUP's position 154
-     * is R248) and what Mol*'s own hover label shows. Display only; every
-     * coordinate the plugin computes with stays a 0-based position, and molstar
-     * is addressed through `seqIds`. Absent when the model has no atomic
-     * hierarchy to read it from. See `residueNumber`. */
+    /** `auth_seq_id` per position: the depositors' numbering, which papers cite
+     * (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[];
 }
-interface Column<T> {
+export interface Column<T> {
     rowCount: number;
     value(row: number): T;
 }
-interface StructureModel {
+export interface StructureModel {
     obj?: {
         data: {
             entities?: {
@@ -123,8 +116,8 @@ export declare function oneLetterSequence(codes: ArrayLike<string>, canonical: s
 export declare function extractEntities(model: StructureModel): Entity[] | undefined;
 /** A user-facing name for an entity: its chains when known, else its id. */
 export declare function entityLabel(entity: Entity): string;
-/** 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 declare function extractStructureSequences(model: StructureModel): string[] | undefined;
 /**
  * The molstar `label_seq_id`s for a set of 0-based structure positions. Unknown
@@ -139,4 +132,3 @@ export declare function rangeToLabelSeqIds(entity: Entity | undefined, range: {
 } | undefined): number[];
 /** Reverse of `seqIds`: molstar's label_seq_id -> 0-based structure position. */
 export declare function makeLabelSeqIdIndex(entity: Entity | undefined): Map<number, number>;
-export {};

package/dist/extractStructureSequences.js

@@ -169,8 +169,8 @@ function entityLabel(entity) {
         : `Entity ${entity.entityId}`;
     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. */
 function extractStructureSequences(model) {
     return extractEntities(model)
         ?.filter(e => !e.nucleicAcid)