ChemDraw figures with cdxkit
cdxkit turns a short Python description of a figure into two files: a CDXML that opens in ChemDraw and stays fully editable, and a PNG rendered to look like ChemDraw (600 dpi). The library is in cdxkit/ next to this file; the examples in examples/ are the fastest way to see how a figure is built.
1. Settle content and style first
- Content. Which reactions, structures, conditions and numbers go in, and where each one comes from (a paper, the user's own ChemDraw file, their notes). If something is missing, ask; never fill in a yield, condition or structure from memory.
- Style. Styles live in
styles/. Use one only when the user asks for it by name (or says e.g. "like Chapter 1", "Chapter 1 style" →styles/literature-rows.md). If the user did not name a style, ask once, offering:acs-plain: ChemDraw's ACS Document 1996 defaults, black only (styles/acs-plain.md);literature-rows: one literature reaction per row, a few colours with fixed meanings, curved in/out arrows on cycles (styles/literature-rows.md);liu-group: computational figures, i.e. energy profiles, transition states and intermediates, following the Liu group SOPs (styles/liu-group.md; also "Liu group style");- match a figure or spec the user provides. Do not apply colours or layout conventions from a style the user did not choose. For an energy profile with no style named, offer liu-group first: it is the only style with rules for profiles.
2. Rules that hold in every style
-
Faithful to the source. Draw each structure as the source draws it: same orientation, same stereochemistry (do not mirror or flip a product "to fit"; a flipped drawing suggests a different stereoisomer). Copy conditions and numbers exactly, and say what a number is (isolated vs NMR yield, d.r., ee). If the source is not available, say so instead of guessing.
-
Consistent within a figure. The same kind of thing is drawn the same way everywhere in one figure (do not show one compound as a structure and another as a condensed formula; same abbreviation, same bond length, same label style).
-
Labels read correctly. A label is written so that the bonded atom touches the bond:
- bond from the right →
OTIPSbecomesTIPSO; - bond from the left → start with the bonded atom, e.g.
Fe(CO)<sub>2</sub>Cp*; - bond from above or below → start with the bonded atom and left-align it, e.g.
('OBBu<sub>2</sub>', 'left').
Write labels as they should appear. In the CDXML, cdxkit stores a label that sits left of its bond in ChemDraw's typed order (
TIPSOis stored asOTIPS), because ChemDraw reads labels that way when it opens or saves a file. Do not reverse labels yourself. - bond from the right →
-
Look at it. Always render the PNG and view it before showing it to the user. Check for: reversed or misplaced labels, overlapping text, arrows that do not reach, crowded conditions, rows that are not centred, empty space on one side.
-
Check the file.
layout.save()printsname: self-check PASSplus anyWARNING:lines.- PASS means the CDXML reads back with RDKit with the same nodes, bonds and organic skeleton (fragments made only of labels such as
[Fe],L,Arare checked for counts only). It says nothing about how the PNG looks. - Two warnings concern bonds squeezed between labels; in both cases lengthen the bond (
L.MLfor metal bonds) or move the labels:- "bond X-Y … is hidden by its labels": the bond is missing from the PNG (it is still in the CDXML);
- "bond X-Y … shows only n pt between its labels": the bond is too short to read. A dashed TS bond shorter than about 4 pt looks solid.
- On Windows with ChemDraw installed,
cdxkit.chemdraw.export()opens the CDXML in ChemDraw and saves a ChemDraw-rendered PNG/CDX. It refuses to run while ChemDraw is already open (the user may have unsaved work) and never quits a ChemDraw it did not start.
- PASS means the CDXML reads back with RDKit with the same nodes, bonds and organic skeleton (fragments made only of labels such as
-
Hand over the
.cdxml(for editing in ChemDraw) and the.png, and list anything the user should still adjust by hand (see Limitations).
3. Using the library
import sys; sys.path.insert(0, r'<this skill folder>')
from cdxkit import Scene, mid, register_color
from cdxkit import layout as L
from cdxkit.cycle import Cycle
s = Scene() # ACS 1996: Arial 10 pt, bond 14.4 pt
m, box = L.place(s, 'C=CCC', 10, 60) # SMILES -> atoms; box = ink bbox
fe = s.add_atom_label(*L.metal_above(m[0], m[1]), '[Fe]<sup>+</sup>')
L.eta2(s, fe, m[0], m[1]) # dashed eta-2 line to the C=C midpoint
L.add_h(s, m[2], deg=-90, color='red') # explicit H (optional colour)
x = L.arrow_with_conditions(s, box[2] + 12, 60, above=['Et<sub>3</sub>N'], below=['CH<sub>2</sub>Cl<sub>2</sub>'])
L.place(s, '*CC=CC', x + 12, 60, labels={0: '[Fe]'})
L.save(s, 'out/figure') # out/figure.cdxml + .png, prints self-check
Coordinates are points (1/72 in), y grows downwards; angles are degrees counter-clockwise on paper (0 = right, 90 = up).
Atoms are found by position. add_bond(p1, p2) connects whatever atom sits at p1/p2 (within 0.6 pt), so never draw a second fragment on top of an existing one ("draw at the origin, move later" goes wrong). Draw each part at its final position, or draw it in its own Scene and copy it in with L.merge(s, part, dx, dy); RowFigure already does this for every row. The library warns when an atom lands on another one, and save() lists labels left without bonds. Text accepts <sub> <sup> <i> <b>, \n, and HTML entities (′ ′, π π, ° °).
| Need | Call |
|---|---|
| sizes | L.BL = 14.4 pt (C–C bond), L.ML = 21 pt (metal–ligand bond) |
| molecule from SMILES | L.place(s, smi, left, cy, rotate=, flip=, labels={i: 'Ar'}, align_atom=None) → (AtomMap, ink box); cy centres the ink box, or puts atom align_atom at height cy (to sit a chain on the arrow axis). L.place_center(...); L.ink_size(smi); L.orient(smi, i, j, deg, flip=) gives the rotate that points bond i→j at deg (pass the same flip as to place). AtomMaps are snapshots: after moving atoms, look them up again. A metal on a * gets a C–C length bond; lengthen it with L.stretch(s, m[c], m[star], L.ML). Put abbreviations on * atoms; give stereo in the SMILES, e.g. SMILES C/C=C(\*)c1ccccc1 (in a Python string 'C/C=C(\\*)c1ccccc1'). |
| hand-drawn fragment | `s.add_atom_label(x, y, text, align=None |
| colour a label / bond | s.paint(p, 'navy') (atom label at p), s.color_bond(p1, p2, 'red', style='bold') |
| point at an angle | L.pol(p, deg, d=L.BL) |
| metal on a π bond | L.metal_above(a1, a2), L.eta2(s, metal, a1, a2) |
| explicit H | L.add_h(s, p, deg=None, color=None) (deg=None: open direction) |
| allene centre dot | L.allene_dot(s, p) |
| arrows | L.arrow_with_conditions(s, x1, y, above=[...], below=[...], eq=False), `s.add_arrow(x1, y1, x2, y2, head='full' |
| chair / boat (six-membered cyclic TS) | L.chair(center, side=L.ML, mirror=False, flip=False) → 6 positions in ring order (plain-line textbook chair); L.boat(center, side=, mirror=, flip=) → positions of ChemDraw's boat template (draw front edge bold, tip-to-front edges as wedges; see docstring). L.polygon(center, n, side=) is for planar rings only |
| energy profile | see "Energy profiles" below |
| text | `s.add_text(x, y, text, align=, valign='baseline' |
| boxes | L.fill_box(s, box_or_Mark, pad=4, fill='fill') (tile behind a structure), s.add_rect(x, y, w, h, fill=, dashed=, rounded=), L.label_box(s, x_right, y_base, text, fill), s.add_bracket(...), L.via_bracket(s, box) |
| colours | palette names red navy grey fill rule redfill navyfill greyfill darkblue darkred (grey = #797979, darkblue #011993 and darkred #941100 are the liu-group pathway colours); more with register_color('teal', '#13786F') |
| one row per reaction | `L.RowFigure(width=468, title_position='top' |
| combine pieces | L.merge(s, part, dx, dy) copies scene part into s |
| catalytic cycle | see "Catalytic cycles" below |
| move / measure a part | mk = L.Mark(s) … draw … mk.bbox(), mk.shift(dx, dy) |
| output | L.save(s, base) → base.cdxml, base.png + self-check (s.check_cdxml needs s.to_cdxml first; save does both); cdxkit.chemdraw.export(cdxml, [png, cdx]) |
Metal centres and labels
-
Atom labels are anchored automatically:
- a label or metal symbol bonded on both sides, or with three or more bonds, is centred on the atom (
Ar–Pd–Xwith twoPPh3,L–Pd<sup>II</sup>–L); - a label whose bond comes from the right is right-aligned (
Fp–CH2,TIPSO–); - otherwise it is left-aligned, so the first character sits on the atom (
PPh3above or below a metal).
Override with
align='left'|'right'|'center'. A label cannot be anchored on a character in its middle (e.g. the Fe ofCp*Fe(CO)2); write it so that the bonded atom comes first or last. - a label or metal symbol bonded on both sides, or with three or more bonds, is centred on the atom (
-
Use
L.MLfor metal–ligand bonds. If two labels end up so close that the bond between them would vanish,save()warns.
Catalytic cycles
cyc = Cycle(s, cx, cy, r, clockwise=True, hook_radius=17, hook_sweep=72)
cyc.arc(62, 16) # arc arrow, head at 16 deg (clockwise)
cyc.hook(54, 'in', 'base') # reagent joins at 54 deg
cyc.hook(34, 'out', 'BH<sup>+</sup>') # by-product leaves at 34 deg
cyc.hook(148, 'in', draw_fn) # draw_fn(scene, (x, y)): a structure
cyc.label(26, 'deprotonation', dist=8, color='navy') # step name inside, next to its arc
- A hook touches the cycle at
thetaand curls outwards. For a clockwise cycle the free end of an'in'hook lies upstream (counter-clockwise of theta) and that of an'out'hook lies downstream. Pick theta so the free end lands in empty space. - The label or structure goes beyond the free end: to its right on the right half of the cycle, to its left on the left half, centred near the top and bottom. Force a side with
side='left'|'right'|'center';gap=sets the distance;head_in='full'puts a head on an 'in' hook. cyc.labelaccepts multi-line text ('reductive\nelimination') and keeps wide text near the top and bottom clear of the arc. Increasedistif it still touches.- Typical sizes with 10 pt text: r = 55–65 pt.
Energy profiles
from cdxkit.energy import EnergyProfile, load_energies, common_sides
E = load_energies('energies.csv', column='M06/def2-TZVP') # {label: kcal/mol}, see below
ep = EnergyProfile(energies=E) # liu-group defaults; bars='bonds' optional
ep.path(['1', 'TS1', ('2', None, dict(add='R<sub>2</sub>C=O')), '3', 'TS3a',
('4a', None, dict(add='R<sub>3</sub>SiH', remove='LCuH')), ('5a', None, dict(shift=25))])
ep.path(['3', 'TS3b', '4b']) # starts at a known label = branches there
ep.structure('TS1', draw_ts1) # draw_ts1(scene) draws the TS anywhere
# ep.note('M06/def2-TZVP/SMD(DCE)//B3LYP-D3(BJ)/6-31G(d)') # only if the user asks for it
ep.save('out/profile') # .cdxml + .png + checks + table of values
- Numbers. Take them from the user's table, never from memory or from an old figure.
- The CSV has the label in the first column and one column per method, in kcal/mol relative to one reference. Columns whose header starts with
#are notes; an empty cell or n.a. means no value. - A step given only by its label is looked up in that table.
('TS1', 12.4)gives the value directly; use it only when there is no table. - The same label in two pathways is one point. It must have the same energy in both; give different species different labels.
- The CSV has the label in the first column and one column per method, in kcal/mol relative to one reference. Columns whose header starts with
- Step options (on the step, as a dict):
add=,remove=: a reagent entering or a product leaving on the connector to the next step;at=,curve='above'|'below': where on that connector the curve touches (0 to 1), and on which side of it the curve goes. If either is left out, the library tries positions and both sides until the curve and its texts touch nothing;shift=: a scale break on the connector into this step; this and later steps are drawn that many kcal/mol higher;x=: the column slot;side='above'|'below': put both texts on that side of the bar;text=: how the number is printed, e.g.'TS2-<i>cis</i>';dh=: ΔH, printed in parentheses under ΔG.
EnergyProfileoptions:columns=1|2,span=,bar=,scale=: override the automatic layout;axis=: the axis text, e.g.'Δ<i>G</i><sub>sol</sub>\n(kcal/mol)';enthalpies=: a ΔH table;bars='lines'|'bonds': draw bars and connectors as Line-tool objects (as the SOP text says) or as bonds (as in the group's reference figure);