使用 cdxkit 繪製 ChemDraw 圖形
cdxkit 可將一段簡短的 Python 圖形描述轉換為兩個檔案:一個可在 ChemDraw 中開啟並保持完全可編輯的 CDXML 檔案,以及一個渲染成 ChemDraw 風格的 PNG 圖片(600 dpi)。函式庫位於此檔案旁的 cdxkit/ 目錄中;examples/ 中的範例是了解如何建構圖形的最快方式。
1. 先確定內容與樣式
- 內容。 要納入哪些反應、結構、條件與數字,以及每個項目的來源(論文、使用者自己的 ChemDraw 檔案、筆記)。如有遺漏,應提問;絕不憑記憶填入產率、條件或結構。
- 樣式。 樣式位於
styles/目錄中。僅在使用者以名稱要求(或說「像第 1 章那樣」、「第 1 章那种风格」→styles/literature-rows.md)時才使用。如果使用者未指定樣式,則詢問一次,提供以下選項:acs-plain:ChemDraw 的 ACS Document 1996 預設值,僅黑色(styles/acs-plain.md);literature-rows:每行一個文獻反應,少數顏色具有固定含義,循環使用彎曲進/出箭頭(styles/literature-rows.md);liu-group:計算圖形,即能量輪廓、過渡態與中間體,遵循劉組 SOP(styles/liu-group.md;亦稱「刘组风格」);- 匹配使用者提供的圖形或規格。 除非使用者選擇,否則不得套用未經選取的樣式中的顏色或佈局慣例。對於未指定樣式的能量輪廓,優先提供 liu-group:它是唯一對輪廓有規則的樣式。
2. 適用於所有樣式的規則
-
忠於來源。 按照來源繪製每個結構:相同的取向,相同的立體化學(不要為了「配合」而鏡像或翻轉產物;翻轉的繪圖暗示不同的立體異構物)。精確複製條件與數字,並說明數字代表什麼(分離產率 vs. NMR 產率、d.r.、ee)。如果來源不可用,請如實告知,而非猜測。
-
圖內一致。 同一圖形中,相同類型的項目應以相同方式繪製(不要將一個化合物畫成結構式,另一個畫成縮寫式;相同的縮寫、相同的鍵長、相同的標籤樣式)。
-
標籤閱讀正確。 標籤的書寫方式應使鍵結原子接觸鍵結:
- 鍵從右側來 →
OTIPS變成TIPSO; - 鍵從左側來 → 以鍵結原子開頭,例如
Fe(CO)<sub>2</sub>Cp*; - 鍵從上方或下方來 → 以鍵結原子開頭並靠左對齊,例如
('OBBu<sub>2</sub>', 'left')。
按標籤應呈現的方式書寫。在 CDXML 中,cdxkit 儲存標籤的方式是讓其在 ChemDraw 中顯示於鍵的左側(
TIPSO儲存為OTIPS),因為 ChemDraw 在開啟或儲存檔案時會以此方式讀取標籤。請勿自行反轉標籤。 - 鍵從右側來 →
-
檢查圖形。 務必先渲染 PNG 並檢視後再展示給使用者。檢查項目包括:反轉或錯置的標籤、重疊的文字、未達終點的箭頭、擁擠的條件、未置中的行、一側的空白空間。
-
檢查檔案。
layout.save()會輸出name: self-check PASS以及任何WARNING:訊息。- PASS 表示 CDXML 可被 RDKit 正確讀回,具有相同的節點、鍵結和有機骨架(僅由
[Fe]、L、Ar等標籤組成的片段僅檢查計數)。這與 PNG 的外觀無關。 - 有兩個警告與夾在標籤之間的鍵結有關;在兩種情況下,應延長鍵結(金屬鍵使用
L.ML)或移動標籤:- "bond X-Y … is hidden by its labels":該鍵結在 PNG 中遺失(但仍存在於 CDXML 中);
- "bond X-Y … shows only n pt between its labels":該鍵結太短而無法辨識。短於約 4 pt 的虛線 TS 鍵看起來會是實線。
- 在安裝了 ChemDraw 的 Windows 系統上,
cdxkit.chemdraw.export()會在 ChemDraw 中開啟 CDXML 並儲存 ChemDraw 渲染的 PNG/CDX。如果 ChemDraw 已開啟,則拒絕執行(使用者可能有未儲存的工作),並且絕不會關閉非由它啟動的 ChemDraw。
- PASS 表示 CDXML 可被 RDKit 正確讀回,具有相同的節點、鍵結和有機骨架(僅由
-
交付
.cdxml(供在 ChemDraw 中編輯)和.png,並列出使用者仍需手動調整的項目(請參閱限制)。
3. 使用函式庫
import sys; sys.path.insert(0, r'<此技能資料夾>')
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, 鍵長 14.4 pt
m, box = L.place(s, 'C=CCC', 10, 60) # SMILES -> 原子; box = 墨跡邊界框
fe = s.add_atom_label(*L.metal_above(m[0], m[1]), '[Fe]<sup>+</sup>')
L.eta2(s, fe, m[0], m[1]) # 虛線 eta-2 線到 C=C 中點
L.add_h(s, m[2], deg=-90, color='red') # 顯式 H(可選顏色)
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, 輸出自我檢查資訊
座標以點為單位(1/72 英吋),y 軸向下增長;角度以逆時針方向測量(0 = 右,90 = 上)。
原子按位置尋找。 add_bond(p1, p2) 連接位於 p1/p2 的任何原子(容差 0.6 pt),因此切勿在現有片段之上繪製第二個片段(「在原點繪製,之後再移動」會出錯)。在最終位置繪製每個部分,或在自己的 Scene 中繪製,然後用 L.merge(s, part, dx, dy) 複製進來;RowFigure 已為每一行執行此操作。當一個原子落在另一個原子上時,函式庫會發出警告,save() 會列出沒有鍵結的標籤。文字支援 <sub> <sup> <i> <b>、\n 和 HTML 實體(′ ′、π π、° °)。
| 需求 | 呼叫方式 |
|---|---|
| 尺寸 | L.BL = 14.4 pt(C–C 鍵)、L.ML = 21 pt(金屬–配體鍵) |
| 從 SMILES 繪製分子 | L.place(s, smi, left, cy, rotate=, flip=, labels={i: 'Ar'}, align_atom=None) → (AtomMap, 墨跡框);cy 置中墨跡框,或將原子 align_atom 置於高度 cy(將鏈條置於箭頭軸線上)。L.place_center(...);L.ink_size(smi);L.orient(smi, i, j, deg, flip=) 提供將鍵結 i→j 指向 deg 所需的 rotate(傳遞與 place 相同的 flip)。AtomMap 是快照:移動原子後,重新查找它們。* 上的金屬會得到 C–C 長度的鍵結;用 L.stretch(s, m[c], m[star], L.ML) 將其延長。將縮寫放在 * 原子上;在 SMILES 中給出立體化學,例如 SMILES C/C=C(\*)c1ccccc1(在 Python 字串中為 'C/C=C(\\*)c1ccccc1')。 |
| 手繪片段 | `s.add_atom_label(x, y, text, align=None |
| 為標籤/鍵著色 | s.paint(p, 'navy')(在 p 處的原子標籤)、s.color_bond(p1, p2, 'red', style='bold') |
| 指定角度的點 | L.pol(p, deg, d=L.BL) |
| π 鍵上的金屬 | L.metal_above(a1, a2)、L.eta2(s, metal, a1, a2) |
| 顯式 H | L.add_h(s, p, deg=None, color=None)(deg=None:開放方向) |
| 丙二烯中心點 | L.allene_dot(s, p) |
| 箭頭 | L.arrow_with_conditions(s, x1, y, above=[...], below=[...], eq=False)、`s.add_arrow(x1, y1, x2, y2, head='full' |
| 椅式/船式(六元環過渡態) | L.chair(center, side=L.ML, mirror=False, flip=False) → 按環順序的 6 個位置(普通線條教科書椅式);L.boat(center, side=, mirror=, flip=) → ChemDraw 船式模板的位置(將前緣繪製為粗體,尖端到前緣的邊繪製為楔形;請參閱 docstring)。L.polygon(center, n, side=) 僅適用於平面環 |
| 能量輪廓 | 請參閱下方的「能量輪廓」 |
| 文字 | `s.add_text(x, y, text, align=, valign='baseline' |
| 框 | L.fill_box(s, box_or_Mark, pad=4, fill='fill')(結構後方的底色)、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) |
| 顏色 | 色板名稱 red navy grey fill rule redfill navyfill greyfill darkblue darkred(grey = #797979、darkblue #011993 和 darkred #941100 是 liu-group 路徑顏色);更多顏色可使用 register_color('teal', '#13786F') |
| 每行一個反應 | `L.RowFigure(width=468, title_position='top' |
| 合併片段 | L.merge(s, part, dx, dy) 將場景 part 複製到 s 中 |
| 催化循環 | 請參閱下方的「催化循環」 |
| 移動/測量部分 | mk = L.Mark(s) … 繪製 … mk.bbox()、mk.shift(dx, dy) |
| 輸出 | L.save(s, base) → base.cdxml、base.png + 自我檢查(s.check_cdxml 需要先執行 s.to_cdxml;save 會同時執行兩者);cdxkit.chemdraw.export(cdxml, [png, cdx]) |
金屬中心與標籤
-
原子標籤會自動錨定:
- 兩側都有鍵結,或有三個或更多鍵結的標籤或金屬符號,會置中於原子上(
Ar–Pd–X有兩個PPh3、L–Pd<sup>II</sup>–L); - 鍵從右側來的標籤會靠右對齊(
Fp–CH2、TIPSO–); - 否則會靠左對齊,因此第一個字元位於原子上(
PPh3在金屬上方或下方)。
使用
align='left'|'right'|'center'覆寫。標籤無法以其中間的字元(例如Cp*Fe(CO)2中的 Fe)進行錨定;書寫時應使鍵結原子位於開頭或結尾。 - 兩側都有鍵結,或有三個或更多鍵結的標籤或金屬符號,會置中於原子上(
-
對金屬–配體鍵使用
L.ML。如果兩個標籤靠得太近,導致它們之間的鍵結消失,save()會發出警告。
催化循環
cyc = Cycle(s, cx, cy, r, clockwise=True, hook_radius=17, hook_sweep=72)
cyc.arc(62, 16) # 弧形箭頭,箭頭在 16 度(順時針)
cyc.hook(54, 'in', 'base') # 試劑在 54 度加入
cyc.hook(34, 'out', 'BH<sup>+</sup>') # 副產物在 34 度離開
cyc.hook(148, 'in', draw_fn) # draw_fn(scene, (x, y)): 一個結構
cyc.label(26, 'deprotonation', dist=8, color='navy') # 步驟名稱在內部,靠近其弧形
- 掛鉤在
theta處接觸循環,並向外彎曲。對於順時針循環,'in'掛鉤的自由端位於上游(theta 的逆時針方向),而'out'掛鉤的自由端位於下游。選擇 theta 使自由端落在空白空間。 - 標籤或結構位於自由端之外:在循環的右半部分靠右,在左半部分靠左,在頂部和底部附近置中。使用
side='left'|'right'|'center'強制指定側邊;gap=設定距離;head_in='full'為 'in' 掛鉤加上箭頭。 cyc.label接受多行文字('reductive\nelimination'),並使寬文字在頂部和底部附近保持遠離弧形。如果仍然接觸,請增加dist。- 使用 10 pt 文字時的典型尺寸:r = 55–65 pt。
能量輪廓
from cdxkit.energy import EnergyProfile, load_energies, common_sides
E = load_energies('energies.csv', column='M06/def2-TZVP') # {label: kcal/mol}, 請參閱下方
ep = EnergyProfile(energies=E) # liu-group 預設值; bars='bonds' 可選
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']) # 從已知標籤開始 = 在那裡分支
ep.structure('TS1', draw_ts1) # draw_ts1(scene) 在任意位置繪製 TS
# ep.note('M06/def2-TZVP/SMD(DCE)//B3LYP-D3(BJ)/6-31G(d)') # 僅在使用者要求時
ep.save('out/profile') # .cdxml + .png + 檢查 + 數值表
- 數值。 從使用者的表格中獲取,絕不憑記憶或舊圖形獲取。
- CSV 的第一欄是標籤,其餘每欄是一種方法,單位為 kcal/mol,相對於某個參考點。標題以
#開頭的欄位是註解;空白儲存格或 n.a. 表示無數值。 - 僅由標籤給出的步驟會從該表格中查找。
('TS1', 12.4)直接給出數值;僅在沒有表格時使用。 - 兩個路徑中的相同標籤是同一點。它在兩個路徑中必須具有相同的能量;對不同的物種使用不同的標籤。
- CSV 的第一欄是標籤,其餘每欄是一種方法,單位為 kcal/mol,相對於某個參考點。標題以
- 步驟選項(在步驟上,作為字典傳入):
add=,remove=:在連接到下一步的連接器上進入的試劑或離開的產物;at=,curve='above'|'below':曲線觸及該連接器的位置(0 到 1),以及曲線位於連接器的哪一側。如果任一項未提供,函式庫會嘗試位置和兩側,直到曲線及其文字不接觸任何東西;shift=:在連接器 i 上設定的刻度中斷
…
[為翻譯而截斷]