CodeEntropy.levels.dihedrals module

Dihedral state assignment for conformational entropy.

This module converts dihedral angle time series into discrete conformational state labels. The resulting state labels are used downstream to compute conformational entropy.

class CodeEntropy.levels.dihedrals.ConformationStateBuilder(universe_operations: Any)[source]

Bases: object

Build conformational state labels from dihedral angles.

build_conformational_states(data_container: Any, levels: dict[Any, list[str]], groups: dict[int, list[Any]], bin_width: float, progress: _RichProgressSink | None = None) → tuple[dict[tuple[int, int], list[str]], list[list[str]], dict[tuple[int, int], int], list[int]][source]

Build conformational state labels from trajectory dihedrals.

This method constructs discrete conformational state descriptors used in configurational entropy calculations. It supports united-atom (UA) and residue-level state generation depending on which hierarchy levels are enabled per molecule.

Progress reporting is optional and UI-agnostic. If a progress sink is provided, the method will create a single task and advance it once per molecule group.

Parameters:

  • data_container – MDAnalysis Universe (or compatible container) used to extract fragments and compute dihedral time series.

  • levels – Mapping of molecule_id -> iterable of enabled level names (e.g., [“united_atom”, “residue”]).

  • groups – Mapping of group_id -> list of molecule_ids.

  • bin_width – Histogram bin width in degrees used when identifying peak dihedral populations.

  • progress – Optional progress sink (e.g., from ResultsReporter.progress()). Must expose add_task(), update(), and advance().

Returns:

(states_ua, states_res, flexible_ua, flexible_res)

  • states_ua: Dict mapping (group_id, local_residue_id) -> list of state labels (strings) across the analyzed trajectory.

  • states_res: Structure indexed by group_id (or equivalent) containing residue-level state labels (strings) across the analyzed trajectory.

Return type:

tuple

Notes

  • This function advances progress once per group_id. helpers as implemented in this module.