msa-parsers 1.0.3

package/src/gff/parseGFF.ts

@@ -0,0 +1,46 @@
+import type { GFFRecord } from '../types'
+
+function parseAttributes(col9?: string): Record<string, string | undefined> {
+  if (!col9) {
+    return {}
+  }
+  return Object.fromEntries(
+    col9
+      .split(';')
+      .map(f => f.trim())
+      .filter(f => !!f)
+      .map(f => f.split('='))
+      .map(([key, val]) => [
+        key?.trim() ?? '',
+        val ? decodeURIComponent(val).trim().split(',').join(' ') : undefined,
+      ])
+      .filter(([key]) => key !== ''),
+  )
+}
+
+export function parseGFF(str?: string): GFFRecord[] {
+  if (!str) {
+    return []
+  }
+  return str
+    .split('\n')
+    .map(f => f.trim())
+    .filter(f => !!f && !f.startsWith('#'))
+    .map(f => {
+      const parts = f.split('\t')
+      const [seq_id, source, type, start, end, score, strand, phase] = parts
+      const col9 = parts[8]
+
+      return {
+        seq_id: seq_id ?? '',
+        source: source ?? '',
+        type: type ?? '',
+        start: Number(start) || 0,
+        end: Number(end) || 0,
+        score: Number(score) || 0,
+        strand: strand ?? '.',
+        phase: phase ?? '.',
+        ...parseAttributes(col9),
+      }
+    })
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// Types
+export * from './types'
+
+// Utilities
+export { generateNodeIds } from './util'
+
+// MSA parsers
+export {
+  A3mMSA,
+  ClustalMSA,
+  EmfMSA,
+  FastaMSA,
+  StockholmMSA,
+  getUngappedSequence,
+  parseEmfTree,
+  parseMSA,
+  parseNewick,
+  stockholmSniff,
+} from './msa'
+export type { MSAParserType } from './msa'
+
+// GFF parsing
+export {
+  gffToInterProResponse,
+  gffToInterProResults,
+  interProResponseToGFF,
+  interProToGFF,
+  parseGFF,
+} from './gff'

package/src/msa/A3mMSA.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test } from 'vitest'
+
+import A3mMSA from './A3mMSA'
+
+describe('A3mMSA', () => {
+  describe('sniff', () => {
+    test('returns false for non-FASTA text', () => {
+      expect(A3mMSA.sniff('not fasta')).toBe(false)
+      expect(A3mMSA.sniff('CLUSTAL W')).toBe(false)
+    })
+
+    test('returns false for regular FASTA', () => {
+      const fasta = `>seq1
+ACDEFGHIKLMNPQRSTVWY
+>seq2
+ACDEFGHIKLMNPQRSTVWY`
+      expect(A3mMSA.sniff(fasta)).toBe(false)
+    })
+
+    test('returns true for A3M format', () => {
+      const a3m = `>seq1
+ACDEFghiKLMNPQ
+>seq2
+ACDEF---KLMNPQ`
+      expect(A3mMSA.sniff(a3m)).toBe(true)
+    })
+
+    test('returns false for single sequence', () => {
+      const a3m = `>seq1
+ACDEFghiKLMNPQ`
+      expect(A3mMSA.sniff(a3m)).toBe(false)
+    })
+  })
+
+  describe('parsing', () => {
+    test('parses simple A3M', () => {
+      const a3m = `>seq1
+ACDEFghiKLMNPQ
+>seq2
+ACDEF---KLMNPQ`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.getNames()).toEqual(['seq1', 'seq2'])
+      const seq1 = msa.getRow('seq1')
+      const seq2 = msa.getRow('seq2')
+
+      expect(seq1.length).toBe(seq2.length)
+      expect(seq1).toContain('GHI')
+    })
+
+    test('expands lowercase insertions', () => {
+      const a3m = `>seq1
+ACabc
+>seq2
+AC---`
+      const msa = new A3mMSA(a3m)
+
+      const seq1 = msa.getRow('seq1')
+      const seq2 = msa.getRow('seq2')
+
+      expect(seq1).toBe('ACABC')
+      expect(seq2).toBe('AC...')
+    })
+
+    test('handles multiple insertions', () => {
+      const a3m = `>seq1
+AabcDdefG
+>seq2
+A---D---G`
+      const msa = new A3mMSA(a3m)
+
+      const seq1 = msa.getRow('seq1')
+      const seq2 = msa.getRow('seq2')
+
+      expect(seq1.length).toBe(seq2.length)
+    })
+
+    test('getWidth returns correct width', () => {
+      const a3m = `>seq1
+ACDEF
+>seq2
+ACDEF`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.getWidth()).toBe(5)
+    })
+
+    test('getMSA returns seqdata', () => {
+      const a3m = `>seq1
+ACDEF
+>seq2
+GHIKL`
+      const msa = new A3mMSA(a3m)
+      const data = msa.getMSA()
+
+      expect(data.seqdata).toHaveProperty('seq1')
+      expect(data.seqdata).toHaveProperty('seq2')
+    })
+
+    test('getTree returns noTree structure', () => {
+      const a3m = `>seq1
+ACDEF
+>seq2
+GHIKL`
+      const msa = new A3mMSA(a3m)
+      const tree = msa.getTree()
+
+      expect(tree.noTree).toBe(true)
+      expect(tree.children).toHaveLength(2)
+    })
+
+    test('handles empty sequences', () => {
+      const a3m = `>seq1
+ACDEF`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.getNames()).toEqual(['seq1'])
+    })
+
+    test('handles sequences with only ID on defline', () => {
+      const a3m = `>seq1 description here
+ACDEF
+>seq2 another description
+GHIKL`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.getNames()).toEqual(['seq1', 'seq2'])
+    })
+
+    test('preserves sequence order', () => {
+      const a3m = `>z_seq
+AAAAA
+>a_seq
+CCCCC
+>m_seq
+DDDDD`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.getNames()).toEqual(['z_seq', 'a_seq', 'm_seq'])
+    })
+  })
+
+  describe('properties', () => {
+    test('alignmentNames is empty array', () => {
+      const a3m = `>seq1
+ACDEF`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.alignmentNames).toEqual([])
+    })
+
+    test('seqConsensus is undefined', () => {
+      const a3m = `>seq1
+ACDEF`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.seqConsensus).toBeUndefined()
+    })
+
+    test('secondaryStructureConsensus is undefined', () => {
+      const a3m = `>seq1
+ACDEF`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.secondaryStructureConsensus).toBeUndefined()
+    })
+
+    test('tracks is empty array', () => {
+      const a3m = `>seq1
+ACDEF`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.tracks).toEqual([])
+    })
+
+    test('getStructures returns empty object', () => {
+      const a3m = `>seq1
+ACDEF`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.getStructures()).toEqual({})
+    })
+
+    test('getHeader returns empty object', () => {
+      const a3m = `>seq1
+ACDEF`
+      const msa = new A3mMSA(a3m)
+
+      expect(msa.getHeader()).toEqual({})
+    })
+  })
+})

package/src/msa/A3mMSA.ts

@@ -0,0 +1,320 @@
+import type { NodeWithIds } from '../types'
+
+/**
+ * A3M Format Parser
+ *
+ * The A3M format consists of aligned FASTA, in which alignments are shown with:
+ * - Inserts as lowercase characters
+ * - Matches as uppercase characters
+ * - Deletions as '-'
+ * - Gaps aligned to inserts as '.'
+ *
+ * Note that gaps aligned to inserts can be omitted in the A3M format.
+ *
+ * Example:
+ * >query
+ * ETESMKTVRIREKIKKFLGDRPRNTAEILEHINSTMRHGTTSQQLGNVLSKDKDIVKVGYIKRSGILSGGYDICEWATRNWVAEHCPEWTE
+ * >seq1
+ * ----MRTTRLRQKIKKFLNERGeANTTEILEHVNSTMRHGTTPQQLGNVLSKDKDILKVATTKRGGALSGRYEICVWTLRP-----------
+ *
+ * In the above, 'e' after 'G' in seq1 is a lowercase insert.
+ *
+ * @see https://yanglab.qd.sdu.edu.cn/trRosetta/msa_format.html
+ */
+
+// Char code helpers for fast character classification
+const CODE_A = 65 // 'A'
+const CODE_Z = 90 // 'Z'
+const CODE_a = 97 // 'a'
+const CODE_z = 122 // 'z'
+const CODE_DASH = 45 // '-'
+const CODE_DOT = 46 // '.'
+
+function isLower(code: number): boolean {
+  return code >= CODE_a && code <= CODE_z
+}
+
+export default class A3mMSA {
+  private MSA: { seqdata: Record<string, string> }
+  private orderedNames: string[]
+
+  constructor(text: string) {
+    const rawSeqs: string[] = []
+    const names: string[] = []
+
+    // First pass: parse sequences (like FASTA), preserving order
+    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) {
+        rawSeqs.push(entry.slice(newlineIdx + 1).replaceAll(/\s/g, ''))
+        names.push(id)
+      }
+    }
+
+    this.orderedNames = names
+    this.MSA = { seqdata: this.expandA3M(rawSeqs, names) }
+  }
+
+  /**
+   * Detect if text is likely A3M format
+   */
+  static sniff(text: string): boolean {
+    if (!text.startsWith('>')) {
+      return false
+    }
+
+    const seqs: string[] = []
+    for (const entry of text.split('>')) {
+      if (!/\S/.test(entry)) {
+        continue
+      }
+      const newlineIdx = entry.indexOf('\n')
+      if (newlineIdx === -1) {
+        continue
+      }
+      const seq = entry.slice(newlineIdx + 1).replaceAll(/\s/g, '')
+      if (seq) {
+        seqs.push(seq)
+      }
+    }
+
+    if (seqs.length < 2) {
+      return false
+    }
+
+    // Check for lowercase and compute lengths in single pass per sequence
+    // In A3M, only uppercase letters are match columns (not gaps)
+    let hasLowercase = false
+    let firstUppercaseLen = -1
+    let sameUppercaseLength = true
+
+    for (const seq of seqs) {
+      let uppercaseLen = 0
+      for (let i = 0; i < seq.length; i++) {
+        const code = seq.charCodeAt(i)
+        if (isLower(code)) {
+          hasLowercase = true
+        } else if (code >= CODE_A && code <= CODE_Z) {
+          uppercaseLen++
+        }
+      }
+
+      if (firstUppercaseLen === -1) {
+        firstUppercaseLen = uppercaseLen
+      } else {
+        if (uppercaseLen !== firstUppercaseLen) {
+          sameUppercaseLength = false
+        }
+      }
+    }
+
+    return hasLowercase && sameUppercaseLength
+  }
+
+  /**
+   * Expand A3M format to standard aligned format.
+   *
+   * In A3M, lowercase characters are insertions that implicitly introduce
+   * gaps in sequences that don't have an insert at that position.
+   * Gaps (-) following match columns in sequences without inserts align
+   * with lowercase inserts in other sequences.
+   */
+  private expandA3M(
+    rawSeqs: string[],
+    names: string[],
+  ): Record<string, string> {
+    const numSeqs = names.length
+    if (numSeqs === 0) {
+      return {}
+    }
+
+    // Parse sequences: extract match chars (uppercase only) and insert content
+    // For each sequence, track: matchChars, insertContent (after each match)
+    const matchChars: string[][] = []
+    const insertContent: string[][] = []
+
+    for (let seqIdx = 0; seqIdx < numSeqs; seqIdx++) {
+      const seq = rawSeqs[seqIdx]!
+      const matches: string[] = []
+      const inserts: string[] = []
+      let i = 0
+
+      while (i < seq.length) {
+        const code = seq.charCodeAt(i)
+
+        if (code >= CODE_A && code <= CODE_Z) {
+          // Uppercase letter - match column
+          matches.push(seq[i]!)
+          // Collect following lowercase/gap characters as insert content
+          let ins = ''
+          let j = i + 1
+          while (j < seq.length) {
+            const c = seq.charCodeAt(j)
+            if (isLower(c) || c === CODE_DASH || c === CODE_DOT) {
+              ins += seq[j]!
+              j++
+            } else {
+              break
+            }
+          }
+          inserts.push(ins)
+          i = j
+        } else if (code === CODE_DASH || code === CODE_DOT) {
+          // Leading gap before first match - skip
+          i++
+        } else if (isLower(code)) {
+          // Leading insert before first match
+          let ins = ''
+          while (i < seq.length && isLower(seq.charCodeAt(i))) {
+            ins += seq[i]!
+            i++
+          }
+          // Add empty match with this insert
+          matches.push('')
+          inserts.push(ins)
+        } else {
+          i++
+        }
+      }
+
+      matchChars.push(matches)
+      insertContent.push(inserts)
+    }
+
+    // Find number of match positions (should be same for all valid A3M)
+    const numPositions = Math.max(...matchChars.map(m => m.length), 0)
+
+    // Find max insert length at each position (only count lowercase, not gaps)
+    const maxInserts = new Array<number>(numPositions).fill(0)
+    for (let seqIdx = 0; seqIdx < numSeqs; seqIdx++) {
+      const inserts = insertContent[seqIdx]!
+      for (let pos = 0; pos < inserts.length; pos++) {
+        // Count only lowercase characters as actual inserts
+        let lcCount = 0
+        for (const c of inserts[pos]!) {
+          if (isLower(c.charCodeAt(0))) {
+            lcCount++
+          }
+        }
+        if (lcCount > maxInserts[pos]!) {
+          maxInserts[pos] = lcCount
+        }
+      }
+    }
+
+    // Build expanded sequences
+    const expanded: Record<string, string> = {}
+
+    for (let seqIdx = 0; seqIdx < numSeqs; seqIdx++) {
+      const matches = matchChars[seqIdx]!
+      const inserts = insertContent[seqIdx]!
+      const result: string[] = []
+
+      for (let pos = 0; pos < numPositions; pos++) {
+        const maxIns = maxInserts[pos]!
+
+        if (pos < matches.length) {
+          const matchChar = matches[pos]!
+          const insContent = inserts[pos] || ''
+
+          // Add match character (or gap if empty)
+          result.push(matchChar || '-')
+
+          // Process insert content
+          let lcContent = ''
+          for (const c of insContent) {
+            if (isLower(c.charCodeAt(0))) {
+              lcContent += c.toUpperCase()
+            }
+          }
+
+          // Add the insert content (uppercased)
+          result.push(lcContent)
+
+          // Pad with gaps to match max insert length
+          const padding = maxIns - lcContent.length
+          if (padding > 0) {
+            result.push('.'.repeat(padding))
+          }
+        } else {
+          // This sequence is shorter - add gaps
+          result.push('-')
+          if (maxIns > 0) {
+            result.push('.'.repeat(maxIns))
+          }
+        }
+      }
+
+      expanded[names[seqIdx]!] = result.join('')
+    }
+
+    return expanded
+  }
+
+  getMSA() {
+    return this.MSA
+  }
+
+  getRowData() {
+    return undefined
+  }
+
+  getNames() {
+    return this.orderedNames
+  }
+
+  getRow(name: string) {
+    return this.MSA.seqdata[name] || ''
+  }
+
+  getWidth() {
+    const name = Object.keys(this.MSA.seqdata)[0]
+    return name ? this.getRow(name).length : 0
+  }
+
+  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/ClustalMSA.ts

@@ -0,0 +1,67 @@
+import { parse } from 'clustal-js'
+
+import type { NodeWithIds } from '../types'
+
+export default class ClustalMSA {
+  private MSA: ReturnType<typeof parse>
+
+  constructor(text: string) {
+    this.MSA = parse(text)
+  }
+
+  getMSA() {
+    return this.MSA
+  }
+
+  getRow(name: string): string {
+    return this.MSA.alns.find(aln => aln.id === name)?.seq || ''
+  }
+
+  getWidth() {
+    return this.MSA.alns[0]!.seq.length
+  }
+
+  getRowData() {
+    return undefined
+  }
+
+  getHeader() {
+    return this.MSA.header
+  }
+
+  getNames() {
+    return this.MSA.alns.map(aln => aln.id)
+  }
+
+  getStructures() {
+    return {}
+  }
+
+  get alignmentNames() {
+    return []
+  }
+
+  getTree(): NodeWithIds {
+    return {
+      id: 'root',
+      name: 'root',
+      noTree: true,
+      children: this.getNames().map(name => ({
+        id: name,
+        name,
+        children: [],
+      })),
+    }
+  }
+
+  get seqConsensus() {
+    return this.MSA.consensus
+  }
+  get secondaryStructureConsensus() {
+    return undefined
+  }
+
+  get tracks() {
+    return []
+  }
+}

package/src/msa/EmfMSA.ts

@@ -0,0 +1,67 @@
+import { parseEmfAln } from 'emf-js'
+
+import type { NodeWithIds } from '../types'
+
+export default class EmfMSA {
+  private MSA: ReturnType<typeof parseEmfAln>
+
+  constructor(text: string) {
+    this.MSA = parseEmfAln(text)
+  }
+
+  getMSA() {
+    return this.MSA
+  }
+
+  getRow(name: string): string {
+    return this.MSA.find(aln => aln.protein === name)?.seq || ''
+  }
+
+  getWidth() {
+    return this.MSA[0]!.seq.length
+  }
+
+  getRowData() {
+    return undefined
+  }
+
+  getHeader() {
+    return ''
+  }
+
+  getNames() {
+    return this.MSA.map(aln => aln.protein)
+  }
+
+  getStructures() {
+    return {}
+  }
+
+  get alignmentNames() {
+    return []
+  }
+
+  getTree(): NodeWithIds {
+    return {
+      id: 'root',
+      name: 'root',
+      noTree: true,
+      children: this.getNames().map(name => ({
+        id: name,
+        name,
+        children: [],
+      })),
+    }
+  }
+
+  get seqConsensus() {
+    return undefined
+  }
+  get secondaryStructureConsensus() {
+    return undefined
+  }
+
+  get tracks() {
+    return []
+  }
+}