Run a modification workflow¶

This notebook demonstrates a typical workflow for modifying an existing oligonucleotide:

Load from XNA notation
Inspect the molecule
Replace specific monomers
Apply patterns
Export the result

Setup¶

HELMshaker bundles no monomers, so every example needs a monomer library. These docs use a small public HELMCore subset committed at docs/examples/docs_library.json. In your own code, pull a dictionary from TMR instead. See Load a monomer library.

In [1]:

Copied!

from helmshaker import Molecule, MonomerLibrary

library = MonomerLibrary()
library.load_from_file("../examples/docs_library.json")
print(f"{len(library)} monomers available")
from helmshaker import Molecule, MonomerLibrary

library = MonomerLibrary()
library.load_from_file("../examples/docs_library.json")
print(f"{len(library)} monomers available")

40 monomers available

Step 1: Load the Molecule¶

In [2]:

Copied!





from helmshaker import Molecule

xna = {
    "polymers": {
        "RNA1": {
            "phosphate": "sp.p.p.p.p.p.p.p.p.p.p.sp.sp.",
            "base": "C.U.C.C.U.U.A.A.U.C.A.A.A.T",
            "sugar": "m.fl2r.m.fl2r.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.fl2r"
        },
        "RNA2": {
            "phosphate": "sp.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.",
            "base": "U.U.G.A.U.G.G.A.G.G.A.G.A.U.A",
            "sugar": "fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r"
        },
        "CHEM1": {"CHEM": "NAME1"},
        "CHEM2": {"CHEM": "NAME2"},
    },
    "connections": [
        "RNA2,CHEM1,45:R2-1:R1",
        "CHEM1,CHEM2,1:R2-1:R1",
        "RNA1,RNA2,5:pair-38:pair",
        "RNA1,RNA2,38:pair-5:pair",
    ]
}

molecule = Molecule.from_xna(xna, strict=False, monomer_library=library)
molecule.display(separation=False)
from helmshaker import Molecule

xna = {
    "polymers": {
        "RNA1": {
            "phosphate": "sp.p.p.p.p.p.p.p.p.p.p.sp.sp.",
            "base": "C.U.C.C.U.U.A.A.U.C.A.A.A.T",
            "sugar": "m.fl2r.m.fl2r.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.fl2r"
        },
        "RNA2": {
            "phosphate": "sp.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.",
            "base": "U.U.G.A.U.G.G.A.G.G.A.G.A.U.A",
            "sugar": "fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r"
        },
        "CHEM1": {"CHEM": "NAME1"},
        "CHEM2": {"CHEM": "NAME2"},
    },
    "connections": [
        "RNA2,CHEM1,45:R2-1:R1",
        "CHEM1,CHEM2,1:R2-1:R1",
        "RNA1,RNA2,5:pair-38:pair",
        "RNA1,RNA2,38:pair-5:pair",
    ]
}

molecule = Molecule.from_xna(xna, strict=False, monomer_library=library)
molecule.display(separation=False)

Display MoleculeData: polymers=4 (RNA=2, CHEM=2), connections=4

──────────────────────────────────────────────────── Structure ────────────────────────────────────────────────────

 RNA1

│

│

 RNA2 ───  ───  ─── CHEM1

            Connectivity            
┏━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Pair        ┃ H-bonds ┃ Covalent ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ CHEM1—CHEM2 │       0 │        1 │
│ CHEM1—RNA2  │       0 │        1 │
│ RNA1—RNA2   │       2 │        0 │
└─────────────┴─────────┴──────────┘

                          Summary                          
┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓
┃ Polymer ┃ Type ┃ Residues ┃ Sugars ┃ Bases ┃ Phosphates ┃
┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩
│ RNA1    │ RNA  │       14 │     14 │    14 │         13 │
│ RNA2    │ RNA  │       16 │     16 │    16 │         15 │
│ CHEM1   │ CHEM │        1 │      0 │     0 │          0 │
│ CHEM2   │ CHEM │        1 │      0 │     0 │          0 │
└─────────┴──────┴──────────┴────────┴───────┴────────────┘

      CHEM Data      
┏━━━━━━━┳━━━━━━━━━━━┓
┃ CHEM  ┃ Chemistry ┃
┡━━━━━━━╇━━━━━━━━━━━┩
│ CHEM1 │           │
│ CHEM2 │           │
└───────┴───────────┘

                                                RNA Data 5' -> 3'                                                
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ RNA  ┃ Sugar                                                            ┃ Base            ┃ Phosphate         ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ RNA1 │ mfl2rmfl2rfl2rmfl2rmfl2rmfl2rmfl2rfl2r                           │ CUCCUUAAUCAAAT  │ spppppppppppspsp  │
│ RNA2 │ fl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2rfl2r │ UUGAUGGAGGAGAUA │ sppppppppppppppsp │
└──────┴──────────────────────────────────────────────────────────────────┴─────────────────┴───────────────────┘

                                                    Connections                                                    
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Source PolymerID ┃ Target PolymerID ┃ SourceMonomerPosition:SourceAttach… ┃ TargetMonomerPosition:TargetAttach… ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RNA2             │ CHEM1            │ 45:R2                               │ 1:R1                                │
│ CHEM1            │ CHEM2            │ 1:R2                                │ 1:R1                                │
│ RNA1             │ RNA2             │ 5:pair                              │ 38:pair                             │
│ RNA1             │ RNA2             │ 38:pair                             │ 5:pair                              │
└──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘

Step 2: Visualize the Original¶

In [3]:

Copied!

fig, ax = molecule.visualize_cartoon(title="Original Molecule", show_base=True)
fig, ax = molecule.visualize_cartoon(title="Original Molecule", show_base=True)

No description has been provided for this image

Step 3: Replace Specific Monomers¶

Replace the 6th sugar with una and the 6th base with A.

In [4]:

Copied!





# Chain the modifications together
molecule.modify(
    "replace_single", polymer_id="RNA1", pos=6, type="sugar", new_monomer="una"
).modify(
    "replace_single", polymer_id="RNA1", pos=6, type="base", new_monomer="A"
)

fig, ax = molecule.visualize_cartoon(title="After Single Replacements", show_base=True)
# Chain the modifications together
molecule.modify(
    "replace_single", polymer_id="RNA1", pos=6, type="sugar", new_monomer="una"
).modify(
    "replace_single", polymer_id="RNA1", pos=6, type="base", new_monomer="A"
)

fig, ax = molecule.visualize_cartoon(title="After Single Replacements", show_base=True)

Step 4: Apply a Sugar Pattern¶

In [5]:

Copied!

sugar_pattern = "m.fl2r.m.m.m.fl2r.m.fl2r.fl2r.m.m.m.m.fl2r"

molecule.modify("apply_pattern", polymer_id="RNA1", pattern=sugar_pattern, type="sugar")

fig, ax = molecule.visualize_cartoon(title="After Sugar Pattern", show_base=True)
sugar_pattern = "m.fl2r.m.m.m.fl2r.m.fl2r.fl2r.m.m.m.m.fl2r"

molecule.modify("apply_pattern", polymer_id="RNA1", pattern=sugar_pattern, type="sugar")

fig, ax = molecule.visualize_cartoon(title="After Sugar Pattern", show_base=True)

Step 5: Export the Result¶

You can export the modified molecule to HELM or XNA at any step.

In [6]:

Copied!

# Export to HELM
molecule.to_helm()
# Export to HELM
molecule.to_helm()

Out[6]:

'CHEM1{[NAME1]}|CHEM2{[NAME2]}|RNA1{m(C)[sp].[fl2r](U)p.m(C)p.m(C)p.m(U)p.[fl2r](A)p.m(A)p.[fl2r](A)p.[fl2r](U)p.m(C)p.m(A)p.m(A)[sp].m(A)[sp].[fl2r](T)}|RNA2{[fl2r](U)[sp].[fl2r](U)p.[fl2r](G)p.[fl2r](A)p.[fl2r](U)p.[fl2r](G)p.[fl2r](G)p.[fl2r](A)p.[fl2r](G)p.[fl2r](G)p.[fl2r](A)p.[fl2r](G)p.[fl2r](A)p.[fl2r](U)p.[fl2r](A)[sp].[fl2r]}$RNA2,CHEM1,45:R2-1:R1|CHEM1,CHEM2,1:R2-1:R1|RNA1,RNA2,5:pair-38:pair|RNA1,RNA2,38:pair-5:pair$$$V2.0'

In [7]:

Copied!

# Export to XNA
molecule.to_xna()
# Export to XNA
molecule.to_xna()

Out[7]:

defaultdict(dict,
            {'polymers': defaultdict(dict,
                         {'RNA1': {'sugar': 'm.fl2r.m.m.m.fl2r.m.fl2r.fl2r.m.m.m.m.fl2r',
                           'base': 'C.U.C.C.U.A.A.A.U.C.A.A.A.T',
                           'phosphate': 'sp.p.p.p.p.p.p.p.p.p.p.sp.sp.'},
                          'RNA2': {'sugar': 'fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r.fl2r',
                           'base': 'U.U.G.A.U.G.G.A.G.G.A.G.A.U.A.',
                           'phosphate': 'sp.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.'},
                          'CHEM1': {'unknown': 'NAME1'},
                          'CHEM2': {'unknown': 'NAME2'}}),
             'connections': ['RNA2,CHEM1,45:R2-1:R1',
              'CHEM1,CHEM2,1:R2-1:R1',
              'RNA1,RNA2,5:pair-38:pair',
              'RNA1,RNA2,38:pair-5:pair']})