Molecule

The Molecule class is the primary entry point for working with oligonucleotides in HELMshaker. It provides a fluent interface for reading, modifying, and writing molecules.

Quick Example

Every read needs a monomer library; HELMshaker ships none. See Monomer Libraries for how to get one.

from helmshaker import Molecule, MonomerLibrary

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

# Read from HELM notation
molecule = Molecule.from_helm(
    "RNA1{[moe](A)[sp].[moe](U)[sp].[moe](G)}$$$$V2.0", monomer_library=library
)

# Apply modifications
molecule.apply_pattern("moe_gapmer_5_10_5")

# Write to different formats
helm_str = molecule.to_helm()
fasta_str = molecule.to_fasta()
xna_dict = molecule.to_xna()

API Reference

helmshaker.molecule.Molecule

Represents a chemical molecule (oligonucleotide) and provides a high-level API for reading, writing, modification, and visualization.

The Molecule class is the primary entry point for working with oligonucleotides. Use the class methods from_helm(), from_xna(), etc. to create instances, and instance methods to_helm(), to_fasta(), etc. to export.

Example

molecule = Molecule.from_helm("RNA1{moe[sp].moe}$$$$V2.0") molecule.apply_pattern("gapmer_5-10-5") helm_output = molecule.to_helm()

data: MoleculeData property

Provides a deep copy of the internal molecule data structure.

monomer_library: MonomerLibrary property

Returns the monomer library associated with this molecule.

library_ref: Optional[str] property

Returns the pinned name@version library reference, or None.

Sourced from the {lib=name@version} extended annotation read back from the HELM string (see :func:helmshaker.annotations.read_lib_annotation).

__init__(molecule_data, monomer_library)

Initializes a Molecule instance.

Note: Users should typically use the class methods from_helm(), from_xna(), or read() instead of calling this constructor directly.

Parameters:

Name	Type	Description	Default
molecule_data	MoleculeData	The core data structure representing the molecule.	required
monomer_library	MonomerLibrary	The monomer library used for this molecule.	required

Raises:

Type	Description
TypeError	If molecule_data is not an instance of MoleculeData.

from_helm(data, strict=True, monomer_library=None, resolve_pinned=False) classmethod

Creates a Molecule instance from a HELM notation string.

Parameters:

Name	Type	Description	Default
data	str	The HELM notation string.	required
strict	bool	If True (default), reading fails if a monomer is not in the library. If False, unrecognized monomers are allowed.	True
monomer_library	Optional[MonomerLibrary]	Optional custom monomer library. If not provided, the default library is used.	None
resolve_pinned	bool	If True and no explicit monomer_library is given, a {lib=name@version} annotation in the HELM is resolved against the local cache (no network). On a cache hit that pinned library is used; on a miss the default library is used. Defaults to False (behaviour unchanged).	False

Returns:

Type	Description
Molecule	A new Molecule instance.

Raises:

Type	Description
ReadError	If reading fails.

Example

molecule = Molecule.from_helm("RNA1{moe[sp].moe}$$$$V2.0")

from_peptide_sequence(sequence, crosslinks='', modifiers='', monomer_library=None, strict=False) classmethod

Creates a Molecule from a peptide sequence string via the peptide grammar.

Builds a HELM2.0 string from the sequence (plus optional crosslinks and sequence-modifier strings) using the peptide sequence-grammar engine, then reads it into a Molecule.

Parameters:

Name	Type	Description	Default
sequence	str	A modified-FASTA sequence (e.g. CAXRXN) or a dot-delimited sequence with non-natural monomers (e.g. C.A.Nle.R.MeC.N). Chains are separated by |.	required
crosslinks	str	Optional crosslinks string, e.g. C:2-C:7.	''
modifiers	str	Optional explicit sequence-modifier string, e.g. X3=Nle.	''
monomer_library	Optional[MonomerLibrary]	Monomer library used both for grammar connection points and for reading the resulting HELM.	None
strict	bool	Passed through to :meth:from_helm. Defaults to False because grammar sequences may contain undefined X placeholders.	False

Returns:

Type	Description
Molecule	A new Molecule instance.

from_xna(data, strict=True, monomer_library=None) classmethod

Creates a Molecule instance from an XNA notation dictionary.

Parameters:

Name	Type	Description	Default
data	Dict[str, Any]	The XNA notation dictionary with 'polymers' and optionally 'connections'.	required
strict	bool	If True (default), reading fails if a monomer is not in the library. If False, unrecognized monomers are allowed.	True
monomer_library	Optional[MonomerLibrary]	Optional custom monomer library.	None

Returns:

Type	Description
Molecule	A new Molecule instance.

Raises:

Type	Description
ReadError	If reading fails.

Example

xna_data = {"polymers": {"RNA1": {"base": "ACGU", "sugar": "moe.moe.moe.moe"}}} molecule = Molecule.from_xna(xna_data)

from_sequence(data, strict=True, monomer_library=None) classmethod

Creates a Molecule instance from a raw sequence string.

The sequence is automatically assembled with default sugar (ribose) and phosphate monomers.

Parameters:

Name	Type	Description	Default
data	Union[str, List[str]]	A sequence string (e.g., 'ACGU') or list of sequence strings.	required
strict	bool	If True (default), reading fails if a base is not in the library.	True
monomer_library	Optional[MonomerLibrary]	Optional custom monomer library.	None

Returns:

Type	Description
Molecule	A new Molecule instance.

Raises:

Type	Description
ReadError	If reading fails.

Example

molecule = Molecule.from_sequence("ACGUACGU")

from_notation(data, notation='example', *, mapping_path=None, strict=True, monomer_library=None) classmethod

Creates a Molecule instance from a token-based (vendor/CRO) notation.

Token notations map short codes (e.g. 'Aes', 'Ad') to HELM residues via a mapping file. A small example mapping ships with the package; supply your own vendor/CRO mapping via mapping_path to read other notations.

Parameters:

Name	Type	Description	Default
data	Union[str, List[str]]	A token-notation string or list of strings.	required
notation	str	The notation name. Defaults to the bundled example mapping. When mapping_path is given, this is just a label for the mapping.	'example'
mapping_path	Optional[str]	Optional path to a custom token-to-HELM mapping JSON file.	None
strict	bool	If True (default), reading fails if a token is not recognized.	True
monomer_library	Optional[MonomerLibrary]	Optional custom monomer library.	None

Returns:

Type	Description
Molecule	A new Molecule instance.

Raises:

Type	Description
ReadError	If reading fails.

Example

molecule = Molecule.from_notation("AeCeGeTe") molecule = Molecule.from_notation(seq, notation="myvendor", mapping_path="myvendor.json")

read(data, notation, strict=True, monomer_library=None, mapping_path=None, resolve_pinned=False) classmethod

Creates a Molecule instance by reading input data in the specified notation.

This is the generic read method. For convenience, use the notation-specific methods like from_helm(), from_xna(), etc.

Parameters:

Name	Type	Description	Default
data	Union[str, List[str], Dict[str, Any]]	The input data (string, list, or dict depending on notation).	required
notation	str	The format notation (e.g., 'helm', 'xna', 'sequence', 'example').	required
strict	bool	If True (default), reading fails if a monomer is not in the library. If False, unrecognized monomers are allowed.	True
monomer_library	Optional[MonomerLibrary]	Optional custom monomer library.	None
mapping_path	Optional[str]	Optional path to a custom token-to-HELM mapping JSON file, used to read vendor/CRO token notations via the generic token reader.	None
resolve_pinned	bool	If True and no explicit monomer_library is given, a {lib=name@version} annotation in the HELM string is resolved against the local cache (no network). Ignored for non-HELM input.	False

Returns:

Type	Description
Molecule	A new Molecule instance.

Raises:

Type	Description
ReadError	If reading fails.

to_helm()

Writes the molecule to HELM notation.

Returns:

Type	Description
str	The molecule as a HELM notation string.

Raises:

Type	Description
WriteError	If writing fails.

Example

helm_str = molecule.to_helm()

to_xna()

Writes the molecule to XNA notation.

Returns:

Type	Description
Dict[str, Any]	The molecule as an XNA notation dictionary.

Raises:

Type	Description
WriteError	If writing fails.

Example

xna_dict = molecule.to_xna()

to_fasta()

Writes the molecule to FASTA notation (natural analog sequence).

Returns:

Type	Description
Union[str, Dict[str, str]]	A string if the molecule has one RNA strand, or a dictionary
Union[str, Dict[str, str]]	mapping polymer IDs to sequences if multiple strands.

Raises:

Type	Description
WriteError	If writing fails.

Example

fasta = molecule.to_fasta()

write(notation)

Writes the molecule to the specified notation.

This is the generic write method. For convenience, use the notation-specific methods like to_helm(), to_fasta(), etc.

Parameters:

Name	Type	Description	Default
notation	str	The target format notation (e.g., 'helm', 'fasta', 'xna').	required

Returns:

Type	Description
Any	The molecule in the target notation (type depends on notation).

Raises:

Type	Description
WriteError	If writing fails.

analyze_structure()

Assembles the whole-molecule structure and derives its properties.

Returns:

Type	Description
StructureResult	A StructureResult with molecular weight, monoisotopic mass, formula,
StructureResult	SMILES and molblock.

Raises:

Type	Description
ImportError	If RDKit is not installed (install helmshaker[chem]).
NotImplementedError	If the molecule contains non-peptide polymers.

molecular_weight()

Returns the average molecular weight (g/mol) of the assembled molecule.

molecular_formula()

Returns the Hill-system molecular formula of the assembled molecule.

to_smiles()

Returns the canonical SMILES of the assembled molecule.

to_molblock()

Returns the MDL molblock (V2000) of the assembled molecule.

modify(modification_type, **kwargs)

Applies a modification to the molecule's internal data structure.

Automatically re-validates the molecule after modification.

Parameters:

Name	Type	Description	Default
modification_type	str	The type of modification to apply (e.g., 'apply_pattern', 'replace_single', 'complete_h_pairs', 'extend_rna').	required
**kwargs	Any	Additional arguments required for the specific modification.	{}

Returns:

Type	Description
Molecule	The Molecule instance (self) for method chaining.

Raises:

Type	Description
ModificationError	If the modification process fails.
ValidationError	If re-validation after modification encounters an error.

apply_pattern(pattern, polymer_ids=None)

Applies a modification pattern to the molecule.

Parameters:

Name	Type	Description	Default
pattern	Union[str, Dict[str, Any]]	A named pattern ID (e.g. "full_phosphorothioate"), an inline dict with "rules" key, or a shorthand string (e.g. "phosphate:sp", "sugar[1-5]:moe", "sugar:moe,d").	required
polymer_ids	Optional[List[str]]	Optional list of polymer IDs to apply the pattern to. If None, applies to all applicable polymers.	None

Returns:

Type	Description
Molecule	The Molecule instance (self) for method chaining.

replace_monomer_at(polymer_id, position, new_symbol)

Replaces a single monomer at a specific position.

Parameters:

Name	Type	Description	Default
polymer_id	str	The ID of the polymer containing the monomer.	required
position	int	The 1-based position of the monomer to replace.	required
new_symbol	str	The symbol of the new monomer.	required

Returns:

Type	Description
Molecule	The Molecule instance (self) for method chaining.

align_and_pair_strands(target_id=None, query_id=None, **kwargs)

Aligns two strands and adds hydrogen bond pairings.

Parameters:

Name	Type	Description	Default
target_id	Optional[str]	The ID of the target strand. If None, uses the first polymer.	None
query_id	Optional[str]	The ID of the query strand. If None, uses the second polymer.	None
**kwargs	Any	Additional alignment options.	{}

Returns:

Type	Description
Molecule	The Molecule instance (self) for method chaining.

validate()

Validates the internal molecule data structure.

Updates the internal validation result state which can be retrieved using get_validation_result().

Returns:

Type	Description
Molecule	The Molecule instance (self) for method chaining.

Raises:

Type	Description
ValidationError	If the validation process itself encounters an error.

get_validation_result()

Returns the result of the last validation performed on the molecule.

Returns:

Type	Description
Optional[ValidationResult]	The ValidationResult object, or None if validate() has not been called.

visualize_cartoon(**kwargs)

Generates a 2D cartoon schematic of the molecule.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional arguments passed to the visualizer, including: - title: Title for the plot - figsize: Figure size tuple (width, height) - show_base: Whether to show base labels - show_direction: Whether to show 5'/3' direction indicators - show_phosphate: Whether to show phosphate markers - show_position: Whether to show position numbers	{}

Returns:

Type	Description
Tuple[Figure, Axes]	A tuple containing the Matplotlib Figure and Axes objects.

Raises:

Type	Description
VisualizationError	If visualization fails.

Example

fig, ax = molecule.visualize_cartoon(title="My Molecule") fig.savefig("molecule.png")

visualize_display(separation=True)

Displays a summary of the molecule in formatted tables in the console.

Parameters:

Name	Type	Description	Default
separation	bool	If True, monomers in sequences are separated by dots.	True

Raises:

Type	Description
VisualizationError	If visualization fails.

display(separation=True)

Alias for visualize_display(). Displays molecule summary in console.

Parameters:

Name	Type	Description	Default
separation	bool	If True, monomers in sequences are separated by dots.	True