app/kb/registry/reference.mjs

Functions

Imports

It imports app/lib/primers.mjs. Imported by app/kb/registry/align.mjs.

Source

1// The reference sequences a primer is placed on (docs/REGISTRY.md): GenBank records, fetched once into data/references/ as
2// FASTA files that keep NCBI's own header, and read here. A primer's position, strand and mismatches, and a pair's product,
3// are COMPUTED from a reference by align.mjs (the tested code in primers.mjs), never copied from a paper or a database, and
4// the page states which accession it used.
5//
6// A reference is a whole record (`DQ387450.1`) or a region of one (`NC_052532.1:76902320-76906237`, how NCBI names a slice of
7// a chromosome). A position is reported in the ACCESSION's own coordinates, so a region's offset is added back and a reader
8// can check it against the record at NCBI.
9
10import { parseFasta } from "../../lib/primers.mjs";
11
12/** The id a header names: an accession.version, and for a slice of a record its from-to span. */
13const HEADER = /^>?\s*([A-Z]{1,2}_?[0-9]+\.[0-9]+)(?::([0-9]+)-([0-9]+))?\s+(.*)$/;
14
15/**
16 * @typedef {{
17 *   id: string,
18 *   accession: string,
19 *   from: number,
20 *   to: number,
21 *   description: string,
22 *   sequence: string,
23 * }} Reference
24 */
25
26/**
27 * One FASTA text, parsed. The header must be NCBI's own (`>accession.version[:from-to] description`) and the sequence must
28 * be the length that header says, so a truncated or edited file cannot be read as the record it names.
29 *
30 * @param {string} text
31 * @returns {Reference}
32 */
33export function parseReference(text) {
34  const { header, sequence } = parseFasta(text);
35  const match = HEADER.exec(header);
36  if (!match) throw new Error(`"${header}" is not an NCBI FASTA header: >accession.version[:from-to] description`);
37  const [, accession = "", fromText, toText, description = ""] = match;
38  const from = fromText === undefined ? 1 : Number(fromText);
39  const to = toText === undefined ? sequence.length : Number(toText);
40  if (to - from + 1 !== sequence.length) {
41    throw new Error(`${accession}: the header spans ${from}-${to} (${to - from + 1} bases) but the sequence is ${sequence.length}`);
42  }
43  if (!/^[ACGT]+$/.test(sequence)) throw new Error(`${accession}: the sequence has a base other than A, C, G and T, so it cannot be a placement reference`);
44  const id = fromText === undefined ? accession : `${accession}:${from}-${to}`;
45  return { id, accession, from, to, description, sequence };
46}
47
48/**
49 * A 1-based position on the reference's own sequence, as the accession numbers it.
50 *
51 * @param {Reference} reference
52 * @param {number} position 1-based on `reference.sequence`
53 */
54export function accessionPosition(reference, position) {
55  return reference.from + position - 1;
56}