msa-parsers 1.0.3

package/src/msa/FastaMSA.ts

@@ -0,0 +1,82 @@
+import type { NodeWithIds } from '../types'
+
+export default class FastaMSA {
+  private MSA: { seqdata: Record<string, string> }
+
+  constructor(text: string) {
+    const seqdata: Record<string, string> = {}
+    for (const entry of text.split('>')) {
+      if (!/\S/.test(entry)) {
+        continue
+      }
+      const newlineIdx = entry.indexOf('\n')
+      if (newlineIdx === -1) {
+        continue
+      }
+      const defLine = entry.slice(0, newlineIdx)
+      const spaceIdx = defLine.indexOf(' ')
+      const id = spaceIdx === -1 ? defLine : defLine.slice(0, spaceIdx)
+      if (id) {
+        seqdata[id] = entry.slice(newlineIdx + 1).replaceAll(/\s/g, '')
+      }
+    }
+    this.MSA = { seqdata }
+  }
+
+  getMSA() {
+    return this.MSA
+  }
+
+  getRowData() {
+    return undefined
+  }
+
+  getNames() {
+    return Object.keys(this.MSA.seqdata)
+  }
+
+  getRow(name: string) {
+    return this.MSA.seqdata[name] || ''
+  }
+
+  getWidth() {
+    const name = Object.keys(this.MSA.seqdata)[0]!
+    return this.getRow(name).length
+  }
+
+  getStructures() {
+    return {}
+  }
+
+  get alignmentNames() {
+    return []
+  }
+
+  getHeader() {
+    return {}
+  }
+
+  getTree(): NodeWithIds {
+    return {
+      id: 'root',
+      name: 'root',
+      noTree: true,
+      children: this.getNames().map(name => ({
+        id: name,
+        children: [],
+        name,
+      })),
+    }
+  }
+
+  get seqConsensus() {
+    return undefined
+  }
+  get secondaryStructureConsensus() {
+    return undefined
+  }
+
+  get tracks() {
+    return []
+  }
+}

package/src/msa/StockholmMSA.ts

@@ -0,0 +1,141 @@
+import parseNewick from './parseNewick'
+import { parseAll } from './stockholmParser'
+import { generateNodeIds } from '../util'
+
+import type { NodeWithIds } from '../types'
+import type { StockholmData } from './stockholmParser'
+
+export default class StockholmMSA {
+  private data: StockholmData[]
+  private MSA: StockholmData
+
+  constructor(text: string, currentAlignment: number) {
+    const res = parseAll(text)
+    this.data = res
+    this.MSA = res[currentAlignment]!
+  }
+
+  getMSA() {
+    return this.MSA
+  }
+
+  getRow(name: string) {
+    return this.MSA.seqdata[name] || ''
+  }
+
+  getWidth() {
+    const name = Object.keys(this.MSA.seqdata)[0]!
+    return this.getRow(name).length
+  }
+
+  get alignmentNames() {
+    return this.data.map((aln, idx) => aln.gf.DE?.[0] ?? `Alignment ${idx + 1}`)
+  }
+
+  getHeader() {
+    const acEntries = this.MSA.gs.AC ?? {}
+    const drEntries = this.MSA.gs.DR ?? {}
+    return {
+      General: this.MSA.gf,
+      Accessions: Object.fromEntries(
+        Object.entries(acEntries).map(([k, v]) => [k, v[0]]),
+      ),
+      Dbxref: Object.fromEntries(
+        Object.entries(drEntries).map(([k, v]) => [k, v.join('; ')]),
+      ),
+    }
+  }
+
+  getRowData(rowName: string) {
+    return {
+      name: rowName,
+      accession: this.MSA.gs.AC?.[rowName]?.[0],
+      dbxref: this.MSA.gs.DR?.[rowName]?.join('; '),
+    }
+  }
+
+  getNames() {
+    return Object.keys(this.MSA.seqdata)
+  }
+
+  getSeqCoords() {}
+
+  getStructures() {
+    const pdbRegex = /PDB; +(\S+) +(\S); ([0-9]+)-([0-9]+)/
+    const drEntries = this.MSA.gs.DR ?? {}
+    const args = Object.entries(drEntries)
+      .flatMap(([id, drList]) =>
+        drList.map(dr => {
+          const match = pdbRegex.exec(dr)
+          return match ? { id, match } : null
+        }),
+      )
+      .filter((item): item is { id: string; match: RegExpExecArray } => !!item)
+      .map(({ id, match }) => ({
+        id,
+        pdb: match[1]!.toLowerCase(),
+        chain: match[2]!,
+        startPos: +match[3]!,
+        endPos: +match[4]!,
+      }))
+
+    const ret = {} as Record<
+      string,
+      { pdb: string; chain: string; startPos: number; endPos: number }[]
+    >
+    for (const entry of args) {
+      const { id, ...rest } = entry
+      if (!ret[id]) {
+        ret[id] = []
+      }
+      ret[id].push(rest)
+    }
+    return ret
+  }
+
+  getTree(): NodeWithIds {
+    const tree = this.MSA.gf.NH?.[0]
+    return tree
+      ? generateNodeIds(parseNewick(tree))
+      : {
+          id: 'root',
+          name: 'root',
+          noTree: true,
+          children: this.getNames().map(name => ({
+            id: name,
+            children: [],
+            name,
+          })),
+        }
+  }
+
+  get seqConsensus() {
+    return this.MSA.gc.seq_cons
+  }
+
+  get secondaryStructureConsensus() {
+    return this.MSA.gc.SS_cons
+  }
+
+  get tracks() {
+    return [
+      {
+        id: 'seqConsensus',
+        name: 'Sequence consensus',
+        data: this.seqConsensus,
+        customColorScheme: {},
+      },
+      {
+        id: 'secondaryStruct',
+        name: 'Secondary-structure',
+        data: this.secondaryStructureConsensus,
+        customColorScheme: {
+          '>': 'pink',
+          '<': 'lightblue',
+        },
+      },
+    ]
+  }
+}
+
+export { sniff as stockholmSniff } from './stockholmParser'

package/src/msa/index.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'vitest'
+
+import A3mMSA from './A3mMSA'
+import ClustalMSA from './ClustalMSA'
+import FastaMSA from './FastaMSA'
+import { getUngappedSequence, parseMSA } from './index'
+
+describe('parseMSA', () => {
+  test('parses FASTA format', () => {
+    const fasta = `>seq1
+ACDEF
+>seq2
+GHIKL`
+    const msa = parseMSA(fasta)
+
+    expect(msa).toBeInstanceOf(FastaMSA)
+    expect(msa.getNames()).toEqual(['seq1', 'seq2'])
+  })
+
+  test('parses A3M format', () => {
+    const a3m = `>seq1
+ACDEFghiKLMNPQ
+>seq2
+ACDEF---KLMNPQ`
+    const msa = parseMSA(a3m)
+
+    expect(msa).toBeInstanceOf(A3mMSA)
+  })
+
+  test('parses Clustal format', () => {
+    const clustal = `CLUSTAL W (1.83) multiple sequence alignment
+
+seq1      ACDEFGHIKL
+seq2      ACDEFGHIKL
+          **********`
+    const msa = parseMSA(clustal)
+
+    expect(msa).toBeInstanceOf(ClustalMSA)
+  })
+
+  test('defaults to Clustal for unknown format', () => {
+    const unknown = `some unknown format
+that doesn't match anything`
+    const msa = parseMSA(unknown)
+
+    expect(msa).toBeInstanceOf(ClustalMSA)
+  })
+})
+
+describe('getUngappedSequence', () => {
+  test('removes dashes', () => {
+    expect(getUngappedSequence('AC--DEF')).toBe('ACDEF')
+  })
+
+  test('removes dots', () => {
+    expect(getUngappedSequence('AC..DEF')).toBe('ACDEF')
+  })
+
+  test('removes mixed gaps', () => {
+    expect(getUngappedSequence('A-C.D--E..F')).toBe('ACDEF')
+  })
+
+  test('handles empty string', () => {
+    expect(getUngappedSequence('')).toBe('')
+  })
+
+  test('handles string with only gaps', () => {
+    expect(getUngappedSequence('---...')).toBe('')
+  })
+
+  test('handles string with no gaps', () => {
+    expect(getUngappedSequence('ACDEF')).toBe('ACDEF')
+  })
+})

package/src/msa/index.ts

@@ -0,0 +1,44 @@
+import A3mMSA from './A3mMSA'
+import ClustalMSA from './ClustalMSA'
+import EmfMSA from './EmfMSA'
+import FastaMSA from './FastaMSA'
+import StockholmMSA, { stockholmSniff } from './StockholmMSA'
+
+export { parseEmfTree } from 'emf-js'
+export { default as parseNewick } from './parseNewick'
+
+export type MSAParserType =
+  | StockholmMSA
+  | A3mMSA
+  | FastaMSA
+  | EmfMSA
+  | ClustalMSA
+
+export function parseMSA(text: string, currentAlignment = 0): MSAParserType {
+  if (stockholmSniff(text)) {
+    return new StockholmMSA(text, currentAlignment)
+  }
+  if (A3mMSA.sniff(text)) {
+    return new A3mMSA(text)
+  }
+  if (text.startsWith('>')) {
+    return new FastaMSA(text)
+  }
+  if (text.startsWith('SEQ')) {
+    return new EmfMSA(text)
+  }
+  return new ClustalMSA(text)
+}
+
+/**
+ * Get ungapped sequence from an aligned row
+ */
+export function getUngappedSequence(alignedSeq: string): string {
+  return alignedSeq.replaceAll(/[.-]/g, '')
+}
+
+export { default as A3mMSA } from './A3mMSA'
+export { default as ClustalMSA } from './ClustalMSA'
+export { default as EmfMSA } from './EmfMSA'
+export { default as FastaMSA } from './FastaMSA'
+export { default as StockholmMSA, stockholmSniff } from './StockholmMSA'

package/src/msa/parseNewick.ts

@@ -0,0 +1,94 @@
+/**
+ * Newick format parser in JavaScript.
+ *
+ * Copyright (c) Jason Davies 2010.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * Example tree (from http://en.wikipedia.org/wiki/Newick_format):
+ *
+ * +--0.1--A
+ * F-----0.2-----B            +-------0.3----C
+ * +------------------0.5-----E
+ *                            +---------0.4------D
+ *
+ * Newick format:
+ * (A:0.1,B:0.2,(C:0.3,D:0.4)E:0.5)F;
+ *
+ * Converted to JSON:
+ * {
+ *   name: "F",
+ *   children: [
+ *     {name: "A", length: 0.1},
+ *     {name: "B", length: 0.2},
+ *     {
+ *       name: "E",
+ *       length: 0.5,
+ *       children: [
+ *         {name: "C", length: 0.3},
+ *         {name: "D", length: 0.4}
+ *       ]
+ *     }
+ *   ]
+ * }
+ *
+ * Converted to JSON, but with no names or lengths:
+ * {
+ *   children: [
+ *     {}, {}, {
+ *       children: [{}, {}]
+ *     }
+ *   ]
+ * }
+ */
+export default function parse(s: string) {
+  const ancestors = []
+
+  let tree = {} as Record<string, any>
+  const tokens = s.split(/\s*(;|\(|\)|,|:)\s*/)
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!
+    const subtree = {}
+    switch (token) {
+      case '(': // new children
+        tree.children = [subtree]
+        ancestors.push(tree)
+        tree = subtree
+        break
+      case ',': // another branch
+        ancestors.at(-1)?.children.push(subtree)
+        tree = subtree
+        break
+      case ')': // optional name next
+        tree = ancestors.pop()!
+        break
+      case ':': // optional length next
+        break
+      default: {
+        const x = tokens[i - 1]!
+        if (x === ')' || x === '(' || x === ',') {
+          tree.name = token
+        } else if (x === ':') {
+          tree.length = Number.parseFloat(token)
+        }
+      }
+    }
+  }
+  return tree
+}

package/src/msa/stockholmParser.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from 'vitest'
+
+import { parse, parseAll, sniff } from './stockholmParser'
+
+describe('stockholmParser', () => {
+  describe('sniff', () => {
+    test('returns true for Stockholm format', () => {
+      expect(sniff('# STOCKHOLM 1.0\n')).toBe(true)
+    })
+
+    test('returns false for non-Stockholm format', () => {
+      expect(sniff('>seq1\nACDEF')).toBe(false)
+      expect(sniff('CLUSTAL W')).toBe(false)
+    })
+  })
+
+  describe('parseAll', () => {
+    test('parses simple Stockholm file', () => {
+      const stockholm = `# STOCKHOLM 1.0
+seq1  ACDEFGHIKL
+seq2  ACDEFGHIKL
+//`
+      const result = parseAll(stockholm)
+      expect(result).toHaveLength(1)
+      expect(result[0]?.seqdata).toEqual({
+        seq1: 'ACDEFGHIKL',
+        seq2: 'ACDEFGHIKL',
+      })
+      expect(result[0]?.seqname).toEqual(['seq1', 'seq2'])
+    })
+
+    test('parses GF lines', () => {
+      const stockholm = `# STOCKHOLM 1.0
+#=GF DE Description of the alignment
+#=GF NH (A:0.1,B:0.2);
+seq1  ACDEF
+//`
+      const result = parseAll(stockholm)
+      expect(result[0]?.gf.DE).toEqual(['Description of the alignment'])
+      expect(result[0]?.gf.NH).toEqual(['(A:0.1,B:0.2);'])
+    })
+
+    test('parses GC lines', () => {
+      const stockholm = `# STOCKHOLM 1.0
+seq1          ACDEF
+#=GC seq_cons *****
+#=GC SS_cons  <<>>>
+//`
+      const result = parseAll(stockholm)
+      expect(result[0]?.gc.seq_cons).toBe('*****')
+      expect(result[0]?.gc.SS_cons).toBe('<<>>>')
+    })
+
+    test('parses GS lines', () => {
+      const stockholm = `# STOCKHOLM 1.0
+#=GS seq1 AC P12345
+#=GS seq1 DR PDB; 1ABC A; 1-100
+seq1  ACDEF
+//`
+      const result = parseAll(stockholm)
+      expect(result[0]?.gs.AC?.seq1).toEqual(['P12345'])
+      expect(result[0]?.gs.DR?.seq1).toEqual(['PDB; 1ABC A; 1-100'])
+    })
+
+    test('parses multiple alignments', () => {
+      const stockholm = `# STOCKHOLM 1.0
+seq1  ACDEF
+//
+# STOCKHOLM 1.0
+seq2  GHIKL
+//`
+      const result = parseAll(stockholm)
+      expect(result).toHaveLength(2)
+      expect(result[0]?.seqdata.seq1).toBe('ACDEF')
+      expect(result[1]?.seqdata.seq2).toBe('GHIKL')
+    })
+
+    test('concatenates interleaved sequence blocks', () => {
+      const stockholm = `# STOCKHOLM 1.0
+seq1  ACDEF
+seq2  GHIKL
+
+seq1  MNOPQ
+seq2  RSTUV
+//`
+      const result = parseAll(stockholm)
+      expect(result[0]?.seqdata.seq1).toBe('ACDEFMNOPQ')
+      expect(result[0]?.seqdata.seq2).toBe('GHIKLRSTUV')
+    })
+
+    test('handles file without trailing //', () => {
+      const stockholm = `# STOCKHOLM 1.0
+seq1  ACDEF`
+      const result = parseAll(stockholm)
+      expect(result).toHaveLength(1)
+      expect(result[0]?.seqdata.seq1).toBe('ACDEF')
+    })
+  })
+
+  describe('parse', () => {
+    test('returns single alignment', () => {
+      const stockholm = `# STOCKHOLM 1.0
+seq1  ACDEF
+//`
+      const result = parse(stockholm)
+      expect(result.seqdata.seq1).toBe('ACDEF')
+    })
+
+    test('throws on empty input', () => {
+      expect(() => parse('')).toThrow('No alignments found')
+    })
+
+    test('throws on multiple alignments', () => {
+      const stockholm = `# STOCKHOLM 1.0
+seq1  ACDEF
+//
+# STOCKHOLM 1.0
+seq2  GHIKL
+//`
+      expect(() => parse(stockholm)).toThrow('More than one alignment found')
+    })
+  })
+})

package/src/msa/stockholmParser.ts

@@ -0,0 +1,157 @@
+/**
+ * Stockholm format parser
+ * Based on stockholm-js by Ian Holmes
+ * Rewritten in TypeScript
+ */
+
+export interface StockholmData {
+  gf: Record<string, string[]>
+  gc: Record<string, string>
+  gs: Record<string, Record<string, string[]>>
+  gr: Record<string, Record<string, string>>
+  seqname: string[]
+  seqdata: Record<string, string>
+}
+
+function createStockholm(): StockholmData {
+  return {
+    gf: {},
+    gc: {},
+    gs: {},
+    gr: {},
+    seqname: [],
+    seqdata: {},
+  }
+}
+
+const formatStartRegex = /^# STOCKHOLM 1.0/
+const formatEndRegex = /^\/\/\s*$/
+const gfRegex = /^#=GF\s+(\S+)\s+(.*?)\s*$/
+const gcRegex = /^#=GC\s+(\S+)\s+(.*?)\s*$/
+const gsRegex = /^#=GS\s+(\S+)\s+(\S+)\s+(.*?)\s*$/
+const grRegex = /^#=GR\s+(\S+)\s+(\S+)\s+(.*?)\s*$/
+const lineRegex = /^\s*(\S+)\s+(\S+)\s*$/
+const nonwhiteRegex = /\S/
+
+export function sniff(text: string): boolean {
+  return formatStartRegex.test(text)
+}
+
+export function parseAll(
+  text: string,
+  opts?: { strict?: boolean; quiet?: boolean },
+): StockholmData[] {
+  const options = opts ?? {}
+  const db: StockholmData[] = []
+  let stock: StockholmData | null = null
+
+  const lines = text.split('\n')
+  for (const line of lines) {
+    let match: RegExpExecArray | null
+
+    if (formatStartRegex.test(line)) {
+      stock = createStockholm()
+    } else if (formatEndRegex.test(line)) {
+      if (stock) {
+        db.push(stock)
+      }
+      stock = null
+    } else if ((match = gfRegex.exec(line))) {
+      if (!stock) {
+        if (options.strict) {
+          throw new Error('No format header: # STOCKHOLM 1.0')
+        }
+        stock = createStockholm()
+      }
+      const tag = match[1]!
+      if (!stock.gf[tag]) {
+        stock.gf[tag] = []
+      }
+      stock.gf[tag].push(match[2]!)
+    } else if ((match = gcRegex.exec(line))) {
+      if (!stock) {
+        if (options.strict) {
+          throw new Error('No format header: # STOCKHOLM 1.0')
+        }
+        stock = createStockholm()
+      }
+      const tag = match[1]!
+      if (!stock.gc[tag]) {
+        stock.gc[tag] = ''
+      }
+      stock.gc[tag] += match[2]!
+    } else if ((match = gsRegex.exec(line))) {
+      if (!stock) {
+        if (options.strict) {
+          throw new Error('No format header: # STOCKHOLM 1.0')
+        }
+        stock = createStockholm()
+      }
+      const seqname = match[1]!
+      const tag = match[2]!
+      const value = match[3]!
+      if (!stock.gs[tag]) {
+        stock.gs[tag] = {}
+      }
+      if (!stock.gs[tag][seqname]) {
+        stock.gs[tag][seqname] = []
+      }
+      stock.gs[tag][seqname].push(value)
+    } else if ((match = grRegex.exec(line))) {
+      if (!stock) {
+        if (options.strict) {
+          throw new Error('No format header: # STOCKHOLM 1.0')
+        }
+        stock = createStockholm()
+      }
+      const seqname = match[1]!
+      const tag = match[2]!
+      const value = match[3]!
+      if (!stock.gr[tag]) {
+        stock.gr[tag] = {}
+      }
+      if (!stock.gr[tag][seqname]) {
+        stock.gr[tag][seqname] = ''
+      }
+      stock.gr[tag][seqname] += value
+    } else if ((match = lineRegex.exec(line))) {
+      if (!stock) {
+        if (options.strict) {
+          throw new Error('No format header: # STOCKHOLM 1.0')
+        }
+        stock = createStockholm()
+      }
+      const seqname = match[1]!
+      const seqdata = match[2]!
+      if (!stock.seqdata[seqname]) {
+        stock.seqdata[seqname] = ''
+        stock.seqname.push(seqname)
+      }
+      stock.seqdata[seqname] += seqdata
+    } else if (nonwhiteRegex.test(line)) {
+      if (options.strict) {
+        throw new Error('Malformed line')
+      }
+    }
+  }
+
+  if (stock) {
+    db.push(stock)
+  }
+
+  return db
+}
+
+export function parse(
+  text: string,
+  opts?: { strict?: boolean; quiet?: boolean },
+): StockholmData {
+  const db = parseAll(text, opts)
+  if (db.length === 0) {
+    throw new Error('No alignments found')
+  }
+  if (db.length > 1) {
+    throw new Error('More than one alignment found')
+  }
+  return db[0]!
+}