The notation model¶

HELM strings can become long and complex. XNA is an abstraction that divides oligonucleotides into their 3 building blocks:

• Sugar (e.g., mR, fR, dR)
• Base (e.g., A, U, G, C)
• Phosphate (e.g., P, sP)

The dots in XNA represent nucleotide separations.

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

Rule of Thumb¶

When writing XNA:

• Dots represent nucleotide separations
• You need the same number of dots for sugar, base, and phosphate
• Empty positions are represented by dots with nothing between them

HELM to XNA Conversion¶

In [2]:

from helmshaker import Molecule

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

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

In [3]:

molecule.to_xna()

molecule.to_xna()

Out[3]:

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

In [4]:

fig, ax = molecule.visualize_cartoon(
    show_phosphate=True,
    show_base=False,
    show_direction=True,
    show_position=True,
    show_legend=True
)

fig, ax = molecule.visualize_cartoon( show_phosphate=True, show_base=False, show_direction=True, show_position=True, show_legend=True )

Understanding the Phosphate Pattern¶

Notice the phosphate: P.sP.

The HELM RNA1{r(A)p.[m](U)[sp].[fl2r](G)} has:

• Position 1: R(A)P → sugar R, base A, phosphate P
• Position 2: [m](U)[sp] → sugar mR, base U, phosphate sP
• Position 3: [fl2r](G) → sugar fR, base G, no phosphate

The trailing . indicates there's no phosphate at the end.

Adding a Phosphate at the End¶

If we add a phosphate at position 3, the XNA changes:

In [5]:

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

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

Out[5]:

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

In [6]:

fig, ax = molecule.visualize_cartoon(
    show_phosphate=True,
    show_direction=True,
    show_position=True,
    show_legend=True
)

fig, ax = molecule.visualize_cartoon( show_phosphate=True, show_direction=True, show_position=True, show_legend=True )

Phosphate Caps (5' End)¶

A phosphate cap at the 5' end means the first "nucleotide" is just a phosphate. This requires a dot at the beginning for sugars and bases too:

In [7]:

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

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

Out[7]:

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

Notice:

• Sugar: .R.mR.fR (leading dot for empty sugar at position 1)
• Base: .A.U.G (leading dot for empty base at position 1)
• Phosphate: PN.P.sP. (phosphate cap at position 1)

In [8]:

fig, ax = molecule.visualize_cartoon(
    show_phosphate=True,
    show_direction=True,
    show_position=True,
    show_legend=True
)

fig, ax = molecule.visualize_cartoon( show_phosphate=True, show_direction=True, show_position=True, show_legend=True )

Phosphate at Both Ends¶

A molecule with phosphates at both 5' and 3' ends:

In [9]:

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

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

helm = "RNA1{[eop].r(A)p.[m](U)[sp].[fl2r](G)[s2p]}$$$$V2.0" molecule = Molecule.from_helm(helm, monomer_library=library) print("XNA:") print(molecule.to_xna())

XNA:
defaultdict(<class 'dict'>, {'polymers': defaultdict(<class 'dict'>, {'RNA1': {'sugar': '.r.m.fl2r', 'base': '.A.U.G', 'phosphate': 'eop.p.sp.s2p'}}), 'connections': []})

In [10]:

fig, ax = molecule.visualize_cartoon(
    show_phosphate=True,
    show_direction=True,
    show_position=True,
    show_legend=True
)

fig, ax = molecule.visualize_cartoon( show_phosphate=True, show_direction=True, show_position=True, show_legend=True )

XNA to HELM Conversion¶

You can also read from XNA and convert to HELM:

In [11]:

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

molecule = Molecule.from_xna(xna, monomer_library=library)
print(f"HELM: {molecule.to_helm()}")

xna = { "polymers": { "RNA1": { "sugar": "m.fl2r.m.fl2r", "base": "A.U.G.C", "phosphate": "sp.p.sp." } } } molecule = Molecule.from_xna(xna, monomer_library=library) print(f"HELM: {molecule.to_helm()}")

HELM: RNA1{m(A)[sp].[fl2r](U)p.m(G)[sp].[fl2r](C)}$$$$V2.0

In [12]:

fig, ax = molecule.visualize_cartoon(title="From XNA", show_phosphate=True)

fig, ax = molecule.visualize_cartoon(title="From XNA", show_phosphate=True)

Summary¶

XNA Pattern	Meaning
A.U.G	3 nucleotides
.A.U.G	Empty first position, then 3 nucleotides
A.U.G.	3 nucleotides, empty last position
P.sP.P.	3 phosphates + empty at end
PN.P.sP.P	Phosphate cap + 3 phosphates