How to Standardize Molecules, Calculate Descriptors, Cluster Fingerprints, and Generate 3D Conformers with Datamol

Table of contents

• Scientific introduction
  • Why molecule preparation comes before analysis
  • Canonical SMILES and chemical identity
  • Interpreting molecular descriptors
  • Fingerprints, similarity, and distance
  • Butina clustering as a diversity summary
  • Three-dimensional conformers
  • Why semantic validation is necessary
• Test progress
• Demo user request
• Demo data
• Validated workflow
• Results and artifacts
• What attempts 1–4 repaired
• Applying the workflow to a real library
• Reproducibility
• Limitations
• References
• Try this workflow

A validated Datamol workflow standardized six named SMILES records, calculated molecular weight, cLogP, hydrogen-bond donor and acceptor counts, and topological polar surface area, generated 2048-bit radius-2 ECFP fingerprints, calculated a symmetric 6 × 6 distance matrix, assigned every molecule to one of five Butina clusters, and generated five three-dimensional conformers for ibuprofen. Datamol 0.12.5 produced canonical text, CSV, JSON, and SDF deliverables in retained attempt 4. The outputs passed checks for finite descriptor values, complete cluster membership, zero-diagonal symmetric distances, and a readable SDF containing nonzero three-dimensional coordinates. These are computational representations of a small synthetic teaching set, not evidence of biological activity, binding, safety, or a uniquely correct solution conformation.

Scientific introduction

Why molecule preparation comes before analysis

Cheminformatics begins with a representation, not with the physical molecule itself. A SMILES string describes a molecular graph using atoms, bonds, ring closures, branches, aromatic notation, charges, isotopes, and optional stereochemistry. Several strings can encode the same graph, and apparently similar strings can describe different protonation, tautomeric, salt, or stereochemical states. If those distinctions are ignored, duplicate detection, descriptor calculation, fingerprint similarity, database joins, and model inference can become inconsistent.

Molecular standardization applies declared graph transformations so records can be compared under a chosen convention. Typical operations include disconnecting metals, normalizing functional groups, selecting charge conventions, reionizing, removing fragments, and canonicalizing a graph into a deterministic text form. There is no universally correct standardization for every scientific question. A parent-fragment workflow appropriate for compound registration may discard a counterion that matters for formulation; neutralization may be inappropriate for a permanently charged species; tautomer canonicalization may erase a state relevant to a binding hypothesis.

The retained test uses Datamol’s standardize_mol with metal disconnection, normalization, and reionization. It then serializes canonical SMILES. The input contains aspirin, salicylic acid, acetaminophen, caffeine, ibuprofen, and ethanol. All six parse successfully. The purpose is to test a transparent preparation and analysis chain across varied small organic structures, not to define a medicinal-chemistry benchmark or a production registration policy.

Canonical SMILES and chemical identity

Canonicalization chooses one deterministic traversal and notation for a molecular graph under a particular toolkit and version. It is valuable for reproducible files and comparisons, but a canonical SMILES is not a universal chemical identifier. Different toolkits may choose different canonical strings while representing equivalent graphs. Stereochemistry can be lost if absent from the input, and protonation or tautomer state remains a modeling decision.

In this fixture, acetaminophen enters as CC(=O)NC1=CC=C(O)C=C1 and is emitted in aromatic notation as CC(=O)Nc1ccc(O)cc1. Ibuprofen retains its specified chiral marker in the standardized string. Aspirin remains CC(=O)Oc1ccccc1C(=O)O. These transformations are suitable evidence that parsing, normalization, and serialization ran. They should not be interpreted as an experimental confirmation of stereochemical purity or solution-state speciation.

For production work, preserve the original record alongside the standardized representation, version the rules, and record any rejected structures. Mapping source identifiers through preparation avoids a common failure in which the final model input can no longer be traced to the submitted compound. A scientific audit should be able to answer which transformation changed each record and why.

Interpreting molecular descriptors

Descriptors compress aspects of a graph into numerical features. Exact molecular weight in the retained CSV is computed from the represented isotopic composition and differs from an average molecular mass based on natural isotope abundance. cLogP is a calculated estimate of lipophilicity for a defined neutral representation, not a measured distribution coefficient at a stated pH. Hydrogen-bond donor and acceptor counts follow toolkit rules. Topological polar surface area estimates polar surface contribution from fragments and is not a three-dimensional solvent-accessible surface.

The six rows illustrate a useful range. Ethanol has exact molecular weight 46.041864812, cLogP approximately −0.0014, one donor, one acceptor, and TPSA 20.23 Ų. Caffeine has molecular weight 194.08037556, cLogP −1.0293, no donors, six acceptors, and TPSA 61.82 Ų. Ibuprofen has molecular weight 206.130679816, cLogP 3.0732, one donor, two acceptors, and TPSA 37.3 Ų. Aspirin has molecular weight 180.042258736, cLogP 1.3101, one donor, four acceptors, and TPSA 63.6 Ų.

These values are appropriate for software validation and exploratory comparison. They are not direct measurements, and extra decimal places do not imply corresponding experimental accuracy. Descriptor definitions and aromaticity, protonation, and sanitization rules can change values. A model trained with one toolkit and preparation pipeline should not silently receive descriptors from another.

Fingerprints, similarity, and distance

Circular fingerprints describe atom-centered neighborhoods out to a chosen radius. The demonstration requests ECFP-style fingerprints with radius 2 and 2048 bits, commonly described as ECFP4 because the diameter is four bonds. Local substructures are hashed into a fixed-length bit vector. Hash collisions are possible: different environments may activate the same bit. Increasing bit length can reduce collisions but does not turn the representation into a complete molecular identity.

Similarity between bit fingerprints is commonly calculated with the Tanimoto coefficient. For bit sets A and B, it is the size of their intersection divided by the size of their union. The retained summary stores distances rather than similarities, with zero on the diagonal and values between zero and one. The matrix is symmetric. Aspirin and salicylic acid have the smallest off-diagonal distance in this fixture, approximately 0.6410, consistent with their shared aromatic carboxylic-acid motif and related substructure. Caffeine and ethanol have distance approximately 0.9744, one of the largest pairwise separations in this small set.

Fingerprint distance is representation-dependent. Radius, bit length, chirality handling, feature type, standardization, and coefficient all matter. A smaller distance means greater similarity under those choices, not guaranteed shared target activity or interchangeable chemistry. Similarity thresholds used for library diversity or train/test splitting must be documented and validated for the scientific purpose.

Butina clustering as a diversity summary

Butina clustering groups objects by neighbors within a distance threshold. A typical procedure counts each molecule’s neighbors, chooses a high-connectivity center, forms a cluster from its unassigned neighbors, and repeats. It is deterministic only when distances and tie ordering are controlled. Cluster count depends strongly on representation and cutoff; it is not an intrinsic number of “chemical families.”

At cutoff 0.65, the retained run produces five clusters covering indices 0 through 5 exactly once. Aspirin and salicylic acid form the only two-member cluster; ethanol, ibuprofen, caffeine, and acetaminophen are singletons in this tiny collection. This is a faithful description of the selected fingerprint-distance geometry. It does not establish scaffold classes, pharmacological classes, or statistically stable chemical-space populations.

For a larger library, cluster-size distribution can support diversity selection, redundancy analysis, or split design. Researchers should check threshold sensitivity and visualize representative structures. A random split of close analogues across training and test sets can exaggerate apparent model generalization; similarity-aware splits can better test extrapolation, but no single clustering rule solves every leakage problem.

Three-dimensional conformers

A molecular graph does not specify one three-dimensional geometry. Rotatable bonds and ring flexibility can produce multiple conformers, while protonation, tautomerism, solvent, temperature, and environment influence their populations. Distance-geometry embedding creates candidate coordinates subject to graph-derived constraints, and a force field may refine them to local minima. Generated conformers are hypotheses, not experimentally determined structures.

The test asks Datamol to generate five ibuprofen conformers using random_seed=7 and RMS cutoff 0.2. The in-memory molecule reports five conformers. The SDF writer serializes a readable 3D structure record containing nonzero z coordinates; the validator confirms a V2000 or V3000 mol block and a successful RDKit round trip. The SDF is one molecular record, not five separately enumerated records. Accordingly, the result should be described as a molecule for which five conformers were generated before serialization, with a validated 3D SDF deliverable.

If an application requires an explicit ensemble file, it should export one record per conformer with stable identifiers, energies, method parameters, units, and ranking. Conformer count alone does not demonstrate coverage. Flexible molecules may need more candidates, alternate embedding parameters, energy minimization, duplicate pruning, and comparison with experimental structures.

Why semantic validation is necessary

File existence is weak evidence. A CSV can contain NaN, an SDF can be two-dimensional or unreadable, a distance matrix can be asymmetric, and a clustering list can omit molecules. The Datamol validator opens every deliverable. It requires version 0.12.5, six molecules, a 2048-bit fingerprint setting, matrix shape 6 × 6, complete cluster membership, at least one reported conformer, six finite descriptor rows, six standardized SMILES, a readable mol block, and nonzero third-coordinate values.

The validator also accepts documented semantic field aliases. Language-generated code can use molecule_count instead of molecules or fingerprint_bit_count instead of fingerprint_bits without changing meaning. A robust contract should permit equivalent explicit names while rejecting missing concepts. Attempts 1 and 3 were scientifically correct in major outputs but failed because the validator did not yet recognize the actual alias. The eventual repair expanded accepted aliases, then reran the unchanged scientific case.

Test progress

Demo user request

Use Datamol 0.12.5 to load the six molecules in data/molecules.csv, standardize and canonicalize them, calculate molecular weight, cLogP, hydrogen-bond donor and acceptor counts, and TPSA, generate 2048-bit radius-2 ECFP fingerprints, compute the pairwise distance matrix, cluster the molecules with a 0.65 cutoff, and generate five ibuprofen conformers with seed 7. Save descriptors.csv, standardized.smi, summary.json, and ibuprofen-conformers.sdf, then verify the SDF contains real 3D coordinates.

The request names scientific outcomes and reproducibility parameters. It does not require the user to translate them into toolkit APIs. Canonical filenames make automated review deterministic.

Demo data

The six-row input CSV is a synthetic, repository-owned fixture. Its common molecule names aid human review, but the names are not used to calculate results. SMILES are input representations rather than verified samples from a physical inventory. The local provenance note records its test role.

Validated workflow

The installer first used a download-only preflight for datamol==0.12.5 on Linux AMD64 and Python 3.11. It observed 137,032,438 bytes, below the strict 500,000,000-byte local ceiling. Packages and the managed environment were retained after testing rather than uninstalled.

The workflow parsed each SMILES, standardized the graph, and generated canonical text. It calculated descriptors, created radius-2 2048-bit fingerprints, computed pairwise distances with one job for determinism, and checked the matrix bounds, diagonal, and symmetry. Butina clustering at 0.65 had to assign all six indices exactly once. Ibuprofen conformers were generated with a fixed seed, checked as 3D, serialized to SDF, and read back.

six named SMILES
  → parse and standardize molecular graphs
  → canonical SMILES and finite descriptors
  → 2048-bit radius-2 circular fingerprints
  → symmetric pairwise distance matrix
  → cutoff-based Butina clustering
  → seeded ibuprofen 3D conformer generation
  → CSV + SMI + JSON + SDF semantic validation

For transparent developer reproduction:

python test/scientific-skills/run_skill_cycle.py datamol
python test/scientific-skills/skills/datamol/chat_e2e.py
python test/scientific-skills/validate_how_to.py \
  test/scientific-skills/skills/datamol

These commands document the test chain; they are not a requirement that scientific users write cheminformatics code.

Results and artifacts

The validated result contains six standardized structures and descriptor rows, 2048-bit radius-2 ECFP settings, a symmetric 6 × 6 distance matrix, five clusters with complete membership, and five generated ibuprofen conformers before SDF serialization. The SDF contains a readable 3D molecular record. No activity prediction, docking score, conformer energy, experimental agreement, or pharmacokinetic conclusion was calculated.

The focused result capture displays actual retained results and qualifications rather than a file list, prompt composer, raw JSON editor, or terminal.

The inventory visual is derived from real output sizes. The authoritative deliverables are descriptors.csv, standardized.smi, summary.json, and ibuprofen-conformers.sdf.

The table visual is derived from retained structured data. Exact decimal values and the complete distance matrix remain in the machine-readable files.

What attempts 1–4 repaired

Attempt 1 generated correct major outputs: six molecules, 2048-bit ECFP4, a symmetric 6 × 6 matrix, five clusters, and five conformers. It nevertheless failed closed because the summary used fingerprint_bit_count, while the validator accepted only fingerprint_bits or fingerprint_size. The right repair was not to discard correct evidence or weaken the scientific requirement; it was to recognize an unambiguous semantic alias.

Attempt 2 did not complete chat execution. The runtime produced no activity for 180 seconds, and the watchdog interrupted the stalled turn. It received no feature credit. This distinguishes infrastructure liveness from chemical correctness.

Attempt 3 again generated correct outputs and passed substantial checks, but its conformer count used actual_conformer_count. The validator accepted only conformers or conformer_count, so semantic validation failed. The accepted alias list was extended to cover the equally explicit name.

Attempt 4 reran the same case and passed. The final validator accepts datamol_version or version; molecules or molecule_count; three explicit fingerprint-bit names; two distance-shape names; and three conformer-count names. It still requires the exact meanings, values, full cluster membership, finite descriptors, six SMILES, readable SDF syntax, and nonzero 3D coordinates. Alias flexibility therefore improves robustness without granting credit to missing science.

Applying the workflow to a real library

Begin by defining a standardization policy suitable for the question. Decide how to handle salts, mixtures, isotopes, charges, tautomers, stereochemistry, organometallics, and invalid structures. Preserve source records and transformation logs. Evaluate the policy on known edge cases before processing millions of records.

Calculate only descriptors with a declared role. Check distributions, missingness, extreme values, duplicates, and dependence on molecular size. When descriptors feed a model, fit preprocessing on training data only and pin the exact software environment. Avoid interpreting correlated heuristic descriptors as independent experimental facts.

For fingerprints, record algorithm, radius, length, feature and chirality settings, and similarity coefficient. Test clustering stability across cutoffs. Inspect representative structures and cluster sizes rather than accepting a cluster count alone. For model evaluation, assess whether near neighbors cross dataset splits.

For conformers, enumerate relevant protonation and tautomer states before embedding when the application requires them. Generate enough candidates for flexibility, minimize with an appropriate force field, record energies and convergence, remove duplicates with a declared RMS rule, and export each intended conformer explicitly. High-consequence structural conclusions require comparison with experimental or higher-level computational evidence.

Reproducibility

Validation was completed on 2026-07-26 using Linux AMD64, Python 3.11, and Datamol 0.12.5. The preflight observed 137,032,438 bytes. Execution used CPU only and did not require CUDA. The generated artifacts then passed independent semantic checks.

The exact six input SMILES, standardization flags, fingerprint radius 2, bit length 2048, clustering cutoff 0.65, one-job distance calculation, requested five conformers, RMS cutoff 0.2, and seed 7 should be preserved. A new Datamol or RDKit version is a new validation condition because canonicalization, descriptors, fingerprints, embedding, and SDF behavior can change. Publication manifests bind each image to source evidence using SHA-256.

Limitations

The fixture has only six familiar molecules. It does not exercise salts, metals, malformed SMILES, unusual valence, isotopes, multiple fragments, tautomer enumeration, stereochemical ambiguity, or macromolecules. Five clusters from six records are not evidence of broad chemical diversity.

Descriptor values are computed, not measured. Fingerprint distance is not biological similarity. The generated conformers have no reported energies or population weights and were not compared with crystal or solution structures. The SDF validation establishes readable three-dimensional coordinates, not five separately serialized conformer records.

The test does not validate QSAR modeling, docking, pharmacophore generation, database searching, GPU acceleration, or production-scale throughput. Scientific and regulatory use requires domain-specific review and data governance.

References

• Maziarka, Ł. et al. “Molecule Attention Transformer.” arXiv (2020), describing graph-based molecular representation context. DOI: 10.48550/arXiv.2002.08264
• Rogers, D. and Hahn, M. “Extended-Connectivity Fingerprints.” Journal of Chemical Information and Modeling 50(5), 742–754 (2010). DOI: 10.1021/ci100050t
• Butina, D. “Unsupervised Data Base Clustering Based on Daylight’s Fingerprint and Tanimoto Similarity.” Journal of Chemical Information and Computer Sciences 39(4), 747–750 (1999). DOI: 10.1021/ci9803381
• Riniker, S. and Landrum, G. A. “Better Informed Distance Geometry: Using What We Know To Improve Conformation Generation.” Journal of Chemical Information and Modeling 55(12), 2562–2574 (2015). DOI: 10.1021/acs.jcim.5b00654
• Datamol project. Official Datamol documentation
• RDKit project. Official RDKit documentation

Try this workflow

MindPlot has built-in support for the demonstrated Datamol skill. A user can describe molecular preparation, descriptors, fingerprints, clustering, and conformer deliverables in ordinary language; the MindPlot agent writes and runs the necessary code, preserves the chemical outputs, and presents the validated result. Users do not need to write the reproduction commands above. Try it at https://mindplot.ai, or download the desktop version for a more integrated experience and stronger local-data privacy.