Medchem

Medchem

Overview

Medchem is a Python library from datamol-io for molecular filtering and prioritization in drug discovery. Apply literature-derived drug-likeness rules, named alert catalogs, complexity thresholds, chemical-group detection, and a custom query language to triage compound libraries at scale. Filters are context-specific guidelines — combine with domain expertise and target knowledge.

Verified runtime: medchem 2.1.1, datamol 0.13.0, RDKit 2026.3.6; Python 3.11+. RuleFilters and structural classes return pandas DataFrames. Filters run locally; installation and documentation lookup need network access. Lilly native execution was not tested in this review.

When to Use This Skill

This skill should be used when:

• Applying drug-likeness rules (Lipinski, Veber, CNS, lead-like) to compound libraries
• Filtering molecules by structural alerts, PAINS, or NIBR screening-deck rules
• Prioritizing compounds for hit-to-lead or lead optimization
• Calculating complexity metrics against ZINC-derived thresholds
• Detecting functional groups or named substructure catalogs
• Building multi-criteria filters with the medchem query language

Installation

uv pip install "medchem==2.1.1" "datamol==0.13.0" "rdkit==2026.3.6"

Optional Lilly integration: install the upstream checksum-pinned native tools beside the active Python. This downloads source, builds executables, and runs native regression tests (C++ compiler, make, zlib, Ruby; WSL on Windows). This installation command is documented upstream, not executed here:

medchem install-lilly

Core Capabilities

1. Medicinal Chemistry Rules

Apply established drug-likeness rules via medchem.rules.

List available rules:

import medchem as mc

mc.rules.RuleFilters.list_available_rules_names()
# ['rule_of_five', 'rule_of_five_beyond', 'rule_of_four', 'rule_of_three', ...]

Single rule on one molecule:

import datamol as dm
import medchem as mc

smiles = "CC(=O)OC1=CC=CC=C1C(=O)O"  # aspirin
mc.rules.basic_rules.rule_of_five(smiles)   # True
mc.rules.basic_rules.rule_of_cns(smiles)    # True
mc.rules.basic_rules.rule_of_veber(smiles)  # True

Multiple rules with RuleFilters (returns a DataFrame):

import datamol as dm
import medchem as mc

mols = [dm.to_mol(s) for s in smiles_list]

rfilter = mc.rules.RuleFilters(
    rule_list=["rule_of_five", "rule_of_oprea", "rule_of_cns", "rule_of_leadlike_soft"]
)
df = rfilter(mols=mols, n_jobs=-1, progress=True, keep_props=False)

# Columns: mol, pass_all, pass_any, rule_of_five, rule_of_oprea, ...
passing = df[df["pass_all"]]

Examples below use already parsed mol_list, smiles_list, and candidates supplied by the caller; reject missing/empty structures before filtering. Use keep_props=True to include computed descriptors (mw, clogp, tpsa, etc.) in the result.

2. Structural Alert Filters

Detect problematic patterns with medchem.structural. Both classes return DataFrames with pass_filter, status, and reasons columns.

Common alerts (ChEMBL-derived rule sets):

import medchem as mc

alert_filter = mc.structural.CommonAlertsFilters(alerts_set=["BMS", "Dundee", "Glaxo"])
df = alert_filter(mols=mol_list, n_jobs=-1, progress=True)
# df columns: mol, pass_filter, status, reasons

clean = df[df["pass_filter"]]

NIBR filters (Novartis screening-deck curation):

nibr_filter = mc.structural.NIBRFilters()
df = nibr_filter(mols=mol_list, n_jobs=-1, progress=True)
# df columns: mol, pass_filter, status, severity, reasons, n_covalent_motif, special_mol

The class rejects explicit exclusion alerts. To also reject accumulated flag severity ≥10, use df["pass_filter"] & (df["severity"] < 10), or mc.functional.nibr_filter(..., max_severity=10). The functional cutoff is strict < 10 and assumes valid molecules: it checks severity alone and can admit parse failures with severity zero. Prevalidate inputs.

3. Named Catalog Filters (PAINS, Brenk, etc.)

Use medchem.catalogs.NamedCatalogs for RDKit FilterCatalog instances, or the functional API:

import medchem as mc

# List available named catalogs
mc.catalogs.list_named_catalogs()
# ['tox', 'pains', 'pains_a', 'brenk', 'nibr', 'zinc', ...]

# Functional API — True means molecule passes (no alert match)
passes = mc.functional.catalog_filter(mols=mol_list, catalogs=["pains"], n_jobs=-1)

# Or via catalog objects
passes = mc.functional.catalog_filter(
    mols=mol_list,
    catalogs=[mc.catalogs.NamedCatalogs.pains()],
    n_jobs=-1,
)

alert_filter is a different API: it uses the ChEMBL common-alert collection names from CommonAlertsFilters.list_default_available_alerts(), not every NamedCatalogs name. For example, brenk and pains_a belong in catalog_filter. Set common-alert sets explicitly; the current class implementation defaults to BMS only. catalog_filter rejects the string names nibr and bredt; use their dedicated functional filters. Raw NIBR catalog matches include annotations, regardless of severity.

4. Functional API

medchem.functional provides one-call wrappers that return boolean masks (True = passes):

import medchem as mc

mc.functional.rules_filter(mols=mol_list, rules=["rule_of_five", "rule_of_cns"], n_jobs=-1)
mc.functional.nibr_filter(mols=mol_list, max_severity=10, n_jobs=-1)
mc.functional.catalog_filter(mols=mol_list, catalogs=["pains", "brenk"], n_jobs=-1)
mc.functional.complexity_filter(mols=mol_list, complexity_metric="bertz", limit="99", n_jobs=-1)

Other helpers: catalog_filter, chemical_group_filter, lilly_demerit_filter (requires optional binaries), macrocycle_filter, bredt_filter, protecting_groups_filter, and more. Pass copies to bredt_filter ([Chem.Mol(m) for m in mol_list], after from rdkit import Chem): its in-place kekulization changes later aromatic alert matches in 2.1.1.

5. Chemical Groups

Detect functional groups and curated pattern collections via medchem.groups:

import medchem as mc

# Browse available group collections
mc.groups.list_default_chemical_groups()
# ['privileged_scaffolds', 'common_warhead_covalent_inhibitors', 'rings_in_drugs', ...]

group = mc.groups.ChemicalGroup(groups=["privileged_scaffolds"])
group.has_match(mol)                          # bool
group.get_matches(mol)                        # DataFrame, including a matches column
matching_mols = [mol for mol in mol_list if group.has_match(mol)]
# group.filter(names=[...]) narrows pattern names in place; it does not filter molecules.

# Returns a boolean mask: True means the molecule does NOT match the group
mc.functional.chemical_group_filter(mols=mol_list, chemical_group=group, n_jobs=-1)

Custom groups use groups_db CSV with both smiles and smarts, plus name and group columns. SMILES and SMARTS matching can differ; record the representation and exact_match setting.

6. Molecular Complexity

Compare complexity metrics to precomputed, molecular-weight-binned ZINC-15 thresholds. Valid default limit labels are median, 90, 99, 999 (99.9th percentile), and max; 95 is not provided. spacialscore needs a custom threshold file. All metrics use an upper cutoff, including QED; do not interpret that as selecting high QED.

import medchem as mc

# Single molecule
cf = mc.complexity.ComplexityFilter(limit="99", complexity_metric="bertz")
cf(mol)  # True if below 99th-percentile threshold

# Batch via functional API
mc.functional.complexity_filter(
    mols=mol_list,
    complexity_metric="bertz",  # also: sas, qed, whitlock, barone, smcm, twc
    limit="99",
    n_jobs=-1,
)

# Direct metric functions
mc.complexity.WhitlockCT(mol)
mc.complexity.BaroneCT(mol)

7. Scaffold Constraints

medchem.constraints.Constraints matches a core scaffold and applies per-atom constraint functions — not simple MW/LogP ranges. For property bounds, use RuleFilters, descriptors via mc.rules.list_descriptors(), or the query language.

import datamol as dm
import medchem as mc

core = dm.from_smarts("c1cncc([*:1])c1")
for atom in core.GetAtoms():
    if atom.GetAtomMapNum() == 1:
        atom.SetProp("query", "aromatic_sidechain")
constraints = mc.constraints.Constraints(
    core=core,
    constraint_fns={"aromatic_sidechain": lambda fragment: dm.descriptors.n_aromatic_atoms(fragment) > 0},
)
assert not constraints(dm.to_mol("CN(C)C(=O)c1cncc(C)c1"))
assert constraints(dm.to_mol("c1ccc(cc1)-c1cccnc1"))

8. Medchem Query Language

Build multi-criteria filters with medchem.query.QueryFilter:

import medchem as mc

# Rule + alert combination
qf = mc.query.QueryFilter('MATCHRULE("rule_of_five") AND NOT HASALERT("pains")')
mask = qf(mols=mol_list, n_jobs=-1)  # list[bool]

# CNS-like with property bounds
qf = mc.query.QueryFilter('MATCHRULE("rule_of_cns") AND HASPROP("tpsa", <=, 90)')
mask = qf(mols=mol_list, n_jobs=-1)

Query syntax:

• MATCHRULE("rule_of_five") — apply a named rule
• HASALERT("pains") — match a named catalog (pains, brenk, nibr, tox, …)
• HASPROP("mw", <, 500) — compare a descriptor (unquoted comparator)
• HASGROUP("Primary amines") — match a functional-group name from mc.groups.get_functional_group_map(); collection names such as privileged_scaffolds are not valid here
• HASSUBSTRUCTURE("c1ccccc1") — substructure match
• Operators: AND, OR, NOT

List available descriptors: mc.rules.list_descriptors()

Workflow Patterns

Pattern 1: Initial Triage of a Compound Library

Before filtering, assign stable source-row IDs and separate failed SMILES/SDF parses from valid molecules that fail a chemical rule. Retain original structure text and a rejected-input table; report input, parsed, rule-failed, and retained counts. The bundled loader removes invalid molecules (and resets tabular indices), so do not align results back to the original file by row position. The example below assumes all supplied structures parse successfully.

import datamol as dm
import medchem as mc
import pandas as pd

df = pd.read_csv("compounds.csv")
mols = [dm.to_mol(s) for s in df["smiles"]]

# Drug-likeness rules
rules_df = mc.rules.RuleFilters(rule_list=["rule_of_five", "rule_of_veber"])(mols=mols, n_jobs=-1)

# PAINS + common alerts via query
qf = mc.query.QueryFilter('MATCHRULE("rule_of_five") AND NOT HASALERT("pains")')
pass_mask = qf(mols=mols, n_jobs=-1)

df["passes_rules"] = rules_df["pass_all"].values
df["drug_like"] = pass_mask
filtered_df = df[df["drug_like"]]
filtered_df.to_csv("filtered_compounds.csv", index=False)