react-msaview-cli 1.0.0

package/README.md

@@ -0,0 +1,178 @@
+# @react-msaview/cli
+
+Command-line tools for [react-msaview](../) (JBrowseMSA), including batch
+InterProScan processing for multiple sequence alignments.
+
+Uses [msa-parsers](../msa-parsers/) for file format support.
+
+## Installation
+
+```bash
+# From the monorepo root
+yarn install
+yarn workspace @react-msaview/cli build
+
+# Or install globally (after publishing)
+npm install -g @react-msaview/cli
+```
+
+## Commands
+
+### interproscan
+
+Run InterProScan on all sequences in an MSA file and output results as GFF3.
+
+```bash
+react-msaview-cli interproscan <input-msa> [options]
+```
+
+#### Options
+
+| Option                       | Description                                            | Default            |
+| ---------------------------- | ------------------------------------------------------ | ------------------ |
+| `-o, --output <file>`        | Output GFF file path                                   | `domains.gff`      |
+| `--local`                    | Use local InterProScan installation instead of EBI API | `false`            |
+| `--interproscan-path <path>` | Path to local interproscan.sh                          | `interproscan.sh`  |
+| `--programs <list>`          | Comma-separated list of InterProScan programs          | `Pfam`             |
+| `--email <email>`            | Email for EBI API (required for EBI API usage)         | `user@example.com` |
+| `--batch-size <n>`           | Number of sequences per API batch                      | `30`               |
+| `-h, --help`                 | Show help message                                      |                    |
+
+#### Supported MSA Formats
+
+The CLI automatically detects the input format:
+
+- **FASTA** (`.fasta`, `.fa`, `.faa`)
+- **Clustal** (`.clustal`, `.aln`)
+- **Stockholm** (`.sto`, `.stockholm`)
+- **A3M** (`.a3m`) - AlphaFold/ColabFold format
+- **EMF** (`.emf`) - Ensembl Multi Format
+
+#### Available InterProScan Programs
+
+When using `--programs`, you can specify any combination of:
+
+- `Pfam` - Protein families (default)
+- `SMART` - Simple Modular Architecture Research Tool
+- `SUPERFAMILY` - Structural and functional annotation
+- `Gene3D` - Structural domain assignments
+- `CDD` - Conserved Domain Database
+- `PANTHER` - Protein Analysis Through Evolutionary Relationships
+- `TIGRFAM` - TIGR protein families
+- `Hamap` - High-quality Automated Annotation of Microbial Proteomes
+- `ProSiteProfiles` - PROSITE profiles
+- `ProSitePatterns` - PROSITE patterns
+- `PRINTS` - Protein fingerprints
+- `PIRSF` - PIR SuperFamily
+- `MobiDBLite` - Disorder prediction
+
+## Examples
+
+### Using EBI API (recommended for small datasets)
+
+```bash
+# Basic usage - runs Pfam analysis
+react-msaview-cli interproscan alignment.fasta -o domains.gff --email your@email.com
+
+# Multiple programs
+react-msaview-cli interproscan alignment.fasta -o domains.gff \
+  --programs Pfam,SMART,Gene3D \
+  --email your@email.com
+
+# Smaller batch size for large sequences
+react-msaview-cli interproscan large_proteins.fasta -o domains.gff \
+  --batch-size 10 \
+  --email your@email.com
+```
+
+### Using Local InterProScan
+
+For large datasets or frequent usage, install InterProScan locally:
+
+```bash
+# With interproscan.sh in PATH
+react-msaview-cli interproscan alignment.fasta -o domains.gff --local
+
+# With custom path
+react-msaview-cli interproscan alignment.fasta -o domains.gff \
+  --local \
+  --interproscan-path /opt/interproscan/interproscan.sh
+
+# With specific programs
+react-msaview-cli interproscan alignment.fasta -o domains.gff \
+  --local \
+  --programs Pfam,SMART
+```
+
+### Different Input Formats
+
+```bash
+# Clustal format
+react-msaview-cli interproscan alignment.clustal -o domains.gff
+
+# Stockholm format
+react-msaview-cli interproscan PF00001.stockholm -o domains.gff
+
+# A3M format (from ColabFold/AlphaFold)
+react-msaview-cli interproscan colabfold.a3m -o domains.gff
+```
+
+## Output Format
+
+The output is standard GFF3 format compatible with react-msaview:
+
+```gff
+##gff-version 3
+seq1	InterProScan	protein_match	10	150	.	.	.	Name=PF00001;signature_desc=7tm_1;description=7 transmembrane receptor (rhodopsin family)
+seq1	InterProScan	protein_match	200	350	.	.	.	Name=PF00002;signature_desc=7tm_2;description=7 transmembrane receptor (Secretin family)
+seq2	InterProScan	protein_match	5	120	.	.	.	Name=PF00001;signature_desc=7tm_1;description=7 transmembrane receptor (rhodopsin family)
+```
+
+## Loading Results in react-msaview
+
+After generating the GFF file, you can load it in react-msaview:
+
+1. Open your MSA file in react-msaview
+2. Go to **Menu > Open domains...**
+3. Select the generated GFF file
+4. Domains will appear as colored boxes on the alignment
+
+## Troubleshooting
+
+### EBI API Timeout
+
+If you get timeout errors with the EBI API:
+
+- Reduce `--batch-size` (try 10-20 for large proteins)
+- Use `--local` with a local InterProScan installation
+- Check your internet connection
+
+### Local InterProScan Not Found
+
+```
+Error: Failed to run InterProScan: spawn interproscan.sh ENOENT
+```
+
+Make sure InterProScan is installed and specify the full path:
+
+```bash
+--interproscan-path /full/path/to/interproscan-5.xx/interproscan.sh
+```
+
+### No Results in Output
+
+- Check that your sequences are protein sequences (not nucleotide)
+- Try different programs (some may not have hits for your sequences)
+- Verify the input file is valid MSA format
+
+## API Rate Limits
+
+The EBI InterProScan API has usage limits:
+
+- Maximum ~30 sequences per request (configurable via `--batch-size`)
+- Requests are processed sequentially to avoid overwhelming the server
+- For large datasets (>100 sequences), consider using local InterProScan
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "react-msaview-cli",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "react-msaview-cli": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "msa-parsers": "workspace:*"
+  }
+}

package/src/ebi-api.ts

@@ -0,0 +1,112 @@
+import type { InterProScanResults } from 'msa-parsers'
+
+const BASE_URL = 'https://www.ebi.ac.uk/Tools/services/rest/iprscan5'
+
+interface InterProScanResponse {
+  results: InterProScanResults[]
+}
+
+async function submitJob(
+  sequences: { id: string; seq: string }[],
+  programs: string[],
+  email: string,
+): Promise<string> {
+  const fastaSeq = sequences.map(s => `>${s.id}\n${s.seq}`).join('\n')
+
+  const response = await fetch(`${BASE_URL}/run`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: new URLSearchParams({
+      email,
+      sequence: fastaSeq,
+      appl: programs.join(','),
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to submit job: ${response.statusText}`)
+  }
+
+  return response.text()
+}
+
+async function checkStatus(jobId: string): Promise<string> {
+  const response = await fetch(`${BASE_URL}/status/${jobId}`)
+  if (!response.ok) {
+    throw new Error(`Failed to check status: ${response.statusText}`)
+  }
+  return response.text()
+}
+
+async function getResults(jobId: string): Promise<InterProScanResponse> {
+  const response = await fetch(`${BASE_URL}/result/${jobId}/json`)
+  if (!response.ok) {
+    throw new Error(`Failed to get results: ${response.statusText}`)
+  }
+  return response.json() as Promise<InterProScanResponse>
+}
+
+async function waitForJob(jobId: string): Promise<void> {
+  console.log(`  Waiting for job ${jobId}...`)
+  let attempts = 0
+  const maxAttempts = 300 // 5 minutes max wait
+
+  while (attempts < maxAttempts) {
+    const status = await checkStatus(jobId)
+
+    if (status.includes('FINISHED')) {
+      return
+    }
+    if (status.includes('FAILURE') || status.includes('ERROR')) {
+      throw new Error(`Job ${jobId} failed: ${status}`)
+    }
+
+    await new Promise(resolve => setTimeout(resolve, 1000))
+    attempts++
+
+    if (attempts % 10 === 0) {
+      console.log(`  Still waiting... (${attempts}s)`)
+    }
+  }
+
+  throw new Error(`Timeout waiting for job ${jobId}`)
+}
+
+export async function runEbiInterProScan(
+  sequences: { id: string; seq: string }[],
+  programs: string[],
+  email: string,
+  batchSize: number,
+): Promise<InterProScanResults[]> {
+  const allResults: InterProScanResults[] = []
+  const batches: { id: string; seq: string }[][] = []
+
+  for (let i = 0; i < sequences.length; i += batchSize) {
+    batches.push(sequences.slice(i, i + batchSize))
+  }
+
+  console.log(`  Submitting ${batches.length} batch(es)...`)
+
+  for (let i = 0; i < batches.length; i++) {
+    const batch = batches[i]!
+    console.log(
+      `  Processing batch ${i + 1}/${batches.length} (${batch.length} sequences)...`,
+    )
+
+    const jobId = await submitJob(batch, programs, email)
+    console.log(`  Job submitted: ${jobId}`)
+
+    await waitForJob(jobId)
+
+    const results = await getResults(jobId)
+    for (const r of results.results) {
+      allResults.push(r)
+    }
+
+    console.log(`  Batch ${i + 1} complete`)
+  }
+
+  return allResults
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util'
+
+import { runInterProScan } from './interproscan-msa'
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    output: {
+      type: 'string',
+      short: 'o',
+      default: 'domains.gff',
+    },
+    local: {
+      type: 'boolean',
+      default: false,
+    },
+    'interproscan-path': {
+      type: 'string',
+      default: 'interproscan.sh',
+    },
+    programs: {
+      type: 'string',
+      default: 'Pfam',
+    },
+    email: {
+      type: 'string',
+      default: 'user@example.com',
+    },
+    'batch-size': {
+      type: 'string',
+      default: '30',
+    },
+    help: {
+      type: 'boolean',
+      short: 'h',
+      default: false,
+    },
+  },
+})
+
+function printHelp() {
+  console.log(`
+react-msaview-cli - CLI tools for react-msaview
+
+USAGE:
+  react-msaview-cli interproscan <input-msa> [options]
+
+COMMANDS:
+  interproscan    Run InterProScan on all sequences in an MSA file
+
+OPTIONS:
+  -o, --output <file>           Output GFF file (default: domains.gff)
+  --local                       Use local InterProScan installation
+  --interproscan-path <path>    Path to interproscan.sh (default: interproscan.sh)
+  --programs <list>             Comma-separated list of programs (default: Pfam)
+  --email <email>               Email for EBI API (default: user@example.com)
+  --batch-size <n>              Number of sequences per API batch (default: 30)
+  -h, --help                    Show this help message
+
+EXAMPLES:
+  # Run InterProScan using EBI API
+  react-msaview-cli interproscan alignment.fasta -o domains.gff
+
+  # Run with local InterProScan
+  react-msaview-cli interproscan alignment.fasta -o domains.gff --local
+
+  # Specify programs
+  react-msaview-cli interproscan alignment.clustal -o domains.gff --programs Pfam,SMART
+`)
+}
+
+async function main() {
+  if (values.help || positionals.length === 0) {
+    printHelp()
+    process.exit(0)
+  }
+
+  const command = positionals[0]
+
+  if (command === 'interproscan') {
+    const inputFile = positionals[1]
+    if (!inputFile) {
+      console.error('Error: Input MSA file is required')
+      process.exit(1)
+    }
+
+    await runInterProScan({
+      inputFile,
+      outputFile: values.output,
+      useLocal: values.local,
+      interproscanPath: values['interproscan-path'],
+      programs: values.programs.split(','),
+      email: values.email,
+      batchSize: Number.parseInt(values['batch-size'], 10),
+    })
+  } else {
+    console.error(`Unknown command: ${command}`)
+    printHelp()
+    process.exit(1)
+  }
+}
+
+main().catch((error: unknown) => {
+  console.error('Error:', error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/src/interproscan-msa.ts

@@ -0,0 +1,74 @@
+import * as fs from 'node:fs'
+
+import {
+  getUngappedSequence,
+  interProResponseToGFF,
+  parseMSA,
+} from 'msa-parsers'
+
+import { runEbiInterProScan } from './ebi-api'
+import { runLocalInterProScan } from './local-runner'
+
+import type { InterProScanResults } from 'msa-parsers'
+
+export interface InterProScanOptions {
+  inputFile: string
+  outputFile: string
+  useLocal: boolean
+  interproscanPath: string
+  programs: string[]
+  email: string
+  batchSize: number
+}
+
+export async function runInterProScan(options: InterProScanOptions) {
+  const {
+    inputFile,
+    outputFile,
+    useLocal,
+    interproscanPath,
+    programs,
+    email,
+    batchSize,
+  } = options
+
+  console.log(`Reading MSA from ${inputFile}...`)
+  const msaText = fs.readFileSync(inputFile, 'utf8')
+  const msa = parseMSA(msaText)
+
+  const names = msa.getNames()
+  console.log(`Found ${names.length} sequences`)
+
+  const sequences: { id: string; seq: string }[] = []
+  for (const name of names) {
+    const alignedSeq = msa.getRow(name)
+    const ungappedSeq = getUngappedSequence(alignedSeq)
+    if (ungappedSeq.length > 0) {
+      sequences.push({ id: name, seq: ungappedSeq })
+    }
+  }
+
+  console.log(`Processing ${sequences.length} non-empty sequences...`)
+
+  let allResults: InterProScanResults[]
+
+  if (useLocal) {
+    console.log(`Running local InterProScan at ${interproscanPath}...`)
+    allResults = await runLocalInterProScan(
+      sequences,
+      interproscanPath,
+      programs,
+    )
+  } else {
+    console.log(`Running InterProScan via EBI API...`)
+    allResults = await runEbiInterProScan(sequences, programs, email, batchSize)
+  }
+
+  console.log(`Converting results to GFF...`)
+  const gff = interProResponseToGFF(allResults)
+
+  console.log(`Writing output to ${outputFile}...`)
+  fs.writeFileSync(outputFile, gff, 'utf8')
+
+  console.log('Done!')
+}

package/src/local-runner.ts

@@ -0,0 +1,87 @@
+import { spawn } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import path from 'node:path'
+
+import type { InterProScanResults } from 'msa-parsers'
+
+interface InterProScanResponse {
+  results: InterProScanResults[]
+}
+
+export async function runLocalInterProScan(
+  sequences: { id: string; seq: string }[],
+  interproscanPath: string,
+  programs: string[],
+): Promise<InterProScanResults[]> {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'interproscan-'))
+  const inputFile = path.join(tmpDir, 'input.fasta')
+  const outputFile = path.join(tmpDir, 'output.json')
+
+  try {
+    const fastaContent = sequences.map(s => `>${s.id}\n${s.seq}`).join('\n')
+
+    fs.writeFileSync(inputFile, fastaContent, 'utf8')
+
+    console.log(`  Running InterProScan on ${sequences.length} sequences...`)
+
+    await new Promise<void>((resolve, reject) => {
+      const args = [
+        '-i',
+        inputFile,
+        '-o',
+        outputFile,
+        '-f',
+        'JSON',
+        '-appl',
+        programs.join(','),
+        '--goterms',
+        '--pathways',
+      ]
+
+      const proc = spawn(interproscanPath, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+
+      let stderr = ''
+
+      proc.stdout.on('data', (data: Buffer) => {
+        const line = data.toString().trim()
+        if (line) {
+          console.log(`  ${line}`)
+        }
+      })
+
+      proc.stderr.on('data', (data: Buffer) => {
+        stderr += data.toString()
+      })
+
+      proc.on('close', code => {
+        if (code === 0) {
+          resolve()
+        } else {
+          reject(new Error(`InterProScan failed with code ${code}: ${stderr}`))
+        }
+      })
+
+      proc.on('error', err => {
+        reject(new Error(`Failed to run InterProScan: ${err.message}`))
+      })
+    })
+
+    if (!fs.existsSync(outputFile)) {
+      throw new Error('InterProScan did not produce output file')
+    }
+
+    const outputContent = fs.readFileSync(outputFile, 'utf8')
+    const response: InterProScanResponse = JSON.parse(outputContent)
+
+    return response.results
+  } finally {
+    try {
+      fs.rmSync(tmpDir, { recursive: true })
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}