Multiple Sequence Alignment (MSA)
Relevant source files
The following files were used as context for generating this wiki page:
The Multiple Sequence Alignment (MSA) module is a core service within the platform that allows users to align biological sequences (DNA or protein) using various algorithms like Muscle or Mafft. It provides both a submission interface for launching alignment jobs and a sophisticated interactive viewer for analyzing results. The system supports multiple input methods, including manual FASTA entry, workspace files, and genome/feature groups.
The module is built upon the BioJS MSA Viewer, which handles the front-end visualization and interaction. This integration allows for features such as interactive zooming, dynamic color schemes, and the ability to export alignments as images or FASTA files. In addition to general alignment, the system is utilized for specific analytical tasks such as HA Subtype Numbering Conversion and variation/SNP analysis.
Sources: public/js/p3/widget/app/MSA.js:20-30, public/js/msa/README.md:1-20
Service Architecture and Job Submission
The MSA service utilizes an application-based architecture where users define input sequences, selection parameters, and alignment strategies before submitting a job to the backend. The submission interface manages state transitions between "unaligned" and "aligned" inputs, ensuring that the appropriate parameters are collected for each mode.
Data Flow and Input Handling
The system supports four primary input types for unaligned sequences: feature groups, genome groups, FASTA files from the workspace, and direct text input. The MSA.js application validates these inputs, ensuring that a minimum number of sequences are provided (typically two) and that the sequences match the expected alphabet (DNA or protein).
The application performs real-time validation of FASTA records, checking for valid characters and sequence counts. For genome groups, it specifically verifies that the group contains viral genomes and does not exceed the maximum allowed count (5000) or individual genome length (250,000 bp).
Sources: public/js/p3/widget/app/MSA.js:77-110, public/js/p3/widget/app/MSA.js:316-330, public/js/p3/widget/app/MSA.js:452-475
Alignment Algorithms and Strategies
Users can select between different alignment tools, with the UI dynamically adjusting options based on the selection.
| Aligner | Description | Strategy Options |
|---|---|---|
| Mafft | High-performance alignment tool | Auto, FFT-NS-1, FFT-NS-2, G-INS-i, L-INS-i, E-INS-i |
| Muscle | Reliable sequence alignment tool | Default (no specific strategy selection in UI) |
Sources: public/js/p3/widget/app/MSA.js:415-425, public/js/p3/widget/app/MSA.js:527-535
MSA Visualization and Interaction
The visualization component is powered by the BioJS MSA viewer, which is integrated into results viewers like the HASubtypeNumberingReport.js. This viewer provides a rich set of interactive features.
Viewer Configuration
The viewer is highly customizable through a global configuration object (g). This object manages various aspects of the visualization:
| Category | Key Options |
|---|---|
| vis | sequences, markers, metacell, conserv, overviewbox, seqlogo, gapHeader, labels |
| zoomer | alignmentWidth, alignmentHeight, columnWidth, rowHeight, labelFontsize, residueFont |
| conf | registerMouseHover, registerMouseClicks, importProxy, alphabetSize |
| colorscheme | scheme (e.g., taylor, hydro), colorBackground, showLowerCase, opacity |
Sources: public/js/msa/README.md:270-350, public/js/p3/widget/viewer/HASubtypeNumberingReport.js:46-75
User Interactions and Events
The viewer supports a wide range of events that allow developers to hook into user interactions:
- Residue Events:
residue:click,residue:mousein,residue:mouseout. - Structural Events:
row:click,column:click,meta:click. - State Changes: Listening to changes in the selection collection (
m.g.selcol.on("change", ...)).
Sources: public/js/msa/README.md:238-260
Interaction Flow
The following diagram illustrates how the viewer handles user interaction to update the display or select data.
Sequence and Selection Models
The MSA viewer uses internal models to manage sequences and user selections.
Sequence Model Structure
Each sequence in the alignment is represented by an object containing:
name: The display name of the sequence.id: Unique identifier.seq: The raw character data.height: Vertical scaling.ref: Boolean indicating if the sequence is a reference (e.g., consensus).
Sources: public/js/msa/README.md:386-395
Selection Management
The system supports three types of selections:
- Row Selection: Entire sequences.
- Column Selection: Specific vertical slices of the alignment.
- Position Selection: A specific residue (union of row and column).
Selections can be manipulated via methods such as invertRow, invertCol, and getBlocksForRow.
Sources: public/js/msa/README.md:195-210
Export and Utility Functions
The MSA module provides utilities for exporting data and interacting with external tools.
- File Export: Supports saving as FASTA (
saveAsFile), GFF3 features (saveAnnots), or Image (saveAsImg). - External Integration: Capabilities to share links or open the alignment in Jalview.
- Coordination: Functions like
setLeftOffsetallow jumping to specific columns programmatically.
Sources: public/js/msa/README.md:215-235, public/js/p3/widget/viewer/HASubtypeNumberingReport.js:630-650
Implementation Example: HA Subtype Numbering Report
The HASubtypeNumberingReport.js demonstrates a complex implementation of the MSA viewer. It parses FASTA results from a workspace folder, generates a conversion table between query and reference positions, and renders multiple MSA viewer instances—one for each query sequence. It also includes custom action menus for switching between simplified and strain names in the viewer labels.
Sources: public/js/p3/widget/viewer/HASubtypeNumberingReport.js:350-420, public/js/p3/widget/viewer/HASubtypeNumberingReport.js:560-590
Summary
Multiple Sequence Alignment is a multi-faceted system combining robust backend job submission with a flexible, interactive frontend. By leveraging the BioJS MSA viewer, it provides researchers with powerful tools to visualize conserved regions, SNPs, and structural features across large sets of genomic or proteomic data. The integration with the broader workspace ensures a seamless flow from raw data to aligned results and downstream analysis.