科研 Skill
分子机器学习特征化
molfeat
Converts molecules into ML-ready features using 100+ pretrained and hand-crafted featurizers. Use for QSAR modeling or virtual-screening feature generation at scale.
SKILL.md
Molfeat - Molecular Featurization Hub
Overview
Molfeat is a comprehensive Python library for molecular featurization that unifies 100+ pre-trained embeddings and hand-crafted featurizers. Convert chemical structures (SMILES strings or RDKit molecules) into numerical representations for machine learning tasks including QSAR modeling, virtual screening, similarity searching, and deep learning applications. Features fast parallel processing, scikit-learn compatible transformers, and built-in caching.
Version note: Examples target molfeat 0.11.0 (PyPI stable, May 2025). Requires Python 3.9–3.10 (requires-python caps below 3.11). Depends on datamol ≥0.8.0 and PyTorch ≥1.13. Since 0.8.7, prefer datamol Mol objects over raw rdkit.Chem.Mol. Since 0.10.1, fingerprint calculators use RDKit's rdFingerprintGenerator API internally. Since 0.11.0, pretrained models load in memory and base models are set to PyTorch evaluation mode automatically.
When to Use This Skill
This skill should be used when working with:
- Molecular machine learning: Building QSAR/QSPR models, property prediction
- Virtual screening: Ranking compound libraries for biological activity
- Similarity searching: Finding structurally similar molecules
- Chemical space analysis: Clustering, visualization, dimensionality reduction
- Deep learning: Training neural networks on molecular data
- Featurization pipelines: Converting SMILES to ML-ready representations
- Cheminformatics: Any task requiring molecular feature extraction
Installation
Use a Python 3.9 or 3.10 environment (molfeat does not install on 3.11+ as of 0.11.0):
uv pip install "molfeat==0.11.0"
# With all pip-installable optional dependencies
uv pip install "molfeat[all]==0.11.0"
Optional dependency extras (PyPI):
molfeat[dgl]— GNN models (GIN variants); upstream recommendsdgl<=2.0(graphbolt issues in newer DGL)molfeat[graphormer]— Graphormer modelsmolfeat[transformer]— ChemBERTa, ChemGPT, MolT5molfeat[fcd]— FCD descriptorsmolfeat[pyg]— PyTorch Geometric featurizersmolfeat[viz]— NGLView visualization widgets
External featurizers: MAP4 is not bundled in molfeat extras — install from reymond-group/map4 separately. Some heavy deps (DGL, dgllife, graphormer-pretrained) are easier via conda-forge; see optional dependencies.
Core Concepts
Molfeat organizes featurization into three hierarchical classes:
1. Calculators (molfeat.calc)
Callable objects that convert individual molecules into feature vectors. Accept RDKit Chem.Mol objects or SMILES strings.
Use calculators for:
- Single molecule featurization
- Custom processing loops
- Direct feature computation
Example:
from molfeat.calc import FPCalculator
calc = FPCalculator("ecfp", radius=3, fpSize=2048)
features = calc("CCO") # Returns numpy array (2048,)
2. Transformers (molfeat.trans)
Scikit-learn compatible transformers that wrap calculators for batch processing with parallelization.
Use transformers for:
- Batch featurization of molecular datasets
- Integration with scikit-learn pipelines
- Parallel processing (automatic CPU utilization)
Example:
from molfeat.trans import MoleculeTransformer
from molfeat.calc import FPCalculator
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
features = transformer(smiles_list) # Parallel processing
3. Pretrained Transformers (molfeat.trans.pretrained)
Specialized transformers for deep learning models with batched inference and caching.
Use pretrained transformers for:
- State-of-the-art molecular embeddings
- Transfer learning from large chemical datasets
- Deep learning feature extraction
Example:
from molfeat.trans.pretrained import PretrainedMolTransformer
transformer = PretrainedMolTransformer("ChemBERTa-77M-MLM", n_jobs=-1)
embeddings = transformer(smiles_list) # Deep learning embeddings
Quick Start Workflow
Basic Featurization
import datamol as dm
from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer
# Load molecular data
smiles = ["CCO", "CC(=O)O", "c1ccccc1", "CC(C)O"]
# Create calculator and transformer
calc = FPCalculator("ecfp", radius=3)
transformer = MoleculeTransformer(calc, n_jobs=-1)
# Featurize molecules
features = transformer(smiles)
print(f"Shape: {features.shape}") # (4, 2048)
Save and Load Configuration
# Save featurizer configuration for reproducibility
transformer.to_state_yaml_file("featurizer_config.yml")
# Reload exact configuration
loaded = MoleculeTransformer.from_state_yaml_file("featurizer_config.yml")
Handle Errors Gracefully
# Process dataset with potentially invalid SMILES
transformer = MoleculeTransformer(
calc,
n_jobs=-1,
ignore_errors=True, # Continue on failures
verbose=True # Log error details
)
features = transformer(smiles_with_errors)
# Returns None for failed molecules
Choosing the Right Featurizer
For Traditional Machine Learning (RF, SVM, XGBoost)
Start with fingerprints:
# ECFP - Most popular, general-purpose
FPCalculator("ecfp", radius=3, fpSize=2048)
# MACCS - Fast, good for scaffold hopping
FPCalculator("maccs")
# MAP4 - Efficient for large-scale screening
FPCalculator("map4")
For interpretable models:
# RDKit 2D descriptors (200+ named properties)
from molfeat.calc import RDKitDescriptors2D
RDKitDescriptors2D()
# Mordred (1800+ comprehensive descriptors)
from molfeat.calc import MordredDescriptors
MordredDescriptors()
Combine multiple featurizers:
from molfeat.trans import FeatConcat
concat = FeatConcat([
FPCalculator("maccs"), # 167 dimensions
FPCalculator("ecfp") # 2048 dimensions
]) # Result: 2215-dimensional combined features
For Deep Learning
Transformer-based embeddings:
# ChemBERTa - Pre-trained on 77M PubChem compounds
PretrainedMolTransformer("ChemBERTa-77M-MLM")
# ChemGPT - Autoregressive language model
PretrainedMolTransformer("ChemGPT-1.2B")
Graph neural networks:
# GIN models with different pre-training objectives
PretrainedMolTransformer("gin-supervised-masking")
PretrainedMolTransformer("gin-supervised-infomax")
# Graphormer for quantum chemistry
PretrainedMolTransformer("Graphormer-pcqm4mv2")
For Similarity Searching
# ECFP - General purpose, most widely used
FPCalculator("ecfp")
# MACCS - Fast, scaffold-based similarity
FPCalculator("maccs")
# MAP4 - Efficient for large databases
FPCalculator("map4")
# USR/USRCAT - 3D shape similarity
from molfeat.calc import USRDescriptors
USRDescriptors()
For Pharmacophore-Based Approaches
# FCFP - Functional group based
FPCalculator("fcfp")
# CATS - Pharmacophore pair distributions
from molfeat.calc import CATSCalculator
CATSCalculator(mode="2D")
# Gobbi - Explicit pharmacophore features
FPCalculator("gobbi2D")
Common Workflows
Building a QSAR Model
from molfeat.trans import MoleculeTransformer
from molfeat.calc import FPCalculator
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import cross_val_score
# Featurize molecules
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
X = transformer(smiles_train)
# Train model
model = RandomForestRegressor(n_estimators=100)
scores = cross_val_score(model, X, y_train, cv=5)
print(f"R² = {scores.mean():.3f}")
# Save configuration for deployment
transformer.to_state_yaml_file("production_featurizer.yml")
Virtual Screening Pipeline
from sklearn.ensemble import RandomForestClassifier
# Train on known actives/inactives
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
X_train = transformer(train_smiles)
clf = RandomForestClassifier(n_estimators=500)
clf.fit(X_train, train_labels)
# Screen large library
X_screen = transformer(screening_library) # e.g., 1M compounds
predictions = clf.predict_proba(X_screen)[:, 1]
# Rank and select top hits
top_indices = predictions.argsort()[::-1][:1000]
top_hits = [screening_library[i] for i in top_indices]
Similarity Search
from sklearn.metrics.pairwise import cosine_similarity
# Query molecule
calc = FPCalculator("ecfp")
query_fp = calc(query_smiles).reshape(1, -1)
# Database fingerprints
transformer = MoleculeTransformer(calc, n_jobs=-1)
database_fps = transformer(database_smiles)
# Compute similarity
similarities = cosine_similarity(query_fp, database_fps)[0]
top_similar = similarities.argsort()[-10:][::-1]
Scikit-learn Pipeline Integration
from sklearn.pipeline import Pipeline
from sklearn.ensemble import RandomForestClassifier
# Create end-to-end pipeline
pipeline = Pipeline([
('featurizer', MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)),
('classifier', RandomForestClassifier(n_estimators=100))
])
# Train and predict directly on SMILES
pipeline.fit(smiles_train, y_train)
predictions = pipeline.predict(smiles_test)
Comparing Multiple Featurizers
featurizers = {
'ECFP': FPCalculator("ecfp"),
'MACCS': FPCalculator("maccs"),
'Descriptors': RDKitDescriptors2D(),
'ChemBERTa': PretrainedMolTransformer("ChemBERTa-77M-MLM")
}
results = {}
for name, feat in featurizers.items():
transformer = MoleculeTransformer(feat, n_jobs=-1)
X = transformer(smiles)
# Evaluate with your ML model
score = score_model(X, y)
results[name] = score
Discovering Available Featurizers
Use the ModelStore to explore all available featurizers:
from molfeat.store.modelstore import ModelStore
store = ModelStore()
# List all available models
all_models = store.available_models
print(f"Total featurizers: {len(all_models)}")
# Search for specific models
chemberta_models = store.search(name="ChemBERTa")
for model in chemberta_models:
print(f"- {model.name}: {model.description}")
# Get usage information
model_card = store.search(name="ChemBERTa-77M-MLM")[0]
model_card.usage() # Display usage examples
# Load model
transformer = store.load("ChemBERTa-77M-MLM")
Advanced Features
Custom Preprocessing
class CustomTransformer(MoleculeTransformer):
def preprocess(self, mol):
"""Custom preprocessing pipeline"""
if isinstance(mol, str):
mol = dm.to_mol(mol)
mol = dm.standardize_mol(mol)
mol = dm.remove_salts(mol)
return mol
transformer = CustomTransformer(FPCalculator("ecfp"), n_jobs=-1)
Batch Processing Large Datasets
import numpy as np
def featurize_in_chunks(smiles_list, transformer, chunk_size=10000):
"""Process large datasets in chunks to manage memory"""
all_features = []
for i in range(0, len(smiles_list), chunk_size):
chunk = smiles_list[i:i+chunk_size]
features = transformer(chunk)
all_features.append(features)
return np.vstack(all_features)
Caching Expensive Embeddings
Prefer molfeat's built-in pretrained-model cache when possible. For custom embedding caches, use NumPy arrays instead of pickle (pickle can execute arbitrary code when loading untrusted files):
import numpy as np
from pathlib import Path
cache_file = Path("embeddings_cache.npz") # fixed path under your project
transformer = PretrainedMolTransformer("ChemBERTa-77M-MLM", n_jobs=-1)
if cache_file.exists():
embeddings = np.load(cache_file)["embeddings"]
else:
embeddings = transformer(smiles_list)
np.savez(cache_file, embeddings=embeddings)
Performance Tips
- Use parallelization: Set
n_jobs=-1to utilize all CPU cores - Batch processing: Process multiple molecules at once instead of loops
- Choose appropriate featurizers: Fingerprints are faster than deep learning models
- Cache pretrained models: Leverage built-in caching for repeated use
- Use float32: Set
dtype=np.float32when precision allows - Handle errors efficiently: Use
ignore_errors=Truefor large datasets
Common Featurizers Reference
Quick reference for frequently used featurizers:
| Featurizer | Type | Dimensions | Speed | Use Case |
|---|---|---|---|---|
ecfp | Fingerprint | 2048 | Fast | General purpose |
maccs | Fingerprint | 167 | Very fast | Scaffold similarity |
desc2D | Descriptors | 200+ | Fast | Interpretable models |
mordred | Descriptors | 1800+ | Medium | Comprehensive features |
map4 | Fingerprint | 1024 | Fast | Large-scale screening |
ChemBERTa-77M-MLM | Deep learning | 768 | Slow* | Transfer learning |
gin-supervised-masking | GNN | Variable | Slow* | Graph-based models |
*First run is slow; subsequent runs benefit from caching
Resources
This skill includes comprehensive reference documentation:
references/api_reference.md
Complete API documentation covering:
molfeat.calc- All calculator classes and parametersmolfeat.trans- Transformer classes and methodsmolfeat.store- ModelStore usage- Common patterns and integration examples
- Performance optimization tips
When to load: Reference when implementing specific calculators, understanding transformer parameters, or integrating with scikit-learn/PyTorch.
references/available_featurizers.md
Comprehensive catalog of all 100+ featurizers organized by category:
- Transformer-based language models (ChemBERTa, ChemGPT)
- Graph neural networks (GIN, Graphormer)
- Molecular descriptors (RDKit, Mordred)
- Fingerprints (ECFP, MACCS, MAP4, and 15+ others)
- Pharmacophore descriptors (CATS, Gobbi)
- Shape descriptors (USR, ElectroShape)
- Scaffold-based descriptors
When to load: Reference when selecting the optimal featurizer for a specific task, exploring available options, or understanding featurizer characteristics.
Search tip: Use grep to find specific featurizer types:
grep -i "chembert" references/available_featurizers.md
grep -i "pharmacophore" references/available_featurizers.md
references/examples.md
Practical code examples for common scenarios:
- Installation and quick start
- Calculator and transformer examples
- Pretrained model usage
- Scikit-learn and PyTorch integration
- Virtual screening workflows
- QSAR model building
- Similarity searching
- Troubleshooting and best practices
When to load: Reference when implementing specific workflows, troubleshooting issues, or learning molfeat patterns.
Troubleshooting
Invalid Molecules
Enable error handling to skip invalid SMILES:
transformer = MoleculeTransformer(
calc,
ignore_errors=True,
verbose=True
)
Memory Issues with Large Datasets
Process in chunks or use streaming approaches for datasets > 100K molecules.
Pretrained Model Dependencies
Some models require additional packages. Install specific extras (pin version for reproducibility):
uv pip install "molfeat[transformer]==0.11.0" # For ChemBERTa/ChemGPT
uv pip install "molfeat[dgl]==0.11.0" # For GIN models
uv pip install "molfeat[graphormer]==0.11.0" # For Graphormer
Reproducibility
Save exact configurations and document versions:
transformer.to_state_yaml_file("config.yml")
import molfeat
print(f"molfeat version: {molfeat.__version__}")
Additional Resources
- Official Documentation: https://molfeat-docs.datamol.io/
- GitHub Repository: https://github.com/datamol-io/molfeat
- PyPI Package: https://pypi.org/project/molfeat/
- Tutorial: https://portal.valencelabs.com/datamol/post/types-of-featurizers-b1e8HHrbFMkbun6
示例提示词
我想用molfeat调用ChemBERTa预训练模型给化合物生成QSAR特征。
所属插件
安装该插件会一并获得同领域的 32 个 Skill / MCP。
同插件的其他科研 Skill
- ASE原子模拟环境Builds and analyzes atomic structures with ASE: geometry optimization, NEB transition states, and MD trajectories. Use for setting up or analyzing atomistic simulations.
- 电池材料计算工作流Guides DFT/pymatgen workflows for battery materials: voltage profiles, phase stability, and ion migration barriers. Use for cathode, anode, or electrolyte computation.
- 催化剂设计指导Advises on catalyst composition, structure, and synthesis strategy using a traceable methodology base. Use when designing or optimizing a catalyst for a given reaction.
- 催化文献检索整理Searches arXiv, OpenAlex, and journal sites for catalysis literature and outputs a structured matrix. Use for catalysis literature reviews on a reaction or material system.
- ChEMBL生物活性数据查询Queries the ChEMBL API for bioactivity data: target lookup, IC50/Ki retrieval, and SAR tables. Use to build bioactivity datasets for a protein target.
- 量子化学计算工作流Guides quantum chemistry workflows with ORCA and xTB: geometry optimization, thermochemistry, and transition-state search. Use for first-principles energy calculations.
- 分子描述符与指纹计算Computes versioned 2D descriptors, Morgan/MACCS fingerprints, and dataset quality profiles with fixed RDKit. Use to generate reproducible features or audit data quality.
- 腐蚀电化学分析Guides corrosion analysis: electrode potentials, polarization curves, impedance, and Pourbaix diagrams. Use for electrochemical stability or corrosion-kinetics reasoning.
- 化学反应数据整理Curates structured single-step reactions against an ORD schema and RDKit, preserving originals. Use to clean reaction SMILES or tables and flag duplicates or mass-balance issues.
- RDKit简化分子处理Wraps RDKit with sensible defaults for SMILES parsing, standardization, descriptors, and conformers. Use for standard drug-discovery tasks; use rdkit for advanced control.
- 红外拉曼光谱分析Processes IR and Raman spectra with baseline correction, peak picking, and functional-group assignment. Use to interpret vibrational spectra against reference data.
- 质谱相似性比对Computes spectral similarity scores and identifies unknown compounds from mass-spectral libraries. Use for metabolite identification; use pyopenms for full proteomics pipelines.
- 分子动力学轨迹分析Analyzes MD trajectories from GROMACS, AMBER, LAMMPS, or NAMD with MDAnalysis: RMSD, RMSF, and contact maps. Use when analyzing existing trajectory files.
- 药物化学分子过滤Applies drug-likeness rules and structural alert catalogs (PAINS, NIBR) to compound libraries. Use for triaging compound libraries early in drug discovery.
- 分子数据集构建与清洗Guides molecular ML dataset building: source selection, deduplication, unit harmonization, and leakage-aware splits. Use before training molecular property models.
- 分子特征化方法Guides molecular featurization strategy for ML: parsing, fingerprints, and descriptor selection. Use when designing a featurization pipeline before model training.
- 核磁共振谱图分析Processes raw NMR FID data through Fourier transform and phase correction, then picks peaks with nmrglue. Use for processing and interpreting 1D/2D NMR spectra.
- 化学文件格式转换Converts chemical file formats and generates 3D coordinates and conformers with OpenBabel and RDKit. Use when interconverting structure formats or generating 3D structures.
- 粉末XRD物相分析Simulates powder XRD patterns from candidate structures and matches them to an experimental pattern. Use for phase ID; use dedicated software for full Rietveld refinement.
- pymatgen晶体材料分析Manipulates crystal structures and queries the Materials Project API for band gaps and formation energies. Use for computational materials science on crystal structures.
- 蛋白质组质谱分析Processes proteomics and metabolomics MS data via OpenMS bindings: feature detection and peptide ID. Use for LC-MS/MS pipelines; use matchms for simpler spectral comparison.
- PySCF量子化学计算Runs ab initio and DFT calculations with PySCF: HF/DFT energies, optimization, and MP2/CCSD(T). Use for first-principles molecular energy and property calculations.
- RDKit化学信息学Provides fine-grained RDKit control: I/O, descriptors, fingerprints, substructure search, and reactions. Use for advanced workflows; use datamol for a simpler interface.
- 化学物质身份解析Resolves chemical names, SMILES, InChI, or registry IDs into auditable records, preserving ambiguity. Use to confirm a chemical’s identity before standardization.
常见问题
分子机器学习特征化能做什么?
Converts molecules into ML-ready features using 100+ pretrained and hand-crafted featurizers. Use for QSAR modeling or virtual-screening feature generation at scale。
如何安装分子机器学习特征化?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「分子机器学习特征化」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
分子机器学习特征化需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
分子机器学习特征化经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。