Tutorial 03 — Dataset hierarchy and HTML reports¶

This notebook shows the main “chemical space browser” workflow:

1. create a list of ligands
2. build a hierarchy: denticity → topology → skeleton → ligand
3. export a single self-contained HTML that you can share

Prerequisites¶

RDKit + cTopo installed in the environment.

In [1]:

try:
    from rdkit import Chem
except ImportError as e:
    raise ImportError('RDKit is required: `conda install -c conda-forge rdkit`.') from e

from IPython.display import HTML

from ctopo import ligand_from_smiles
from ctopo.trees import build_ligand_tree, tree_to_html

try: from rdkit import Chem except ImportError as e: raise ImportError('RDKit is required: `conda install -c conda-forge rdkit`.') from e from IPython.display import HTML from ctopo import ligand_from_smiles from ctopo.trees import build_ligand_tree, tree_to_html

1. A tiny example dataset¶

In real projects you’d load ligands from a file or extract them from complexes. Here we just build a small set by hand.

In [2]:

examples = {
    # bidentate N-N
    'en': '[NH2:1]CC[NH2:2]',
    'en-Me': '[NH2:1]C(C)C[NH2:2]',
    'en-Me2': '[NH2:1]C(C)C(C)[NH2:2]',
    'en-cHex': '[NH2:1]C(CCCC1)C1[NH2:2]',
    'biph': 'c1ccc[n:1]c1-c1[n:2]cccc1',
    'biph-OMe': 'c1cc(OC)c[n:1]c1-c1[n:2]cc(OC)cc1',
    'phen': 'c1cc2ccc3ccc[n:1]c3c2[n:2]c1',
    'pn': '[NH2:1]CCC[NH2:2]',
    'pn-Et': '[NH2:1]CC(CC)C[NH2:2]',
    # bidentate N-O
    'gly': '[NH2:1]CC(=O)[O-:2]',
    'ala': '[NH2:1]C(C)C(=O)[O-:2]',
    'pyCOOH': 'c1ccc[n:1]c1C(=O)[O-:2]',
    # bidentate O-O
    'ox': '[O-:1]C(=O)C(=O)[O-:2]',
    'catechol': '[O-:1]c(cccc1)c1[O-:2]',
    'acac': '[O-:1]C(=O)C(=O)[O-:2]',
    # linear tridentate
    'NNhN': 'C[N:1](C)CC[NH:2]CC[N:3](C)C',
    'PNhN': 'C[P:1](C)CC[NH:2]CC[N:3](C)C',
    'PNhP': 'C[P:1](C)CC[NH:2]CC[P:3](C)C',
    'SNhN': 'C[S:1]CC[NH:2]CC[N:3](C)C',
    'SNhP': 'C[S:1]CC[NH:2]CC[P:3](C)C',
    'SNhS': 'C[S:1]CC[NH:2]CC[S:3]C',
    'NNmeN': 'C[N:1](C)CC[N:2](C)CC[N:3](C)C',
    'PNmeN': 'C[P:1](C)CC[N:2](C)CC[N:3](C)C',
    'PNmeP': 'C[P:1](C)CC[N:2](C)CC[P:3](C)C',
    'SNmeN': 'C[S:1]CC[N:2](C)CC[N:3](C)C',
    'SNmeP': 'C[S:1]CC[N:2](C)CC[P:3](C)C',
    'SNmeS': 'C[S:1]CC[N:2](C)CC[S:3]C',
    'NNpyN': 'C[N:1](C)Cc(ccc1)[n:2]c1C[N:3](C)C',
    'PNpyN': 'C[P:1](C)Cc(ccc1)[n:2]c1C[N:3](C)C',
    'PNpyP': 'C[P:1](C)Cc(ccc1)[n:2]c1C[P:3](C)C',
    'SNpyN': 'C[S:1]Cc(ccc1)[n:2]c1C[N:3](C)C',
    'SNpyP': 'C[S:1]Cc(ccc1)[n:2]c1C[P:3](C)C',
    'SNpyS': 'C[S:1]Cc(ccc1)[n:2]c1C[S:3]C',
    # tripod tridentate
    'tripod_N_N3': 'N(CC[NH2:1])(CC[NH2:2])CC[NH2:3]',
    'tripod_N_N3_long1': 'N(CC[NH2:1])(CC[NH2:2])CCC[NH2:3]',
    'tripod_N_N3_long3': 'N(CCC[NH2:1])(CCC[NH2:2])CCC[NH2:3]',
    'tripod_C_N3': 'C(CC[NH2:1])(CC[NH2:2])CC[NH2:3]',
    'tripod_C_N3_long1': 'C(CC[NH2:1])(CC[NH2:2])CCC[NH2:3]',
    'tripod_C_N3_long3': 'C(CCC[NH2:1])(CCC[NH2:2])CCC[NH2:3]',
    'tripod_B_N3': '[BH-](CC[NH2:1])(CC[NH2:2])CC[NH2:3]',
    'tripod_B_N3_py': '[BH-](c1[n:1]cccc1)(c1[n:2]cccc1)c1[n:3]cccc1',
}

ligands = [ligand_from_smiles(smi) for smi in examples.values()]
ligand_ids = list(examples.keys())

print(f'Total number of ligands: {len(ligands)}')

examples = { # bidentate N-N 'en': '[NH2:1]CC[NH2:2]', 'en-Me': '[NH2:1]C(C)C[NH2:2]', 'en-Me2': '[NH2:1]C(C)C(C)[NH2:2]', 'en-cHex': '[NH2:1]C(CCCC1)C1[NH2:2]', 'biph': 'c1ccc[n:1]c1-c1[n:2]cccc1', 'biph-OMe': 'c1cc(OC)c[n:1]c1-c1[n:2]cc(OC)cc1', 'phen': 'c1cc2ccc3ccc[n:1]c3c2[n:2]c1', 'pn': '[NH2:1]CCC[NH2:2]', 'pn-Et': '[NH2:1]CC(CC)C[NH2:2]', # bidentate N-O 'gly': '[NH2:1]CC(=O)[O-:2]', 'ala': '[NH2:1]C(C)C(=O)[O-:2]', 'pyCOOH': 'c1ccc[n:1]c1C(=O)[O-:2]', # bidentate O-O 'ox': '[O-:1]C(=O)C(=O)[O-:2]', 'catechol': '[O-:1]c(cccc1)c1[O-:2]', 'acac': '[O-:1]C(=O)C(=O)[O-:2]', # linear tridentate 'NNhN': 'C[N:1](C)CC[NH:2]CC[N:3](C)C', 'PNhN': 'C[P:1](C)CC[NH:2]CC[N:3](C)C', 'PNhP': 'C[P:1](C)CC[NH:2]CC[P:3](C)C', 'SNhN': 'C[S:1]CC[NH:2]CC[N:3](C)C', 'SNhP': 'C[S:1]CC[NH:2]CC[P:3](C)C', 'SNhS': 'C[S:1]CC[NH:2]CC[S:3]C', 'NNmeN': 'C[N:1](C)CC[N:2](C)CC[N:3](C)C', 'PNmeN': 'C[P:1](C)CC[N:2](C)CC[N:3](C)C', 'PNmeP': 'C[P:1](C)CC[N:2](C)CC[P:3](C)C', 'SNmeN': 'C[S:1]CC[N:2](C)CC[N:3](C)C', 'SNmeP': 'C[S:1]CC[N:2](C)CC[P:3](C)C', 'SNmeS': 'C[S:1]CC[N:2](C)CC[S:3]C', 'NNpyN': 'C[N:1](C)Cc(ccc1)[n:2]c1C[N:3](C)C', 'PNpyN': 'C[P:1](C)Cc(ccc1)[n:2]c1C[N:3](C)C', 'PNpyP': 'C[P:1](C)Cc(ccc1)[n:2]c1C[P:3](C)C', 'SNpyN': 'C[S:1]Cc(ccc1)[n:2]c1C[N:3](C)C', 'SNpyP': 'C[S:1]Cc(ccc1)[n:2]c1C[P:3](C)C', 'SNpyS': 'C[S:1]Cc(ccc1)[n:2]c1C[S:3]C', # tripod tridentate 'tripod_N_N3': 'N(CC[NH2:1])(CC[NH2:2])CC[NH2:3]', 'tripod_N_N3_long1': 'N(CC[NH2:1])(CC[NH2:2])CCC[NH2:3]', 'tripod_N_N3_long3': 'N(CCC[NH2:1])(CCC[NH2:2])CCC[NH2:3]', 'tripod_C_N3': 'C(CC[NH2:1])(CC[NH2:2])CC[NH2:3]', 'tripod_C_N3_long1': 'C(CC[NH2:1])(CC[NH2:2])CCC[NH2:3]', 'tripod_C_N3_long3': 'C(CCC[NH2:1])(CCC[NH2:2])CCC[NH2:3]', 'tripod_B_N3': '[BH-](CC[NH2:1])(CC[NH2:2])CC[NH2:3]', 'tripod_B_N3_py': '[BH-](c1[n:1]cccc1)(c1[n:2]cccc1)c1[n:3]cccc1', } ligands = [ligand_from_smiles(smi) for smi in examples.values()] ligand_ids = list(examples.keys()) print(f'Total number of ligands: {len(ligands)}')

Total number of ligands: 41

2. Build the tree¶

build_ligand_tree groups ligands by a sequence of “levels”. The default levels are intended for large (> 100) datasets:

• denticity
• topology
• skeleton
• skeleton (+bond types)
• skeleton (+donor labels +bond types)
• full ligand

You can provide your own level sequence depending on the problem under consideration. Two practical patterns:

• Fast overview: stop at topology or skeleton
• Strict canonical: include bond types and donor labels before the final ligand

In [3]:

levels = ('denticity', ('topo',), ('skeleton',), "ligand")
tree = build_ligand_tree(ligands, ligand_ids=ligand_ids, levels=levels)
tree.number_of_nodes(), tree.number_of_edges()

levels = ('denticity', ('topo',), ('skeleton',), "ligand") tree = build_ligand_tree(ligands, ligand_ids=ligand_ids, levels=levels) tree.number_of_nodes(), tree.number_of_edges()

Out[3]:

(54, 53)

3. Export HTML¶

The HTML report is self-contained (inline SVG). That makes it easy to email or attach as supplementary material.

In [4]:

html = tree_to_html(tree)

# Preview in the notebook (works best locally)
HTML(html)

html = tree_to_html(tree) # Preview in the notebook (works best locally) HTML(html)

Out[4]:

root

root · leaves: 41

DA=2 [1/2]

denticity · leaves: 15

topo [1/1]

topo · leaves: 15

skeleton [1/2]

skeleton · leaves: 13

en [1/13]

ligand · leaves: 1

gly [2/13]

ligand · leaves: 1

en-Me [3/13]

ligand · leaves: 1

ox [4/13]

ligand · leaves: 1

acac [5/13]

ligand · leaves: 1

ala [6/13]

ligand · leaves: 1

en-Me2 [7/13]

ligand · leaves: 1

catechol [8/13]

ligand · leaves: 1

en-cHex [9/13]

ligand · leaves: 1

pyCOOH [10/13]

ligand · leaves: 1

biph [11/13]

ligand · leaves: 1

phen [12/13]

ligand · leaves: 1

biph-OMe [13/13]

ligand · leaves: 1

skeleton [2/2]

skeleton · leaves: 2

pn [1/2]

ligand · leaves: 1

pn-Et [2/2]

ligand · leaves: 1

DA=3 [2/2]

denticity · leaves: 26

topo [1/2]

topo · leaves: 18

skeleton [1/1]

skeleton · leaves: 18

SNhS [1/18]

ligand · leaves: 1

SNmeS [2/18]

ligand · leaves: 1

SNhN [3/18]

ligand · leaves: 1

SNhP [4/18]

ligand · leaves: 1

SNmeN [5/18]

ligand · leaves: 1

SNmeP [6/18]

ligand · leaves: 1

NNhN [7/18]

ligand · leaves: 1

PNhN [8/18]

ligand · leaves: 1

PNhP [9/18]

ligand · leaves: 1

SNpyS [10/18]

ligand · leaves: 1

NNmeN [11/18]

ligand · leaves: 1

PNmeN [12/18]

ligand · leaves: 1

PNmeP [13/18]

ligand · leaves: 1

SNpyN [14/18]

ligand · leaves: 1

SNpyP [15/18]

ligand · leaves: 1

NNpyN [16/18]

ligand · leaves: 1

PNpyN [17/18]

ligand · leaves: 1

PNpyP [18/18]

ligand · leaves: 1

topo [2/2]

topo · leaves: 8

skeleton [1/4]

skeleton · leaves: 1

tripod_B_N3_py [1/1]

ligand · leaves: 1

skeleton [2/4]

skeleton · leaves: 3

tripod_N_N3 [1/3]

ligand · leaves: 1

tripod_C_N3 [2/3]

ligand · leaves: 1

tripod_B_N3 [3/3]

ligand · leaves: 1

skeleton [3/4]

skeleton · leaves: 2

tripod_N_N3_long1 [1/2]

ligand · leaves: 1

tripod_C_N3_long1 [2/2]

ligand · leaves: 1

skeleton [4/4]

skeleton · leaves: 2

tripod_N_N3_long3 [1/2]

ligand · leaves: 1

tripod_C_N3_long3 [2/2]

ligand · leaves: 1

Save to a file¶

In [5]:

from pathlib import Path

out = Path("ligand_tree_demo.html")
out.write_text(html, encoding="utf-8")
out.resolve()

from pathlib import Path out = Path("ligand_tree_demo.html") out.write_text(html, encoding="utf-8") out.resolve()

Out[5]:

WindowsPath('D:/Work/Science/_Codes/ctopo/docs/tutorials/ligand_tree_demo.html')

4. Customizing levels¶

By default, build_ligand_tree() groups a dataset using a hierarchy that goes from coarse to fine representations:

denticity → topology → skeleton → ligand

This order is fixed because each step adds information. In other words, keys are inherited: every node at a deeper level must represent a refinement of a parent node at the previous level.

4.1 Available level families¶

Levels belong to four conceptual groups:

1. Denticity. Number of donor atoms in a ligand. This is usually the first split, because denticity defines the coordination mode and strongly constrains possible skeletons/topologies.
2. Topology has two variants:
   • bare topology: connectivity pattern only
   • topology with donor atoms (DAs): donors shown explicitly as DA nodes, so topologies are comparable across donor-element types
3. Skeleton has 3 independent toggles:
   • donors: keep donor atoms identies (instead of marked dummy nodes)
   • bonds: keep bond types inside the skeleton instead of default single bonds
   • skeleton: keep skeleton atom identities (instead of dummy nodes)
   • Inheritance rule: skeleton levels must be ordered from less detailed to more detailed (a more detailed skeleton key must refine a less detailed skeleton key).
4. Ligand nodes are leafs of the tree and correspond to actual ligands. If your dataset contains repeats (e.g. ligands extracted from many complexes), leaf nodes contain a count.

4.2 Good examples¶

In [6]:

# topo + DA => skeleton + DA + bonds
levels = ['denticity', ('topo', 'donors'), ('skeleton', 'donors', 'bonds'), 'ligand']
tree = build_ligand_tree(ligands, levels=levels)

# topo + DA => skeleton + DA + bonds levels = ['denticity', ('topo', 'donors'), ('skeleton', 'donors', 'bonds'), 'ligand'] tree = build_ligand_tree(ligands, levels=levels)

In [7]:

# topo => skeleton => skeleton + DA
levels = ['denticity', ('topo',), ('skeleton',), ('skeleton', 'donors'), 'ligand']
tree = build_ligand_tree(ligands, levels=levels)

# topo => skeleton => skeleton + DA levels = ['denticity', ('topo',), ('skeleton',), ('skeleton', 'donors'), 'ligand'] tree = build_ligand_tree(ligands, levels=levels)

4.3 Bad examples¶

In [8]:

levels = ['denticity', ('skeleton',), ('topology',), 'ligand'] # skeleton before topology

try:
    tree = build_ligand_tree(ligands, levels=levels)
except Exception as e:
    print('Invalid level specification: skeleton used before topology')

levels = ['denticity', ('skeleton',), ('topology',), 'ligand'] # skeleton before topology try: tree = build_ligand_tree(ligands, levels=levels) except Exception as e: print('Invalid level specification: skeleton used before topology')

Invalid level specification: skeleton used before topology

In [9]:

levels = ['denticity', ('skeleton', 'DA'), ('skeleton', 'bonds'), 'ligand'] # lost DA toggle

try:
    tree = build_ligand_tree(ligands, levels=levels)
except Exception as e:
    print('Invalid level specification: loist DA toggle')

levels = ['denticity', ('skeleton', 'DA'), ('skeleton', 'bonds'), 'ligand'] # lost DA toggle try: tree = build_ligand_tree(ligands, levels=levels) except Exception as e: print('Invalid level specification: loist DA toggle')

Invalid level specification: loist DA toggle

Takeaways¶

• Hierarchical grouping produces an interpretable map of ligand space.
• The HTML report is an easy “deliverable” for collaborators.

Next: Tutorial 04 demonstrates role-aware fingerprints and similarity on skeleton-only vs full-ligand views.