ContextQMD
Back to Claude Scientific Skills

Datamol Descriptors and Visualization Reference

scientific-skills/datamol/references/descriptors_viz.md

2.38.07.2 KB
Original Source

Datamol Descriptors and Visualization Reference

Descriptors Module (datamol.descriptors)

The descriptors module provides tools for computing molecular properties and descriptors.

Specialized Descriptor Functions

dm.descriptors.n_aromatic_atoms(mol)

Calculate the number of aromatic atoms.

  • Returns: Integer count
  • Use case: Aromaticity analysis

dm.descriptors.n_aromatic_atoms_proportion(mol)

Calculate ratio of aromatic atoms to total heavy atoms.

  • Returns: Float between 0 and 1
  • Use case: Quantifying aromatic character

dm.descriptors.n_charged_atoms(mol)

Count atoms with nonzero formal charge.

  • Returns: Integer count
  • Use case: Charge distribution analysis

dm.descriptors.n_rigid_bonds(mol)

Count non-rotatable bonds (neither single bonds nor ring bonds).

  • Returns: Integer count
  • Use case: Molecular flexibility assessment

dm.descriptors.n_stereo_centers(mol)

Count stereogenic centers (chiral centers).

  • Returns: Integer count
  • Use case: Stereochemistry analysis

dm.descriptors.n_stereo_centers_unspecified(mol)

Count stereocenters lacking stereochemical specification.

  • Returns: Integer count
  • Use case: Identifying incomplete stereochemistry

Batch Descriptor Computation

dm.descriptors.compute_many_descriptors(mol, properties_fn=None, add_properties=True)

Compute multiple molecular properties for a single molecule.

  • Parameters:
    • properties_fn: Custom list of descriptor functions
    • add_properties: Include additional computed properties
  • Returns: Dictionary of descriptor name → value pairs
  • Default descriptors include:
    • Molecular weight, LogP, number of H-bond donors/acceptors
    • Aromatic atoms, stereocenters, rotatable bonds
    • TPSA (Topological Polar Surface Area)
    • Ring count, heteroatom count
  • Example:
    python
    mol = dm.to_mol("CCO")
descriptors = dm.descriptors.compute_many_descriptors(mol)
# Returns: {'mw': 46.07, 'logp': -0.03, 'hbd': 1, 'hba': 1, ...}

dm.descriptors.batch_compute_many_descriptors(mols, properties_fn=None, add_properties=True, n_jobs=1, batch_size=None, progress=False)

Compute descriptors for multiple molecules in parallel.

  • Parameters:
    • mols: List of molecules
    • n_jobs: Number of parallel jobs (-1 for all cores)
    • batch_size: Chunk size for parallel processing
    • progress: Show progress bar
  • Returns: Pandas DataFrame with one row per molecule
  • Example:
    python
    mols = [dm.to_mol(smi) for smi in smiles_list]
df = dm.descriptors.batch_compute_many_descriptors(
    mols,
    n_jobs=-1,
    progress=True
)

RDKit Descriptor Access

dm.descriptors.any_rdkit_descriptor(name)

Retrieve any descriptor function from RDKit by name.

  • Parameters: name - Descriptor function name (e.g., 'MolWt', 'TPSA')
  • Returns: RDKit descriptor function
  • Available descriptors: From rdkit.Chem.Descriptors and rdkit.Chem.rdMolDescriptors
  • Example:
    python
    tpsa_fn = dm.descriptors.any_rdkit_descriptor('TPSA')
tpsa_value = tpsa_fn(mol)

Common Use Cases

Drug-likeness Filtering (Lipinski's Rule of Five):

python
descriptors = dm.descriptors.compute_many_descriptors(mol)
is_druglike = (
    descriptors['mw'] <= 500 and
    descriptors['logp'] <= 5 and
    descriptors['hbd'] <= 5 and
    descriptors['hba'] <= 10
)

ADME Property Analysis:

python
df = dm.descriptors.batch_compute_many_descriptors(compound_library)
# Filter by TPSA for blood-brain barrier penetration
bbb_candidates = df[df['tpsa'] < 90]

Visualization Module (datamol.viz)

The viz module provides tools for rendering molecules and conformers as images.

Main Visualization Function

dm.viz.to_image(mols, legends=None, n_cols=4, use_svg=False, mol_size=(200, 200), highlight_atom=None, highlight_bond=None, outfile=None, max_mols=None, copy=True, indices=False, ...)

Generate image grid from molecules.

  • Parameters:
    • mols: Single molecule or list of molecules
    • legends: String or list of strings as labels (one per molecule)
    • n_cols: Number of molecules per row (default: 4)
    • use_svg: Output SVG format (True) or PNG (False, default)
    • mol_size: Tuple (width, height) or single int for square images
    • highlight_atom: Atom indices to highlight (list or dict)
    • highlight_bond: Bond indices to highlight (list or dict)
    • outfile: Save path (local or remote, supports fsspec)
    • max_mols: Maximum number of molecules to display
    • indices: Draw atom indices on structures (default: False)
    • align: Align molecules using MCS (Maximum Common Substructure)
  • Returns: Image object (can be displayed in Jupyter) or saves to file
  • Example:
    python
    # Basic grid
dm.viz.to_image(mols[:10], legends=[dm.to_smiles(m) for m in mols[:10]])

# Save to file
dm.viz.to_image(mols, outfile="molecules.png", n_cols=5)

# Highlight substructure
dm.viz.to_image(mol, highlight_atom=[0, 1, 2], highlight_bond=[0, 1])

# Aligned visualization
dm.viz.to_image(mols, align=True, legends=activity_labels)

Conformer Visualization

dm.viz.conformers(mol, n_confs=None, align_conf=True, n_cols=3, sync_views=True, remove_hs=True, ...)

Display multiple conformers in grid layout.

  • Parameters:
    • mol: Molecule with embedded conformers
    • n_confs: Number or list of conformer indices to display (None = all)
    • align_conf: Align conformers for comparison (default: True)
    • n_cols: Grid columns (default: 3)
    • sync_views: Synchronize 3D views when interactive (default: True)
    • remove_hs: Remove hydrogens for clarity (default: True)
  • Returns: Grid of conformer visualizations
  • Use case: Comparing conformational diversity
  • Example:
    python
    mol_3d = dm.conformers.generate(mol, n_confs=20)
dm.viz.conformers(mol_3d, n_confs=10, align_conf=True)

Circle Grid Visualization

dm.viz.circle_grid(center_mol, circle_mols, mol_size=200, circle_margin=50, act_mapper=None, ...)

Create concentric ring visualization with central molecule.

  • Parameters:
    • center_mol: Molecule at center
    • circle_mols: List of molecule lists (one list per ring)
    • mol_size: Image size per molecule
    • circle_margin: Spacing between rings (default: 50)
    • act_mapper: Activity mapping dictionary for color-coding
  • Returns: Circular grid image
  • Use case: Visualizing molecular neighborhoods, SAR analysis, similarity networks
  • Example:
    python
    # Show a reference molecule surrounded by similar compounds
dm.viz.circle_grid(
    center_mol=reference,
    circle_mols=[nearest_neighbors, second_tier]
)

Visualization Best Practices

  1. Use legends for clarity: Always label molecules with SMILES, IDs, or activity values
  2. Align related molecules: Use align=True in to_image() for SAR analysis
  3. Adjust grid size: Set n_cols based on molecule count and display width
  4. Use SVG for publications: Set use_svg=True for scalable vector graphics
  5. Highlight substructures: Use highlight_atom and highlight_bond to emphasize features
  6. Save large grids: Use outfile parameter to save rather than display in memory