modelomics is a Python package for structural biology and protein design — the way i like it.
- PDB parsing: Complete PDB file parser with support for ATOM and HETATM records
- Hierarchical organization: Four-level structure hierarchy (PDB → Chain → Residue → Atom)
- Flexible indexing: Access structures by name or integer index at any level
- Structure cleaning: Remove waters, heteroatoms, and filter by specific chains
- Comprehensive atom properties: Coordinates, van der Waals radii, element types, occupancy, B-factors
- Insertion code support: Full support for PDB insertion codes in residue numbering
- Dictionary and list access: Access residues by
("name", number, "insertion")tuples or integer index
- Comprehensive atom organization: Residues contain atoms as both dictionary (by name) and list (by index)
- Structural analysis methods: Alpha carbon positioning, geometric calculations, coordinate extraction
- Interaction detection: Covalent bond detection using atomic radii and distance criteria
- Hydrogen bond analysis: Geometric hydrogen bond detection with donor-acceptor distance and angle constraints
- Multiple embedding models: Support for ESM-C (300M), E1 (150M/300M), ESM3, and ProtT5-XL protein language models
- ESM-C embeddings: Generate 960-dimensional sequence embeddings from pretrained models
- E1 embeddings: Alternative embedding model with flexible sizing (requires Python 3.12)
- ProtT5-XL embeddings: Per-residue embeddings from the ProtT5-XL-UniRef50 encoder (1024D)
- Masked sequence analysis: Create embeddings with specific residue positions masked for mutation effect studies (ESM-C/ESM3)
- Embedding integration: Integration of sequence embeddings into graph neural network node features
- PyTorch Geometric integration: Native
torch_geometric.data.Dataobjects for GNN training - Rich residue-level graphs: Features combining sequence embeddings, physicochemical properties, SASA, and normal mode analysis
- Multi-scale edge features: Distance, covalent bonds, hydrogen bonds, and hydrophobic contacts
- ESM-C sequence embeddings: 960-dimensional protein language model representations
- Structural features: SASA analysis (5D), normal mode fluctuations, physicochemical properties (5D)
- Efficient bond detection: Fast algorithms for covalent bonding, hydrogen bonding
- Fibonacci sphere sampling: Mathematically optimal point distribution on atomic surfaces (92 points per atom)
- Van der Waals surface modeling: Accurate molecular surface generation with customizable probe radius (1.4Å default)
- SASA calculations: Solvent-accessible surface area calculations with atomic-level precision
- Buried point removal: KDTree-based neighbor search algorithms for efficient buried point identification
- Typed SASA analysis: Surface area breakdown by polarity (polar/nonpolar/positive/negative/total)
- Residue-level SASA: Aggregate surface area calculations at the residue level for binding site analysis
- Visualization export: Export point clouds in XYZ format with atomic coloring for molecular visualization
- Python 3.10 or higher (Python 3.12 required for E1 embeddings)
pip install git+https://github.com/alanclayrichard/modelomics.gitE1 requires Python 3.12. Create a separate virtual environment:
# Create Python 3.12 virtual environment
python3.12 -m venv venv_e1
source venv_e1/bin/activate # On macOS/Linux
# venv_e1\Scripts\activate # On Windows
# Install modelomics
pip install git+https://github.com/alanclayrichard/modelomics.gitProtT5 depends on transformers, sentencepiece, and protobuf, which can conflict with the ESM and E1 dependency versions. Create a separate virtual environment:
python3 -m venv venv_prott5
source venv_prott5/bin/activate # On macOS/Linux
# venv_prott5\Scripts\activate # On Windows
# Install modelomics + ProtT5 dependencies
pip install git+https://github.com/alanclayrichard/modelomics.git
pip install transformers sentencepiece protobuffrom modelomics.PDB import PDB
# Load a PDB structure
pdb = PDB("protein.pdb")
# Access by chain name or index
chain_A = pdb['A'] # Access by name
first_chain = pdb[0] # Access by index
# Access residues within chains
residue = chain_A['GLN', 1, ''] # Access by (name, number, insertion)
residue = chain_A[0] # Access by index
# Access atoms within residues
atom = residue['CA'] # Access by atom name
atom = residue[0] # Access by index
# Complete hierarchical access
ca_atom = pdb['A']['GLN', 1, '']['CA'] # Chain A, GLN 1, CA atomfrom modelomics.PDB import PDB
# Load and clean structure
pdb = PDB("protein.pdb")
print(f"Original: {len(pdb.atoms)} atoms in {len(pdb.chains)} chains")
# Remove waters and heteroatoms
pdb.strip_waters() # Remove HOH residues
pdb.strip_hetatm() # Keep only ATOM records
print(f"Cleaned: {len(pdb.atoms)} atoms")
# Access cleaned structure
for chain_id, chain in pdb.chains.items():
print(f"Chain {chain_id}: {len(chain.residues)} residues")
for residue in chain._residue_list[:3]: # First 3 residues
print(f" {residue.name}{residue.number}: {len(residue.atoms)} atoms")from modelomics import sequence_embeddings
# Extract sequences from structures
seq_cif = sequence_embeddings.sequence_from_cif("protein.cif", chain='B')
seq_pdb = sequence_embeddings.sequence_from_pdb("protein.pdb", chain='A')
print("Sequence:", seq_pdb)
# Generate ESM-C protein language model embeddings (default)
embedding_esmc = sequence_embeddings.embed_sequence(seq_pdb, model="esmc")
print("ESM-C embedding shape:", embedding_esmc.shape) # [1, seq_len+2, 960]
# Generate E1 protein language model embeddings (requires Python 3.12)
embedding_e1 = sequence_embeddings.embed_sequence(seq_pdb, model="e1", model_size="150m")
print("E1 embedding shape:", embedding_e1.shape) # [seq_len, hidden_dim]
# Generate ProtT5-XL embeddings (requires separate venv)
embedding_prott5 = sequence_embeddings.embed_sequence(seq_pdb, model="prott5")
print("ProtT5 embedding shape:", embedding_prott5.shape) # [seq_len, 1024]
# Create masked embeddings for mutation analysis (ESM-C/ESM3 only)
masked_embedding = sequence_embeddings.embed_sequence(seq_pdb, model="esmc", mask_positions=[5, 10])
print("Masked embedding shape:", masked_embedding.shape)from modelomics import PDB, Graph
import torch
# Load and prepare protein structure
pdb = PDB("protein.pdb")
pdb.strip_waters()
pdb.rename_to_charmm() # Standardize atom naming
# Create rich residue-level graph with comprehensive features
graph = Graph(pdb["A"], cutoff=15.0)
print(f"Graph: {graph.num_nodes} residues, {graph.num_edges} edges")
print(f"Node features: {graph.x.shape} (971D: 960 ESM + 5 physicochemical + 5 SASA + 1 NMA)")
print(f"Edge features: {graph.edge_attr.shape} (distance + covalent + H-bonds + hydrophobic)")
# Access rich structural features
print("\nNode feature breakdown:")
print(f"- ESM-C embeddings: {graph.x[:, :960].shape}")
print(f"- Physicochemical properties: {graph.x[:, 960:965].shape}")
print(f"- SASA features: {graph.x[:, 965:970].shape}")
print(f"- Normal mode analysis: {graph.x[:, 970:971].shape}")
# Examine edge features for molecular interactions
print(f"\nEdge features: [distance, covalent_bond, hydrogen_bond, hydrophobic_contact]")
print(f"Sample edges: {graph.edge_attr[:5]}")
# Ready for PyTorch Geometric neural networks
print(f"\nPyTorch Geometric Data object: {type(graph)}")
print(f"Device ready: {graph.x.device}")from modelomics import PDB, VDWPointCloud
# Load and prepare structure
pdb = PDB("protein.pdb")
pdb.strip_waters()
chain_atoms = pdb['A'].atoms
# Generate high-quality molecular surface
pc = VDWPointCloud(chain_atoms, N=92, probe_radius=1.4)
pc.populate() # Generate Fibonacci spheres on all atoms
pc.remove_buried() # KDTree-based buried point removal
# Comprehensive SASA analysis
total_sasa = pc.sasa_by_type()
print("Global SASA breakdown:")
for sasa_type, value in total_sasa.items():
print(f" {sasa_type}: {value:.2f} Ų")
# Residue-specific SASA for binding site analysis
binding_site_residues = [pdb['A'][i] for i in range(10, 20)] # Example binding site
site_sasa = pc.residue_sasa_by_type(binding_site_residues)
print(f"\nBinding site SASA: {site_sasa['total']:.2f} Ų")
print(f"Hydrophobic surface: {site_sasa['nonpolar']:.2f} Ų")
# Per-atom SASA calculations
for i, atom in enumerate(chain_atoms[:5]):
atom_sasa = pc.get_atom_sasa(i)
print(f"{atom.residue}{atom.resnum} {atom.name}: {atom_sasa:.2f} Ų")
# Export surface for molecular visualization
pc.write_points("surface.xyz")
total_points = sum(len(pts) for pts in pc.points)
print(f"\nExported {total_points} surface points to surface.xyz")from modelomics import PDB
# Load and prepare protein complex
pdb = PDB("complex.pdb")
pdb.strip_waters()
pdb.rename_to_charmm()
# Advanced residue interaction analysis
chain_a = pdb['A']
chain_b = pdb['B']
# Find interface residues with molecular interactions
interface_pairs = []
for res_a in chain_a._residue_list:
for res_b in chain_b._residue_list:
# Check all types of molecular interactions
if res_a.covalent_bond(res_b):
interface_pairs.append((res_a, res_b, "covalent"))
elif res_a.hydrogen_bond(res_b):
interface_pairs.append((res_a, res_b, "hydrogen_bond"))
print(f"Found {len(interface_pairs)} interface interactions:")
for res1, res2, interaction_type in interface_pairs[:10]: # First 10
pos1 = res1.pos
pos2 = res2.pos
distance = ((pos1[0]-pos2[0])**2 + (pos1[1]-pos2[1])**2 + (pos1[2]-pos2[2])**2)**0.5
print(f"{res1.name}{res1.number} - {res2.name}{res2.number}: {interaction_type} ({distance:.2f}Å)")