Skip to content

HELM annotations

A HELM string records symbols, not what they mean, so it does not say which dictionary it was written against. These functions write that answer into the HELM extended-annotations field and read it back.

from helmshaker import Molecule, MonomerLibrary
from helmshaker.annotations import annotate_helm, read_lib_annotation

library = MonomerLibrary()
library.load_from_file("monomers.json")  # your dictionary, or one pulled from TMR

pinned = annotate_helm("PEPTIDE1{C.A.A.A.C}$$$$V2.0", "peptides@1.2.0")
# PEPTIDE1{C.A.A.A.C}$$${lib=peptides@1.2.0}$V2.0

read_lib_annotation(pinned)
# 'peptides@1.2.0'

Where the marker lives

HELM V2.0 has four $-separated sections after the polymer list: connections, polymer groups, extended annotations, and the version. The marker goes in the third:

PEPTIDE1{C.A.A.A.C} $ <connections> $ <groups> $ {lib=peptides@1.2.0} $ V2.0

Because that field is part of the standard, other HELM tools parse the string without tripping over it, and a string that already carries annotations keeps them.

Reading it back

Molecule.library_ref surfaces the marker whichever library you actually read with:

m = Molecule.from_helm(pinned, monomer_library=library)
m.library_ref  # 'peptides@1.2.0'

Passing resolve_pinned=True goes further: with no explicit library, HELMshaker loads the pinned dictionary from the local cache, so validation flags monomers that version does not contain. That needs the dictionary to have been pulled already, and does not hit the network. See Pin a library version.

API reference

HELM extended-annotation helpers.

Roche pins the source monomer dictionary into a HELM string's extended-annotations field as {lib=name@version} (see the Forge monomer-registration spec). A HELM2.0 string has five $-delimited sections:

SimplePolymers $ Connections $ PolymerGroups $ ExtendedAnnotations $ V2.0

This module writes the {lib=...} marker into section 4 (index 3). Pure string manipulation — no helmshaker imports, so it is safe to use anywhere.

annotate_helm(helm, lib)

Inject a {lib=name@version} marker into a HELM2.0 string's annotations field.

Idempotent: if a lib= marker is already present in the annotations section the string is returned unchanged. Returns the input unchanged when lib is falsy or the string is not a well-formed 5-section HELM2.0 string.

read_lib_annotation(helm)

Extract the name@version from a {lib=...} marker in a HELM string.

Reads the extended-annotations section (index 3 of the $-delimited HELM2.0 string). Returns None if the marker is absent, the string is not a well-formed HELM string, or the marker is empty.

lib_annotation(lib)

Return the {lib=name@version} marker for a library id, or "" if none.

parse_annotations(section)

Parse a HELM extended-annotations section string into a dict.

Recognises two shapes and merges them:

  • the {lib=name@version} marker written by :func:annotate_helm (yields {"lib": "name@version"}), and
  • a JSON object, the form emitted by writers.helm_writer.HelmWriter._create_annotations via json.dumps.

Never raises on a malformed field; unrecognised content yields {}.