vibesketch.document.scheme

Tidy scheme: a whole reaction drawing laid out the way chemists draw schemes (#20).

Tidy scheme is an explicit action, never automatic, and keeps what the user decided: the order of the steps, which molecule is a reactant, a reagent or a product, and every annotation. It first cleans each molecule (vibesketch.document.clean), then places them, reading the drawing exactly as vibesketch.document.derive does:

  • The steps of a linear sequence, where one step’s products are the next step’s reactants, go in one row. Molecules are centred on the arrows’ line. A row longer than width continues below: the arrow turns down and the next row runs back the other way, as mechanisms are often drawn. Each other sequence starts a row of its own, in step order.

  • A divergent scheme, where a molecule feeds two or three steps (#81), keeps its first step in the row. The second leaves by a diagonal arrow down to a row below, the third up to a row above, and each branch runs on to the right in its row.

  • A convergent scheme, where two sequences meet in one step (#81), is laid out as a Y: the two molecules that react sit side by side, one sequence arriving from above and the other from below, and the joint step runs on to the right.

  • Each arrow is long enough for what it carries: the reagent molecules drawn above it and its condition texts below it, in their order. Beside a vertical or diagonal arrow they sit on its outer side, reagents first.

  • A side whose molecules plus signs join is laid out in a row with fresh plus signs. A side the user arranged otherwise, such as a base drawn by the hydrogen it takes, keeps that arrangement and its plus signs.

  • Compound numbers are centred under their structures.

  • Curved (electron-pushing) arrows, crossed-out arrows and free text are not laid out. Each end of a curved arrow moves with the molecule it is drawn at; free text moves with the nearest molecule.

  • Molecules in no step go in a last row.

The result is checked: vibesketch.document.derive.derive() must read the same reactions back, with the same conditions and compound numbers. If it would not, a layout without row breaks is tried. A branched scheme’s steps may come back in another order, since derive orders them by where they are drawn. If that fails too, or the scheme branches in a way the layout cannot express (a molecule feeding four steps, a branch that branches again, a join fed by a branch, or two branches that would run into each other), the drawing is left as it was and the report says why. All distances are in drawing bond lengths.

Module Attributes

WIDTH

about a two-column journal page.

Functions

scheme_metrics(ket, *[, preset])

How tidy a drawing's scheme is, its texts measured as preset publishes them.

tidy_ket(ket, *[, width, document])

A copy of ket with its scheme laid out, and what was done.

tidy_scheme(document, *[, width])

document with its scheme laid out; the normalized layer is re-derived.

Classes

SchemeReport([tidied, cleaned, rows, left, ...])

What tidying a scheme did.
vibesketch.document.scheme.WIDTH = 24.0

about a two-column journal page.

Type:

The default longest row, in bond lengths

class vibesketch.document.scheme.SchemeReport(tidied=False, cleaned=0, rows=0, left=<factory>, reason=None)[source]

Bases: object

What tidying a scheme did.

Parameters:
tidied: bool = False

Whether the drawing was laid out; False when it was left as drawn.

cleaned: int = 0

Molecules that got standard coordinates first.

rows: int = 0

Rows in the laid-out scheme.

left: list[str]

Molecules clean-up left as drawn, one line each.

reason: str | None = None

Why the scheme was left as drawn, when it was.

vibesketch.document.scheme.scheme_metrics(ket, *, preset='acs-1996')[source]

How tidy a drawing’s scheme is, its texts measured as preset publishes them.

overlaps counts the pairs of molecules, texts and plus signs whose boxes intersect (a molecule’s box reaches 0.3 bond lengths beyond its atoms), and reaction arrows, as lines 0.3 wide, that touch a box or each other; curved arrows are not counted. baseline_offset is the largest distance of a reactant or product side’s centre from its arrow’s line, along the line’s normal. arrow_room is the smallest margin of a reaction arrow’s length over its widest condition text, measured along the arrow.

Parameters:
Return type:

dict[str, float]

vibesketch.document.scheme.tidy_ket(ket, *, width=24.0, document=None)[source]

A copy of ket with its scheme laid out, and what was done.

document is the document the drawing belongs to: the check that the reactions read back unchanged keeps its species and reaction ids, and texts are measured in its publication style.

Parameters:
Return type:

tuple[dict[str, Any], SchemeReport]

vibesketch.document.scheme.tidy_scheme(document, *, width=24.0)[source]

document with its scheme laid out; the normalized layer is re-derived.

The reactions and species do not change, so they keep their ids, names, conformers and jobs. A drawing that cannot be tidied is returned as it was, and the report says why.

Parameters:
Return type:

tuple[Derivation, SchemeReport]