Apply patterns and visualize¶
This guide shows how to:
- Build molecules from simple base sequences
- Apply built-in modification patterns (gapmers, full PS, context-aware base edits)
- Visualize results with the cartoon view
Setup¶
In [1]:
Copied!
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. Build Molecules from Sequences¶
The sequence reader takes raw base strings and assembles RNA residues with default sugar and phosphate.
In [2]:
Copied!
# Two strands for an siRNA
seq1 = 'AUGCUGACUUGCUAUGCUAA'
seq2 = 'UUAGCAUAGCAAGUCAGCAU'
sirna = Molecule.from_sequence([seq1, seq2], monomer_library=library)
sirna.align_and_pair_strands()
fig, ax = sirna.visualize_cartoon(title='Native siRNA')
sirna.display()
# Two strands for an siRNA
seq1 = 'AUGCUGACUUGCUAUGCUAA'
seq2 = 'UUAGCAUAGCAAGUCAGCAU'
sirna = Molecule.from_sequence([seq1, seq2], monomer_library=library)
sirna.align_and_pair_strands()
fig, ax = sirna.visualize_cartoon(title='Native siRNA')
sirna.display()
Display MoleculeData: polymers=2 (RNA=2, CHEM=0), connections=20
──────────────────────────────────────────────────── Structure ────────────────────────────────────────────────────
RNA1
│
│
RNA2
Connectivity ┏━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓ ┃ Pair ┃ H-bonds ┃ Covalent ┃ ┡━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩ │ RNA1—RNA2 │ 20 │ 0 │ └───────────┴─────────┴──────────┘
Summary ┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓ ┃ Polymer ┃ Type ┃ Residues ┃ Sugars ┃ Bases ┃ Phosphates ┃ ┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩ │ RNA1 │ RNA │ 20 │ 20 │ 20 │ 19 │ │ RNA2 │ RNA │ 20 │ 20 │ 20 │ 19 │ └─────────┴──────┴──────────┴────────┴───────┴────────────┘
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.… │ A.U.G.C.U.G.A.C.U.U.G.C.U.A.U.G… │ p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.p.… │ │ RNA2 │ r.r.r.r.r.r.r.r.r.r.r.r.r.r.r.r.… │ U.U.A.G.C.A.U.A.G.C.A.A.G.U.C.A… │ 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… ┃ ┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ RNA1 │ RNA2 │ 2:pair │ 59:pair │ │ RNA1 │ RNA2 │ 5:pair │ 56:pair │ │ RNA1 │ RNA2 │ 8:pair │ 53:pair │ │ RNA1 │ RNA2 │ 11:pair │ 50:pair │ │ RNA1 │ RNA2 │ 14:pair │ 47:pair │ │ RNA1 │ RNA2 │ 17:pair │ 44:pair │ │ RNA1 │ RNA2 │ 20:pair │ 41:pair │ │ RNA1 │ RNA2 │ 23:pair │ 38:pair │ │ RNA1 │ RNA2 │ 26:pair │ 35:pair │ │ RNA1 │ RNA2 │ 29:pair │ 32:pair │ │ RNA1 │ RNA2 │ 32:pair │ 29:pair │ │ RNA1 │ RNA2 │ 35:pair │ 26:pair │ │ RNA1 │ RNA2 │ 38:pair │ 23:pair │ │ RNA1 │ RNA2 │ 41:pair │ 20:pair │ │ RNA1 │ RNA2 │ 44:pair │ 17:pair │ │ RNA1 │ RNA2 │ 47:pair │ 14:pair │ │ RNA1 │ RNA2 │ 50:pair │ 11:pair │ │ RNA1 │ RNA2 │ 53:pair │ 8:pair │ │ RNA1 │ RNA2 │ 56:pair │ 5:pair │ │ RNA1 │ RNA2 │ 59:pair │ 2:pair │ └──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘
2. Apply Built-in Modification Patterns¶
Patterns are defined in helmshaker/data/core_patterns.yaml and loaded by default. You can target all polymers or specific ones.
2.1 Full Phosphorothioate Backbone¶
In [3]:
Copied!
# Apply full PS backbone to RNA1 only
sirna.apply_pattern('full_phosphorothioate', ['RNA1'])
fig, ax = sirna.visualize_cartoon(title='Full PS Backbone on RNA1', show_phosphate=True)
# Apply full PS backbone to RNA1 only
sirna.apply_pattern('full_phosphorothioate', ['RNA1'])
fig, ax = sirna.visualize_cartoon(title='Full PS Backbone on RNA1', show_phosphate=True)
2.2 MOE Gapmer 5-10-5¶
In [4]:
Copied!
# Apply 5-10-5 moe gapmer pattern
sirna.apply_pattern('moe_gapmer_5_10_5', ['RNA1'])
fig, ax = sirna.visualize_cartoon(title='MOE Gapmer 5-10-5')
# Apply 5-10-5 moe gapmer pattern
sirna.apply_pattern('moe_gapmer_5_10_5', ['RNA1'])
fig, ax = sirna.visualize_cartoon(title='MOE Gapmer 5-10-5')
2.3 Alternating Sugar Pattern¶
In [5]:
Copied!
# Apply alternating cEt/d sugar pattern to RNA2
sirna.apply_pattern('alternating_cet', ['RNA2'])
fig, ax = sirna.visualize_cartoon(title='Alternating cEt/d on RNA2')
# Apply alternating cEt/d sugar pattern to RNA2
sirna.apply_pattern('alternating_cet', ['RNA2'])
fig, ax = sirna.visualize_cartoon(title='Alternating cEt/d on RNA2')
Check Validation and Display¶
In [6]:
Copied!
sirna.validate()
print(sirna.get_validation_result())
sirna.display()
sirna.validate()
print(sirna.get_validation_result())
sirna.display()
ValidationResult(is_valid=True, errors=[], warnings=[], applicable_dictionaries={'monomer_library'}, missing_rna_monomers={}, mismatch_base_pairs=[], missing_peptide_monomers=set())
Display MoleculeData: polymers=2 (RNA=2, CHEM=0), connections=20
──────────────────────────────────────────────────── Structure ────────────────────────────────────────────────────
RNA1
│
│
RNA2
Connectivity ┏━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓ ┃ Pair ┃ H-bonds ┃ Covalent ┃ ┡━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩ │ RNA1—RNA2 │ 20 │ 0 │ └───────────┴─────────┴──────────┘
Summary ┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓ ┃ Polymer ┃ Type ┃ Residues ┃ Sugars ┃ Bases ┃ Phosphates ┃ ┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩ │ RNA1 │ RNA │ 20 │ 20 │ 20 │ 19 │ │ RNA2 │ RNA │ 20 │ 20 │ 20 │ 19 │ └─────────┴──────┴──────────┴────────┴───────┴────────────┘
CHEM Data ┏━━━━━━┳━━━━━━━━━━━┓ ┃ CHEM ┃ Chemistry ┃ ┡━━━━━━╇━━━━━━━━━━━┩ └──────┴───────────┘
RNA Data 5' -> 3' ┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ RNA ┃ Sugar ┃ Base ┃ Phosphate ┃ ┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ RNA1 │ moe.moe.moe.moe.moe.d.d.d.d.d.d.… │ A.U.G.C.U.G.A.C.U.U.G.C.U.A.U.G.… │ sp.sp.sp.sp.sp.sp.sp.sp.sp.sp.s… │ │ RNA2 │ cet.d.cet.d.cet.d.cet.d.cet.d.ce… │ U.U.A.G.C.A.U.A.G.C.A.A.G.U.C.A.… │ 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… ┃ ┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ RNA1 │ RNA2 │ 2:pair │ 59:pair │ │ RNA1 │ RNA2 │ 5:pair │ 56:pair │ │ RNA1 │ RNA2 │ 8:pair │ 53:pair │ │ RNA1 │ RNA2 │ 11:pair │ 50:pair │ │ RNA1 │ RNA2 │ 14:pair │ 47:pair │ │ RNA1 │ RNA2 │ 17:pair │ 44:pair │ │ RNA1 │ RNA2 │ 20:pair │ 41:pair │ │ RNA1 │ RNA2 │ 23:pair │ 38:pair │ │ RNA1 │ RNA2 │ 26:pair │ 35:pair │ │ RNA1 │ RNA2 │ 29:pair │ 32:pair │ │ RNA1 │ RNA2 │ 32:pair │ 29:pair │ │ RNA1 │ RNA2 │ 35:pair │ 26:pair │ │ RNA1 │ RNA2 │ 38:pair │ 23:pair │ │ RNA1 │ RNA2 │ 41:pair │ 20:pair │ │ RNA1 │ RNA2 │ 44:pair │ 17:pair │ │ RNA1 │ RNA2 │ 47:pair │ 14:pair │ │ RNA1 │ RNA2 │ 50:pair │ 11:pair │ │ RNA1 │ RNA2 │ 53:pair │ 8:pair │ │ RNA1 │ RNA2 │ 56:pair │ 5:pair │ │ RNA1 │ RNA2 │ 59:pair │ 2:pair │ └──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘
3. Context-Aware Patterns¶
Some patterns use sequence context to apply modifications (e.g., CpG methylation).
In [7]:
Copied!
# CpG methylation example
mol_cpg = Molecule.from_sequence('ACGCCGACGCGAUGACAGUG', monomer_library=library)
mol_cpg.apply_pattern('moe_gapmer_5_10_5')
mol_cpg.apply_pattern('cpg_methylation')
fig, ax = mol_cpg.visualize_cartoon(title='CpG Methylation', show_base=True)
# CpG methylation example
mol_cpg = Molecule.from_sequence('ACGCCGACGCGAUGACAGUG', monomer_library=library)
mol_cpg.apply_pattern('moe_gapmer_5_10_5')
mol_cpg.apply_pattern('cpg_methylation')
fig, ax = mol_cpg.visualize_cartoon(title='CpG Methylation', show_base=True)
4. Drug-like Patterns¶
Apply patterns similar to approved therapeutics.
In [8]:
Copied!
# Fomivirsen-like pattern (full PS + deoxy sugars)
mol_fomivirsen = Molecule.from_sequence('GCGTTTTTTTTTTTTTTTTTT', monomer_library=library)
mol_fomivirsen.apply_pattern('fomivirsen_vitravene')
fig, ax = mol_fomivirsen.visualize_cartoon(title='Fomivirsen-like Chemistry', show_phosphate=True)
# Fomivirsen-like pattern (full PS + deoxy sugars)
mol_fomivirsen = Molecule.from_sequence('GCGTTTTTTTTTTTTTTTTTT', monomer_library=library)
mol_fomivirsen.apply_pattern('fomivirsen_vitravene')
fig, ax = mol_fomivirsen.visualize_cartoon(title='Fomivirsen-like Chemistry', show_phosphate=True)
5. Target Specific Strands¶
Patterns can be restricted to specific polymers.
In [9]:
Copied!
# Create a fresh duplex
mol_duplex = Molecule.from_sequence([seq1, seq2], monomer_library=library)
# Apply gapmer only to RNA1
mol_duplex.apply_pattern('moe_gapmer_5_10_5', polymer_ids=['RNA1'])
fig, ax = mol_duplex.visualize_cartoon(title='Duplex: Gapmer on RNA1 Only')
# Create a fresh duplex
mol_duplex = Molecule.from_sequence([seq1, seq2], monomer_library=library)
# Apply gapmer only to RNA1
mol_duplex.apply_pattern('moe_gapmer_5_10_5', polymer_ids=['RNA1'])
fig, ax = mol_duplex.visualize_cartoon(title='Duplex: Gapmer on RNA1 Only')
6. Working with HELM Input¶
In [10]:
Copied!
helm = "RNA1{r(A)p.r(U)p}$$$$V2.0"
mol_helm = Molecule.from_helm(helm, monomer_library=library)
mol_helm.apply_pattern('full_phosphorothioate')
fig, ax = mol_helm.visualize_cartoon(title='From HELM with PS', show_phosphate=True)
mol_helm.display()
helm = "RNA1{r(A)p.r(U)p}$$$$V2.0"
mol_helm = Molecule.from_helm(helm, monomer_library=library)
mol_helm.apply_pattern('full_phosphorothioate')
fig, ax = mol_helm.visualize_cartoon(title='From HELM with PS', show_phosphate=True)
mol_helm.display()
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 │ 2 │ 2 │ 2 │ 2 │ └─────────┴──────┴──────────┴────────┴───────┴────────────┘
CHEM Data ┏━━━━━━┳━━━━━━━━━━━┓ ┃ CHEM ┃ Chemistry ┃ ┡━━━━━━╇━━━━━━━━━━━┩ └──────┴───────────┘
RNA Data 5' -> 3' ┏━━━━━━┳━━━━━━━┳━━━━━━┳━━━━━━━━━━━┓ ┃ RNA ┃ Sugar ┃ Base ┃ Phosphate ┃ ┡━━━━━━╇━━━━━━━╇━━━━━━╇━━━━━━━━━━━┩ │ RNA1 │ r.r │ A.U │ sp.sp │ └──────┴───────┴──────┴───────────┘
Connections ┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Source PolymerID ┃ Target PolymerID ┃ SourceMonomerPosition:SourceAttach… ┃ TargetMonomerPosition:TargetAttach… ┃ ┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ └──────────────────┴──────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘
Notes¶
- The default pattern set is loaded automatically from
core_patterns.yaml - Sequence parser builds RNA by default (sugar 'r', phosphate 'p')
- Patterns modify chemistry as specified in their definitions
- The cartoon legend uses colors to distinguish different monomers