Python package to run the SIFTS (Structure Integration with Function, Taxonomy and Sequences) pipeline locally.
Developed at EMBL-EBI by the PDBe team.
SIFTS provides residue-level mappings between structures and sequences. This package automates the full pipeline:
- Build a reference sequence database (MMseqs2 or BLASTP)
- Align structure sequences against it to identify the best match per chain (≥ 90% identity) according to the SIFTS scoring function
- Generate precise residue- and segment-level structure-sequence mappings via local alignment (FASTA36
lalign36) - Store results in a DuckDB database and per-entry CSV files
- Export mappings back into annotated mmCIF files
The whole pipeline can work on non-UniProt or non-PDB entries. However, it will use only the adjusted score to rank the hits.
The notebook https://github.com/PDBeurope/SIFTS/blob/master/notebooks/quickstart.ipynb also go throught the installation.
The following binaries must be installed and available on PATH:
| Tool | Purpose | Install |
|---|---|---|
| MMseqs2 | Fast global sequence search | conda install -c conda-forge mmseqs2 |
FASTA36 (lalign36) |
Local pairwise alignment | conda install -c bioconda fasta3 |
| BLAST+ | Optional alternative to MMseqs2 | conda install -c bioconda blast |
# Create environment from file
conda env create -f environment.yml
# Activate environment
conda activate pdbe_sifts
# Install pdbe_sifts package in editable mode
pip install -e .
# Or install directly
pip install pdbe_sifts# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Alternative via pip
pip install uvgit clone https://github.com/PDBeurope/SIFTS
cd SIFTS# Create a virtual environment and install all dependencies
uv sync
# This will:
# - Create a .venv directory
# - Install Python 3.10 if needed
# - Install all dependencies from pyproject.toml
# - Lock versions in uv.lock# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activateRequirements: Python ≥ 3.10 · 8 GB RAM minimum (32 GB+ recommended for large datasets)
Install BLAST+:
brew install blast # MacOS
sudo apt install ncbi-blast+ # Linux
# Windows
# Download the latest version executable and follow the installation guide
https://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/Install MMseqs2
brew install mmseqs2 # MacOS or Linux
# Windows
# Not supported yet (it is recommanded to use the linux subsytem from Windows.)Install FASTA36
git clone https://github.com/wrpearson/fasta36.git
cd ~/fasta36/src
make -f ../make/Makfile.linux64_sse2 all
# Windows
# Not supported yet (it is recommanded to use the linux subsytem from Windows.)You first need a fasta file containing sequences and a taxonomic mapping file. For that you can use the command:
pdbe_sifts prepare_build_db --output-fasta /my/path/to/myfile.fasta.gz --output-tax-mapping /my/path/to/taxonomy_mapping.tsvYou can also specify a exiting fasta file using the argument --input-fasta. Without it, the command will download by default the UniProtKB/SwissProt fasta file.
This command assume the fasta header follow the UniProtKB conventions.
pdbe_sifts init
# → creates ~/.config/pdbe_sifts/config.yaml
# → downloads the NCBI taxonomy database (~70 MB, first run only) (this is not the two-column TSV file.)Edit the config to set your paths (base_dir, nobackup_dir, target_db (after building it), etc.). You can also setup different alignment parameters.
base_dir: path to where you want the results to be saved
nobackup_dir:path to where you want the tmp files to be saved
target_db: path to the database created using build_db
pdbe_sifts build_db \
-i myfile.fasta # .gz accepted with mmseqs\
-o ./my/folder/prefix \
-t taxonomy_mapping.tsv # TSV: sequence_id <tab> tax_idThis will create a database using the fasta file provided. The argument -o allow to create, in your current location, several files with the prefix given.
# Single CIF entry
pdbe_sifts sequence_match -i 1abc.cif -o ./results -d ./my/db/folder/prefix
# Batch (one mmCIF path per line)
pdbe_sifts sequence_match -i entries.txt -o ./results -d ./my/db/folder/prefix --threads 8At this step you can also provide a .csv file to faster the scoring function. This CSV file must contains per row: row_num, uniprot_accession, dataset (Swiss-Prot or TrEMBL), pdb cross-references, annotation score.
This command produces hits.duckdb and hits.tsv — a scored and raw table of sequence candidates per structure entity. The files will be located in results in a subfolder named according to your input in the argument -i. In this case, it will be in ./results/mmseqs_entries/hits.duckdb for example. The template is ./results/usedTool_inputName/.
# With DuckDB hits (from structure to sequence matching step)
pdbe_sifts segments -i 1abc.cif.gz -o ./segments -d hits.duckdb
# Manual structure-sequence mapping (chain:accession)
pdbe_sifts segments -i 1abc.cif.gz -o ./segments -m "A:P00963,B:P00963"
# Custom FASTA mapping (headers: >{structure_id}|{auth_asym_id}|{sequence_id})
pdbe_sifts segments -i 1abc.cif.gz -o ./segments -m custom_seqs.fastaProduces per-entry gzip-compressed CSV files under {output_dir}/.
pdbe_sifts db_load -i ./segments/ -d hits.duckdbBulk-loads the segment and residue CSVs produced in step 4 into the sifts_xref_segment and sifts_xref_residue tables of the DuckDB file.
If you run the db_load command, you can use the command below because the -d argument requires two tables created by the db_load
step.
# Reading from DuckDB (after step 5)
pdbe_sifts sifts2mmcif \
-i 1abc.cif.gz \
-o ./sifts_mmcif \
-d hits.duckdbIf not please use:
# Or reading segment CSVs directly (skip step 5)
pdbe_sifts sifts2mmcif \
-i 1abc.cif.gz \
-o ./sifts_mmcif \
-s ./segments/This integrates the computed SIFTS annotations into the source PDBx/mmCIF file by populating the _pdbx_sifts_unp_segments. Additionally, the atom_site category is extended to include the sequence accession and residue number from the best available mapping, enabling each atomic coordinate to be associated directly with the corresponding mapped residue.
| Command | Description |
|---|---|
pdbe_sifts init |
Copy default config to ~/.config/pdbe_sifts/config.yaml and init NCBI taxonomy DB |
pdbe_sifts show |
Print the fully resolved configuration |
pdbe_sifts update_ncbi |
Force-update the local NCBI taxonomy database (ete4) |
pdbe_sifts prepare_build_db |
Prepare FASTA and taxonomy mapping inputs for target database creation |
pdbe_sifts build_db |
Build a reference sequence database (MMseqs2 or BLASTP) from a FASTA file |
pdbe_sifts fasta_build |
Extract entity sequences from mmCIF files and write a FASTA |
pdbe_sifts sequence_match |
Align structure sequences against the reference DB; score and store hits in DuckDB |
pdbe_sifts segments |
Generate SIFTS mappings for a single mmCIF entry |
pdbe_sifts db_load |
Bulk-load segment/residue CSVs from segments generation into DuckDB |
pdbe_sifts sifts2mmcif |
Inject SIFTS mappings into an annotated mmCIF file |
pdbe_sifts update_ccd_mapping |
Check whether the remote CCD file is newer than the cached three-to-one letter mapping CSV and regenerate it if so |
pdbe_sifts seq2seq |
Align canonical deposited sequence vs coordinate sequence |
The pipeline classes can be used directly in Python scripts without going through the CLI.
from pdbe_sifts.sequence_match.target_database import TargetDb
TargetDb(
input_path="uniprot_sprot.fasta",
output_path="./my_db/target_db",
tax_mapping_file="taxonomy.tsv",
tool="mmseqs", # or "blastp"
threads=8,
).run()from pdbe_sifts.sifts_fasta_builder import FastaBuilder
fasta_path = FastaBuilder(
input_path="1abc.cif", # or .cif.gz, or a .txt file listing CIF paths
out_dir="./fasta/",
threads=4,
).build()from pdbe_sifts.sifts_sequence_match import SiftsSequenceMatch
SiftsSequenceMatch(
input_file="1abc.cif", # or .fasta, or a .txt list of CIF paths
out_dir="./results/",
db_file="./my_db/target_db",
tool="mmseqs", # or "blastp"
threads=8,
).process()
# → writes hits.duckdb and hits_<entry>.tsv to out_dirfrom pdbe_sifts.sifts_segments_generation import SiftsAlign
# Mode 1: use scored hits from sequence_match
sa = SiftsAlign(
cif_file="1abc.cif",
out_dir="./segments/",
db_conn_str="hits.duckdb",
)
# Mode 2: provide a manual mapping (accessions or custom FASTA)
sa = SiftsAlign(
cif_file="1abc.cif",
out_dir="./segments/",
unp_mode="A:P00963,B:P00963", # or path to a FASTA file
)
sa.process_entry("1abc")
if sa.conn:
sa.conn.close()
# → writes {out_dir}/1abc_seg.csv.gz
# {out_dir}/1abc_res.csv.gzimport duckdb
from pdbe_sifts.database.sifts_db_wrapper import SiftsDB
conn = duckdb.connect("hits.duckdb")
SiftsDB(conn).bulk_load_from_entries("./segments/")
conn.close()| File | Format | Content |
|---|---|---|
hits.duckdb |
DuckDB | Scored sequence accession candidates per structure entity |
hits_<entry>.tsv |
TSV | Raw MMseqs2 / BLASTP alignment hits |
Per entry, under {output_dir}:
| File | Format | Content |
|---|---|---|
{entry}_seg.csv.gz |
CSV (gzip) | One row per contiguous aligned range (structure ↔ sequence positions, identity, conflicts, chimera flag) |
{entry}_res.csv.gz |
CSV (gzip) | One row per mapped structure residue (auth seq id, sequence position, one-letter codes, observed flag) |
{entry}_nf90_seg.csv.gz |
CSV (gzip) | NF90 variant of the segment file (written when applicable) |
After running db_load, results are available in DuckDB tables sifts_xref_segment and sifts_xref_residue.
| Variable | Default | Description |
|---|---|---|
SIFTS_LOG_LEVEL |
INFO |
Logging verbosity: DEBUG, INFO, WARNING, ERROR, CRITICAL |
SIFTS_N_PROC |
auto | Number of internal threads per worker (lalign36 jobs). Override manually to cap CPU use. |
SIFTS_NO_CACHE_ALL |
unset | If set (any value), disables the UniProt pickle cache and always fetches from the REST API. |
SLURM_CPUS_PER_TASK |
unset | Detected automatically on SLURM clusters. Used by get_allocated_cpus() to set the thread count when running under a SLURM job allocation. |
src/pdbe_sifts/
├── cli.py # CLI entry point (pdbe_sifts command)
├── sifts_sequence_match.py # Global mapping pipeline (SiftsSequenceMatch)
├── sifts_segments_generation.py # Single-entry segment generation (SiftsAlign)
├── sifts_fasta_builder.py # Extract sequences from mmCIF → FASTA (FastaBuilder)
├── sifts_database_loader.py # Standalone bulk-loader script (wraps SiftsDB)
├── config/ # OmegaConf configuration loading — defines load_config()
├── base/
│ ├── paths.py # All configuration getters (imports load_config() from config/)
│ ├── utils.py # UniProt fetch, CPU helpers, SiftsAction
│ ├── log.py # Logging setup (StreamHandler, coloredlogs)
│ └── exceptions.py # All custom exceptions (centralised)
├── database/
│ └── sifts_db_wrapper.py # SiftsDB: DuckDB schema + bulk loader
├── mmcif/ # mmCIF parsing (Entry, Chain, Entity, Residue, ChemComp)
├── sequence_match/
│ ├── target_database.py # Build MMseqs2 / BLAST reference database (TargetDb)
│ ├── mmseqs_search.py # MMseqs2 easy-search wrapper
│ ├── blastp.py # BLASTP wrapper
│ └── sequence_match_parser.py # Parse TSV hits, score, store in DuckDB
├── segments_generation/
│ └── alignment/ # lalign36 wrapper, isoform alignment, residue mapping
├── sifts_to_mmcif/ # Inject SIFTS data back into mmCIF files
├── unp/
│ └── unp.py # UniProt REST client, pickle cache, isoform handling
└── data/
└── default_config.yaml # Default configuration template (all tuneable params)
EMBL-EBI PDBe team: Adam Bellaiche, Preeti Choudhary, Sreenath Sasidharan Nair, Jennifer Fleming, Sameer Velankar
Apache-2.0