CReM — chemically reasonable mutations

CReM is an open-source Python framework to generate chemical structures using a fragment-based approach.

The idea is similar to matched molecular pairs: fragments that occur in the same context are considered interchangeable. CReM stores such context–fragment relationships in a database and uses them to generate chemically valid structures.

Features

• Four generation modes — mutate, grow, link, and make_cycle (ring closure / macrocyclization).
• Custom fragment databases built in one step with cremdb_create, or downloaded as precompiled ChEMBL databases.
• Multiple fragment sets per database — switch between them at generation time with set_names and a frequency threshold (min_freq).
• Fine control — context radius, fragment-size windows, replaceable/protected atoms, and replace_cycles for partial-ring replacement.
• Custom selection — bias or restrict fragments with filter_func / sample_func, or with molecular-property columns.
• Reproducible and parallel — seed for deterministic sampling; ncores and picklable *_mol2 wrappers for multiprocessing.

Links

• Documentation: https://crem.readthedocs.io/
• Tutorials: https://github.com/DrrDom/crem-tutorials
• Web app: https://crem.imtm.cz/
• Precompiled fragment databases: http://www.qsar4u.com/pages/crem.php
• Changelog: changelog

Installation

pip install crem

From source:

git clone https://github.com/DrrDom/crem
cd crem
pip install .

CReM requires rdkit>=2025.3.5. Optional extras: guacamol (to run the benchmark) and zstandard (to read .zst-compressed input when building databases).

Quick start

Worked tutorials — three Jupyter notebooks and eighteen one-page reference cards — live in a separate repository: https://github.com/DrrDom/crem-tutorials.

All examples assume a fragment database fragments.db — build one or download a precompiled ChEMBL database.

from rdkit import Chem
from crem.crem import mutate_mol, grow_mol, link_mols, make_cycle

m = Chem.MolFromSmiles('c1cc(OC)ccc1C')          # methoxytoluene

# replace an existing fragment
mutants = list(mutate_mol(m, db_name='fragments.db', max_size=1))

# decorate by replacing a hydrogen
grown = list(grow_mol(m, db_name='fragments.db'))

# link two molecules with a linker
m2 = Chem.MolFromSmiles('NCC(=O)O')              # glycine
linked = list(link_mols(m, m2, db_name='fragments.db'))

# form a new ring
cyclic = list(make_cycle(m, db_name='fragments.db', ring_size=(5, 7)))

All four are generators (wrap in list(...)) and share many options — radius, size windows, min_freq / set_names, replace_ids / protected_ids, filter_func / sample_func, max_replacements, seed, and ncores. See Mutate, grow, link, Advanced fragment selection, and the API reference.

Build a fragment database

Build a database directly from a SMILES file in one step:

cremdb_create -i input.smi -o fragments.db -s chembl

This produces the current database format with fragment-set support and ring-closure fragments. For multiple sets, property columns, sharded/parallel builds, conversion of older databases, and the programmatic crem.db API, see Fragment databases.

Benchmarks

GuacaMol goal-directed benchmark (scores marked * are from the original GuacaMol publication):

Limitations

• Very large molecules are skipped in some workflows: a molecule with more than 30 non-ring single bonds is not mutated, and one with more than 100 hydrogen atoms is not grown or linked.
• Context canonicalization relies on RDKit's SMILES output. A database is best used with the RDKit version it was built with (no incompatibilities observed so far); pin RDKit when sharing databases across machines.

License

BSD-3-Clause. See LICENSE.txt.

Citation

CReM: chemically reasonable mutations framework for structure generation Pavel Polishchuk Journal of Cheminformatics 2020, 12, (1), 28 https://doi.org/10.1186/s13321-020-00431-w

Control of Synthetic Feasibility of Compounds Generated with CReM Pavel Polishchuk Journal of Chemical Information and Modeling 2020, 60, 6074-6080 https://dx.doi.org/10.1021/acs.jcim.0c00792