references/citation.bib
@ARTICLE{Sievers2011,
ABSTRACT = {Multiple sequence alignments are fundamental to many sequence analysis methods. Most alignments are computed using the progressive alignment heuristic. These methods are starting to become a bottleneck in some analysis pipelines when faced with data sets of the size of many thousands of sequences. Some methods allow computation of larger data sets while sacrificing quality, and others produce high‐quality alignments, but scale badly with the number of sequences. In this paper, we describe a new program called Clustal Omega, which can align virtually any number of protein sequences quickly and that delivers accurate alignments. The accuracy of the package on smaller test cases is similar to that of the high‐quality aligners. On larger data sets, Clustal Omega outperforms other packages in terms of execution time and quality. Clustal Omega also has powerful features for adding sequences to and exploiting information in existing alignments, making use of the vast amount of precomputed information in public databases like Pfam.},
AUTHOR = {Sievers, Fabian and Wilm, Andreas and Dineen, David and Gibson, Toby J. and Karplus, Kevin and Li, Weizhong and Lopez, Rodrigo and McWilliam, Hamish and Remmert, Michael and Söding, Johannes and Thompson, Julie D. and Higgins, Desmond G.},
URL = {https://doi.org/10.1038/msb.2011.75},
DATE = {2011-10-11},
DOI = {10.1038/msb.2011.75},
ISSN = {1744-4292},
JOURNALTITLE = {Molecular Systems Biology},
NUMBER = {1},
PAGES = {MSB201175},
TITLE = {Fast, scalable generation of high‐quality protein multiple sequence alignments using Clustal Omega},
VOLUME = {7},
}
@ARTICLE{Goujon2010,
ABSTRACT = {The EMBL-EBI provides access to various mainstream sequence analysis applications. These include sequence similarity search services such as BLAST, FASTA, InterProScan and multiple sequence alignment tools such as ClustalW, T-Coffee and MUSCLE. Through the sequence similarity search services, the users can search mainstream sequence databases such as EMBL-Bank and UniProt, and more than 2000 completed genomes and proteomes. We present here a new framework aimed at both novice as well as expert users that exposes novel methods of obtaining annotations and visualizing sequence analysis results through one uniform and consistent interface. These services are available over the web and via Web Services interfaces for users who require systematic access or want to interface with customized pipe-lines and workflows using common programming languages. The framework features novel result visualizations and integration of domain and functional predictions for protein database searches. It is available at http://www.ebi.ac.uk/Tools/sss for sequence similarity searches and at http://www.ebi.ac.uk/Tools/msa for multiple sequence alignments.},
AUTHOR = {Goujon, Mickael and McWilliam, Hamish and Li, Weizhong and Valentin, Franck and Squizzato, Silvano and Paern, Juri and Lopez, Rodrigo},
URL = {https://doi.org/10.1093/nar/gkq313},
DATE = {2010-07},
DOI = {10.1093/nar/gkq313},
EPRINT = {https://academic.oup.com/nar/article-pdf/38/suppl_2/W695/3832907/gkq313.pdf},
ISSN = {0305-1048},
JOURNALTITLE = {Nucleic Acids Research},
NUMBER = {2},
PAGES = {W695--W699},
TITLE = {A new bioinformatics analysis tools framework at EMBL–EBI},
VOLUME = {38},
}
@ARTICLE{Madeira2024,
ABSTRACT = {The EMBL-EBI Job Dispatcher sequence analysis tools framework (https://www.ebi.ac.uk/jdispatcher) enables the scientific community to perform a diverse range of sequence analyses using popular bioinformatics applications. Free access to the tools and required sequence datasets is provided through user-friendly web applications, as well as via RESTful and SOAP-based APIs. These are integrated into popular EMBL-EBI resources such as UniProt, InterPro, ENA and Ensembl Genomes. This paper overviews recent improvements to Job Dispatcher, including its brand new website and documentation, enhanced visualisations, improved job management, and a rising trend of user reliance on the service from low- and middle-income regions.},
AUTHOR = {Madeira, Fábio and Madhusoodanan, Nandana and Lee, Joonheung and Eusebi, Alberto and Niewielska, Ania and Tivey, Adrian R N and Lopez, Rodrigo and Butcher, Sarah},
URL = {https://doi.org/10.1093/nar/gkae241},
DATE = {2024-07},
DOI = {10.1093/nar/gkae241},
EPRINT = {https://academic.oup.com/nar/article-pdf/52/W1/W521/58436149/gkae241.pdf},
ISSN = {0305-1048},
JOURNALTITLE = {Nucleic Acids Research},
NUMBER = {W1},
PAGES = {W521--W525},
TITLE = {The EMBL-EBI Job Dispatcher sequence analysis tools framework in 2024},
VOLUME = {52},
}
scripts/msa_align.py
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "polite-http",
# "python-dotenv",
# ]
# ///
"""Runs EBI Clustal Omega for MSA computation.
Takes a file with multiple sequences and provides the alignment.
"""
import argparse
import os
import sys
import time
import urllib.parse
import dotenv
from polite_http import http_client
_POLLING_TIMEOUT_SECS = 15 * 60 # 15 minutes.
_CLIENT = http_client.HttpClient(
"https://www.ebi.ac.uk/Tools/services/rest/clustalo/", qps=1
)
def _prepare_payload(email: str, title: str, sequences: str) -> bytes:
"""Prepares the payload for the EBI Clustal Omega API."""
params = {
"email": email,
"title": title,
"sequence": sequences,
}
return urllib.parse.urlencode(params).encode("utf-8")
def _align_sequences(
*, input_file: str, output_file: str, dry_run: bool = False
) -> None:
"""Runs EBI Clustal Omega alignment for sequences in a FASTA file.
This function takes a FASTA formatted file, submits the sequences to the
EBI Clustal Omega web service, polls for the alignment completion, and
saves the resulting alignment in FASTA format to the specified output file.
Args:
input_file: Path to the input file containing sequences in FASTA format.
output_file: Path where the resulting MSA in FASTA format will be saved.
dry_run: If True, print the payload and exit without submitting the job.
"""
if not os.path.exists(input_file):
print(f"[!] Error: Input file not found: {input_file}")
sys.exit(1)
max_size_bytes = 4 * 1024 * 1024 # 4 MB
file_size = os.path.getsize(input_file)
if file_size > max_size_bytes:
print(
"[!] Error: At most 4 MB file size supported. Found"
f" {file_size / (1024 * 1024):.2f} MB."
)
sys.exit(1)
with open(input_file, "r") as f:
sequences = f.read().strip()
if not sequences:
print("[!] Error: Empty input file.")
sys.exit(1)
num_sequences = sequences.count(">")
if num_sequences < 2:
print(f"[!] Error: At least 2 sequences required. Found {num_sequences}.")
sys.exit(1)
if num_sequences > 4000:
print(
f"[!] Error: At most 4000 sequences supported. Found {num_sequences}."
)
sys.exit(1)
print("[*] Submitting sequences to EBI Clustal Omega API...")
# 1. Submit Job
user_email = os.environ.get("USER_EMAIL")
if not user_email:
print("[!] Error: USER_EMAIL environment variable is required.")
sys.exit(1)
data = _prepare_payload(user_email, "MSA", sequences)
if dry_run:
print(data)
sys.exit(0)
job_id = _CLIENT.fetch_text(
"run", method="POST", data=data, headers={"Accept": "text/plain"}
).strip()
print(f"[*] Job ID generated: {job_id}")
# 2. Poll the server
print("[*] Polling server for completion...")
start_time = time.time()
while time.time() - start_time < _POLLING_TIMEOUT_SECS:
status = _CLIENT.fetch_text(
f"status/{job_id}", headers={"Accept": "text/plain"}, timeout=20
).strip()
sys.stdout.write(".")
sys.stdout.flush()
if status == "FINISHED":
print("\n[*] Job marked as FINISHED.")
break
elif status in ["ERROR", "FAILURE", "NOT_FOUND"]:
print(f"\n[!] Job failed with status: {status}")
sys.exit(1)
time.sleep(10)
else:
print(f"\n[!] Job timed out after {_POLLING_TIMEOUT_SECS // 60} minutes.")
sys.exit(1)
# 3. Fetch Results
print("\n[*] Job complete. Fetching results...\n")
result_text = _CLIENT.fetch_text(f"result/{job_id}/fa", timeout=60)
with open(output_file, "w") as f:
f.write(result_text)
print(f"[*] Alignment results saved to: {output_file}")
def main() -> None:
dotenv.load_dotenv(os.path.expanduser("~/.env"))
parser = argparse.ArgumentParser(
description="MSA computation using EBI Clustal Omega."
)
parser.add_argument(
"input", help="Path to FASTA file containing multiple sequences"
)
parser.add_argument(
"-o",
"--output",
required=True,
help="Path to save the output alignment file",
)
parser.add_argument(
"--dry-run",
action="store_true",
help="Dry run: print payload and exit without submitting job",
)
args = parser.parse_args()
_align_sequences(
input_file=args.input, output_file=args.output, dry_run=args.dry_run
)
if __name__ == "__main__":
main()
SKILL.md
---
name: protein-sequence-msa
description: >
Performs multiple sequence alignment of proteins with EBI Clustal Omega.
Use when you need to align multiple sequences to assess similarity, domain
conservation, or key residue conservation. Supports up to 4000 sequences and
a maximum file size of 4 MB. Do not use to search for homologous proteins in
a database (use MMseqs2, BLAST), align non-protein sequences (DNA, RNA),
perform structural alignment (use Foldseek, PyMOL), or if you only have a
single sequence.
---
## Prerequisites
1. **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
`uv` is installed and on PATH.
2. **User Notification**: If .licenses/protein_sequence_msa_LICENSE.txt does
not already exist in the workspace root directory then (1) prominently
notify the user to check the terms at
https://www.ebi.ac.uk/jdispatcher/msa/clustalo and
https://www.ebi.ac.uk/about/terms-of-use/, then (2) create the file
recording the notification text and timestamp.
3. **`.env` file**: Make sure the `.env` file exists in your home directory.
Create one if it does not exist.
4. **`USER_EMAIL`**: Required by the wrapper script for Clustal Omega job
tracking (recommended by the EBI). You **MUST** use the safe credentials
protocol in the `credentials` skill to check for and request this credential
if this skill looks relevant to the user's request.
## Core Rules
- **Use the Wrapper**: ALWAYS execute the alignment using
`scripts/msa_align.py` rather than writing your own curl or custom Python
requests. The script automatically enforces the required rate limit to
respect EBI's Terms of Use.
- **Notification**: If this skill is used, ensure this is mentioned in the
output.
* **Always state the method:** Every report must clearly state that the
alignment was performed using **EBI Clustal Omega**.
- **No Hallucinations**: Do NOT invent alignments or conservation metrics.
Report only what is present in the alignment file.
## Goal
Take a file containing multiple protein sequences in FASTA format, perform
multiple sequence alignment using the EBI Clustal Omega API, save the resulting
alignment locally for future programmatic analysis, and interpret the results
towards addressing the user's specific research objective (e.g., assessing
similarity, identifying conserved domains, or analyzing key residues).
## Instructions
1. **Prepare Input File:** The input must be a plain text file containing two
or more protein sequences in FASTA format. Each sequence header must start
with a `>` symbol. Example:
```
>Sequence_1_Name
MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQ
QRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG
>Sequence_2_Name
MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQ
QRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG
```
2. **Execute Alignment:** Run the alignment script:
```bash
uv run scripts/msa_align.py <INPUT_FASTA> -o <OUTPUT_FILE>
```
Always specify the output file with `-o` or `--output`.
3. **Interpret and Report Results:** Analyze the Clustal Omega alignment by
selecting metrics and mapping strategies aligned with the research
objective. Note that while Clustal Omega produces a Global Alignment,
pairwise metrics can be extracted to evaluate specific relationships within
the set:
* **Identity Metric Options:** The choice of denominator determines how
insertions/deletions (gaps) affect the final percentage. Select the most
appropriate calculation based on the biological context:
* **Pairwise - Sequence Coverage:** `(Identical Residue Matches) /
(Length of Shorter Sequence)`. Use when determining if a specific
domain or fragment is fully preserved within a larger protein. This
ignores gaps in the longer sequence, focusing purely on the
"content" of the shorter one.
* **Pairwise - Global Identity:** `(Identical Residue Matches) /
(Total Alignment Columns)`. Use when comparing full-length sequences
of similar expected length. This is the most conservative metric; it
penalizes for all gaps (indels) introduced by any sequence in the
MSA.
* **Pairwise - Overlap Identity:** `(Identical Residue Matches) /
(Total Alignment Columns - Terminal Gaps)`. Use when comparing a
fragment to a full-length protein or when sequences have long
unaligned "tails." This focuses on similarity only where the
sequences physically overlap.
* **Multisequence - Conservation Index:** `(Fully Conserved Columns) /
(Total Alignment Columns)`. Use for quantifying the percentage of
residues that are 100% identical across the entire alignment set.
This identifies the core evolutionary signature of the protein
family.
* **Feature Mapping:** Leverage known biological data from specific
sequences to ground the analysis:
* **Knowledge Gathering:** Identify relevant known sites or regions
(e.g., catalytic residues, binding motifs) from your input or via
external tools.
* **Coordinate Projection:** Map these features onto the corresponding
Column Indices of the alignment.
* **Targeted Discussion:** Use these columns to drive the assessment:
* **Local Conservation:** Analyze if the known functional residues
are invariant across the set.
* **Region-Specific Metrics:** Calculate identity/similarity
specifically within the mapped functional regions rather than
the whole sequence.
* **Goal Contribution:** Discuss how this data contributes to your
goal, e.g. using conservation to corroborate a prediction or
divergence to reject a functional hypothesis.
## References
- Multiple Sequence Alignment: https://www.ebi.ac.uk/jdispatcher/msa/clustalo