DOCSEARCHbyAlgolia
Submit Docs

Ketcher Documentation

repository·master·Indexed 21 days ago

https://github.com/epam/ketcher

An open-source, web-based chemical structure editor for chemists and laboratory scientists. It supports 2D and 3D structure drawing, reaction editing, and integration into web applications via a React component library. The project includes ketcher-core for domain logic and shared services, and supports both standalone and remote Indigo service providers.

Tokens
116K
Snippets
388
Records
681
Agent score
71%

What's inside Ketcher

  1. Context menu structure for monomers on micromolecules canvas

    master

    When using the FOR_MACROMOLECULE mode on a micromolecules canvas, right-clicking a monomer or a selection containing monomers displays a specific context menu structure. The menu items are organized into groups separated by visual lines (—).

    Menu Order:

    1. Collapse Monomer | Expand Monomer (only one is shown based on current state)
    2. Remove Grouping —
    3. Create Monomer (visibility depends on selection context) —
    4. Edit Monomer (enabled only for single monomer context)
    5. Edit All [monomer_code] (number_of_monomers_on_canvas) —
    6. Delete

  2. Understand monomer representations on the canvas

    master

    Ketcher uses specific geometric shapes to represent monomers on the canvas, following the notation from J.Milton (J. Chem. Inf. Model. 2017).

    Key visual characteristics:

    • Symbol Code: Each monomer shape contains a central symbol code that is unique to that specific monomer within its polymer type.
    • Color Coding: Monomers are color-filled based on their natural analog color coding.

    Monomer Shape Reference:

    NameShape Description
    Peptide monomerHexagon with edges at the top and bottom positions.
    RNA monomerA triplet of connected shapes.
    PhosphateA round shape.
    RiboseA square shape with rounded corners, oriented with an edge at the bottom.
    NucleobaseA square shape oriented as a corner at the bottom (e.g., a rhombus).
    CHEMA rectangle where the bottom edge is longer than the side edges.

  3. Use the Macromolecules Library tabs

    master

    The Macromolecules library is organized into four functional tabs to manage different types of chemical entities:

    • Favorites tab: Contains elements manually added by the user (via the star icon on library cards).
    • Peptides tab: Contains amino acid monomers organized alphabetically by their one-letter symbols. Includes an _X section_ for common N/C end modifications and amino acids without natural analogues, plus ambiguous amino acids at the bottom.
    • RNA tab: Contains the RNA builder, a presets section, and monomers categorized into sugars, bases, phosphates, and nucleotides.
    • CHEM tab: Contains non-RNA and non-amino acid monomers, such as linkers and tags.

  4. Understand Snake and Flex modes in Macromolecules mode

    master

    In Macromolecules mode, Ketcher provides two layout modes for representing polymers: Snake and Flex.

    Key Differences

    • Bond Appearance: In Flex mode, bonds are straight lines connecting monomer centers. In Snake mode, bonds can be "snake-like" with joints that avoid overlapping other monomers.
    • Layout Behavior: Entering Snake mode triggers an automatic layout of monomers and small molecules on the canvas. Entering Flex mode does not apply an automatic layout.
    • Snapping:
      • Flex mode: Supports snapping every 30 degrees (plus an additional snapping area at one bond length) and snapping to distance (horizontal/vertical).
      • Snake mode: Supports snapping every 90 degrees.

    Monomer Representations

    Unlike sequence mode where multiple monomers use one symbol, Snake and Flex modes represent every single monomer with a specific shape and color:

    • Hexagons: Amino acids (colors indicate acidity/basicity/polarity).
    • White boxes (black outline): CHEMs.
    • Blue rounded squares: Sugars.
    • Rhombuses: Bases (Purines are gray; Pyrimidines are yellow/orange/purple).
    • Coral circles: Phosphates.
    • Pentagons: Unsplit nucleotides.
    • Dark rounded squares: Unresolved IDT or AxoLabs nucleotides.

  5. Understand RNA monomer numeration in HELM notation

    master

    When RNA is graphically displayed in Ketcher using HELM notation, monomers are numbered from left to right to describe connections between polymers and to define the sequence in the HELM string representation.

    Key concepts for RNA numeration:

    • Repeating Unit: In RNA, a repeating unit consists of three connected monomers: a sugar linker, a phosphate linker (both are 'backbone' monomer types), and a nucleobase (a 'branch' monomer type).
    • Chain Selection: The longest chain of 'backbone' monomer types is selected and numbered from left to right.
    • Cycles: If the chain contains a cycle, the longest chain is selected for numbering. Any sugar or phosphate monomers not part of this chain are treated as a separate polymer.

    Numeration Sequences based on starting monomer

    The numbering within a repetitive unit depends on the starting monomer of the chain:

    1. Starting with Sugar (with nucleobase):

      • Sugar: 1
      • Nucleobase: 2
      • Phosphate: 3
      • Next repeating unit starts at: 4

    2. Starting with Sugar (without nucleobase):

      • Sugar: 1
      • Phosphate: 2
      • Next repeating unit starts at: 3

    3. Starting with Phosphate:

      • Phosphate: 1
      • Next repeating unit starts at: 2 (regardless of whether the next monomer is sugar or phosphate).

  6. Understand the LayoutData interface

    master

    The LayoutData interface is a composite data structure used in ketcher-core to represent the state of a chemical structure along with its intended output format. It inherits properties from both WithStruct and WithOutputFormat.

    An object implementing LayoutData must contain:

    1. struct: A string representing the chemical structure data.
    2. output_format: A ChemicalMimeType specifying the format in which the structure should be processed or returned.

  7. Understand the CleanResult interface

    master

    The CleanResult interface is a data structure used in ketcher-core to represent the result of a cleaning operation on a chemical structure. It combines a structural representation with its corresponding MIME type. It inherits from both WithStruct and WithFormat.

    It contains two primary properties:

    1. struct: A string representing the cleaned chemical structure.
    2. format: A ChemicalMimeType indicating the format of the structure (e.g., MDL Molfile, SMILES, etc.).

  8. Use the WithOutputFormat interface for data operations

    master

    The WithOutputFormat interface is used in ketcher-core to specify the desired chemical format for various data processing operations. It is a base interface that is extended by several core service operations, including:

    • ConvertData
    • LayoutData
    • CleanData
    • AromatizeData
    • DearomatizeData
    • CalculateCipData
    • AutomapData
    • RecognizeResult

    When calling these methods, you must provide an output_format property to tell the service which chemical MIME type the resulting data should be returned in.

  9. Use Sequence Mode for macromolecules

    master

    Sequence mode provides a text-editor-like view where nucleotides and amino acids are represented by single-letter codes.

    Visual Indicators

    • Nucleic Acids:
      • Gray background: Modified base.
      • Black frame: Modified sugar.
      • Dot: Modified phosphate.
    • Peptides:
      • Underlined: Modified amino acids.
    • Other elements: Represented by an @ symbol.

    Interaction and Editing

    • Typing/Pasting: Entities are added based on the active Typing Switcher type. Backbone connections (e.g., R1-R2 peptide bonds) are established automatically.
    • Replacing Monomers: Select an existing monomer and click a library card to replace it.
    • Modifying Nucleotides: Right-click a preset and select Modify in RNA Builder...
    • Modifying Amino Acids: Right-click an amino acid and select an appropriate modification from the context menu.

  10. Understand Monomer Context Menu behavior and items

    master

    Monomers on the micromolecules canvas are represented as MonomerMicromolecule S-groups. Right-clicking a monomer triggers the CONTEXT_MENU_ID.FOR_MACROMOLECULE menu.

    Key menu items and behaviors include:

    • Edit Monomer: Renamed from "Edit Instance". This is disabled (with a tooltip) if more than one monomer is in the current selection.
    • Edit All [code] (n): Renamed from "Edit All Instances". The count (n) represents the total number of that specific monomer on the canvas (matching library code across all SGroups), not just the selected ones. Hovering over this item highlights all matching instances on the canvas via CSS class toggling.
    • Remove Grouping: Reuses the fromSgroupDeletion() logic (the same mechanism used for "Remove Abbreviation").
    • Create Monomer: Visible only when the selection contains multiple monomers, or one monomer plus a chemical structure.
    • Delete: Always visible and enabled.
    • Expand/Collapse monomer: Standard monomer state controls.

  11. Snake Bond Drawing Logic by Monomer Position

    master

    The SnakeModePolymerBondRenderer determines the bond path by calculating the position of the second monomer relative to the first. It uses a switching logic for the R1 attachment point to ensure natural connections and avoid scenarios where both bonds connect to the same side of a monomer.

    Positional Scenarios

    For most relative positions (Bottom-Right, Top-Left, Top-Right, Bottom-Left, and Left), the renderer performs a check:

    • If the first monomer's attachment point is R1: The start and end positions are switched to recalculate and redraw a more natural bond. This prevents awkward connections (e.g., connecting two bonds to the left side of a single monomer).
    • If the attachment point is not R1: The bond is drawn directly from the starting position to the end position following the standard sequence.

    If the specific positional logic cannot be applied, the renderer defaults to drawing a simple straight line from the starting position to the end position.

  12. Monomer Context Menu Actions on Micromolecules Canvas

    master

    When working in the micromolecules (small molecules) mode, right-clicking a monomer on the canvas provides a context menu for editing and managing monomers. The menu items available and their enabled states depend on the current selection:

    • Edit Monomer: Opens the monomer creation wizard pre-loaded with the selected monomer's properties. This is only enabled when exactly one monomer is selected.
    • Edit All [monomer_code] (count): Opens the monomer creation wizard to edit all instances of the same monomer. This action is preceded by a confirmation modal. Hovering over this menu item highlights all affected monomer instances on the canvas.
    • Create Monomer: Shown only when the selection contains multiple monomers or a combination of one monomer and a chemical structure.
    • Remove Grouping: Replaces the previous "Remove Abbreviation" action. It expands the monomer if it was previously collapsed.
    • Delete: Deletes the selected monomer and any other selected elements. This is always visible and enabled.