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.

Version note: Examples target medchem 2.0.5 (PyPI stable, Nov 2024). Requires Python ≥3.9. Depends on datamol and RDKit (installed automatically). RuleFilters and structural filter classes return pandas DataFrames. Lilly demerits require optional native binaries (mamba install lilly-medchem-rules).

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 datamol

Optional — Eli Lilly demerit filter (requires conda-forge native binaries):

mamba install -c conda-forge lilly-medchem-rules

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"]]

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()
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

Compounds with severity >= 10 are excluded by default (see NIBR paper).

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.alert_filter(mols=mol_list, alerts=["pains"], n_jobs=-1)

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

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.alert_filter(mols=mol_list, alerts=["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.

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)                        # dict of group → atom indices
group.filter(mols)                            # molecules matching the group

# Returns molecules that do NOT match the group
mc.functional.chemical_group_filter(mols=mol_list, chemical_group=group, n_jobs=-1)

Custom groups can be loaded from a file via groups_db (CSV with smiles/smarts, name, group columns).

6. Molecular Complexity

Compare complexity metrics to precomputed ZINC-15 percentile thresholds:

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.to_mol("c1ccccc1")
constraints = mc.constraints.Constraints(
    core=core,
    constraint_fns={"query": lambda mol, atom_idx, query: ...},
)
constraints(mol)

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("privileged_scaffolds") — match a chemical group
• 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

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)

Pattern 2: Lead Optimization Filtering

import medchem as mc

rules_df = mc.rules.RuleFilters(rule_list=["rule_of_leadlike_soft"])(mols=candidates, n_jobs=-1)
nibr_df = mc.structural.NIBRFilters()(mols=candidates, n_jobs=-1)
complex_mask = mc.functional.complexity_filter(
    mols=candidates, complexity_metric="bertz", limit="95", n_jobs=-1
)

passes = (
    rules_df["pass_all"]
    & nibr_df["pass_filter"]
    & complex_mask
)

Pattern 3: Detect Functional Groups

import medchem as mc

group = mc.groups.ChemicalGroup(groups=["common_warhead_covalent_inhibitors"])
matches = [group.has_match(mol) for mol in mol_list]
warhead_mols = [mol for mol, m in zip(mol_list, matches) if m]

Best Practices

1. Context matters — marketed drugs often violate Ro5; prodrugs and natural products are common exceptions. 2. Combine filters — rules, alert catalogs, and complexity thresholds work best together. 3. Use parallelization — pass n_jobs=-1 for libraries >1000 molecules. 4. Check return types — RuleFilters and structural classes return DataFrames; functional helpers return boolean arrays. 5. Lilly demerits are optional — install lilly-medchem-rules separately; default max demerits is 160 in the functional API. 6. Document decisions — retain status, reasons, and severity columns for audit trails.

Resources

references/api_guide.md

Module-by-module API reference with signatures, return types, and patterns.

references/rules_catalog.md

Catalog of available rules, alert sets, complexity metrics, and filter selection guidelines.

scripts/filter_molecules.py

Batch filtering script for CSV/TSV/SDF/SMILES inputs with configurable rules, alerts, and complexity thresholds.

uv run python scripts/filter_molecules.py input.csv \
  --rules rule_of_five,rule_of_cns --pains --nibr --output filtered.csv

Documentation

• Official docs: https://medchem-docs.datamol.io/
• GitHub: https://github.com/datamol-io/medchem
• PyPI: https://pypi.org/project/medchem/ (2.0.5)

Medchem API Reference

Reference for medchem 2.0.5. Official docs: https://medchem-docs.datamol.io/stable/api/

Module: medchem.rules

Class: RuleFilters

Filter molecules by multiple medicinal chemistry rules. Returns a pandas DataFrame.

Constructor:

RuleFilters(rule_list: List[Union[str, Callable]], rule_list_names: Optional[List[str]] = None)

Call signature:

__call__(
    mols: Sequence[Union[str, Mol]],
    n_jobs: int = -1,
    progress: bool = False,
    progress_leave: bool = False,
    scheduler: str = "auto",
    keep_props: bool = False,
    fail_if_invalid: bool = True,
) -> pd.DataFrame

Return columns: mol, pass_all, pass_any, plus one boolean column per rule. With keep_props=True, descriptor columns (mw, clogp, tpsa, etc.) are included.

Class methods:

RuleFilters.list_available_rules_names()  # list of 22 rule names
RuleFilters.list_available_rules()        # rules with property metadata

Example:

rfilter = mc.rules.RuleFilters(rule_list=["rule_of_five", "rule_of_cns"])
df = rfilter(mols=mol_list, n_jobs=-1, progress=True)
passing = df[df["pass_all"]]

Module: medchem.rules.basic_rules

Individual rule functions for single molecules. Each returns bool (True = passes).

Descriptor helpers

mc.rules.list_descriptors()  # property names for query language

---

Module: medchem.structural

Class: CommonAlertsFilters

ChEMBL-derived structural alert filter sets (Glaxo, Dundee, BMS, etc.).

CommonAlertsFilters()

Returns DataFrame columns: mol, pass_filter, status, reasons

• status: one of "exclude", "flag", "annotations", "ok"
• pass_filter: bool — True if compound passes

Methods:

list_default_available_alerts()  # DataFrame of alert definitions
__call__(mols, n_jobs=-1, progress=False, ...) -> pd.DataFrame

Class: NIBRFilters

Novartis screening-deck curation filters (Schuffenhauer et al., J. Med. Chem. 2020).

NIBRFilters()

Returns DataFrame columns: mol, pass_filter, status, severity, reasons, n_covalent_motif, special_mol

• severity: 0 = clean; 1–9 = flags; ≥10 = excluded by default

Lilly demerits (optional)

Requires mamba install lilly-medchem-rules. Access via:

mc.functional.lilly_demerit_filter(mols, max_demerits=160, n_jobs=-1)
# or
from medchem.structural.lilly_demerits import LillyDemeritsFilters

---

Module: medchem.functional

High-level boolean-mask API. True = passes (no alert / passes all rules).

---

Module: medchem.catalogs

NamedCatalogs

Static methods returning RDKit FilterCatalog objects:

mc.catalogs.list_named_catalogs()
# tox, pains, pains_a, pains_b, pains_c, nih, zinc, brenk, dundee, bms,
# glaxo, schembl, mlsmr, inpharmatica, lint, nibr, bredt, toxicophore, ...

mc.catalogs.NamedCatalogs.pains()
mc.catalogs.NamedCatalogs.brenk()
mc.catalogs.NamedCatalogs.nibr()
mc.catalogs.NamedCatalogs.bredt()

Helpers:

catalog_from_smarts(smarts_list)
merge_catalogs(catalogs)
list_named_catalogs()

---

Module: medchem.groups

ChemicalGroup

Detect functional groups from the global-chem curated library.

ChemicalGroup(groups=None, n_jobs=None, groups_db=None)

Methods:

has_match(mol, exact_match=False, terminal_only=False) -> bool
get_matches(mol, use_smiles=True, exact_match=False, terminal_only=False) -> dict
filter(mols) -> list[Mol]
get_catalog() -> FilterCatalog
list_groups() -> list
list_hierarchy_groups() -> list

Listing helpers:

mc.groups.list_default_chemical_groups(hierarchy=False)
mc.groups.list_functional_group_names(unique=True)
mc.groups.get_functional_group_map()  # name → SMARTS

---

Module: medchem.complexity

Class: ComplexityFilter

Compare a metric to ZINC-15 percentile thresholds. Operates on single molecules.

ComplexityFilter(
    limit="99",
    complexity_metric="bertz",
    threshold_stats_file="zinc_15_available",
)
cf(mol)  # -> bool

Available metrics (ComplexityFilter.list_default_available_filters()): bertz, sas, qed, clogp, whitlock, barone, smcm, twc

Direct metric functions:

mc.complexity.WhitlockCT(mol)
mc.complexity.BaroneCT(mol)
mc.complexity.SMCM(mol)
mc.complexity.TWC(mol)

For batch filtering, use mc.functional.complexity_filter().

---

Module: medchem.constraints

Class: Constraints

Scaffold-based substructure matching with per-atom constraint functions — not simple property-range filters.

Constraints(core: Mol, constraint_fns: Dict[str, Callable], prop_name: str = "query")
constraints(mol)  # -> bool or match details

Use RuleFilters or the query language for MW/LogP/TPSA bounds.

---

Module: medchem.query

Class: QueryFilter

Parse and evaluate the medchem query language.

QueryFilter(query: str, grammar: Optional[str] = None, parser: str = "lalr")
qf(mols, n_jobs=-1, progress=True, scheduler="processes") -> list[bool]

Grammar constructs:

Example queries:

'MATCHRULE("rule_of_five") AND NOT HASALERT("pains")'
'MATCHRULE("rule_of_cns") AND HASPROP("tpsa", <=, 90)'
'NOT HASALERT("brenk") AND HASPROP("mw", >=, 200)'

Class: QueryOperator

Holds available properties, catalogs, rules, and functional groups used by the parser.

---

Common Patterns

Parallel processing

df = mc.rules.RuleFilters(rule_list=["rule_of_five"])(mols=mol_list, n_jobs=-1, progress=True)
mask = mc.functional.nibr_filter(mols=mol_list, n_jobs=-1)

Combining filters

rules_df = mc.rules.RuleFilters(rule_list=["rule_of_five"])(mols=mol_list, n_jobs=-1)
alerts_df = mc.structural.CommonAlertsFilters()(mols=mol_list, n_jobs=-1)

passing = [
    mol for i, mol in enumerate(mol_list)
    if rules_df.iloc[i]["pass_all"] and alerts_df.iloc[i]["pass_filter"]
]

Working with DataFrames

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

df = pd.read_csv("molecules.csv")
df["mol"] = df["smiles"].apply(dm.to_mol)

results = mc.rules.RuleFilters(rule_list=["rule_of_five", "rule_of_cns"])(
    mols=df["mol"].tolist(), n_jobs=-1
)
df = pd.concat([df, results.drop(columns=["mol"])], axis=1)
filtered = df[df["pass_all"]]

Medchem Rules and Filters Catalog

Catalog of medicinal chemistry rules, alert sets, and filters in medchem 2.0.5.

Table of Contents

1. Drug-Likeness Rules 2. Lead-Likeness Rules 3. Fragment Rules 4. CNS and Target-Class Rules 5. Structural Alert Filters 6. Named Catalogs 7. Complexity Metrics 8. Chemical Group Collections 9. Filter Selection Guidelines

---

Drug-Likeness Rules

Rule of Five (Lipinski)

Reference: Lipinski et al., Adv Drug Deliv Rev (1997) 23:3–25

Criteria: MW ≤ 500, LogP ≤ 5, HBD ≤ 5, HBA ≤ 10

mc.rules.basic_rules.rule_of_five(mol)
# or
mc.rules.RuleFilters(rule_list=["rule_of_five"])

Rule of Five Beyond

Reference: Doak et al., (2015) — compounds beyond Ro5 for large binding sites

Criteria: MW ≤ 1000, LogP ∈ [-2, 10], HBD ≤ 6, HBA ≤ 15, TPSA ≤ 250, rotatable bonds ≤ 20

mc.rules.basic_rules.rule_of_five_beyond(mol)

Rule of Veber

Reference: Veber et al., J Med Chem (2002) 45:2615–2623

Criteria: Rotatable bonds ≤ 10, TPSA ≤ 140 Ų

mc.rules.basic_rules.rule_of_veber(mol)

REOS (Rapid Elimination Of Swill)

Reference: Walters & Murcko, Adv Drug Deliv Rev (2002) 54:255–271

Criteria: MW 200–500, LogP −5 to 5, HBD 0–5, HBA 0–10

mc.rules.basic_rules.rule_of_reos(mol)

Egan, Ghose, Pfizer, GSK, Xu

Additional literature filters available as rule_of_egan, rule_of_ghose, rule_of_pfizer_3_75, rule_of_gsk_4_400, rule_of_xu.

Rule of Druglike (Soft)

Combined soft drug-likeness criteria:

mc.rules.basic_rules.rule_of_druglike_soft(mol)

---

Lead-Likeness Rules

Rule of Oprea

Reference: Oprea et al., J Chem Inf Comput Sci (2001) 41:1308–1315

Criteria: MW 200–350, LogP −2 to 4, rotatable bonds ≤ 7, rings ≤ 4

mc.rules.basic_rules.rule_of_oprea(mol)

Rule of Leadlike (Soft)

Criteria: MW 250–450, LogP −3 to 4, rotatable bonds ≤ 10

mc.rules.basic_rules.rule_of_leadlike_soft(mol)

---

Fragment Rules

Rule of Three

Reference: Congreve et al., Drug Discov Today (2003) 8:876–877

Criteria: MW ≤ 300, LogP ≤ 3, HBD ≤ 3, HBA ≤ 3, rotatable bonds ≤ 3, PSA ≤ 60 Ų

mc.rules.basic_rules.rule_of_three(mol)

Also available: rule_of_three_extended, rule_of_two, rule_of_four.

---

CNS and Target-Class Rules

Rule of CNS

Criteria: MW ≤ 450, LogP −1 to 5, HBD ≤ 2, TPSA ≤ 90 Ų

mc.rules.basic_rules.rule_of_cns(mol)

Rule of Respiratory

Target-class filter for respiratory drugs:

mc.rules.basic_rules.rule_of_respiratory(mol)

Generative Design Rules

For ML-generated molecules:

mc.rules.basic_rules.rule_of_generative_design(mol)
mc.rules.basic_rules.rule_of_generative_design_strict(mol)

---

Structural Alert Filters

PAINS (Pan Assay INterference compoundS)

Reference: Baell & Holloway, J Med Chem (2010) 53:2719–2740

Apply via named catalog — not a basic_rules function:

mc.functional.alert_filter(mols, alerts=["pains"], n_jobs=-1)
# or query: NOT HASALERT("pains")

Sub-catalogs: pains_a, pains_b, pains_c.

Common Alerts Filters

ChEMBL-curated rule sets (Glaxo, Dundee, BMS, MLSMR, etc.):

alert_filter = mc.structural.CommonAlertsFilters()
df = alert_filter(mols=mol_list, n_jobs=-1)
# status: exclude | flag | annotations | ok

NIBR Filters

Novartis screening-deck curation (Schuffenhauer et al., 2020):

nibr_filter = mc.structural.NIBRFilters()
df = nibr_filter(mols=mol_list, n_jobs=-1)
# severity >= 10 → excluded by default

Or via functional API with max_severity=10.

Lilly Demerits (optional)

Requires mamba install lilly-medchem-rules. 275 structural patterns; default exclusion at >160 demerits:

mc.functional.lilly_demerit_filter(mols, max_demerits=160, n_jobs=-1)

---

Named Catalogs

Available via mc.catalogs.list_named_catalogs() and NamedCatalogs static methods:

cat = mc.catalogs.NamedCatalogs.brenk()
passes = mc.functional.catalog_filter(mols, catalogs=[cat], n_jobs=-1)

---

Complexity Metrics

Compared to ZINC-15 percentile thresholds via ComplexityFilter or complexity_filter():

mc.functional.complexity_filter(mols, complexity_metric="bertz", limit="99", n_jobs=-1)

limit="99" keeps compounds below the 99th percentile on ZINC-15.

---

Chemical Group Collections

Browse with mc.groups.list_default_chemical_groups():

group = mc.groups.ChemicalGroup(groups=["privileged_scaffolds"])
group.has_match(mol)

Custom groups: provide a CSV via groups_db with columns smiles/smarts, name, group.

---

Filter Selection Guidelines

Initial Screening (HTS deck)

qf = mc.query.QueryFilter('MATCHRULE("rule_of_five") AND NOT HASALERT("pains")')
mask = qf(mols=mol_list, n_jobs=-1)

Hit-to-Lead

rules = mc.rules.RuleFilters(rule_list=["rule_of_oprea"])(mols, n_jobs=-1)
nibr = mc.structural.NIBRFilters()(mols, n_jobs=-1)

Lead Optimization

rules = mc.rules.RuleFilters(rule_list=["rule_of_druglike_soft"])(mols, n_jobs=-1)
alerts = mc.structural.CommonAlertsFilters()(mols, n_jobs=-1)
complexity = mc.functional.complexity_filter(mols, complexity_metric="bertz", limit="95", n_jobs=-1)

CNS Targets

qf = mc.query.QueryFilter('MATCHRULE("rule_of_cns") AND HASPROP("tpsa", <=, 90)')
mask = qf(mols, n_jobs=-1)

Fragment-Based Discovery

rules = mc.rules.RuleFilters(rule_list=["rule_of_three"])(mols, n_jobs=-1)
complexity = mc.functional.complexity_filter(mols, complexity_metric="bertz", limit="90", n_jobs=-1)

---

Important Considerations

Filters are guidelines, not absolutes:

• ~10% of marketed oral drugs violate Ro5
• Natural products and prodrugs often fail standard rules
• Passing filters does not guarantee clinical success

Combine with ML when appropriate:

rules_df = mc.rules.RuleFilters(rule_list=["rule_of_five"])(mols, n_jobs=-1)
filtered_mols = [m for m, ok in zip(mols, rules_df["pass_all"]) if ok]
# score filtered_mols with downstream ML model

---

References

1. Lipinski CA et al. Adv Drug Deliv Rev (1997) 23:3–25 2. Veber DF et al. J Med Chem (2002) 45:2615–2623 3. Oprea TI et al. J Chem Inf Comput Sci (2001) 41:1308–1315 4. Congreve M et al. Drug Discov Today (2003) 8:876–877 5. Baell JB & Holloway GA. J Med Chem (2010) 53:2719–2740 6. Walters WP & Murcko MA. Adv Drug Deliv Rev (2002) 54:255–271 7. Schuffenhauer A et al. J Med Chem (2020) — NIBR screening deck 8. Doak BC et al. (2015) — Beyond Rule of Five