Skip to content

Why a monomer library is mandatory

If you have just hit this:

MonomerLibraryError: No monomer library available. HELMshaker ships no bundled monomers.

then this page explains why, and the how-to guide shows you what to do about it.

A HELM string is not self-describing

HELM records which symbols appear in which order. It does not record what those symbols mean. This string:

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

says there are two residues, each built from a sugar called moe, a base, and a linker called sp. It says nothing about what moe is made of. Without a dictionary that maps moe to a structure, a natural analog and a set of R-group attachment points, HELMshaker cannot compute a molecular weight, assemble a structure, write FASTA, or tell you whether the string is even valid.

So the dictionary is not a configuration detail. It is half the molecule.

Why nothing is bundled

Earlier versions shipped a copy of the public HELMCore dictionary and defaulted to it. That was convenient and wrong, for two reasons.

The bundled copy went stale. A dictionary pinned inside a release drifts from the registry it was copied from. Monomers get added, corrected and deprecated in TMR; a frozen copy silently disagrees.

It made the wrong answer the easy one. Reading a Roche HELM against public HELMCore appears to work and produces wrong results, because the two vocabularies overlap without agreeing. Failing loudly is better than a plausible wrong number.

Refusing to guess forces the question "which dictionary?" to be answered explicitly, once, where you can see it.

Symbols are namespaced by polymer type

The same symbol can mean different things in different polymers, and a library holds both. In public HELMCore:

Symbol As RNA As PEPTIDE
A Adenine Alanine
C Cytosine Cysteine
P not defined Proline
d Deoxyribose not defined
dR not defined D-Arginine

This is worth knowing because it produces the most confusing failure mode in practice. An oligonucleotide written with dR for deoxyribose and P for phosphate parses against public HELMCore, because both symbols exist there, as amino acids. The result is not an error. It is a molecule made of the wrong things. The public spellings for an oligo are d and p.

Which dictionary should you use

Situation Source
Roche registration work Pull the relevant dictionary from TMR
Reading a HELM someone sent you Ask which dictionary it was written against, then pin it
Public or published sequences Public HELMCore
Tests and examples A small fixed dictionary committed next to them

The documentation itself follows the last row: every example on this site resolves against docs/examples/docs_library.json, a small public HELMCore subset committed to the repository so the examples run in CI.

Pinning the answer into the string

Because the dictionary travels separately from the HELM, it is easy to lose track of which one a string was written against. HELMshaker can write the answer into the HELM extended-annotations field:

PEPTIDE1{C.A.A.A.C}$$${lib=peptides@1.2.0}$V2.0

The marker is ordinary HELM, so other tools ignore it, but HELMshaker can read it back and re-resolve that exact dictionary version from the local cache. See Pin a library version.