CodeEntropy.levels.hierarchy module

Hierarchy level selection and bead construction.

This module defines HierarchyBuilder, which is responsible for:

  • Determining which hierarchy levels apply to each molecule.

  • Constructing “beads” (AtomGroups) for a given molecule at a given level.

Notes

The “residue” bead construction must use residues attached to the provided AtomGroup/container. Using resindex selection strings is unsafe because resindex is global to the Universe and can produce empty or incorrect beads when operating on per-molecule containers beyond the first molecule.

class CodeEntropy.levels.hierarchy.HierarchyBuilder[source]

Bases: object

Determine applicable hierarchy levels and build beads for each level.

A “level” represents a resolution scale used throughout the entropy workflow:

  • united_atom: heavy-atom-centered beads (plus bonded hydrogens)

  • residue: residue beads

  • polymer: whole-molecule bead

This class intentionally does not perform any entropy calculations. It only provides structural information (levels and beads).

get_beads(data_container, level: str) → list[source]

Build beads for a given container at a given hierarchy level.

Parameters:

  • data_container – An MDAnalysis AtomGroup representing a molecule or other container that has .select_atoms(…) and .residues.

  • level – One of {“united_atom”, “residue”, “polymer”}.

Returns:

A list of MDAnalysis AtomGroups representing beads at that level.

Raises:

ValueError – If level is not a supported hierarchy level.

select_levels(data_container) → tuple[int, list[list[str]]][source]

Select applicable hierarchy levels for each molecule in the container.

A molecule is always assigned the united_atom level.

Additional levels are included if:

  • residue: the heavy-atom subset has more than one atom.

  • polymer: the heavy-atom subset spans more than one residue.

Parameters:

data_container – An MDAnalysis Universe (or compatible object) with atoms.fragments available.

Returns:

  • number_molecules: Number of molecular fragments.

  • levels: List where levels[mol_id] is a list of level names (strings) for that molecule in increasing coarseness.

Return type:

A tuple of