Convert between notations¶

HELMshaker makes it easy to convert oligonucleotides between different notation formats.

Supported input formats: HELM, XNA, Sequence, and token-based vendor/CRO notations

Supported output formats: HELM, XNA, FASTA

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

Quick Example¶

In [2]:

from helmshaker import Molecule

# Read from HELM
molecule = Molecule.from_helm("RNA1{[lna](G)p.[lna](A)}$$$$V2.0", monomer_library=library)

# Convert to XNA
molecule.to_xna()

from helmshaker import Molecule # Read from HELM molecule = Molecule.from_helm("RNA1{[lna](G)p.[lna](A)}$$$$V2.0", monomer_library=library) # Convert to XNA molecule.to_xna()

Out[2]:

defaultdict(dict,
            {'polymers': defaultdict(dict,
                         {'RNA1': {'sugar': 'lna.lna',
                           'base': 'G.A',
                           'phosphate': 'p.'}}),
             'connections': []})

Step 1: Read Your Molecule¶

Use the from_X methods to read molecules from different formats. The molecule is parsed and stored internally as a MoleculeData object.

In [3]:

from helmshaker import Molecule

helm = "CHEM1{[Ahx]}|RNA1{[lna](G)p.[lna](A)}$CHEM1,RNA1,1:R1-1:R1$$$V2.0"

molecule = Molecule.from_helm(helm, monomer_library=library)

from helmshaker import Molecule helm = "CHEM1{[Ahx]}|RNA1{[lna](G)p.[lna](A)}$CHEM1,RNA1,1:R1-1:R1$$$V2.0" molecule = Molecule.from_helm(helm, monomer_library=library)

Step 2: Write to Your Desired Format¶

Use the to_X methods to convert the molecule to different output formats:

• to_xna() - XNA notation (sugar/base/phosphate sequences)
• to_helm() - HELM notation
• to_fasta() - FASTA (natural analog sequence)

In [4]:

molecule.to_xna()

molecule.to_xna()

Out[4]:

defaultdict(dict,
            {'polymers': defaultdict(dict,
                         {'CHEM1': {'CHEM': 'Ahx'},
                          'RNA1': {'sugar': 'lna.lna',
                           'base': 'G.A',
                           'phosphate': 'p.'}}),
             'connections': ['CHEM1,RNA1,1:R1-1:R1']})

In [5]:

molecule.to_helm()

molecule.to_helm()

Out[5]:

'CHEM1{[Ahx]}|RNA1{[lna](G)p.[lna](A)}$CHEM1,RNA1,1:R1-1:R1$$$V2.0'

In [6]:

molecule.to_fasta()

molecule.to_fasta()

Out[6]:

'GA'

Reading from Different Formats¶

From XNA¶

The dots in XNA represent nucleotide separation.

In [7]:

from helmshaker import Molecule

xna = {
    'polymers': {
        'CHEM1': {'CHEM': 'Ahx'},
        'RNA1': {'base': '.C.A.G', 'phosphate': 'p.p.p.', 'sugar': '.d.d.lna'}
    },
    'connections': ['CHEM1,RNA1,1:R2-1:R1']
}

molecule = Molecule.from_xna(xna, monomer_library=library)
print(molecule.to_helm())

from helmshaker import Molecule xna = { 'polymers': { 'CHEM1': {'CHEM': 'Ahx'}, 'RNA1': {'base': '.C.A.G', 'phosphate': 'p.p.p.', 'sugar': '.d.d.lna'} }, 'connections': ['CHEM1,RNA1,1:R2-1:R1'] } molecule = Molecule.from_xna(xna, monomer_library=library) print(molecule.to_helm())

CHEM1{[Ahx]}|RNA1{p.d(C)p.d(A)p.[lna](G)}$CHEM1,RNA1,1:R2-1:R1$$$V2.0

From Sequence¶

Simple base sequences are automatically assembled with default sugar and phosphate.

In [8]:

from helmshaker import Molecule

# Single strand
molecule = Molecule.from_sequence("ACGUACGU", monomer_library=library)
print(molecule.to_helm())

from helmshaker import Molecule # Single strand molecule = Molecule.from_sequence("ACGUACGU", monomer_library=library) print(molecule.to_helm())

RNA1{r(A)p.r(C)p.r(G)p.r(U)p.r(A)p.r(C)p.r(G)p.r(U)}$$$$V2.0

In [9]:

# Multiple strands
molecule = Molecule.from_sequence(["ACGUACGU", "UGCAUGCA"], monomer_library=library)
print(molecule.to_helm())

# Multiple strands molecule = Molecule.from_sequence(["ACGUACGU", "UGCAUGCA"], monomer_library=library) print(molecule.to_helm())

RNA1{r(A)p.r(C)p.r(G)p.r(U)p.r(A)p.r(C)p.r(G)p.r(U)}|RNA2{r(U)p.r(G)p.r(C)p.r(A)p.r(U)p.r(G)p.r(C)p.r(A)}$$$$V2.0

From a Token-Based (Vendor/CRO) Notation¶

Token-based notations encode each residue as a short token (e.g. Ae, Aes, Ad) combining a base, a sugar modification, and an optional phosphorothioate. HELMshaker ships with a bundled example mapping.

In [10]:

from helmshaker import Molecule

# Using the dedicated from_notation method with the bundled 'example' mapping
tokens = "AesGesUesCes"
molecule = Molecule.from_notation(tokens, notation="example", monomer_library=library)
molecule.to_helm()

from helmshaker import Molecule # Using the dedicated from_notation method with the bundled 'example' mapping tokens = "AesGesUesCes" molecule = Molecule.from_notation(tokens, notation="example", monomer_library=library) molecule.to_helm()

Out[10]:

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

In [11]:

# Or using the generic read method
molecule = Molecule.read("GesTesCesAesTe", notation="example", monomer_library=library)
molecule.to_xna()

# Or using the generic read method molecule = Molecule.read("GesTesCesAesTe", notation="example", monomer_library=library) molecule.to_xna()

Out[11]:

defaultdict(dict,
            {'polymers': defaultdict(dict,
                         {'RNA1': {'sugar': 'moe.moe.moe.moe.moe',
                           'base': 'G.T.C.A.T',
                           'phosphate': 'sp.sp.sp.sp.'}}),
             'connections': []})

From a Custom Vendor Notation¶

To read a notation that is not bundled, supply your own token-to-HELM mapping as a JSON file via mapping_path. This lets you read arbitrary vendor/CRO notations.

In [12]:

from helmshaker import Molecule

# Read a custom vendor notation from a user-supplied mapping file
tokens = "AeCeGeUe"
molecule = Molecule.from_notation(tokens, notation="myvendor", mapping_path="../examples/myvendor.json", monomer_library=library)
molecule.to_helm()

from helmshaker import Molecule # Read a custom vendor notation from a user-supplied mapping file tokens = "AeCeGeUe" molecule = Molecule.from_notation(tokens, notation="myvendor", mapping_path="../examples/myvendor.json", monomer_library=library) molecule.to_helm()

Out[12]:

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

In [13]:

# Or using the generic read method with a custom mapping file
molecule = Molecule.read("AeCeGeUe", notation="myvendor", mapping_path="../examples/myvendor.json", monomer_library=library)
molecule.to_xna()

# Or using the generic read method with a custom mapping file molecule = Molecule.read("AeCeGeUe", notation="myvendor", mapping_path="../examples/myvendor.json", monomer_library=library) molecule.to_xna()

Out[13]:

defaultdict(dict,
            {'polymers': defaultdict(dict,
                         {'RNA1': {'sugar': 'm.m.m.m',
                           'base': 'A.C.G.U',
                           'phosphate': 'sp.sp.sp.sp'}}),
             'connections': []})

Using Custom Monomer Libraries¶

You can specify a custom monomer library when reading molecules.

In [14]:

from helmshaker import Molecule, MonomerLibrary

helm = "RNA1{[m](A)[sp].[m](U)}$$$$V2.0"
molecule = Molecule.from_helm(helm, monomer_library=library)

molecule.to_xna()

from helmshaker import Molecule, MonomerLibrary helm = "RNA1{[m](A)[sp].[m](U)}$$$$V2.0" molecule = Molecule.from_helm(helm, monomer_library=library) molecule.to_xna()

Out[14]:

defaultdict(dict,
            {'polymers': defaultdict(dict,
                         {'RNA1': {'sugar': 'm.m',
                           'base': 'A.U',
                           'phosphate': 'sp.'}}),
             'connections': []})

Summary¶

Input Format	Method
HELM	Molecule.from_helm(data)
XNA	Molecule.from_xna(data)
Sequence	Molecule.from_sequence(data)
Token-based (vendor/CRO)	Molecule.from_notation(data, notation="example")
Custom mapping	Molecule.from_notation(data, notation="myvendor", mapping_path="../examples/myvendor.json")
Generic	Molecule.read(data, notation=...)

Output Format	Method
HELM	molecule.to_helm()
XNA	molecule.to_xna()
FASTA	molecule.to_fasta()