{"slug":"alterlab-medchem","title":"alterlab-medchem","summary":"Applies medicinal-chemistry filters with the medchem library — drug-likeness rules (Lipinski, Veber), PAINS filters, structural alerts, and molecular complexity metrics for compound prioritization and library cleanup. Use when filtering or triaging a compound library, flagging PA","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-23T18:56:59.105666Z","repo":{"url":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","stars":68,"forks":13,"license":"MIT","updatedAt":"2026-09-23T13:42:59Z"},"bodyHtml":"
\n

name: alterlab-medchem\ndescription: Applies medicinal-chemistry filters with the medchem library — drug-likeness rules (Lipinski, Veber), PAINS filters, structural alerts, and molecular complexity metrics for compound prioritization and library cleanup. Use when filtering or triaging a compound library, flagging PAINS or reactive groups, or assessing drug-likeness of candidate molecules. Part of the AlterLab Academic Skills suite.\nlicense: Apache-2.0\nallowed-tools: Read Write Edit Bash(python:) Bash(uv:)\ncompatibility: \"Self-contained — runs under uv run python with the skill's Python package installed; no API key or account required.\"\nmetadata:\nskill-author: AlterLab\nversion: \"1.2.0\"\nlast_updated: \"2026-09-23\"

\n

Medchem

\n

Overview

\n

Medchem (datamol-io/medchem) is a Python library for molecular filtering and prioritization in drug-discovery workflows: medicinal-chemistry rules, structural alerts (ChEMBL/NIBR/PAINS), chemical-group detection, complexity metrics, and a query DSL. Rules and filters are context-specific guidelines, not hard truth — combine with domain expertise.

\n

Verified against medchem==2.1.0 (current as of 2026-09; Python ≥ 3.11, RDKit 2026.03). API names below are checked against this version; earlier docs/blog posts described a different surface.

\n

When to Use This Skill

\n

This skill should be used when:

\n\n

Does NOT Trigger

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ScenarioUse Instead
Just computing descriptors (MW, cLogP, TPSA, HBD/HBA) or standardizing structures, no rule/alert filteringalterlab-datamol
Writing custom SMARTS queries or substructure logic outside the curated catalogsalterlab-rdkit
Fetching a labeled toxicity/ADMET benchmark (e.g. hERG, AMES) with scaffold splitsalterlab-pytdc
Retrieving measured bioactivity (IC50/Ki) for compounds or targetsalterlab-chembl
\n

Installation

\n
uv pip install medchem    # PyPI; pulls rdkit + datamol\n
\n

Two features need extra native deps that PyPI cannot provide:

\n\n

Everything else (RuleFilters, CommonAlerts, NIBR, complexity, groups, query) works from the PyPI wheel alone.

\n

Core Capabilities

\n
\n

Conventions that hold across medchem. Filters take mols (a sequence of SMILES strings or RDKit mols), default to n_jobs=-1 (all cores), and accept progress=True. The medchem.structural / medchem.rules filter classes return a pandas DataFrame (one row per input mol); the medchem.functional.* helpers return a NumPy boolean array where True = the molecule passes / is kept. Get the canonical rule and alert names from mc.rules.RuleFilters.list_available_rules() and mc.structural.CommonAlertsFilters.list_default_available_alerts() rather than guessing.

\n
\n

1. Medicinal Chemistry Rules — medchem.rules

\n

Single rule — medchem.rules.basic_rules.* functions take one mol (SMILES or RDKit) and return a plain bool:

\n
import medchem as mc\n\nsmi = \"CC(=O)OC1=CC=CC=C1C(=O)O\"  # aspirin\nmc.rules.basic_rules.rule_of_five(smi)   # -> True\nmc.rules.basic_rules.rule_of_veber(smi)  # -> True\nmc.rules.basic_rules.rule_of_cns(smi)\n
\n

Available rules (full list via mc.rules.RuleFilters.list_available_rules()): rule_of_five, rule_of_five_beyond, rule_of_four, rule_of_three, rule_of_three_extended, rule_of_two, rule_of_ghose, rule_of_veber, rule_of_reos, rule_of_egan, rule_of_pfizer_3_75, rule_of_gsk_4_400, rule_of_oprea, rule_of_xu, rule_of_cns, rule_of_respiratory, rule_of_zinc, rule_of_leadlike_soft, rule_of_druglike_soft, rule_of_generative_design, rule_of_generative_design_strict, rule_of_chemaxon_druglikeness (needs ChemAxon).

\n
\n

There is no rule_of_drug, rule_of_leadlike_strict, golden_triangle, or pains_filter function (checked in 2.1.0). PAINS lives in the alert system (HASALERT(\"pains\") or CommonAlertsFilters(alerts_set=[\"PAINS\"])). For lead-likeness use rule_of_leadlike_soft or rule_of_oprea.

\n
\n

Multiple rules — RuleFilters returns a DataFrame with columns mol, pass_all, pass_any, and one boolean column per rule:

\n
import datamol as dm\nimport medchem as mc\n\nmols = [dm.to_mol(s) for s in smiles_list]\nrfilter = mc.rules.RuleFilters(rule_list=[\"rule_of_five\", \"rule_of_veber\", \"rule_of_cns\"])\ndf = rfilter(mols=mols, n_jobs=-1, progress=True)\n# df[\"pass_all\"] -> bool per molecule; df[\"rule_of_five\"] -> per-rule bool\nclean = [m for m, ok in zip(mols, df[\"pass_all\"]) if ok]\n
\n

Property windows — there is no all-in-one \"Constraints(mw_range=...)\" object (see note in section 7). Build custom property cutoffs with mc.rules.in_range over descriptor names from mc.rules.list_descriptors() (mw, clogp, tpsa, n_lipinski_hbd, n_lipinski_hba, n_rotatable_bonds, n_rings, ...), or use the query DSL (HASPROP, section 8).

\n

2. Structural Alert Filters — medchem.structural

\n

Two filter classes ship in medchem.structural: CommonAlertsFilters and NIBRFilters. (Lilly demerits is reached through medchem.functional, see section 3 — its class lives under medchem.structural.lilly_demerits and needs external binaries.)

\n

Common alerts — curated alert sets from ChEMBL (Glaxo, Dundee, BMS, PAINS, SureChEMBL, ...). Returns a DataFrame with mol, pass_filter (bool), status (ok/exclude), reasons (matched alert names, ;-joined):

\n
import medchem as mc\n\ncaf = mc.structural.CommonAlertsFilters()                 # all default sets\ncaf_pains = mc.structural.CommonAlertsFilters(alerts_set=[\"PAINS\"])  # PAINS only\ndf = caf(mols=mol_list, n_jobs=-1, progress=True)\nclean = df[df[\"pass_filter\"]]\n# discover sets: mc.structural.CommonAlertsFilters.list_default_available_alerts()\n
\n

NIBR filters — Novartis filter set. Returns a DataFrame including mol, pass_filter, severity, status, reasons:

\n
nibr = mc.structural.NIBRFilters()\ndf = nibr(mols=mol_list, n_jobs=-1)\n
\n

3. Functional API — medchem.functional

\n

One-call helpers that return a NumPy boolean array (True = keep). Pass return_idx=True to get indices of passing mols instead:

\n
import medchem as mc\n\nmc.functional.rules_filter(mol_list, rules=[\"rule_of_five\", \"rule_of_veber\"], n_jobs=-1)\nmc.functional.alert_filter(mol_list, alerts=[\"pains\"], n_jobs=-1)   # alert names are lowercase here\nmc.functional.nibr_filter(mol_list, max_severity=10, n_jobs=-1)\nmc.functional.complexity_filter(mol_list, complexity_metric=\"bertz\", limit=\"99\", n_jobs=-1)\nmc.functional.chemical_group_filter(mol_list, chemical_group=mc.groups.ChemicalGroup(groups=[\"hinge_binders\"]))\n
\n

Lilly demerits — requires the Lilly tools (medchem install-lilly, see Installation); raises ImportError if missing. Molecules above max_demerits (default 160) are rejected:

\n
keep = mc.functional.lilly_demerit_filter(mol_list, max_demerits=160, n_jobs=-1)  # NumPy bool array\n
\n

4. Chemical Groups Detection — medchem.groups

\n

ChemicalGroup matches curated group catalogs. List valid catalog names with mc.groups.list_default_chemical_groups() (e.g. hinge_binders, electrophilic_warheads_for_kinases, common_warhead_covalent_inhibitors, privileged_kinase_inhibitor_scaffolds, aggregator). Per-mol functional-group names (for the query DSL HASGROUP) come from mc.groups.list_functional_group_names().

\n
import medchem as mc\n\ngroup = mc.groups.ChemicalGroup(groups=[\"hinge_binders\"])\ngroup.has_match(mol)        # bool for one mol\ngroup.get_matches(mol)      # detailed matches\n# batch: mc.functional.chemical_group_filter(mols, chemical_group=group)\n
\n
\n

phosphate_binders, michael_acceptors, and reactive_groups are not default catalog names. For reactive/electrophilic motifs use electrophilic_warheads_for_kinases / common_warhead_covalent_inhibitors, the alert filters (section 2), or a custom SMARTS catalog (mc.catalogs.catalog_from_smarts).

\n
\n

5. Named Catalogs — medchem.catalogs

\n
import medchem as mc\n\nmc.catalogs.list_named_catalogs()      # available catalog names\ncat = mc.catalogs.NamedCatalogs.pains()  # e.g. a PAINS RDKit FilterCatalog\nmc.catalogs.catalog_from_smarts(...)   # build a catalog from custom SMARTS\n
\n

6. Molecular Complexity — medchem.complexity

\n

ComplexityFilter flags molecules whose complexity exceeds a percentile threshold derived from a reference set (default ZINC). It is called per molecule and returns a bool (True = within limit / keep). Metrics: bertz, whitlock (WhitlockCT), barone (BaroneCT), smcm (SMCM), twc (TWC), plus sas/qed/clogp. New in 2.1: mc.complexity.SPS(mol) (normalized SpacialScore, Krzyzanowski et al., J. Med. Chem. 2023); as a ComplexityFilter metric (\"spacialscore\") it needs your own threshold_stats_file.

\n
import medchem as mc\n\ncflt = mc.complexity.ComplexityFilter(limit=\"99\", complexity_metric=\"bertz\")\nkeep = [cflt(m) for m in mol_list]\n# or batch: mc.functional.complexity_filter(mol_list, complexity_metric=\"bertz\", limit=\"99\")\n
\n
\n

There is no mc.complexity.calculate_complexity(...) and ComplexityFilter takes limit/complexity_metric/threshold_stats_file, not max_complexity. For a raw score use the metric classes directly (mc.complexity.TWC, etc.).

\n
\n

7. Substructure Constraints — medchem.constraints

\n

mc.constraints.Constraints(core, constraint_fns, prop_name=\"query\") enforces substructure / R-group constraints around a query core (via has_match / validate) — it is not a physchem property-window filter. For MW/logP/TPSA windows, use RuleFilters + in_range (section 1) or the query DSL HASPROP (section 8).

\n

8. Query DSL — medchem.query

\n

QueryFilter evaluates a boolean expression over rules, properties, alerts, and groups. Operators: AND, OR, NOT, comparisons < > <= >= == !=. Primitives: MATCHRULE(\"...\"), HASPROP(\"<descriptor>\" < value), HASALERT(\"<lowercase set>\"), HASGROUP(\"...\"), HASSUBSTRUCTURE/HASSUPERSTRUCTURE, LIKE.

\n
import medchem as mc\n\nqf = mc.query.QueryFilter('MATCHRULE(\"rule_of_five\") AND HASPROP(\"mw\" < 500) AND NOT HASALERT(\"pains\")')\nkeep = qf(mol_list, n_jobs=-1)   # NumPy bool array\n
\n
\n

The syntax is the structured DSL above — not free-form text like \"rule_of_five AND NOT common_alerts\". There is no mc.query.parse(); construct mc.query.QueryFilter(query_string) and call it on the mols. Alert names inside HASALERT are lowercase (pains, tox, nih, ...).

\n
\n

Workflow Patterns

\n

Pattern 1: Initial Triage of Compound Library

\n

Filter a large collection to drug-like candidates, dropping anything with structural alerts.

\n
import datamol as dm\nimport medchem as mc\nimport pandas as pd\n\ndf = pd.read_csv(\"compounds.csv\")\nmols = [dm.to_mol(smi) for smi in df[\"smiles\"]]\n\n# Rule filter -> DataFrame with pass_all + per-rule columns\nrule_df = mc.rules.RuleFilters(rule_list=[\"rule_of_five\", \"rule_of_veber\"])(\n    mols=mols, n_jobs=-1, progress=True\n)\n\n# Structural alerts -> DataFrame with pass_filter (True = clean)\nalert_df = mc.structural.CommonAlertsFilters()(mols=mols, n_jobs=-1, progress=True)\n\ndf[\"passes_rules\"] = rule_df[\"pass_all\"].to_numpy()\ndf[\"no_alerts\"] = alert_df[\"pass_filter\"].to_numpy()\ndf[\"drug_like\"] = df[\"passes_rules\"] & df[\"no_alerts\"]\n\ndf[df[\"drug_like\"]].to_csv(\"filtered_compounds.csv\", index=False)\n
\n

Pattern 2: Lead Optimization Filtering

\n

Stack stricter filters and keep only molecules passing every stage. The functional.* helpers all return aligned NumPy bool arrays, so intersecting them is straightforward.

\n
import numpy as np\nimport medchem as mc\n\nf = mc.functional\nkeep = (\n    f.rules_filter(candidate_mols, rules=[\"rule_of_oprea\"], n_jobs=-1)\n    & f.nibr_filter(candidate_mols, n_jobs=-1)\n    & f.complexity_filter(candidate_mols, complexity_metric=\"bertz\", limit=\"99\", n_jobs=-1)\n)\n# Add lilly_demerit_filter(...) too if the Lilly binaries are installed.\nsurvivors = [m for m, ok in zip(candidate_mols, keep) if ok]\n
\n

Pattern 3: Identify Specific Chemical Groups

\n

Flag molecules containing a target scaffold/motif (validate names with mc.groups.list_default_chemical_groups()).

\n
import medchem as mc\n\ngroup = mc.groups.ChemicalGroup(groups=[\"hinge_binders\"])\nkeep = mc.functional.chemical_group_filter(mol_list, chemical_group=group)\nwith_group = [m for m, ok in zip(mol_list, keep) if ok]\n
\n

Best Practices

\n
    \n

  1. Context Matters: Don't blindly apply filters. Understand the biological target and chemical space.

    \n
    2. \n

  2. Combine Multiple Filters: Use rules, structural alerts, and domain knowledge together for better decisions.

    \n
    3. \n

  3. Use Parallelization: For large datasets (>1000 molecules), always use n_jobs=-1 for parallel processing.

    \n
    4. \n

  4. Iterative Refinement: Start with broad filters (Ro5), then apply more specific criteria (CNS, leadlike) as needed.

    \n
    5. \n

  5. Document Filtering Decisions: Track which molecules were filtered out and why for reproducibility.

    \n
    6. \n

  6. Validate Results: Remember that marketed drugs often fail standard filters—use these as guidelines, not absolute rules.

    \n
    7. \n

  7. Consider Prodrugs: Molecules designed as prodrugs may intentionally violate standard medicinal chemistry rules.

    \n
    8. \n
\n

Resources

\n

references/api_guide.md

\n

Comprehensive API reference covering all medchem modules with detailed function signatures, parameters, and return types.

\n

references/rules_catalog.md

\n

Complete catalog of available rules, filters, and alerts with descriptions, thresholds, and literature references.

\n

scripts/filter_molecules.py

\n

Batch filtering CLI. Supports CSV/TSV, SDF, and plain-SMILES .txt input, configurable filter combinations, and a summary report.

\n

Usage:

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

Flags are individual switches (--nibr, --common-alerts, --lilly, --pains), not --alerts <name>. --lilly needs the Lilly tools (medchem install-lilly).

\n

Documentation

\n

Official documentation: https://medchem-docs.datamol.io/\nGitHub repository: https://github.com/datamol-io/medchem

\n

Part of the AlterLab Academic Skills suite.

\n","files":[{"path":"evals/evals.json","sizeBytes":4828,"isText":true},{"path":"references/api_guide.md","sizeBytes":8440,"isText":true},{"path":"references/rules_catalog.md","sizeBytes":15386,"isText":true},{"path":"scripts/filter_molecules.py","sizeBytes":16159,"isText":true},{"path":"SKILL.md","sizeBytes":15376,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-23T18:58:10.80888Z","sha256":"BA295AFF7C2C932A29CBE4A642A12A93BB0B6B7C85B970743A4A69A410186BF3","sizeBytes":22159},"review":null,"source":{"repositoryUrl":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","path":"skills/cheminformatics/alterlab-medchem","license":"MIT","commit":"e4836c08a20da195a11f30f203a8cf23ec30aa95","subtreeSha":"0FA564CFA5750BA9D37CA734423F96DA2A1A40433CEF5A922BC94A7A9769721A","lastSyncedAt":"2026-09-23T18:56:52.297238Z"},"reviewedAt":"2026-09-23T19:00:30.108508Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/cheminformatics/alterlab-medchem"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart"},{"target":"git","command":"git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git"}]}