structural-alignment

Name: structural-alignment
Author: GPTomics

1.1kstars185forks

How to install structural-alignment?

gptomics/bioskills/structural-alignment

$npx -y skills add GPTomics/bioSkills --skill structural-alignment

Installs into the current project.

Summary

Align protein structures using Foldseek 3Di, TM-align, US-align, DALI, or Foldmason for structural MSA. Predict, score, and superpose backbone coordinates when sequence identity is below the twilight zone or remote-homology detection is required. Use when sequence MSA fails (<25%

Files · 1

View on GitHub

SKILL.md

1	## Version Compatibility
2
3	Reference examples tested with: Foldseek 8+, TM-align 20220412+, US-align 20231222+, Foldmason 1+, BioPython 1.83+, pymol-open-source 3.0+
4
5	Before using code patterns, verify installed versions match. If versions differ:
6	- CLI: `foldseek --version`, `TMalign`, `USalign`, `foldmason --version`
7	- Python: `pip show <package>` then `help(module.function)` to check signatures
8
9	If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.
10
11	# Structural Alignment
12
13	"Align two protein structures" -> Compute backbone-aware superposition and a fold-similarity score (TM-score, RMSD, or LDDT).
14	- CLI pairwise: `TMalign A.pdb B.pdb`, `USalign A.pdb B.pdb`
15	- CLI search at scale: `foldseek easy-search query/ AFDB result.m8 tmp/`
16	- CLI structural MSA: `foldmason easy-msa structures/*.pdb out tmp/`
17	- Python pairwise: `Bio.PDB.Superimposer`, or `subprocess` wrapping `TMalign` / `USalign` (see `examples/tm_align_pairwise.py`)
18	- GUI / scripted molecular-graphics superposition: ChimeraX `matchmaker`, PyMOL `super`/`cealign`
19
20	"Find structural homologs of an AlphaFold model" -> Search a structure database by 3Di-encoded structural alphabet (Foldseek) or by full TM-align rotation (DALI, US-align).
21
22	## When to Use Structural Alignment
23
24	\| Sequence identity \| Recommended approach \|
25	\|-------------------\|---------------------\|
26	\| >= 40% \| Sequence DP (Bio.Align, BLASTP) is sufficient \|
27	\| 25-40% \| Sensitive sequence (MMseqs2, jackhmmer, profile-profile HHsearch) \|
28	\| 15-25% \| Profile-profile (HHsearch) OR Foldseek if structures available \|
29	\| < 15% (dark proteome / twilight zone) \| Foldseek (3Di), TM-align, US-align, pLM aligners \|
30
31	Sequence alignment below 15% identity is statistically indistinguishable from random pairings. The exact twilight-zone cutoff is length-dependent: Rost 1999 (Prot Eng) showed the curve drops to 25% at length 80, 20% at length 250 -- short alignments need higher identity for the same statistical signal, so a 15-25% rule of thumb is shorthand for "twilight zone for proteins of typical domain size (~150-300 residues)". If reasonable structural models exist (PDB, AlphaFoldDB, ESMFold), structural alignment is far more reliable in this regime.
32
33	### Twilight-Zone Threshold Exceptions
34
35	For families with strong functional or structural constraint (ribosomal proteins, class I aminoacyl-tRNA synthetases with HIGH/KMSKS motifs, histone fold, cytochrome c with CXXCH, or any long alignment with well-distributed conservation), sequence MSA may remain reliable down to ~12-15% identity. Verify with a profile-profile method (HHsearch) before committing to structural alignment.
36
37	## Pairwise Structural Alignment Tool Selection
38
39	\| Tool \| Reference \| Score \| Best for \|
40	\|------\|-----------\|-------\|----------\|
41	\| TM-align \| Zhang & Skolnick 2005 NAR \| TM-score \| Single-chain pairwise; standard fold-similarity benchmark \|
42	\| US-align \| Zhang et al 2022 Nat Methods \| TM-score \| Multi-chain protein, RNA, DNA, complexes; original successor to TM-align \|
43	\| Foldseek-Multimer \| Kim et al 2025 Nat Methods \| TM-score \| Database-scale multi-chain complex search; 10-100x faster than US-align in pairwise mode, 1000-10000x in DB search; preferred at AFDB-multimer scale \|
44	\| FATCAT \| Ye & Godzik 2003 Bioinf \| FATCAT score \| Flexible alignment with allowed twists/breaks \|
45	\| CE \| Shindyalov & Bourne 1998 Prot Eng \| CE score \| Combinatorial extension of fragments; PDB legacy \|
46	\| DALI \| Holm 2022 NAR \| Z-score \| Distance-matrix alignment; superior at TM 0.3-0.5 (twilight fold); operates on AFDB at scale \|
47	\| Bio.PDB.Superimposer \| Cock et al 2009 Bioinf \| RMSD \| Pure-Python superposition with known atom correspondence \|
48
49	TM-align and US-align report two TM-scores by default: one normalised by chain 1 length and one by chain 2 length. The standard fold-similarity metric for asymmetric reporting is the larger of the two (effectively normalising by the shorter chain), since TM-score is length-asymmetric. The `-a T` flag adds a third score normalised by the average of the two chain lengths (useful for symmetric clustering). TM > 0.5 indicates the same fold; TM > 0.8 indicates equivalent topology / close structural relationship; TM < 0.2 indicates random structural similarity. RMSD alone is misleading: RMSD scales with length, depends on outliers, and an "optimization RMSD" (used to fit) is not the same as an "evalu

People who liked this also viewed

6 picks

Type

structural-alignment

1.1kstars185forks

View on GitHub

How to install structural-alignment?

gptomics/bioskills/structural-alignment

$npx -y skills add GPTomics/bioSkills --skill structural-alignment

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Version Compatibility
2
3	Reference examples tested with: Foldseek 8+, TM-align 20220412+, US-align 20231222+, Foldmason 1+, BioPython 1.83+, pymol-open-source 3.0+
4
5	Before using code patterns, verify installed versions match. If versions differ:
6	- CLI: `foldseek --version`, `TMalign`, `USalign`, `foldmason --version`
7	- Python: `pip show <package>` then `help(module.function)` to check signatures
8
9	If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.
10
11	# Structural Alignment
12
13	"Align two protein structures" -> Compute backbone-aware superposition and a fold-similarity score (TM-score, RMSD, or LDDT).
14	- CLI pairwise: `TMalign A.pdb B.pdb`, `USalign A.pdb B.pdb`
15	- CLI search at scale: `foldseek easy-search query/ AFDB result.m8 tmp/`
16	- CLI structural MSA: `foldmason easy-msa structures/*.pdb out tmp/`
17	- Python pairwise: `Bio.PDB.Superimposer`, or `subprocess` wrapping `TMalign` / `USalign` (see `examples/tm_align_pairwise.py`)
18	- GUI / scripted molecular-graphics superposition: ChimeraX `matchmaker`, PyMOL `super`/`cealign`
19
20	"Find structural homologs of an AlphaFold model" -> Search a structure database by 3Di-encoded structural alphabet (Foldseek) or by full TM-align rotation (DALI, US-align).
21
22	## When to Use Structural Alignment
23
24	\| Sequence identity \| Recommended approach \|
25	\|-------------------\|---------------------\|
26	\| >= 40% \| Sequence DP (Bio.Align, BLASTP) is sufficient \|
27	\| 25-40% \| Sensitive sequence (MMseqs2, jackhmmer, profile-profile HHsearch) \|
28	\| 15-25% \| Profile-profile (HHsearch) OR Foldseek if structures available \|
29	\| < 15% (dark proteome / twilight zone) \| Foldseek (3Di), TM-align, US-align, pLM aligners \|
30
31	Sequence alignment below 15% identity is statistically indistinguishable from random pairings. The exact twilight-zone cutoff is length-dependent: Rost 1999 (Prot Eng) showed the curve drops to 25% at length 80, 20% at length 250 -- short alignments need higher identity for the same statistical signal, so a 15-25% rule of thumb is shorthand for "twilight zone for proteins of typical domain size (~150-300 residues)". If reasonable structural models exist (PDB, AlphaFoldDB, ESMFold), structural alignment is far more reliable in this regime.
32
33	### Twilight-Zone Threshold Exceptions
34
35	For families with strong functional or structural constraint (ribosomal proteins, class I aminoacyl-tRNA synthetases with HIGH/KMSKS motifs, histone fold, cytochrome c with CXXCH, or any long alignment with well-distributed conservation), sequence MSA may remain reliable down to ~12-15% identity. Verify with a profile-profile method (HHsearch) before committing to structural alignment.
36
37	## Pairwise Structural Alignment Tool Selection
38
39	\| Tool \| Reference \| Score \| Best for \|
40	\|------\|-----------\|-------\|----------\|
41	\| TM-align \| Zhang & Skolnick 2005 NAR \| TM-score \| Single-chain pairwise; standard fold-similarity benchmark \|
42	\| US-align \| Zhang et al 2022 Nat Methods \| TM-score \| Multi-chain protein, RNA, DNA, complexes; original successor to TM-align \|
43	\| Foldseek-Multimer \| Kim et al 2025 Nat Methods \| TM-score \| Database-scale multi-chain complex search; 10-100x faster than US-align in pairwise mode, 1000-10000x in DB search; preferred at AFDB-multimer scale \|
44	\| FATCAT \| Ye & Godzik 2003 Bioinf \| FATCAT score \| Flexible alignment with allowed twists/breaks \|
45	\| CE \| Shindyalov & Bourne 1998 Prot Eng \| CE score \| Combinatorial extension of fragments; PDB legacy \|
46	\| DALI \| Holm 2022 NAR \| Z-score \| Distance-matrix alignment; superior at TM 0.3-0.5 (twilight fold); operates on AFDB at scale \|
47	\| Bio.PDB.Superimposer \| Cock et al 2009 Bioinf \| RMSD \| Pure-Python superposition with known atom correspondence \|
48
49	TM-align and US-align report two TM-scores by default: one normalised by chain 1 length and one by chain 2 length. The standard fold-similarity metric for asymmetric reporting is the larger of the two (effectively normalising by the shorter chain), since TM-score is length-asymmetric. The `-a T` flag adds a third score normalised by the average of the two chain lengths (useful for symmetric clustering). TM > 0.5 indicates the same fold; TM > 0.8 indicates equivalent topology / close structural relationship; TM < 0.2 indicates random structural similarity. RMSD alone is misleading: RMSD scales with length, depends on outliers, and an "optimization RMSD" (used to fit) is not the same as an "evalu

People who liked this also viewed

6 picks

Type