Comparison utilities#

Two-set comparison: differential protection (occupation difference) with optional threshold. Donor-residue aggregation and comparison DataFrame for plotting / PDB B-factors.

phenoms.comparison.bond_label_to_donor_residue(bond_label)[source]#

‘ALA1 – GLY2’ -> ‘ALA1’ (first residue = donor convention).

phenoms.comparison.aggregate_pivot_by_donor(pivot_tables, total_frames=None, donor_aggregation='sum')[source]#

Aggregate bond-level occupancy to per-donor-residue average protection.

For each donor residue, average the mean occupancy of all bonds that have that donor (first residue in bond label). Uses mean across replicates then mean across bonds per donor.

Parameters:

  • pivot_tables (list of pd.DataFrame) – Each: index = Bond Label, columns = Frame, values = 0/1 or count.

  • total_frames (int or None) – If None, use number of columns (frames) from first pivot.

  • donor_aggregation (str) – How to combine multiple bond labels that share the same donor residue. - “mean”: average across bonds for that donor (current behavior historically) - “sum”: sum across bonds for that donor (matches your old notebook-style weighting) - “max”: maximum across bonds for that donor (donor protected if any bond is present)

Returns:

Columns: Donor Residue, Average (mean protection 0-1).

Return type:

pd.DataFrame

phenoms.comparison.compare_two_sets(pivot_tables_a, pivot_tables_b, label_a='set_a', label_b='set_b', impute_threshold=0.4, flip_difference=False, donor_aggregation='sum')[source]#

Compare two simulation sets: per-donor average protection and difference.

Parameters:

  • pivot_tables_a (list of pd.DataFrame) – Pivot tables (bond x frame) for each set.

  • pivot_tables_b (list of pd.DataFrame) – Pivot tables (bond x frame) for each set.

  • label_a (str) – Column names for the two averages.

  • label_b (str) – Column names for the two averages.

  • impute_threshold (float or None) – Where both average_a and average_b <= impute_threshold, set Difference to 0. Set to None to skip imputation.

  • flip_difference (bool) – If True, Difference = average_b - average_a (e.g. Ligand - No Ligand).

Returns:

Donor Residue, {label_a}, {label_b}, Difference (raw), Difference_clipped (clip to [-1, 1] for visualization / PDB), Residue Number. Sorted by residue.

Return type:

pd.DataFrame

phenoms.comparison.prefer_difference_clipped_column(comparison_df)[source]#

Return Difference_clipped if present (new CSVs), else Difference.

Parameters:

comparison_df (DataFrame)

Return type:

str

phenoms.comparison.differentially_protected(comparison_df, threshold=0.2, *, difference_column='Difference_clipped')[source]#

Filter to rows where abs(difference_column) > threshold (default: clipped difference).

Parameters:

difference_column (str)

phenoms.comparison.per_donor_metric_from_pivots(pivot_tables, metric='variance', donor_aggregation='sum')[source]#

Per-donor metric for single-set structure labeling (fluctuation or mean occupancy). metric ‘variance’: mean across bonds (with that donor) of variance across frames; high = fluctuating. metric ‘mean’: same as aggregate_pivot_by_donor (mean occupancy).

Connectivity (graph) analysis for backbone N–O hydrogen bonds.

R&D module: builds a residue-residue network from bond-level occupancy/delta values derived from SimulationSet pivot tables.

Exports an interactive HTML graph (no Jupyter required).

phenoms.connectivity.bond_label_to_donor_acceptor_residue_numbers(bond_label)[source]#

‘ALA1 – GLY2’ -> (1, 2) Using the convention: first residue is the donor.

Parameters:

bond_label (str)

Return type:

Tuple[int, int]

phenoms.connectivity.bond_occupancy_from_pivot_tables(pivot_tables, bond_labels)[source]#

Compute mean bond presence fraction over frames, averaged across replicates.

Parameters:

  • pivot_tables (Sequence[DataFrame]) – List of pivot tables: index=bond label, columns=Frame, values=0/1 (or counts).

  • bond_labels (Sequence[str]) – Ordered list of bond labels to align to.

Returns:

Index=bond_labels, values=occupancy fraction in [0, 1] (approx).

Return type:

pd.Series

phenoms.connectivity.bond_delta_from_pivot_tables(pivot_tables_a, pivot_tables_b, bond_labels, *, flip_difference, impute_threshold=None)[source]#

Compute bond-level delta values between two sets.

The sign convention matches ComparisonSet.compare(): - if flip_difference=False: delta = average_a - average_b - if flip_difference=True: delta = average_b - average_a

Parameters:
Return type:

Series

class phenoms.connectivity.ResidueGraph(nodes: 'List[dict]', edges: 'List[dict]')[source]#

Bases: object

Parameters:
nodes: List[dict]#
edges: List[dict]#
class phenoms.connectivity.CommunityGraphResult(graph: 'ResidueGraph', community_by_node: 'Dict[str, int]', modularity: 'float')[source]#

Bases: object

Parameters:
graph: ResidueGraph#
community_by_node: Dict[str, int]#
modularity: float#
phenoms.connectivity.build_residue_graph_from_bond_deltas(bond_deltas, *, top_k_edges=30, min_abs_edge_delta=None, aggregate_edges_by_residue_pair=True, directed=False)[source]#

Build residue-residue graph from bond-level delta values.

Nodes are residues (by donor/acceptor residue number). Edges correspond to donor->acceptor backbone H-bonds.

Parameters:

  • bond_deltas (Series)

  • top_k_edges (int)

  • min_abs_edge_delta (float | None)

  • aggregate_edges_by_residue_pair (bool)

  • directed (bool)

Return type:

ResidueGraph

phenoms.connectivity.assign_greedy_modularity_communities(graph, *, directed=False, weight_attr='abs_weight', resolution=1.0)[source]#

Compute residue communities from a ResidueGraph using greedy modularity.

Returns per-node community IDs and modularity score.

Parameters:
Return type:

CommunityGraphResult

phenoms.connectivity.apply_community_annotations(graph, community_by_node)[source]#

Return a graph with node/edge annotations derived from community assignments.

Parameters:
Return type:

ResidueGraph

phenoms.connectivity.build_residue_graph_with_communities(bond_values, *, top_k_edges=30, min_abs_edge_delta=None, aggregate_edges_by_residue_pair=True, directed=False, resolution=1.0)[source]#

Build residue graph and assign community IDs with greedy modularity.

Parameters:

  • bond_values (Series)

  • top_k_edges (int)

  • min_abs_edge_delta (float | None)

  • aggregate_edges_by_residue_pair (bool)

  • directed (bool)

  • resolution (float)

Return type:

CommunityGraphResult

phenoms.connectivity.community_tables(graph_result)[source]#

Build node-level and community-level summary tables.

Parameters:

graph_result (CommunityGraphResult)

Return type:

Tuple[DataFrame, DataFrame]

phenoms.connectivity.export_residue_graph_html(graph, output_html_path, *, title='Residue H-bond connectivity graph', directed=False, summary_stats=None, show_delta_legend=True)[source]#

Export an interactive HTML graph using vis-network (loaded from a CDN).

Parameters:
Return type:

None