End to end¶

This walkthrough covers the main things HELMshaker does:

1. Loading molecules from HELM, XNA, or sequence
2. Visualization with cartoon and display views
3. Conversion between formats
4. Accessing molecule data for analysis
5. Modifications including pattern application
6. Building duplexes with hydrogen bond pairings

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")

from helmshaker import Molecule, MonomerLibrary library = MonomerLibrary() library.load_from_file("../examples/docs_library.json")

1. Loading Molecules¶

HELMshaker supports multiple input formats. Use the appropriate from_* method:

In [2]:

# From HELM notation
helm = "CHEM1{[Ahx]}|CHEM2{[OVal]}|RNA1{[m](U)[sp].[fl2r](U)[sp].[m](U)p.[fl2r](C)p.[m](A)p.[fl2r](U)p.[m](U)p.[fl2r](A)p.[m](A)p.[fl2r](G)p.[m](G)p.[fl2r](C)p.[m](C)p.[fl2r](A)p.[m](C)p.[fl2r](G)p.[m](A)p.[fl2r](G)p.[m](A)[sp].[m](U)[sp].[m](U)}|RNA2{[fl2r](U)[sp].[m](C)[sp].[fl2r](U)p.[m](C)p.[fl2r](G)p.[m](U)p.[fl2r](G)p.[m](G)p.[fl2r](C)p.[m](C)p.[fl2r](U)p.[m](U)p.[fl2r](A)p.[m](A)p.[fl2r](U)p.[m](G)p.[fl2r](A)p.[m](A)[sp].[fl2r](A)[sp]}$RNA2,CHEM1,57:R2-1:R1|CHEM1,CHEM2,1:R2-1:R1|RNA2,RNA1,11:pair-47:pair|RNA2,RNA1,14:pair-44:pair|RNA2,RNA1,17:pair-41:pair|RNA2,RNA1,20:pair-38:pair|RNA2,RNA1,23:pair-35:pair|RNA2,RNA1,26:pair-32:pair|RNA2,RNA1,29:pair-29:pair|RNA2,RNA1,2:pair-56:pair|RNA2,RNA1,32:pair-26:pair|RNA2,RNA1,35:pair-23:pair|RNA2,RNA1,38:pair-20:pair|RNA2,RNA1,41:pair-17:pair|RNA2,RNA1,44:pair-14:pair|RNA2,RNA1,47:pair-11:pair|RNA2,RNA1,50:pair-8:pair|RNA2,RNA1,53:pair-5:pair|RNA2,RNA1,56:pair-2:pair|RNA2,RNA1,5:pair-53:pair|RNA2,RNA1,8:pair-50:pair$$$V2.0"

molecule = Molecule.from_helm(helm, monomer_library=library)
print("Loaded from HELM")

# From HELM notation helm = "CHEM1{[Ahx]}|CHEM2{[OVal]}|RNA1{[m](U)[sp].[fl2r](U)[sp].[m](U)p.[fl2r](C)p.[m](A)p.[fl2r](U)p.[m](U)p.[fl2r](A)p.[m](A)p.[fl2r](G)p.[m](G)p.[fl2r](C)p.[m](C)p.[fl2r](A)p.[m](C)p.[fl2r](G)p.[m](A)p.[fl2r](G)p.[m](A)[sp].[m](U)[sp].[m](U)}|RNA2{[fl2r](U)[sp].[m](C)[sp].[fl2r](U)p.[m](C)p.[fl2r](G)p.[m](U)p.[fl2r](G)p.[m](G)p.[fl2r](C)p.[m](C)p.[fl2r](U)p.[m](U)p.[fl2r](A)p.[m](A)p.[fl2r](U)p.[m](G)p.[fl2r](A)p.[m](A)[sp].[fl2r](A)[sp]}$RNA2,CHEM1,57:R2-1:R1|CHEM1,CHEM2,1:R2-1:R1|RNA2,RNA1,11:pair-47:pair|RNA2,RNA1,14:pair-44:pair|RNA2,RNA1,17:pair-41:pair|RNA2,RNA1,20:pair-38:pair|RNA2,RNA1,23:pair-35:pair|RNA2,RNA1,26:pair-32:pair|RNA2,RNA1,29:pair-29:pair|RNA2,RNA1,2:pair-56:pair|RNA2,RNA1,32:pair-26:pair|RNA2,RNA1,35:pair-23:pair|RNA2,RNA1,38:pair-20:pair|RNA2,RNA1,41:pair-17:pair|RNA2,RNA1,44:pair-14:pair|RNA2,RNA1,47:pair-11:pair|RNA2,RNA1,50:pair-8:pair|RNA2,RNA1,53:pair-5:pair|RNA2,RNA1,56:pair-2:pair|RNA2,RNA1,5:pair-53:pair|RNA2,RNA1,8:pair-50:pair$$$V2.0" molecule = Molecule.from_helm(helm, monomer_library=library) print("Loaded from HELM")

Loaded from HELM

In [3]:

# From XNA notation
xna = {
    "polymers": {
        "RNA1": {
            "sugar": "m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.m.m",
            "phosphate": "sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp.",
            "base": "U.U.U.C.A.U.U.A.A.G.G.C.C.A.C.G.A.G.A.U.U"
        },
        "RNA2": {
            "sugar": "fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r",
            "phosphate": "sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp",
            "base": "U.C.U.C.G.U.G.G.C.C.U.U.A.A.U.G.A.A.A"
        }
    }
}

molecule_xna = Molecule.from_xna(xna, monomer_library=library)
print("Loaded from XNA")

# From XNA notation xna = { "polymers": { "RNA1": { "sugar": "m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.m.m", "phosphate": "sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp.", "base": "U.U.U.C.A.U.U.A.A.G.G.C.C.A.C.G.A.G.A.U.U" }, "RNA2": { "sugar": "fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r", "phosphate": "sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp", "base": "U.C.U.C.G.U.G.G.C.C.U.U.A.A.U.G.A.A.A" } } } molecule_xna = Molecule.from_xna(xna, monomer_library=library) print("Loaded from XNA")

Loaded from XNA

In [4]:

# From simple sequence
molecule_seq = Molecule.from_sequence("AUGCUGACUUGCUAUGCUAA", monomer_library=library)
print("Loaded from sequence")

# From simple sequence molecule_seq = Molecule.from_sequence("AUGCUGACUUGCUAUGCUAA", monomer_library=library) print("Loaded from sequence")

Loaded from sequence

2. Visualization¶

HELMshaker provides two visualization methods:

• display() - Text-based XNA view
• visualize_cartoon() - Graphical cartoon view

In [5]:

# Text display
molecule.display()

# Text display molecule.display()

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

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

 RNA1                    

  │                      

  │                      

 RNA2 ───  ───  ─── CHEM1

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

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

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

                                                 RNA Data 5' -> 3'                                                 
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RNA  ┃ Sugar                             ┃ Base                              ┃ Phosphate                        ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RNA1 │ m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl… │ U.U.U.C.A.U.U.A.A.G.G.C.C.A.C.G.… │ sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p… │
│ RNA2 │ fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r… │ U.C.U.C.G.U.G.G.C.C.U.U.A.A.U.G.… │ sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p… │
└──────┴───────────────────────────────────┴───────────────────────────────────┴──────────────────────────────────┘

                                                    Connections                                                    
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Source PolymerID ┃ Target PolymerID ┃ SourceMonomerPosition:SourceAttach… ┃ TargetMonomerPosition:TargetAttach… ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RNA2             │ CHEM1            │ 57:R2                               │ 1:R1                                │
│ CHEM1            │ CHEM2            │ 1:R2                                │ 1:R1                                │
│ RNA2             │ RNA1             │ 11:pair                             │ 47:pair                             │
│ RNA2             │ RNA1             │ 14:pair                             │ 44:pair                             │
│ RNA2             │ RNA1             │ 17:pair                             │ 41:pair                             │
│ RNA2             │ RNA1             │ 20:pair                             │ 38:pair                             │
│ RNA2             │ RNA1             │ 23:pair                             │ 35:pair                             │
│ RNA2             │ RNA1             │ 26:pair                             │ 32:pair                             │
│ RNA2             │ RNA1             │ 29:pair                             │ 29:pair                             │
│ RNA2             │ RNA1             │ 2:pair                              │ 56:pair                             │
│ RNA2             │ RNA1             │ 32:pair                             │ 26:pair                             │
│ RNA2             │ RNA1             │ 35:pair                             │ 23:pair                             │
│ RNA2             │ RNA1             │ 38:pair                             │ 20:pair                             │
│ RNA2             │ RNA1             │ 41:pair                             │ 17:pair                             │
│ RNA2             │ RNA1             │ 44:pair                             │ 14:pair                             │
│ RNA2             │ RNA1             │ 47:pair                             │ 11:pair                             │
│ RNA2             │ RNA1             │ 50:pair                             │ 8:pair                              │
│ RNA2             │ RNA1             │ 53:pair                             │ 5:pair                              │
│ RNA2             │ RNA1             │ 56:pair                             │ 2:pair                              │
│ RNA2             │ RNA1             │ 5:pair                              │ 53:pair                             │
│ RNA2             │ RNA1             │ 8:pair                              │ 50:pair                             │
└──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘

In [6]:

# Cartoon visualization with options
fig, ax = molecule.visualize_cartoon(
    title="siRNA with Conjugate",
    show_base=True,
    show_phosphate=True,
    show_direction=True,
    show_position=True,
    show_legend=True
)

# Cartoon visualization with options fig, ax = molecule.visualize_cartoon( title="siRNA with Conjugate", show_base=True, show_phosphate=True, show_direction=True, show_position=True, show_legend=True )

Cartoon Options¶

The visualize_cartoon() method accepts many parameters:

Parameter	Description
title	Title for the plot
show_base	Display bases on sugars
show_phosphate	Color phosphate linkers
show_direction	Annotate 5' and 3' ends
show_position	Show nucleotide positions
show_legend	Display color legend
show_conjugate	Include conjugates
start_polymer	Which strand on top

3. Format Conversion¶

Convert between formats using to_* methods:

In [7]:

# To HELM
print("HELM:")
print(molecule.to_helm()[:100] + "...")

# To HELM print("HELM:") print(molecule.to_helm()[:100] + "...")

HELM:
CHEM1{[Ahx]}|CHEM2{[OVal]}|RNA1{m(U)[sp].[fl2r](U)[sp].m(U)p.[fl2r](C)p.m(A)p.[fl2r](U)p.m(U)p.[fl2r...

In [8]:

# To XNA
print("XNA:")
molecule.to_xna()

# To XNA print("XNA:") molecule.to_xna()

XNA:

Out[8]:

defaultdict(dict,
            {'polymers': defaultdict(dict,
                         {'CHEM1': {'CHEM': 'Ahx'},
                          'CHEM2': {'CHEM': 'OVal'},
                          'RNA1': {'sugar': 'm.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.m.m',
                           'base': 'U.U.U.C.A.U.U.A.A.G.G.C.C.A.C.G.A.G.A.U.U',
                           'phosphate': 'sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp.'},
                          'RNA2': {'sugar': 'fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r',
                           'base': 'U.C.U.C.G.U.G.G.C.C.U.U.A.A.U.G.A.A.A',
                           'phosphate': 'sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp'}}),
             'connections': ['RNA2,CHEM1,57:R2-1:R1',
              'CHEM1,CHEM2,1:R2-1:R1',
              'RNA2,RNA1,11:pair-47:pair',
              'RNA2,RNA1,14:pair-44:pair',
              'RNA2,RNA1,17:pair-41:pair',
              'RNA2,RNA1,20:pair-38:pair',
              'RNA2,RNA1,23:pair-35:pair',
              'RNA2,RNA1,26:pair-32:pair',
              'RNA2,RNA1,29:pair-29:pair',
              'RNA2,RNA1,2:pair-56:pair',
              'RNA2,RNA1,32:pair-26:pair',
              'RNA2,RNA1,35:pair-23:pair',
              'RNA2,RNA1,38:pair-20:pair',
              'RNA2,RNA1,41:pair-17:pair',
              'RNA2,RNA1,44:pair-14:pair',
              'RNA2,RNA1,47:pair-11:pair',
              'RNA2,RNA1,50:pair-8:pair',
              'RNA2,RNA1,53:pair-5:pair',
              'RNA2,RNA1,56:pair-2:pair',
              'RNA2,RNA1,5:pair-53:pair',
              'RNA2,RNA1,8:pair-50:pair']})

In [9]:

# To FASTA (natural analog sequence)
print("FASTA:")
print(molecule.to_fasta())

# To FASTA (natural analog sequence) print("FASTA:") print(molecule.to_fasta())

FASTA:
{'RNA1': 'UUUCAUUAAGGCCACGAGAUU', 'RNA2': 'UCUCGUGGCCUUAAUGAAA'}

4. Accessing Molecule Data¶

The underlying MoleculeData object provides many analysis methods:

In [10]:

# Access the data object
data = molecule.data

# Get sequences
print("Base sequence (RNA1):")
print("".join(data.get_sequence("RNA1")))

# Access the data object data = molecule.data # Get sequences print("Base sequence (RNA1):") print("".join(data.get_sequence("RNA1")))

Base sequence (RNA1):
UUUCAUUAAGGCCACGAGAUU

In [11]:

# Sugar and phosphate sequences
print("Sugars (RNA1):")
print(".".join(data.get_sugars("RNA1")))

print("\nPhosphates (RNA1):")
print(".".join(data.get_phosphates("RNA1")))

# Sugar and phosphate sequences print("Sugars (RNA1):") print(".".join(data.get_sugars("RNA1"))) print("\nPhosphates (RNA1):") print(".".join(data.get_phosphates("RNA1")))

Sugars (RNA1):
m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.m.m

Phosphates (RNA1):
sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp

In [12]:

# Lengths and counts
print(f"Residues in RNA1: {data.get_len_residues('RNA1')}")
print(f"Polymer count: {data.get_polymer_count()}")
print(f"RNA IDs: {data.get_rna_ids()}")

# Lengths and counts print(f"Residues in RNA1: {data.get_len_residues('RNA1')}") print(f"Polymer count: {data.get_polymer_count()}") print(f"RNA IDs: {data.get_rna_ids()}")

Residues in RNA1: 21
Polymer count: {'CHEM': 2, 'RNA': 2}
RNA IDs: ['RNA1', 'RNA2']

In [13]:

# Strand modality
print("Strand groupings:")
data.get_modality()

# Strand modality print("Strand groupings:") data.get_modality()

Strand groupings:

Out[13]:

('sirna', [{'RNA1', 'RNA2'}, {'CHEM1', 'RNA2'}, {'CHEM1', 'CHEM2'}])

In [14]:

# Unique monomers
print("Unique RNA monomers:")
data.get_unique_rna_monomers()

# Unique monomers print("Unique RNA monomers:") data.get_unique_rna_monomers()

Unique RNA monomers:

Out[14]:

{'A', 'C', 'G', 'U', 'fl2r', 'm', 'p', 'sp'}

5. Validation¶

Check base pairings and monomer symbols:

In [15]:

molecule.validate()
result = molecule.get_validation_result()

print(f"Valid: {result.is_valid}")
print(f"Warnings: {result.warnings}")
print(f"Mismatched pairs: {result.mismatch_base_pairs}")

molecule.validate() result = molecule.get_validation_result() print(f"Valid: {result.is_valid}") print(f"Warnings: {result.warnings}") print(f"Mismatched pairs: {result.mismatch_base_pairs}")

Valid: True
Warnings: []
Mismatched pairs: []

6. Building Duplexes from Scratch¶

Create a duplex by loading two strands and adding hydrogen bonds:

In [16]:

# Create two unpaired strands
xna_unpaired = {
    "polymers": {
        "RNA1": {
            "sugar": "m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.m.m",
            "phosphate": "sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp.",
            "base": "U.U.U.U.U.U.U.U.U.U.U.U.U.U.U.U.U.G.A.U.U"
        },
        "RNA2": {
            "sugar": "fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r",
            "phosphate": "sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp",
            "base": "U.C.U.U.U.U.U.U.U.U.U.U.U.U.U.G.A.A.A"
        }
    }
}

duplex = Molecule.from_xna(xna_unpaired, monomer_library=library)
print(f"Connections before: {len(duplex.data.connections)}")

# Create two unpaired strands xna_unpaired = { "polymers": { "RNA1": { "sugar": "m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.m.m", "phosphate": "sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp.", "base": "U.U.U.U.U.U.U.U.U.U.U.U.U.U.U.U.U.G.A.U.U" }, "RNA2": { "sugar": "fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r", "phosphate": "sp.sp.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.sp.sp", "base": "U.C.U.U.U.U.U.U.U.U.U.U.U.U.U.G.A.A.A" } } } duplex = Molecule.from_xna(xna_unpaired, monomer_library=library) print(f"Connections before: {len(duplex.data.connections)}")

Connections before: 0

In [17]:

# Auto-align and pair the strands
duplex.align_and_pair_strands("RNA1", "RNA2")

print(f"Connections after: {len(duplex.data.connections)}")

# Auto-align and pair the strands duplex.align_and_pair_strands("RNA1", "RNA2") print(f"Connections after: {len(duplex.data.connections)}")

Connections after: 5

In [18]:

# Check for mismatches and visualize
duplex.validate()
result = duplex.get_validation_result()
print(f"Mismatched pairs: {result.mismatch_base_pairs}")

fig, ax = duplex.visualize_cartoon(title="Paired Duplex", show_base=True)

# Check for mismatches and visualize duplex.validate() result = duplex.get_validation_result() print(f"Mismatched pairs: {result.mismatch_base_pairs}") fig, ax = duplex.visualize_cartoon(title="Paired Duplex", show_base=True)

Mismatched pairs: []

7. Modifying Molecules¶

7.1 Single Monomer Replacement¶

In [19]:

# Create a fresh molecule
xna_mod = {
    "polymers": {
        "RNA1": {
            "phosphate": "sp.p.p.p.p.p.p.p.p.p.p.sp.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"
        }
    }
}

mol_mod = Molecule.from_xna(xna_mod, monomer_library=library)

print("Before modification:")
mol_mod.display()

# Create a fresh molecule xna_mod = { "polymers": { "RNA1": { "phosphate": "sp.p.p.p.p.p.p.p.p.p.p.sp.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" } } } mol_mod = Molecule.from_xna(xna_mod, monomer_library=library) print("Before modification:") mol_mod.display()

Before modification:
Display MoleculeData: polymers=1 (RNA=1, CHEM=0), connections=0

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

 RNA1

             Connectivity             
┏━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Pair          ┃ H-bonds ┃ Covalent ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ (unconnected) │         │     RNA1 │
└───────────────┴─────────┴──────────┘

                          Summary                          
┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓
┃ Polymer ┃ Type ┃ Residues ┃ Sugars ┃ Bases ┃ Phosphates ┃
┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩
│ RNA1    │ RNA  │       14 │     14 │    14 │         14 │
└─────────┴──────┴──────────┴────────┴───────┴────────────┘

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

                                                 RNA Data 5' -> 3'                                                 
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RNA  ┃ Sugar                                    ┃ Base                        ┃ Phosphate                       ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RNA1 │ m.fl2r.m.fl2r.fl2r.m.fl2r.m.fl2r.m.fl2r… │ C.U.C.C.U.U.A.A.U.C.A.A.A.T │ sp.p.p.p.p.p.p.p.p.p.p.sp.sp.sp │
└──────┴──────────────────────────────────────────┴─────────────────────────────┴─────────────────────────────────┘

                                                    Connections                                                    
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Source PolymerID ┃ Target PolymerID ┃ SourceMonomerPosition:SourceAttach… ┃ TargetMonomerPosition:TargetAttach… ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
└──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘

In [20]:

# Replace sugar at position 1 with UNA
mol_mod.modify("replace_single", polymer_id="RNA1", pos=1, type="sugar", new_monomer="una")

# Replace base at position 2 with A
mol_mod.modify("replace_single", polymer_id="RNA1", pos=2, type="base", new_monomer="A")

print("After modification:")
mol_mod.display()

# Replace sugar at position 1 with UNA mol_mod.modify("replace_single", polymer_id="RNA1", pos=1, type="sugar", new_monomer="una") # Replace base at position 2 with A mol_mod.modify("replace_single", polymer_id="RNA1", pos=2, type="base", new_monomer="A") print("After modification:") mol_mod.display()

After modification:
Display MoleculeData: polymers=1 (RNA=1, CHEM=0), connections=0

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

 RNA1

             Connectivity             
┏━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Pair          ┃ H-bonds ┃ Covalent ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ (unconnected) │         │     RNA1 │
└───────────────┴─────────┴──────────┘

                          Summary                          
┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓
┃ Polymer ┃ Type ┃ Residues ┃ Sugars ┃ Bases ┃ Phosphates ┃
┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩
│ RNA1    │ RNA  │       14 │     14 │    14 │         14 │
└─────────┴──────┴──────────┴────────┴───────┴────────────┘

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

                                                 RNA Data 5' -> 3'                                                 
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RNA  ┃ Sugar                                    ┃ Base                        ┃ Phosphate                       ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RNA1 │ una.fl2r.m.fl2r.fl2r.m.fl2r.m.fl2r.m.fl… │ C.A.C.C.U.U.A.A.U.C.A.A.A.T │ sp.p.p.p.p.p.p.p.p.p.p.sp.sp.sp │
└──────┴──────────────────────────────────────────┴─────────────────────────────┴─────────────────────────────────┘

                                                    Connections                                                    
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Source PolymerID ┃ Target PolymerID ┃ SourceMonomerPosition:SourceAttach… ┃ TargetMonomerPosition:TargetAttach… ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
└──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘

In [21]:

fig, ax = mol_mod.visualize_cartoon(title="Modified Molecule", show_base=True)

fig, ax = mol_mod.visualize_cartoon(title="Modified Molecule", show_base=True)

7.2 Pattern Application¶

Apply built-in modification patterns:

In [22]:

# Create a sequence-based molecule
mol_pattern = Molecule.from_sequence("GCGTTTTTTTTTTTTTTTTTT", monomer_library=library)

print("Before pattern:")
mol_pattern.display()

# Create a sequence-based molecule mol_pattern = Molecule.from_sequence("GCGTTTTTTTTTTTTTTTTTT", monomer_library=library) print("Before pattern:") mol_pattern.display()

Before pattern:
Display MoleculeData: polymers=1 (RNA=1, CHEM=0), connections=0

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

 RNA1

             Connectivity             
┏━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Pair          ┃ H-bonds ┃ Covalent ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ (unconnected) │         │     RNA1 │
└───────────────┴─────────┴──────────┘

                          Summary                          
┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓
┃ Polymer ┃ Type ┃ Residues ┃ Sugars ┃ Bases ┃ Phosphates ┃
┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩
│ RNA1    │ RNA  │       21 │     21 │    21 │         20 │
└─────────┴──────┴──────────┴────────┴───────┴────────────┘

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

                                                 RNA Data 5' -> 3'                                                 
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RNA  ┃ Sugar                             ┃ Base                             ┃ Phosphate                         ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RNA1 │ r.r.r.r.r.r.r.r.r.r.r.r.r.r.r.r.… │ G.C.G.T.T.T.T.T.T.T.T.T.T.T.T.T… │ p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.… │
└──────┴───────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┘

                                                    Connections                                                    
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Source PolymerID ┃ Target PolymerID ┃ SourceMonomerPosition:SourceAttach… ┃ TargetMonomerPosition:TargetAttach… ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
└──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘

In [23]:

# Apply moe gapmer pattern
mol_pattern.apply_pattern("moe_gapmer_5_10_5", ["RNA1"])

print("After MOE gapmer 5-10-5:")
mol_pattern.display()

# Apply moe gapmer pattern mol_pattern.apply_pattern("moe_gapmer_5_10_5", ["RNA1"]) print("After MOE gapmer 5-10-5:") mol_pattern.display()

After MOE gapmer 5-10-5:
Display MoleculeData: polymers=1 (RNA=1, CHEM=0), connections=0

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

 RNA1

             Connectivity             
┏━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Pair          ┃ H-bonds ┃ Covalent ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ (unconnected) │         │     RNA1 │
└───────────────┴─────────┴──────────┘

                          Summary                          
┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓
┃ Polymer ┃ Type ┃ Residues ┃ Sugars ┃ Bases ┃ Phosphates ┃
┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩
│ RNA1    │ RNA  │       21 │     21 │    21 │         20 │
└─────────┴──────┴──────────┴────────┴───────┴────────────┘

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

                                                 RNA Data 5' -> 3'                                                 
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ RNA  ┃ Sugar                             ┃ Base                             ┃ Phosphate                         ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RNA1 │ moe.moe.moe.moe.moe.d.d.d.d.d.d.… │ G.C.G.T.T.T.T.T.T.T.T.T.T.T.T.T… │ p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.… │
└──────┴───────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┘

                                                    Connections                                                    
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Source PolymerID ┃ Target PolymerID ┃ SourceMonomerPosition:SourceAttach… ┃ TargetMonomerPosition:TargetAttach… ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
└──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘

In [24]:

# Apply full phosphorothioate backbone
mol_pattern.apply_pattern("full_phosphorothioate", ["RNA1"])

fig, ax = mol_pattern.visualize_cartoon(title="MOE Gapmer with Full PS", show_phosphate=True)

# Apply full phosphorothioate backbone mol_pattern.apply_pattern("full_phosphorothioate", ["RNA1"]) fig, ax = mol_pattern.visualize_cartoon(title="MOE Gapmer with Full PS", show_phosphate=True)

7.3 Custom Pattern String¶

In [25]:

# Apply a custom sugar pattern
mol_custom = Molecule.from_sequence("AUGCAUGCAUGCAUGCAUGC", monomer_library=library)

custom_pattern = "m.fl2r.m.m.m.fl2r.m.fl2r.fl2r.m.m.m.m.fl2r.m.fl2r.m.m.m.m"
mol_custom.modify("apply_pattern", polymer_id="RNA1", pattern=custom_pattern, type="sugar")

fig, ax = mol_custom.visualize_cartoon(title="Custom Sugar Pattern", show_base=True)

# Apply a custom sugar pattern mol_custom = Molecule.from_sequence("AUGCAUGCAUGCAUGCAUGC", monomer_library=library) custom_pattern = "m.fl2r.m.m.m.fl2r.m.fl2r.fl2r.m.m.m.m.fl2r.m.fl2r.m.m.m.m" mol_custom.modify("apply_pattern", polymer_id="RNA1", pattern=custom_pattern, type="sugar") fig, ax = mol_custom.visualize_cartoon(title="Custom Sugar Pattern", show_base=True)

8. Single-Strand vs Duplex¶

For a single-stranded simplex, just define one polymer:

In [26]:

simplex_xna = {
    "polymers": {
        "RNA1": {
            "sugar": "m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r",
            "phosphate": "sp.p.p.p.p.p.p.p.sp.",
            "base": "A.U.G.C.A.U.G.C.A.U"
        }
    }
}

simplex = Molecule.from_xna(simplex_xna, monomer_library=library)
fig, ax = simplex.visualize_cartoon(title="Single Strand (Simplex)", show_base=True)

simplex_xna = { "polymers": { "RNA1": { "sugar": "m.fl2r.m.fl2r.m.fl2r.m.fl2r.m.fl2r", "phosphate": "sp.p.p.p.p.p.p.p.sp.", "base": "A.U.G.C.A.U.G.C.A.U" } } } simplex = Molecule.from_xna(simplex_xna, monomer_library=library) fig, ax = simplex.visualize_cartoon(title="Single Strand (Simplex)", show_base=True)

Summary¶

Task	Method
Load from HELM	Molecule.from_helm(helm)
Load from XNA	Molecule.from_xna(xna)
Load from sequence	Molecule.from_sequence(seq)
Text display	molecule.display()
Cartoon view	molecule.visualize_cartoon()
Export to HELM	molecule.to_helm()
Export to XNA	molecule.to_xna()
Access data	molecule.data
Validate	molecule.validate()
Modify single	molecule.modify("replace_single", ...)
Apply pattern	molecule.apply_pattern(name, polymers)
Pair strands	molecule.align_and_pair_strands(id1, id2)