Skip to content

Pin a library version into a HELM

A HELM string does not record which monomer dictionary it was written against, so the same string can mean different molecules to two teams. Write the dictionary name and version into the string so the answer travels with it.

This guide assumes you already have a library loaded. See Load a monomer library if not.

Write the marker

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")
print(pinned)

The marker goes into the HELM extended-annotations field, which is part of the standard, so other tools parse the string unchanged.

Read it back

print(read_lib_annotation(pinned))

m = Molecule.from_helm(pinned, monomer_library=library)
print(m.library_ref)

library_ref reports what the string claims, regardless of which library you actually passed. That distinction is the point: it lets you notice a mismatch.

Validate against the pinned version

With resolve_pinned=True and no explicit library, HELMshaker loads the pinned dictionary from the local cache instead, so validation flags any monomer that version does not contain. This never touches the network, so the dictionary has to have been pulled first:

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

m = Molecule.from_helm(pinned, resolve_pinned=True)
m.validate()

If the cache does not hold peptides@1.2.0, this raises rather than silently falling back to some other dictionary.