Modification patterns

The helmshaker package allows you to declaratively define and apply common (or custom) oligonucleotide modification patterns using a simple YAML file format. This enables reproducible science and allows for easy extension with internal company or research-specific patterns.

File Structure

A pattern library is a YAML file containing a root key patterns, which is a list of individual pattern definitions:

patterns:
    - id: pattern_one
        ...
    - id: pattern_two
        ...

Pattern Definition

Each pattern is an object with two main parts: metadata for identification and a list of rules that define the actual modifications.

Metadata

• id (string, required):
  A unique, machine-friendly identifier for the pattern (e.g., moe_gapmer_5_10_5).

• name (string, required):
  A human-readable name for display purposes (e.g., "5-10-5 MOE Gapmer").

• description (string, optional):
  A detailed description of the pattern, its purpose, and its effects.

• category (string, optional):
  A category for grouping patterns (e.g., sugar, phosphate, full_aso).

• reference (string, optional):
  A scientific publication or source for the pattern.

Rules

A pattern is composed of one or more rules. Each rule targets a specific type of monomer and applies an action to a selected subset of them.

rules:
    - target: sugar
        selector: ...
        action: ...
    - target: phosphate
        action: ...

target

The target key specifies the type of monomer to modify within a residue. This is the most fundamental part of a rule:

• sugar: Targets the sugar monomer of each residue.
• phosphate: Targets the phosphate linker of each residue.
• base: Targets the base (branch) monomer of each residue.

selector

The selector is an optional key that filters the target monomers. If no selector is provided, the rule applies to all targeted monomers.

1. positions Selector

This is the most common selector. It specifies which residues to modify based on their 1-based index. It accepts a list of strings, which can be:

• Single numbers: ["1", "5", "10"] (modifies the 1st, 5th, and 10th residues)
• Ranges: ["1-5"] (modifies residues 1 through 5, inclusive)
• Negative indices: ["-1", "-2"] (modifies the last and second-to-last residues)
• Negative ranges: ["-1--5"] (modifies the last 5 residues)
• A mix of all: ["1-3", "10", "-1--3"]

Example:

selector:
    positions: ["1-5", "-1--5"] # Selects the first 5 and last 5 sugars

2. sequence_context Selector (Advanced)

This selector targets a base monomer based on the sequence around it, using regular expression syntax. It is particularly useful for context-dependent modifications.

The sequence_context value is a regular expression that will be used to find matching bases in the sequence string. You can use lookarounds to create context without including the context in the match itself.

• (?=...): Positive Lookahead. Matches if the text inside the lookahead follows the current position.
• (?<=...): Positive Lookbehind. Matches if the text inside the lookbehind precedes the current position.

Example 1: CpG Methylation
This rule targets a Cytosine (C) only if it is immediately followed by a Guanine (G):

selector:
    sequence_context: "C(?=G)" 

Example 2: Target U that follows A
This rule targets a Uracil (U) only if it is immediately preceded by an Adenine (A):

selector:
    sequence_context: "(?<=A)U"

action

The action key defines what to do to the selected monomers.

1. replace Action

This is the most common action. It replaces the selected monomer with a new one.

• type: replace
• with_symbol (string, required): The symbol of the new monomer to use, which must exist in the MonomerLibrary.

Example:

action:
    type: replace
    with_symbol: sp # Replaces the target with phosphorothioate

2. replace_pattern Action

This action is used for applying repeating or alternating modifications.

• type: replace_pattern
• symbols (list, required): A list of monomer symbols to apply in a repeating sequence.

Example:

action:
    type: replace_pattern
    symbols: [cet, d] # Creates an alternating cEt, d, cEt, d... pattern