CASyM: Chemotype Annotation Through Synthesis Mapping

Summary

This repository contains the code for the publication CASyM: Chemotype Annotation Through Synthesis Mapping. CASyM annotates the chemotypes of drug discovery targets directly from historical synthesis data: it builds a reaction network for a project, identifies the major common intermediates that convergent routes share, groups them into a chemotype graph, and assigns each target molecule to the chemotype it was (or would most likely be) made from.

How it works

Given a set of reactions (reactant → product pairs, grouped by project), CASyM:

1. Builds reaction networks per project from the reactant/product SMILES (process_reactions.py), removing reaction cycles and keeping convergent routes.
2. Identifies candidate common intermediates — compounds with enough independent routes converging on them relative to the number of target molecules in the project.
3. Groups intermediates into chemotypes, merging ones that are a small number of reaction steps apart, and optionally relinking structurally similar but disconnected chemotypes using maximum common substructure (MCS).
4. Assigns target molecules to the chemotype whose substructure they best match.
5. Produces visualizations and a report: a route/chemotype diagram, a coverage distribution plot, and (optionally) a Markdown summary across all projects.

The core logic lives in casym/main.py (the CASyM class), with shared graph utilities in casym/process_reactions.py and casym/utils.py, and report generation in casym/results_report.py.

Requirements

This repository is built on conda and poetry environments (Python 3.9). To install:

git clone https://github.com/aidd-msca/CASyM.git
cd CASyM

conda env create -f environment.yml
conda activate casym

poetry install

environment.yml also installs pygraphviz, which is required for route/chemotype layout (casym/utils.py uses networkx's Graphviz layout) — install it via conda rather than pip to get the matching Graphviz system libraries.

How to Use

Given a collection of synthesis data, the package is run from the repository root via Hydra:

python casym/main.py -cn config_CS1

-cn (--config-name) selects a YAML config file from experiments/, without the .yaml extension — the repository ships experiments/config_CS1.yaml as a runnable example (see Example below). There is no default config.yaml, so -cn must always be given explicitly. Any field can also be overridden on the command line, e.g.:

python casym/main.py -cn config_CS1 chemotype_steps=3 similarity_threshold=null

Hydra additionally writes its own per-run logs and a snapshot of the resolved config under outputs/<date>/<time>/ (or experiments/outputs/ if run from experiments/) — these are separate from the CASyM results written to store_root, see Output Files.

Data

Reaction data (reaction_file)

A tab-separated file (.tsv) with at least two columns:

• reactants — reactant SMILES, .-separated for multiple reactants
• products — product SMILES

The reaction data for the Example below is based on the publicly available USPTO reaction dataset, atom-mapped using chython.

Optional columns, used if present:

• smiles — an atom-mapped/precedent reaction SMILES to record as provenance for the reactant/product pair; if absent, one is generated from products/reactants
• limiting_reactant — marks which reactant is the limiting reagent for a reaction
• a project column (see project_col) and/or a time and yield column, if filtering by project, date or yield is configured
• any columns listed in additional_data are carried through as edge attributes onto the synthesis and chemotype graphs

Other columns (e.g. reagents) are ignored unless listed in additional_data. See case_study_one/data/CS1_reactions_9patents_subset.tsv for an example.

Target molecules (targetmolecules, optional)

A separate CSV of target compounds can be supplied to focus the analysis (e.g. only molecules actually pursued as targets, rather than every product in the reaction data). If omitted (targetmolecules: null), every root compound in the reaction data (one with no reactions producing it) is treated as a target molecule.

Config Files

Config files live in experiments/ and are passed via -cn <name> (without .yaml). All top-level fields:

Field	Description
reaction_file	File path to the reaction data (see Data).
project_col	Column in reaction_file identifying which project/document a reaction belongs to; use null if all reactions belong to a single project.
time_col	Column in reaction_file containing reaction dates, used by filter_time; use null if not filtering by time.
filter_time	Date filter on reaction_file, or null to disable. min_time / max_time bound the range; either may be null to use the data's actual min/max.
filter_yield	Yield filter on reaction_file, or null to disable. yield_col names the yield column; min_yield is the minimum % yield for a reaction to be kept.
additional_data	List of extra columns from reaction_file to carry onto the synthesis/chemotype graphs as attributes, or null.
targetmolecules	Settings for an optional target-molecules file, or null to derive target molecules from reaction_file instead (see Data). When set: targetmolecules_fp (file path), smiles_col (SMILES column), project_col (project column in this file, matched against the project currently being processed by substring containment rather than exact equality — see the TODO in casym/main.py noting this matching is dataset-specific; use null if every row is relevant), time_col and filter_time (same semantics as above, but applied to this file instead of reaction_file).
projects	Project(s) to analyze. null analyzes every unique value of project_col independently. A flat list runs each listed project separately. A list of lists merges each inner list's projects into one combined analysis — this is how the case study config below analyzes 9 patents as a single project.
chemotype_steps	Number of reaction steps within which two common intermediates are merged into a single chemotype.
common_intermediate_min_connections	Divisor applied to the number of target molecules in a route to derive the minimum number of converging routes a compound needs to be flagged as a common intermediate (capped by common_intermediate_max_connections); larger values make the criterion easier to satisfy.
common_intermediate_max_connections	Upper bound on the derived threshold above — above this many converging routes, a compound is always considered a common intermediate.
similarity_threshold	Minimum fraction of shared atoms (via maximum common substructure) required to relink two otherwise-disconnected chemotypes under a shared node; set to null to skip relinking entirely.
assign_compounds_settings.maximum_similarity	true: assign each target molecule to the chemotype it has the highest substructure-match fraction with. false: down-weight chemotypes by how frequently their cluster is already used, favoring assignment to less-represented chemotypes when matches are ambiguous.
store_root	Directory to write results to, or null to discard them after the run (nothing is written to disk).
create_report	Whether to write a Markdown summary report across all processed projects. Requires store_root to be set.

Output Files

For each processed project, if store_root is set, CASyM writes (<project> is the project id, or &&-joined ids for a merged project):

• chemotypevis_<project>.png — the route network with each identified chemotype's products, laid out against the target molecules it feeds.
• distributionvis_<project>.png — coverage of target molecules across chemotype clusters.
• assigned_chemotypes_<project>.pkl — pickled dict mapping each target molecule SMILES to its assigned [cluster, chemotype] pair(s).
• chemotype_graph_routes_<project>.json — the full chemotype graph (node-link JSON, via networkx's adjacency_data).

If create_report is enabled, a single report.md summarizing every processed project (reaction/chemotype counts, target molecule coverage) is written to store_root once the run completes.

Example

experiments/config_CS1.yaml is a runnable example modeled on one of the case studies from the paper — 9 US patents analyzed as one combined project — but over a reduced subset of the reaction data focusing only on the defined patents.

python casym/main.py -cn config_CS1

Over this reduced subset of 6,603 reactions, the run identifies 141 potential chemotypes, 23 of which are used to assign 83.3% of the 2,945 target molecules, 99.1% of which have a traceable reaction path to their assigned chemotype. Results are written to case_study_one/, including the generated report.md.

License

This project is licensed under the MIT License — see LICENSE for details.