# 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