Skip to content

Get started

This page gets you from nothing to a parsed, validated molecule. It takes about five minutes. When you are done, the tutorials go deeper and the how-to guides answer specific tasks.

Install

pip install helmshaker

The core install parses, validates, converts and modifies. Everything heavier is an optional extra, so add only what you need:

Extra Install Adds
chem pip install "helmshaker[chem]" RDKit, for structure, molecular weight and formula
viz pip install "helmshaker[viz]" matplotlib and rich, for cartoons and console display
remote pip install "helmshaker[remote]" httpx, for pulling dictionaries from TMR and Forge
cli pip install "helmshaker[cli]" The helmshaker command

Combine them with commas, quoting so your shell does not expand the brackets:

pip install "helmshaker[chem,viz,cli]"

To work on HELMshaker itself:

git clone https://github.com/roche-innersource/cscoe-ddc-helmshaker.git
cd cscoe-ddc-helmshaker
poetry install --all-extras --with dev

Using R rather than Python? See Use HELMshaker from R.

Get a monomer library

A HELM string records which symbols appear in which order, not what they mean. HELMshaker ships no monomers, so every read needs a dictionary. Reading without one raises MonomerLibraryError.

Pull one from TMR, which caches it on disk for offline use afterwards:

helmshaker login --janus-env beta
helmshaker library pull --tmr https://api.core.minerva.roche.com/gateway/tmr-tst \
    --dictionary peptides --version 1.2.0

Or load one you already have as JSON:

from helmshaker import MonomerLibrary

library = MonomerLibrary()
library.load_from_file("monomers.json")

Load a monomer library covers all four sources: a file, records in memory, TMR or Forge, and the local cache.

Read a molecule

from helmshaker import Molecule

oligo = Molecule.from_helm(
    "RNA1{[moe](A)[sp].[moe](U)[sp].[moe](G)}$$$$V2.0", monomer_library=library
)

print(oligo.to_fasta())

The same from_X / to_X pair works for every notation:

print(oligo.to_helm())
print(oligo.to_xna())

# From XNA columns instead
xna = {"polymers": {"RNA1": {"base": "A.U.G", "sugar": "moe.moe.moe", "phosphate": "sp.sp."}}}
Molecule.from_xna(xna, monomer_library=library)

# From a plain sequence, or a list of strands for a duplex
Molecule.from_sequence("ACGUACGU", monomer_library=library)
Molecule.from_sequence(["ACGUACGU", "UGCAUGCA"], monomer_library=library)

Build a peptide

You do not have to write HELM by hand. Give the sequence grammar a sequence and it works out the rest:

peptide = Molecule.from_peptide_sequence(
    "CAAAC", crosslinks="C:1-C:5", monomer_library=library
)

print(peptide.to_helm())
print(peptide.data.is_cyclic("PEPTIDE1"))

Modify and validate

Modification methods change the molecule in place and return it, so they chain:

aso = Molecule.from_sequence("ACGUACGUACGUACGUACGU", monomer_library=library)
aso.apply_pattern("moe_gapmer_5_10_5").validate()

print(aso.get_validation_result().is_valid)

Handle errors

Every exception inherits from HelmShakerError, so one except catches the lot:

from helmshaker.exceptions import HelmShakerError, ReadError

try:
    Molecule.from_helm("not a helm string", monomer_library=library)
except ReadError as e:
    print(f"Failed to parse: {e}")
except HelmShakerError as e:
    print(f"HELMshaker error: {e}")

Next