vibesketch.document.ket

The KET bridge: between the canvas engine’s JSON and RDKit molecules.

KET is Ketcher’s document format. Reading goes KET to a molfile to RDKit, so wedge bonds become stereo centres and double-bond geometry becomes E/Z exactly as a molfile reader would see them. KET coordinates have the same orientation as a molfile’s, so no axis flips. Writing goes RDKit to KET with a bond length of 1.0, the length Ketcher draws with.

Anything the reader cannot turn into a well-defined molecule is reported, never guessed: query atoms and bonds, R-groups, polymer brackets and valence errors make a fragment unsupported with the reason.

Module Attributes

BOND_LENGTH	The bond length Ketcher draws with, in KET units.
GAP	Horizontal gap between laid-out items, in bond lengths.
COPOLYMER_SUBTYPES	A molfile copolymer's subtype (MDL SST) as KET writes it, and back.
ARROW_MODES	The KET arrow mode that draws each of the document's arrow kinds.
ROW_GAP	Vertical gap between the rows of a scheme, in bond lengths.

Functions

attachment_label(atom)	The label a KET atom shows for a material it stands for, or None (#139).
molecule_reason(molecule)	Why a KET molecule cannot be read as a plain structure, or None.
molfile(atoms, bonds)	A molfile for KET atoms and bonds, in their order; callers check molecule_reason() first.
placed_molecule(mol[, scale])	A KET molecule where mol's 2D coordinates put it, multiplied by scale.
read_scene(ket)	The molecules, arrows, plus signs and text on a KET canvas.
rgroup_node(number, logic, members, origin)	A KET R-group definition of members in a row from origin; it and its width.
stereo_reason(molecule)	Why the drawing's stereo cannot describe one absolute species, or None.
text_node(text, centre)	A KET text centred at centre, a paragraph per line.
write_scene(molecules, *[, reaction, ...])	A KET document laying molecules out in a row, or a reaction scheme.

Classes

KetAbbreviation(label, atoms)	A contracted superatom (SUP) S-group, such as Ph, drawn as its label.
KetArrow(tail, head, mode[, height])
KetFragment(mol, node, centre, bounds[, ...])	One connected molecule on the canvas.
KetScene([fragments, arrows, pluses, texts])	What the canvas holds, in chemical terms.
KetText(text, centre)
SceneStep(tail, head[, reagents, arrow, ...])	One reaction row: the molecules at the arrow's tail and head, and what is at it.

vibesketch.document.ket.ARROW_MODES = {'equilibrium': 'equilibrium-open-angle', 'forward': 'open-angle', 'resonance': 'both-ends-filled-triangle', 'retrosynthetic': 'retrosynthetic'}

The KET arrow mode that draws each of the document’s arrow kinds.

vibesketch.document.ket.BOND_LENGTH = 1.0

The bond length Ketcher draws with, in KET units.

class vibesketch.document.ket.KetAbbreviation(label, atoms)

Bases: object

A contracted superatom (SUP) S-group, such as Ph, drawn as its label.

Parameters:

• label (str)

• atoms (tuple[int, ...])

label: str

atoms: tuple[int, ...]

Its atoms, as indices of the fragment’s molecule.

class vibesketch.document.ket.KetArrow(tail: 'tuple[float, float]', head: 'tuple[float, float]', mode: 'str', height: 'float' = 1.0)

Bases: object

Parameters:

• tail (tuple[float, float])

• head (tuple[float, float])

• mode (str)

• height (float)

tail: tuple[float, float]

head: tuple[float, float]

mode: str

height: float = 1.0

class vibesketch.document.ket.KetFragment(mol, node, centre, bounds, unsupported=None, atoms=(), abbreviations=(), figure=None, caption=None)

Bases: object

One connected molecule on the canvas.

Parameters:

• mol (Any)

• node (str)

• centre (tuple[float, float])

• bounds (tuple[float, float, float, float])

• unsupported (str | None)

• atoms (tuple[int, ...])

• abbreviations (tuple[KetAbbreviation, ...])

• figure (Any)

• caption (str | None)

mol: Any

The RDKit molecule with the canvas coordinates, or None if unsupported.

node: str

The KET node it came from, for example mol0.

centre: tuple[float, float]

Centre of its atoms, in KET coordinates.

bounds: tuple[float, float, float, float]

Bounding box (xmin, ymin, xmax, ymax).

unsupported: str | None = None

Why the fragment cannot be used as a species, or None.

atoms: tuple[int, ...] = ()

Its atoms’ indices in the KET node, in the molecule’s atom order.

abbreviations: tuple[KetAbbreviation, ...] = ()

Contracted abbreviations within it; their atoms stay in mol.

figure: Any = None

A molecule to draw in figures when it cannot be a species, such as a repeat unit in brackets; None when it cannot be drawn either.

caption: str | None = None

Text figures print to its left, such as R1 = before an R-group’s definition.

class vibesketch.document.ket.KetScene(fragments=<factory>, arrows=<factory>, pluses=<factory>, texts=<factory>)

Bases: object

What the canvas holds, in chemical terms.

Parameters:

• fragments (list[KetFragment])

• arrows (list[KetArrow])

• pluses (list[tuple[float, float]])

• texts (list[KetText])

fragments: list[KetFragment]

arrows: list[KetArrow]

pluses: list[tuple[float, float]]

texts: list[KetText]

class vibesketch.document.ket.KetText(text: 'str', centre: 'tuple[float, float]')

Bases: object

Parameters:

• text (str)

• centre (tuple[float, float])

text: str

centre: tuple[float, float]

class vibesketch.document.ket.SceneStep(tail, head, reagents=<factory>, arrow='forward', conditions=<factory>)

Bases: object

One reaction row: the molecules at the arrow’s tail and head, and what is at it.

Parameters:

• tail (list[Any])

• head (list[Any])

• reagents (list[Any])

• arrow (str)

• conditions (list[str])

tail: list[Any]

head: list[Any]

reagents: list[Any]

arrow: str = 'forward'

conditions: list[str]

vibesketch.document.ket.molecule_reason(molecule)

Why a KET molecule cannot be read as a plain structure, or None.

Parameters:

molecule (dict[str, Any])

Return type:

str | None

vibesketch.document.ket.molfile(atoms, bonds)

A molfile for KET atoms and bonds, in their order; callers check molecule_reason() first.

Parameters:

• atoms (list[dict[str, Any]])

• bonds (list[dict[str, Any]])

Return type:

str

vibesketch.document.ket.placed_molecule(mol, scale=1.0)

A KET molecule where mol’s 2D coordinates put it, multiplied by scale.

For structures whose drawing is kept, such as those read from CDXML.

Parameters:

• mol (Any)

• scale (float)

Return type:

dict[str, Any]

vibesketch.document.ket.rgroup_node(number, logic, members, origin)

A KET R-group definition of members in a row from origin; it and its width.

Parameters:

• number (int)

• logic (dict[str, Any])

• members (list[Any])

• origin (tuple[float, float])

Return type:

tuple[dict[str, Any], float]

vibesketch.document.ket.read_scene(ket)

The molecules, arrows, plus signs and text on a KET canvas.

Parameters:

ket (dict[str, Any])

Return type:

KetScene

vibesketch.document.ket.stereo_reason(molecule)

Why the drawing’s stereo cannot describe one absolute species, or None.

Parameters:

molecule (dict[str, Any])

Return type:

str | None

vibesketch.document.ket.text_node(text, centre)

A KET text centred at centre, a paragraph per line.

Parameters:

• text (str)

• centre (tuple[float, float])

Return type:

dict[str, Any]

vibesketch.document.ket.write_scene(molecules, *, reaction=None, conditions=None, steps=None)

A KET document laying molecules out in a row, or a reaction scheme.

With reaction=(reactants, reagents, products) the row is the reactants joined by plus signs, an arrow with the reagents above it and the conditions below, then the products. With steps each step is such a row, the rows one below the other, a species that takes part in several steps drawn in each, and molecules in a last row.

Parameters:

• molecules (list[Any])

• reaction (tuple[list[Any], list[Any], list[Any]] | None)

• conditions (list[str] | None)

• steps (list[SceneStep] | None)

Return type:

dict[str, Any]