Modify individual monomers¶

HELMshaker provides several ways to modify oligonucleotides:

1. Replace a single monomer at a specific position
2. Apply a pattern to replace multiple monomers at once
3. Apply pre-defined patterns like gapmers, full PS backbone, etc.

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]:

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

Replace a Single Monomer¶

You can replace a specific sugar, base, or phosphate at a given position.

Example: Replace a Sugar¶

Replace the 4th sugar of RNA1 with dR:

In [2]:

from helmshaker import Molecule

helm = "RNA1{[m](A)p.[m](A)p.r(A)p.r(A)}|RNA2{r(U)p.r(U)}$RNA1,RNA2,2:pair-5:pair|RNA1,RNA2,5:pair-2:pair$$$V2.0"
molecule = Molecule.from_helm(helm, monomer_library=library)

# Show original
fig, ax = molecule.visualize_cartoon(title="Before Modification", show_base=True)

from helmshaker import Molecule helm = "RNA1{[m](A)p.[m](A)p.r(A)p.r(A)}|RNA2{r(U)p.r(U)}$RNA1,RNA2,2:pair-5:pair|RNA1,RNA2,5:pair-2:pair$$$V2.0" molecule = Molecule.from_helm(helm, monomer_library=library) # Show original fig, ax = molecule.visualize_cartoon(title="Before Modification", show_base=True)

In [3]:

# Replace the 4th sugar with d
molecule.modify("replace_single", polymer_id="RNA1", type="sugar", pos=4, new_monomer="d")

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

# Replace the 4th sugar with d molecule.modify("replace_single", polymer_id="RNA1", type="sugar", pos=4, new_monomer="d") fig, ax = molecule.visualize_cartoon(title="After Modification", show_base=True)

In [4]:

print(f"Original: {helm}")
print(f"Modified: {molecule.to_helm()}")

print(f"Original: {helm}") print(f"Modified: {molecule.to_helm()}")

Original: RNA1{[m](A)p.[m](A)p.r(A)p.r(A)}|RNA2{r(U)p.r(U)}$RNA1,RNA2,2:pair-5:pair|RNA1,RNA2,5:pair-2:pair$$$V2.0
Modified: RNA1{m(A)p.m(A)p.r(A)p.d(A)}|RNA2{r(U)p.r(U)}$RNA1,RNA2,2:pair-5:pair|RNA1,RNA2,5:pair-2:pair$$$V2.0

Replace a Base¶

In [5]:

from helmshaker import Molecule

helm = "RNA1{r(A)p.r(A)p.r(A)p.r(A)}|RNA2{r(G)p.r(G)}$$$$V2.0"
molecule = Molecule.from_helm(helm, monomer_library=library)

# Replace the 1st base with m5C
molecule.modify("replace_single", polymer_id="RNA1", type="base", pos=1, new_monomer="m5C")

print(f"Original: {helm}")
print(f"Modified: {molecule.to_helm()}")

from helmshaker import Molecule helm = "RNA1{r(A)p.r(A)p.r(A)p.r(A)}|RNA2{r(G)p.r(G)}$$$$V2.0" molecule = Molecule.from_helm(helm, monomer_library=library) # Replace the 1st base with m5C molecule.modify("replace_single", polymer_id="RNA1", type="base", pos=1, new_monomer="m5C") print(f"Original: {helm}") print(f"Modified: {molecule.to_helm()}")

Original: RNA1{r(A)p.r(A)p.r(A)p.r(A)}|RNA2{r(G)p.r(G)}$$$$V2.0
Modified: RNA1{r([m5C])p.r(A)p.r(A)p.r(A)}|RNA2{r(G)p.r(G)}$$$$V2.0

Replace a Phosphate¶

In [6]:

from helmshaker import Molecule

helm = "RNA1{r(A)p.r(A)p.r(A)p.r(A)}|RNA2{r(G)p.r(G)}$$$$V2.0"
molecule = Molecule.from_helm(helm, monomer_library=library)

# Replace the 1st phosphate with sp (phosphorothioate)
molecule.modify("replace_single", polymer_id="RNA1", type="phosphate", pos=1, new_monomer="sp")

print(f"Original: {helm}")
print(f"Modified: {molecule.to_helm()}")

from helmshaker import Molecule helm = "RNA1{r(A)p.r(A)p.r(A)p.r(A)}|RNA2{r(G)p.r(G)}$$$$V2.0" molecule = Molecule.from_helm(helm, monomer_library=library) # Replace the 1st phosphate with sp (phosphorothioate) molecule.modify("replace_single", polymer_id="RNA1", type="phosphate", pos=1, new_monomer="sp") print(f"Original: {helm}") print(f"Modified: {molecule.to_helm()}")

Original: RNA1{r(A)p.r(A)p.r(A)p.r(A)}|RNA2{r(G)p.r(G)}$$$$V2.0
Modified: RNA1{r(A)[sp].r(A)p.r(A)p.r(A)}|RNA2{r(G)p.r(G)}$$$$V2.0

---

Apply a Pattern¶

You can apply a pattern of monomers to replace multiple positions at once.

Patterns are dot-separated strings like "mR.mR.mR.fR" that are applied starting from position 1.

In [7]:

from helmshaker import Molecule

helm = "RNA1{[m](A)p.[m](A)p.r(A)p.r(A)}|RNA2{r(U)p.r(U)}$RNA1,RNA2,2:pair-5:pair|RNA1,RNA2,5:pair-2:pair$$$V2.0"
molecule = Molecule.from_helm(helm, monomer_library=library)

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

from helmshaker import Molecule helm = "RNA1{[m](A)p.[m](A)p.r(A)p.r(A)}|RNA2{r(U)p.r(U)}$RNA1,RNA2,2:pair-5:pair|RNA1,RNA2,5:pair-2:pair$$$V2.0" molecule = Molecule.from_helm(helm, monomer_library=library) fig, ax = molecule.visualize_cartoon(title="Before Pattern", show_base=True)

In [8]:

# Apply a sugar pattern
molecule.modify("apply_pattern", polymer_id="RNA1", pattern="m.m.m.fl2r", type="sugar")

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

# Apply a sugar pattern molecule.modify("apply_pattern", polymer_id="RNA1", pattern="m.m.m.fl2r", type="sugar") fig, ax = molecule.visualize_cartoon(title="After Sugar Pattern", show_base=True)

In [9]:

print(f"Original: {helm}")
print(f"Modified: {molecule.to_helm()}")

print(f"Original: {helm}") print(f"Modified: {molecule.to_helm()}")

Original: RNA1{[m](A)p.[m](A)p.r(A)p.r(A)}|RNA2{r(U)p.r(U)}$RNA1,RNA2,2:pair-5:pair|RNA1,RNA2,5:pair-2:pair$$$V2.0
Modified: RNA1{m(A)p.m(A)p.m(A)p.[fl2r](A)}|RNA2{r(U)p.r(U)}$RNA1,RNA2,2:pair-5:pair|RNA1,RNA2,5:pair-2:pair$$$V2.0

Apply a Base Pattern (Sequence)¶

In [10]:

# Apply a base pattern (this changes the sequence)
molecule.modify("apply_pattern", polymer_id="RNA1", pattern="T.T.T.T", type="base")

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

# Apply a base pattern (this changes the sequence) molecule.modify("apply_pattern", polymer_id="RNA1", pattern="T.T.T.T", type="base") fig, ax = molecule.visualize_cartoon(title="After Base Pattern", show_base=True)

/home/runner/work/cscoe-ddc-helmshaker/cscoe-ddc-helmshaker/helmshaker/services/validation_service.py:128: UserWarning: T does not match with U. Refers to connection: T:pair-U:pair
  warnings.warn(

Apply a Phosphate Pattern¶

In [11]:

# Apply an alternating phosphate pattern
molecule.modify("apply_pattern", polymer_id="RNA1", pattern="sp.p", type="phosphate")

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

# Apply an alternating phosphate pattern molecule.modify("apply_pattern", polymer_id="RNA1", pattern="sp.p", type="phosphate") fig, ax = molecule.visualize_cartoon(title="After Phosphate Pattern", show_base=True, show_phosphate=True)

---

Apply Pre-defined Patterns¶

HELMshaker includes built-in patterns like gapmers and phosphorothioate backbones. Use apply_pattern() with a pattern ID.

In [12]:

from helmshaker import Molecule

# Build a molecule from sequence
molecule = Molecule.from_sequence("ACGUACGUACGUACGUACGU", monomer_library=library)

fig, ax = molecule.visualize_cartoon(title="Before Patterns")

from helmshaker import Molecule # Build a molecule from sequence molecule = Molecule.from_sequence("ACGUACGUACGUACGUACGU", monomer_library=library) fig, ax = molecule.visualize_cartoon(title="Before Patterns")

In [13]:

# Apply a 5-10-5 moe gapmer pattern
molecule.apply_pattern("moe_gapmer_5_10_5")

fig, ax = molecule.visualize_cartoon(title="After MOE Gapmer 5-10-5")

# Apply a 5-10-5 moe gapmer pattern molecule.apply_pattern("moe_gapmer_5_10_5") fig, ax = molecule.visualize_cartoon(title="After MOE Gapmer 5-10-5")

In [14]:

# Apply full phosphorothioate backbone
molecule.apply_pattern("full_phosphorothioate")

fig, ax = molecule.visualize_cartoon(title="After Full PS Backbone", show_phosphate=True)

# Apply full phosphorothioate backbone molecule.apply_pattern("full_phosphorothioate") fig, ax = molecule.visualize_cartoon(title="After Full PS Backbone", show_phosphate=True)

In [15]:

# Check the final HELM
molecule.to_helm()

# Check the final HELM molecule.to_helm()

Out[15]:

'RNA1{[moe](A)[sp].[moe](C)[sp].[moe](G)[sp].[moe](U)[sp].[moe](A)[sp].d(C)[sp].d(G)[sp].d(U)[sp].d(A)[sp].d(C)[sp].d(G)[sp].d(U)[sp].d(A)[sp].d(C)[sp].d(G)[sp].[moe](U)[sp].[moe](A)[sp].[moe](C)[sp].[moe](G)[sp].[moe](U)}$$$$V2.0'