How to Enumerate an R-Group Compound Library with RDKit, SMILES, and SDF

Table of contents

• Scientific introduction
  • Scaffold and attachment semantics
  • Chemical sanitization
  • Canonicalization and deduplication
  • Molecular properties and formats
• Test progress
• Demo user request
• Demo data
• Installation and implementation
• Results and artifacts
• Scaling to production libraries
• Reproducibility
• Limitations
• References
• Try this workflow

R-group enumeration generates a virtual compound library by combining a shared molecular scaffold with a defined set of substituents at labeled attachment positions. In the validated example documented here, a phenyl scaffold containing one dummy atom was combined with methyl, amino, and hydroxy substituents. RDKit 2026.03.4 produced exactly three unique sanitized molecules: toluene (Cc1ccccc1, C7H8), aniline (Nc1ccccc1, C6H7N), and phenol (Oc1ccccc1, C6H6O). Their molecular weights were 92.141, 93.129, and 94.113 g/mol, respectively.

The result is intentionally small enough to audit but complete enough to test the central software contract. The agent must recognize a dummy attachment atom, substitute every declared building block, sanitize each product, remove duplicates, calculate canonical SMILES, molecular formula and molecular weight, and preserve the library in JSON, CSV, and SDF. An earlier test only enumerated stereoisomers of lactic acid; that exercise used RDKit correctly but did not test the advertised R-group feature. It was removed rather than counted as coverage.

Scientific introduction

Medicinal chemistry often explores a series in which a relatively stable core is retained while substituents are varied. The substitutions may probe steric volume, hydrogen-bonding capacity, lipophilicity, electronics, metabolic liability, solubility, permeability, or synthetic accessibility. A virtual library formalizes those combinations before compounds are synthesized or purchased. Enumeration can support idea generation and computational triage, but it does not predict that a product is stable, synthesizable, active, safe, or novel.

The phrase “R group” is a human convention for a variable portion of a structure. In a machine representation, attachment sites must be encoded unambiguously. A dummy atom, commonly written * in SMILES and represented as atomic number zero, can mark a position where a substituent will be connected. Multiple sites generally require atom-map labels or another stable correspondence scheme so that R1, R2, and R3 are not interchanged accidentally.

Scaffold and attachment semantics

The fixture scaffold is c1ccc([*])cc1, a benzene ring with one dummy attachment. Each substituent is represented as a valid molecule: C, N, or O. The replacement operation removes the dummy atom and creates a bond from the aromatic carbon to the selected replacement atom. The resulting structures are canonicalized only after chemical sanitization.

Attachment orientation is trivial for a one-atom substituent but can be ambiguous for a multi-atom building block. If a replacement contains several candidate connection atoms, the intended connection point must be declared. Reaction SMARTS, mapped atoms, or labeled dummy atoms are often safer for production transformations. A syntactically valid SMILES can still encode the wrong connectivity, so a workflow should inspect products rather than assuming that a successful function call captured chemical intent.

The standard fixture contains only one site, producing three combinations. With independent sites, a Cartesian library can grow as the product of building-block counts. Ten options at four sites yield ten thousand nominal combinations before filtering. Symmetry, duplicate reagents, equivalent substitutions, reaction constraints, and invalid products can reduce the unique count; enumerators must report both planned and accepted counts.

Chemical sanitization

RDKit sanitization performs a sequence of consistency and perception operations, including checks related to valence, aromaticity, conjugation, hybridization, and ring information. The exact operations and exceptions are implementation details that can change with version, so both the RDKit release and failure messages should be retained. A product that cannot be sanitized must not be silently written as if it were chemically valid.

The RDKit ReplaceSubstructs documentation explicitly places responsibility for sensible products on the caller. Replacement can produce a molecular graph, but the caller must sanitize and validate it. The corrected workflow calls Chem.SanitizeMol for every product and fails the test if sanitization raises an error. This separates graph construction from chemical acceptance.

Sanitization is necessary but not sufficient. It does not prove synthetic feasibility, correct protonation at experimental pH, stereochemical completeness, tautomer choice, or stability. It proves that the toolkit can assign a coherent valence/aromaticity model under its rules. Applied enumeration should add reaction-specific constraints, protecting-group logic, charge normalization, and expert review.

Canonicalization and deduplication

Different input strings can represent the same molecular graph. Canonical SMILES provides a deterministic toolkit-specific serialization useful for grouping products, while InChIKey, graph hashes, or standardized representations can provide complementary identity keys. Canonical SMILES is version- and settings-dependent and should not be treated as a universal chemical identifier independent of aromaticity, isotope, charge, tautomer, and stereochemical handling.

The test canonicalizes every sanitized product and rejects repeated strings. It also rejects any product whose final SMILES still contains *, because a residual dummy means the requested site was not fully enumerated. Three distinct inputs must yield three distinct accepted products for this fixture. The JSON and CSV representations are then compared with the three records in the SDF.

Deduplication policy should match the research question. Two tautomers may be kept separately for one modeling workflow and merged for another. Protonation states can be biologically meaningful rather than duplicates. Undefined and specified stereoisomers must not be collapsed unintentionally. The current fixture avoids those complications so the attachment operation itself remains transparent.

Molecular properties and formats

The workflow calculates molecular formula and average molecular weight from each sanitized RDKit molecule. These properties provide compact integrity checks: methyl substitution must produce C7H8, amino substitution C6H7N, and hydroxy substitution C6H6O. The values do not rank activity and are not a complete descriptor set. They simply verify that atom composition agrees with the intended transformation.

CSV provides an inspectable table for analysis; JSON preserves structured relationships and feature metadata; SDF preserves explicit molecular records and per-record properties for structure-aware tools. A robust export should maintain stable names and identifiers across all formats. The validator counts exactly three $$$$ record delimiters in the SDF and compares the tabular structures with the JSON.

SDF can represent coordinates, bond information, properties, and multiple records. This example does not generate or validate a three-dimensional conformation, so any displayed 2D depiction is a visualization of connectivity rather than a measured geometry. Docking or physics-based calculations require separately prepared 3D states, protonation, stereochemistry, conformers, charges, and force-field decisions.

Test progress

The package dossier retains about 171 MB of compressed distributions, while the installed environment remains in the managed application directory. No uninstall was performed under the current debugging workflow. Retaining both the environment and archives permits a failed case to be examined without repeating the transfer and can support a separately reviewed offline package bundle.

Attempt 2 generated scientifically correct products but omitted the native probe’s internal feature-flag layout. The first validator treated those incidental keys as mandatory. The repaired contract instead verifies the actual chemistry: exact names, canonical structures and formulas, positive weights, no dummy atoms, three unique rows, and three SDF records. The skill documentation now states that equivalent explicit JSON organizations are accepted while chemical values remain fixed.

Demo user request

Use the R-Group Enumeration skill with data/molecules.json. Read the dummy-atom phenyl scaffold and its methyl, amino, and hydroxy substituent library. Use RDKit to replace the attachment atom, sanitize and deduplicate the products, calculate canonical SMILES, formula, and molecular weight, and report the exact product count. Save outputs/rgroup-enumeration-results.csv, outputs/rgroup-library.sdf, and outputs/enumeration-key-features.json. Do not manually write the expected products.

This request is conversational but testable. It specifies the input, transformation, quality controls, properties, product count requirement, formats, and stable paths. It does not provide a finished script or permit the agent to type the known products from prose. The application must execute the installed toolkit and preserve evidence.

Demo data

The tracked molecule specification contains one dummy-atom phenyl scaffold and three named substituents:

The file is synthetic, contains no proprietary building blocks, and is small enough for deterministic regression. It is not a screening collection and does not provide assay labels, supplier identifiers, synthesis routes, or biological targets. Those omissions prevent unsupported medicinal-chemistry conclusions while keeping the software test reviewable.

Installation and implementation

The exact Conda transaction selected 113 packages totaling 178,213,960 bytes, below the strict 500,000,000-byte automatic-download ceiling. The primary distribution was rdkit-2026.03.4-py311h361cc50_0.conda, 20,594,573 bytes, with SHA-256 a9db1fd192362457e5d1e420286465778b281734d1091f19ff88a1d0f6e2144e.

scaffold = Chem.MolFromSmiles("c1ccc([*])cc1")
dummy = Chem.MolFromSmarts("[#0]")
product = Chem.ReplaceSubstructs(
    scaffold, dummy, replacement, replaceAll=True
)[0]
Chem.SanitizeMol(product)
canonical = Chem.MolToSmiles(product, isomericSmiles=True)

This excerpt exposes the tested package-level operation. It is not a universal synthesis enumerator. Reaction-based libraries should use validated reaction SMARTS and mapped connection points; large libraries should stream records, bound combinatorial growth, and preserve failure reasons. Users of the workflow described at the end do not need to write this code themselves.

Results and artifacts

The result count is exactly three. The SDF contains three record delimiters, and every CSV structure is present in the JSON summary. No canonical product contains a dummy atom. The formulas provide independent atom-composition checks, while positive molecular weights verify that the numeric property field was populated and parseable.

The first image is captured from the focused chat result rather than a file list or raw editor. The other images derive from retained attempt-3 deliverables. Provenance manifests record their sources, generators, focused locator, timestamps, and SHA-256 values.

Scaling to production libraries

A production enumeration should calculate the nominal Cartesian size before generating products. Very large spaces may require random, diversity-based, property-constrained, or reagent-availability sampling. RDKit’s reaction-library APIs expose enumeration strategies and serialization, but the documentation cautions that some spaces can be astronomically large and that random strategies may not terminate without an external bound.

Apply filters in a declared order. Reagent validation can occur before enumeration; sanitization and structural alerts follow product generation; standardization, tautomer and protonation handling precede identity grouping when that policy is scientifically appropriate; descriptors and prediction models then support ranking. Changing the order can change the accepted library and must be recorded.

Synthetic accessibility is not guaranteed by graph substitution. Use reaction transformations grounded in the intended chemistry, verify compatible functional groups, preserve reagent provenance, and involve medicinal or synthetic chemists. Computational filters can prioritize candidates but cannot replace safety review, novelty search, intellectual-property analysis, or experimental confirmation.

Reproducibility

The validated environment was Linux x86_64 CPU with RDKit 2026.03.4 and Python 3.11. Inputs, package plan, archive checksum, native probe, natural-language request, JSON, CSV, SDF, semantic validator output, chat response, and screenshot manifests are retained. CUDA was neither required nor tested. macOS, Windows, ARM64, other RDKit releases, and other standardization policies remain unverified.

Reproduction should compare molecular graphs and declared properties, not merely row order. Canonical strings can change between toolkit versions or aromaticity settings even when graph meaning is equivalent. For the fixed version and fixture, the exact strings are stable regression expectations. An intentional upgrade should regenerate evidence, investigate differences, and update the skill documentation rather than silently accepting new output.

Every rejected product should carry a machine-readable failure reason in larger workflows. Successful output alone hides whether a reagent was incompatible, a valence failed, a transformation did not match, or a duplicate was removed. Counts at each stage—planned combinations, generated graphs, sanitized products, standardized states, duplicates and final records—make attrition auditable.

Limitations

This case tests one scaffold, one attachment site, three one-atom substituents, neutral products, no stereocenters, no tautomers, and no conformers. It does not validate multi-site atom mapping, reaction SMARTS, protecting groups, charged fragments, salts, mixtures, isotopes, organometallics, stereochemical enumeration, tautomer policy, protonation, 3D embedding, docking preparation, or billion-scale streaming.

ReplaceSubstructs is appropriate for this transparent dummy replacement but is not automatically a chemically realistic reaction engine. Sanitization checks toolkit consistency, not laboratory feasibility. Formula and molecular weight are integrity fields, not evidence of potency, selectivity, permeability, solubility, toxicity, or patentability.

The names toluene, aniline, and phenol describe the fixture products, not proposed drug candidates. No biological target or assay is present, so ranking or therapeutic claims would be unjustified. The supported conclusion is limited to correct, reproducible library construction and export for the supplied specification.

References

1. RDKit official documentation.
2. RDKit chemical transformations API, including ReplaceSubstructs.
3. RDKit reaction enumeration API documentation.
4. RDKit Python API reference.
5. Daylight SMILES theory documentation.

Try this workflow

MindPlot has built-in support for this R-group enumeration workflow. You can try it at mindplot.ai or download the desktop version for a more integrated experience and stronger local-data privacy. Users do not need to write the implementation shown above: the agent reads the installed workflow, executes RDKit, validates the products, and presents the CSV, JSON, and SDF deliverables.