Data structures

This page documents the core data structures used to represent molecules in HELMshaker.

Overview

• MoleculeData: The central container holding polymers, connections, and annotations
• Polymer: A chain of residues (RNA, CHEM, or PEPTIDE type)
• Residue: A unit within a polymer containing one or more monomers
• Monomer: The atomic building block (sugar, base, phosphate, etc.)
• Connection: A bond between two monomers

API Reference

MoleculeData dataclass

Mutable data structure defining all information of the oligonucleotide.

This dataclass holds the parsed state of a molecule using standard mutable Python collections. An instance is designed to be modified in-place by services performing operations like modifications.

all_connections: List[Connection] property

Provides access to the internal list of all connections.

find_monomer_position(monomer_to_find)

Finds the polymer ID and 1-based HELM index for a given Monomer object.

Parameters:

Name	Type	Description	Default
monomer_to_find	Monomer	The Monomer object to locate.	required

Returns:

Type	Description
Optional[Tuple[str, int]]	A tuple of (polymer_id, 1-based_index) or None if not found.

get_polymer(polymer_id)

Retrieves a specific polymer by its ID.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier of the polymer.	required

Returns:

Type	Description
Polymer	The requested Polymer object (mutable).

Raises:

Type	Description
ValueError	If the polymerID is not found.

get_residue_at(polymer_id, position)

Retrieves a specific residue using its polymer ID and 1-based position.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier for the polymer (e.g., 'PEPTIDE1').	required
position	int	The 1-based index of the residue within the polymer (e.g., 5).	required

Returns:

Type	Description
Optional[Residue]	Optional[Residue]: The Residue object, or None if the position is out of bounds.

Raises:

Type	Description
ValueError	If the polymer_id does not exist in the molecule data.

get_sequence(polymer_id)

Retrieves the residue sequence for a polymer.

For RNA polymers this is the 5' -> 3' base sequence, using X for abasic residues. For peptides and other linear polymers it is the ordered list of monomer symbols, one per residue (e.g. ["Ac", "G", "A", "C"]).

get_natural_sequence(polymer_id)

Returns the single-letter natural-analog sequence for a polymer.

For peptides this is the canonical amino-acid string (non-natural residues collapse to their natural analog, e.g. Nle -> L); for RNA it is the base string. Monomers without a natural analog become X. Useful for novelty checks, display and search.

get_sugars(polymer_id)

Retrieves the sugar sequence (5' -> 3') for a specific polymer.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier of the polymer.	required

Returns:

Type	Description
List[str]	A list of sugar monomer IDs in 5' -> 3' direction.

Raises:

Type	Description
ValueError	If the polymerID is not found.

get_phosphates(polymer_id)

Retrieves the phosphate sequence (5' -> 3') for a specific polymer.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier of the polymer.	required

Returns:

Type	Description
List[str]	A list of phosphate monomer IDs in 5' -> 3' direction.

Raises:

Type	Description
ValueError	If the polymerID is not found.

get_all_monomers_flat(polymer_id)

Retrieves all monomers for a specific polymer as a single flat list. Order is determined by residue order, then monomer order within residue.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier of the polymer.	required

Returns:

Type	Description
List[Monomer]	The list of Monomer objects. Note: This is the internal list,
List[Monomer]	modifying it will affect the Polymer object.

Raises:

Type	Description
ValueError	If the polymerID is not found.

get_len_residues(polymer_id)

Gets the number of residues (sequence length) in a polymer.

get_len_sequence(polymer_id)

Gets the number of bases (sequence length) in a polymer.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier of the polymer.	required

Returns:

Type	Description
int	The count of base monomers.

Raises:

Type	Description
ValueError	If the polymerID is not found.

get_len_sugars(polymer_id)

Gets the number of sugars in a polymer.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier of the polymer.	required

Returns:

Type	Description
int	The count of sugar monomers.

Raises:

Type	Description
ValueError	If the polymerID is not found.

get_len_phosphates(polymer_id)

Gets the number of phosphates in a polymer.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier of the polymer.	required

Returns:

Type	Description
int	The count of phosphate monomers.

Raises:

Type	Description
ValueError	If the polymerID is not found.

get_count_monomers_by_type(polymer_id, monomer_type)

Gets the number of monomers of a specific type within a polymer.

Parameters:

Name	Type	Description	Default
polymer_id	str	The identifier of the polymer.	required
monomer_type	str	The type of monomers to count (e.g., 'sugar', 'base', 'phosphate', 'CHEM').	required

Returns:

Type	Description
int	The count of monomers of the specified type.

Raises:

Type	Description
ValueError	If the polymerID is not found.

get_count_monomers_by_id(polymer_id, monomer_id)

Gets the number of monomers with a specific ID within a polymer.

get_hydrogen_pairings()

Retrieves all hydrogen-bond-paired connections.

Hydrogen pairings are identified by 'pair' attachment points.

Returns:

Type	Description
List[Connection]	A list of Connection objects representing hydrogen pairings.

get_non_hydrogen_pairings()

Retrieves all connections excluding hydrogen pairings.

Returns:

Type	Description
List[Connection]	A list of Connection objects excluding hydrogen pairings.

get_polymer_count()

Provides a count for each polymer type in the molecule.

Returns:

Type	Description
Dict[str, int]	A dictionary mapping polymer type (e.g., 'RNA', 'CHEM') to its count.

get_rna_ids()

Retrieves the identifiers of all RNA polymers.

Returns:

Type	Description
List[str]	A list of RNA polymer IDs.

get_peptide_ids()

Retrieves the identifiers of all PEPTIDE polymers.

Returns:

Type	Description
List[str]	A list of PEPTIDE polymer IDs.

get_crosslinks(polymer_id=None)

Returns explicit covalent connections (disulfides, cyclizations, conjugations).

Hydrogen-bond base pairings are excluded. For peptides these connections are the crosslinks and macrocyclizations, since the backbone amide bonds are implicit in the residue order and never written as connections.

Parameters:

Name	Type	Description	Default
polymer_id	Optional[str]	If given, only connections with at least one endpoint in that polymer are returned.	None

Returns:

Type	Description
List[Connection]	A list of Connection objects.

is_cyclic(polymer_id=None)

Returns True when a covalent crosslink forms a ring within one polymer.

Head-to-tail cyclizations and side-chain bridges between two residues of the same chain both count. Inter-chain conjugations do not.

Parameters:

Name	Type	Description	Default
polymer_id	Optional[str]	If given, only rings within that polymer are considered.	None

get_modality()

Determines the modality and identifies structural groups for visualization.

This method prioritizes grouping by connection type: 1. It first finds all sets of RNAs connected by hydrogen bonds (duplexes). 2. It then lists all pairs of polymers connected by covalent bonds. 3. Finally, it lists any remaining standalone polymers.

Returns:

Type	Description
str	A tuple containing:
List[Set[str]]	The modality string ('aso', 'sirna', or 'unknown').
Tuple[str, List[Set[str]]]	A prioritized list of sets, where each set is a structural component.

get_unique_rna_monomers()

Retrieves all unique monomer IDs found in RNA polymers.

get_unique_monomers()

Retrieves all unique monomers (ID, type, uniletter) in the molecule.

find_residue_for_monomer(monomer_to_find)

Finds the Residue object that contains a specific Monomer object.

Parameters:

Name	Type	Description	Default
monomer_to_find	Monomer	The Monomer object instance to locate.	required

Returns:

Type	Description
Optional[Residue]	The parent Residue object, or None if the monomer is not found
Optional[Residue]	within any residue in the molecule.

get_connected_residues(connection)

Retrieves the two specific Residue objects linked by a given Connection.

This method leverages the direct monomer references in the Connection object to find their parent residues.

Parameters:

Name	Type	Description	Default
connection	Connection	The Connection object containing references to the linked monomers.	required

Returns:

Type	Description
Optional[Tuple[Residue, Residue]]	A tuple containing the two connected Residue objects (residue1, residue2),
Optional[Tuple[Residue, Residue]]	or None if either parent residue cannot be found.

get_connected_monomers(connection)

Retrieves the two specific Monomer objects linked by a given Connection.

This method leverages the direct monomer references in the Connection object. For hydrogen bonds ('pair'), it intelligently returns the base monomers of the connected residues, reflecting the chemical intent. For all other bonds, it returns the monomers that are directly linked.

Parameters:

Name	Type	Description	Default
connection	Connection	The Connection object.	required

Returns:

Type	Description
Optional[Tuple[Monomer, Monomer]]	A tuple containing the two connected Monomer objects (monomer1, monomer2),
Optional[Tuple[Monomer, Monomer]]	or None if the functional monomers cannot be determined.

Polymer dataclass

Represents a polymer chain (RNA, CHEM, PEPTIDE, etc.).

Attributes:

Name	Type	Description
type	str	The polymer type (e.g., 'RNA', 'CHEM', 'PEPTIDE').
index	str	The numeric index of this polymer within its type (e.g., '1' for RNA1).
residues	List[Residue]	The list of residues in this polymer.

id: str property

Returns the full polymer identifier (e.g., 'RNA1').

This is a computed property combining type and index.

Residue dataclass

Monomer dataclass

uniletter: bool property

Determines if the monomer is represented by a single letter.

Connection dataclass