Molfeat - Molecular Featurization Hub
Overview
Molfeat turns molecules (SMILES strings or RDKit/datamol Mol objects) into numerical
representations for machine learning: fingerprints, descriptors, pharmacophores, shape
descriptors, and pretrained neural embeddings, all behind one scikit-learn-compatible
transformer interface with state serialization and caching.
Current baseline (verified 2026-08-16): molfeat 0.11.0 (May 2025) is still the latest
PyPI and GitHub release; the repository has had no commits since. All examples in this skill
were executed against 0.11.0 on Python 3.10 with datamol 0.12.5, RDKit 2026.03.5, numpy
2.2.6 and torch 2.13.0. Python 3.11+ is not installable (requires-python = ">=3.9,<3.11").
The Python cap isolates this skill from the rest of the bundle. Nothing else here needs an
interpreter below 3.11, so molfeat requires its own environment and cannot share one with
admet-prediction (3.11+), pytdc, or deepchem. That is manageable for a featurisation step
that writes a matrix to disk, and painful for anything interactive. For new work where the
featuriser is not itself the point, RDKit or datamol fingerprints plus a Chemprop or scikit-learn
model reach the same place without the constraint; use molfeat when you specifically want its
breadth of featurisers behind one interface.
0.11.0 loads pretrained models in memory, sets base models to eval mode, and moved the model
store to a Cloudflare HTTP bucket (PR #115) — that last change broke store downloads for the
HuggingFace models (see Pretrained models).
When to Use This Skill
- Converting SMILES into ML-ready feature matrices (QSAR/QSPR, ADMET, activity prediction)
- Virtual screening: featurize a library, score it with a trained model
- Similarity searching and chemical-space analysis (clustering, UMAP/t-SNE)
- Benchmarking several representations against each other on the same task
- Building reproducible featurization pipelines that can be serialized and reloaded
For raw cheminformatics control (custom sanitization, reactions, substructures) use rdkit or
datamol directly; molfeat is the layer above them that produces feature matrices.
Installation
uv venv --python 3.10 && uv pip install "molfeat==0.11.0"
Optional extras (all pin-able the same way):
| Extra | Enables | Note |
|---|
molfeat[transformer] | ChemBERTa, ChemGPT, MolT5, GPT2/Roberta-Zinc | Pins tokenizers<0.13.2, so it resolves to transformers 4.33.x |
molfeat[dgl] | GIN variants, JTVAE | Needs dgl>=1.1.1,<=2.0; conda-forge is easier than PyPI |
molfeat[graphormer] | pcqm4mv2_graphormer_base | graphormer-pretrained |
molfeat[fcd] | FCD descriptors | |
molfeat[pyg] | PyTorch Geometric featurizers | |
molfeat[viz] | NGLView widgets | |
MAP4 is not a molfeat extra. FPCalculator("map4") raises ImportError: Cannot import map4 until you install it from reymond-group/map4.
Three Things to Get Right First
These three calls are where most molfeat scripts go wrong; everything else follows the docs.
import numpy as np
from molfeat.trans import MoleculeTransformer
# 1. Without `dtype`, the transformer returns a LIST of arrays, not a matrix.
# `features.shape` raises AttributeError. Pass dtype to get an ndarray.
transformer = MoleculeTransformer("ecfp", dtype=np.float32)
# 2. `ignore_errors` is a CALL argument, not a constructor argument. Passing it to
# the constructor is silently swallowed by **params and does nothing.
features, valid_ids = transformer(smiles, ignore_errors=True)
# 3. With ignore_errors=True, __call__ returns (features, ids) and DROPS failures.
# Realign the labels with `ids` or the rows no longer match y.
y = np.asarray(y)[valid_ids]
transformer.transform(smiles, ignore_errors=True) is the other half of the pair: it returns a
plain list with None in the failed positions instead of dropping them.
Core Concepts
1. Calculators (molfeat.calc)
Callable objects that featurize one molecule. Exported from molfeat.calc: FPCalculator,
RDKitDescriptors2D, RDKitDescriptors3D, MordredDescriptors, CATS, Pharmacophore2D,
Pharmacophore3D, USRDescriptors, ElectroShapeDescriptors, ScaffoldKeyCalculator,
plus the SerializableCalculator base class. Atom- and bond-level calculators for GNN input
live one level deeper, in molfeat.calc.atom and molfeat.calc.bond.
from molfeat.calc import FPCalculator, get_calculator
calc = FPCalculator("ecfp", radius=2, fpSize=2048) # radius 2 is the default (= ECFP4)
fp = calc("CCO") # numpy uint8 array, shape (2048,)
len(calc) # 2048
calc.columns[:3] # ['fp_0', 'fp_1', 'fp_2']
calc = get_calculator("desc2D") # factory: any built-in by name
get_calculator accepts every name in FP_FUNCS plus desc2D, desc3D, mordred, cats,
cats2D, cats3D, pharm2D, pharm3D, usr*, electroshape, and scaffoldkeys.
2. Transformers (molfeat.trans)
MoleculeTransformer wraps a calculator (or a calculator name) for batch use and plugs into
scikit-learn pipelines. FPVecTransformer is the fingerprint-specific shortcut, and unlike
MoleculeTransformer it defaults to dtype=np.float32, so it returns an array out of the box.
import numpy as np
from molfeat.trans import MoleculeTransformer, FPVecTransformer, FeatConcat
t = MoleculeTransformer("ecfp", n_jobs=1, dtype=np.float32)
X = t(smiles) # (n, 2048) float32
fp = FPVecTransformer(kind="ecfp:4", length=1024) # "name:diameter"; length defaults to 2000
X = fp(smiles) # (n, 1024) float32
both = FeatConcat(["maccs", "ecfp"], dtype=np.float32)
X = both(smiles) # (n, 2167) — 167 + 2048
FeatConcat is itself a transformer. Do not wrap it in MoleculeTransformer.
3. Pretrained transformers (molfeat.trans.pretrained)
One class per backend — there is no generic "load by name" transformer:
| Class | For | Example |
|---|
PretrainedHFTransformer | ChemBERTa, ChemGPT, MolT5, GPT2/Roberta-Zinc | PretrainedHFTransformer(kind="ChemBERTa-77M-MLM", notation="smiles") |
PretrainedDGLTransformer | GIN variants, JTVAE | PretrainedDGLTransformer(kind="gin_supervised_masking", dtype=float) |
GraphormerTransformer | Graphormer | GraphormerTransformer(kind="pcqm4mv2_graphormer_base", dtype=float) |
FCDTransformer | FCD embeddings | FCDTransformer() |
PretrainedMolTransformer is the abstract base for these — instantiating it with a model name
does not work.
Pretrained models
The 8 HuggingFace models in the model store cannot be downloaded from it. Since 0.11.0
serves artifacts over plain HTTP, HTTPFileSystem.find() reports the artifact directory itself
as a file, so datamol's copy_dir tries to write a file over the destination directory:
IsADirectoryError: [Errno 21] Is a directory: '~/Library/Caches/molfeat/ChemBERTa-77M-MLM/model.save'
ModelStoreError: Can't retrieve model ChemBERTa-77M-MLM from the store !
This is not a version-pin problem — it reproduces on fsspec 2024.6.1, 2025.3.0 and 2026.7.0 —
and it is open upstream as
#119 and
#120. It affects only the 8 HuggingFace
cards (ChemBERTa x2, ChemGPT x3, MolT5, GPT2-Zinc480M-87M, Roberta-Zinc480M-102M); the 36
other cards are single-file artifacts and download normally.
Load those models from the HuggingFace Hub instead — verified working:
import numpy as np
from molfeat.trans.pretrained.hf_transformers import HFModel, PretrainedHFTransformer
model = HFModel.from_pretrained("DeepChem/ChemBERTa-77M-MLM", "DeepChem/ChemBERTa-77M-MLM")
transformer = PretrainedHFTransformer(kind=model, notation="smiles", dtype=np.float32)
X = transformer(["CCO", "CC(=O)O", "c1ccccc1"]) # (3, 384) float32, mean pooling
Note the width: ChemBERTa-77M is 384-dimensional, not 768. Check X.shape rather than
assuming a hidden size.
Pooling defaults to mean; avg, sum, and clf (CLS token) also work. pooling="max"
raises RuntimeError: masked_fill_ only supports boolean masks on current PyTorch — molfeat
builds a long mask — so avoid it.
Discovering featurizers
from molfeat.store.modelstore import ModelStore
store = ModelStore()
len(store.available_models) # 44 cards in 0.11.0
card = store.search(name="ChemBERTa-77M-MLM")[0]
print(card.name, card.group, card.inputs, card.description)
print(card.usage()) # returns the canonical snippet as a string
store.load(name) returns a (model, ModelInfo) tuple, not a transformer — use the
transformer classes above for featurization, and store.load only when you want the raw
artifact. A full name-by-name catalog is in
references/available_featurizers.md.
Quick Start
import numpy as np
import datamol as dm
from molfeat.trans import MoleculeTransformer
data = dm.data.freesolv() # 642 molecules: iupac, smiles, expt, calc
smiles = data.smiles.tolist()
transformer = MoleculeTransformer("ecfp", n_jobs=1, dtype=np.float32)
X, ids = transformer(smiles, ignore_errors=True)
y = data.expt.values[ids]
print(X.shape, y.shape) # (642, 2048) (642,)
Save and reload a configuration
transformer.to_state_yaml_file("featurizer.yml") # also to_state_json_file
loaded = MoleculeTransformer.from_state_yaml_file("featurizer.yml")
The state file records the molfeat version alongside the featurizer arguments, which is what
makes it worth committing next to a trained model.
Standardize before featurizing
preprocess() is a batch hook with the signature preprocess(inputs, labels), and transform
never calls it. Overriding it per-molecule does nothing. Standardize explicitly instead:
import datamol as dm
def clean(smi):
mol = dm.to_mol(smi)
if mol is None:
return None
# dont_remove_everything=True, or a molecule that IS a solvent comes back empty
mol = dm.remove_salts_solvents(mol, dont_remove_everything=True)
return dm.to_smiles(dm.standardize_mol(mol, disconnect_metals=True, uncharge=True))
clean_smiles = [s for s in dm.parallelized(clean, smiles, n_jobs=-1) if s]
X = transformer(clean_smiles)
(dm.remove_salts does not exist; the function is dm.remove_salts_solvents.)
Caching expensive featurization
Use molfeat's own cache rather than a hand-rolled dictionary — it hashes molecules canonically,
so a re-run hits the cache even when the input SMILES are written differently:
import numpy as np
from molfeat.trans import MoleculeTransformer
from molfeat.trans.base import PrecomputedMolTransformer
from molfeat.utils.cache import FileCache
base = MoleculeTransformer("desc2D", n_jobs=-1, dtype=np.float32)
cache = FileCache(cache_file="features.parquet", file_type="parquet", clear_on_exit=False)
featurizer = PrecomputedMolTransformer(cache=cache, featurizer=base, dtype=np.float32)
X = featurizer(smiles)
cache.save_to_file("features.parquet")
# next run
cache = FileCache.load_from_file("features.parquet", file_type="parquet")
featurizer = PrecomputedMolTransformer(cache=cache, featurizer=base, dtype=np.float32)
molfeat.utils.cache also offers in-memory DataCache, multiprocessing-safe MPDataCache,
and CacheList for chaining. Prefer these over pickling feature matrices yourself; if you do
persist arrays directly, use np.savez, not pickle, which executes code on load.
Parallelism: measure before setting n_jobs=-1
n_jobs=-1 is not free — molfeat parallelizes with joblib processes, and the pickling overhead
exceeds the work for cheap featurizers. Measured on 12 cores:
| Featurizer | Molecules | n_jobs=1 | n_jobs=-1 |
|---|
ecfp | 642 | 0.03 s | 0.13 s |
ecfp | 10,272 | 0.43 s | 0.56 s |
desc2D | 300 | 0.96 s | 0.23 s |
mordred | 300 | 4.83 s | 4.21 s |
Rule of thumb: keep n_jobs=1 for fingerprints at any scale, use n_jobs=-1 for descriptor
and conformer-dependent calculators (desc2D, desc3D, pharmacophores, shape), and don't
expect much from it for mordred, which does its own batching through batch_compute.
Choosing a Featurizer and Common Workflows
Featurizer choice by task — traditional ML (RF, SVM, XGBoost), deep learning, similarity
searching, pharmacophore-based approaches — plus worked workflows for QSAR model building,
virtual screening, similarity search, scikit-learn pipeline integration, and comparing
featurizers, are in
references/choosing_a_featurizer.md.
The full featurizer catalog with measured output widths is in
references/available_featurizers.md; more worked code is
in references/examples.md; class-by-class signatures are in
references/api_reference.md.
Common Featurizers Reference
Widths below are what molfeat 0.11.0 actually returns for default parameters.
| Featurizer | Type | Width | Speed | Use case |
|---|
ecfp | Fingerprint | 2048 | Fast | General purpose (radius 2 default) |
fcfp | Fingerprint | 2048 | Fast | Pharmacophore-flavored circular FP |
maccs | Fingerprint | 167 | Very fast | Scaffold similarity |
avalon | Fingerprint | 512 | Fast | Similarity searching |
erg | Reduced graph | 315 | Fast | Scaffold hopping |
estate | Descriptors | 79 | Fast | Electrotopological state |
desc2D | Descriptors | 223 | Medium | Interpretable models |
desc3D | Descriptors | 639 | Slow | Needs conformers |
mordred | Descriptors | 1613 | Slow | Comprehensive descriptor sweep |
cats2D | Pharmacophore | 189 | Medium | Pharmacophore pair distributions |
pharm2D | Pharmacophore | 2048 | Medium | factory="pmapper" by default |
usr / usrcat | Shape | 12 / 60 | Fast | 3D shape similarity (needs conformers) |
scaffoldkeys | Scaffold | 42 | Fast | Scaffold-level properties |
ChemBERTa-77M-MLM | Transformer | 384 | Slow | Transfer learning (load from HF Hub) |
gin_supervised_masking | GNN | 300 | Slow | Graph embeddings (needs molfeat[dgl]) |
Troubleshooting
AttributeError: 'list' object has no attribute 'shape' — the transformer has no dtype.
Construct it with dtype=np.float32 (or use FPVecTransformer).
ValueError: Cannot transform molecule at index i — an input failed to parse. Pass
ignore_errors=True to the call, and use the returned ids to realign labels. Set
verbose=True on the constructor to log which molecules failed.
ModelStoreError: Can't retrieve model <name> from the store! — the HuggingFace-artifact
download bug above. Load from the HF Hub with HFModel.from_pretrained.
A fingerprint parameter had no effect — FPCalculator logs unknown parameters as an error
and then drops them; construction still succeeds. FPCalculator("ecfp", n_bits=1024) returns
2048 dimensions (the key is fpSize). Check len(calc) after passing parameters.
ImportError: Cannot import map4 — MAP4 is external; install it from the reymond-group
repository.
Package will not install — check the interpreter first: molfeat 0.11.0 is capped below
Python 3.11 and pip/uv will refuse to resolve on 3.11+.
3D featurizers return errors or zeros — desc3D, usr, usrcat, electroshape,
cats3D and pharm3D need conformers. Generate them first with
dm.conformers.generate(mol, n_confs=1) and pass Mol objects, not SMILES.
Reproducibility — save to_state_yaml_file next to the model, and record
molfeat.__version__; state files carry the writing version in _molfeat_version.
Composing with the rest of the bundle
rdkit / datamol → before: standardise and desalt first. A featurizer embeds whatever
string it is given, so a salt or mixture produces a vector for the wrong species — and no error.chembl → before: curated measured bioactivity is what you want to featurize, not raw rows.pytdc → alongside: the scaffold and cold-start splits. Featurization quality is invisible under
a random split, which reports a fantasy R² regardless of the representation you chose.deepchem → after: model fitting, if you want the training loop rather than just the features.admet-prediction → instead: for standard ADMET endpoints, a ready-made model beats featurizing
and training from scratch unless you have your own measured data.chemical-space / generative-design → after: features are what a similarity or diversity
selection over an enumerated set is computed on.
Try ECFP first. Across most QSAR tasks a count-based Morgan fingerprint with a gradient-boosted
model is within noise of a pretrained transformer embedding, at a fraction of the cost. Reach for
pretrained embeddings when you have shown ECFP is the bottleneck, not before.
Additional Resources