CodeEntropy.results.reporter module

Utilities for logging entropy results and exporting data.

This module provides the ResultsReporter class, which is responsible for:

• Collecting molecule-level entropy results

• Collecting residue-level entropy results

• Storing group metadata labels

• Rendering rich tables to the console

• Exporting results to JSON

class CodeEntropy.results.reporter.ResultsReporter(console: Console | None = None)

Bases: object

Collect, format, and output entropy calculation results.

This reporter accumulates:

• Molecule-level results (group_id, level, entropy_type, value)

• Residue-level results (group_id, resname, level, entropy_type, frame_count, value)

• Group metadata labels (label, residue_count, atom_count)

It can render tables using Rich and export grouped results to JSON with basic provenance metadata.

add_group_label(group_id: Any, label: str, residue_count: int | None = None, atom_count: int | None = None) → None

Store metadata label for a group.

Parameters:

• group_id – Group identifier.

• label – Human-readable label for the group.

• residue_count – Optional residue count for the group.

• atom_count – Optional atom count for the group.

add_residue_data(group_id: Any, resname: str, level: str, entropy_type: str, frame_count: Any, value: Any) → None

Add residue-level entropy result.

Parameters:

• group_id – Group identifier.

• resname – Residue name (will be cleaned to remove dash-like characters).

• level – Hierarchy level label.

• entropy_type – Entropy component/type label.

• frame_count – Number of frames contributing to the value (may be ndarray).

• value – Result value to store (kept as-is).

add_results_data(group_id: Any, level: str, entropy_type: str, value: Any) → None

Add molecule-level entropy result.

Parameters:

• group_id – Group identifier.

• level – Hierarchy level label.

• entropy_type – Entropy component/type label.

• value – Result value to store (kept as-is).

static clean_residue_name(resname: Any) → str

Clean residue name by removing dash-like characters.

Parameters:

resname – Residue name (any type, will be converted to str).

Returns:

Residue name with dash-like characters removed.

log_tables() → None

Render all collected data as Rich tables (grouped by group id).

progress(*, transient: bool = True) → Iterator[_RichProgressSink]

Create a workflow progress context.

Usage:

with reporter.progress() as p:

…

Parameters:

transient – Whether the progress display should be removed on exit.

Yields:

A _RichProgressSink that exposes add_task(), update(), and advance().

save_dataframes_as_json(molecule_df: Any, residue_df: Any, output_file: str, *, args: Any | None = None, include_raw_tables: bool = False) → None

Save results to a grouped JSON structure.

JSON contains:

• args: arguments used (serialized)

• provenance: version, python, platform, optional git sha

• groups: { “<gid>”: { components: {…}, total: … } }

Parameters:

• molecule_df – Pandas DataFrame containing molecule results.

• residue_df – Pandas DataFrame containing residue results.

• output_file – Path to JSON output file.

• args – Optional argparse Namespace or dict of arguments used.

• include_raw_tables – If True, also include old “molecule_data”/”residue_data” arrays for debugging/backwards-compat.