Plotting & reduction#

Heatmaps, top-H-bond bar plot, aggregated heatmap, and bond statistics bar plots.

phenoms.plotting.plot_heatmap(pivot_table, file_name, save_path=None, figsize=(12, 8))[source]#

H-bond occupation over time (bond labels vs frames). Optionally save to file.

Parameters:

  • pivot_table (pd.DataFrame)

  • file_name (str) – Used in title.

  • save_path (str or None) – If set, save figure to this path and do not show.

  • figsize (tuple)

phenoms.plotting.plot_heatmap_with_legend(pivot_table, title, save_path=None, figsize=(12, 8))[source]#

Same as plot_heatmap but with a legend for Absent (0) / Present (1).

phenoms.plotting.plot_top_hbonds(all_pivot_tables, threshold, sub_frames=None, save_path=None)[source]#

Bar chart of top H-bonds by average lifetime (presence fraction > threshold).

phenoms.plotting.plot_bond_lifetimes_with_error_bars(mean_lifetimes, std_lifetimes, title='Average Lifetime of Hydrogen Bonds with Standard Deviation (Threshold = 50%)', save_path=None)[source]#

Bar plot of mean bond lifetimes with std error bars across replicates.

phenoms.plotting.plot_break_frequencies_with_error_bars(mean_break_frequencies, std_break_frequencies, title='Frequency of Breaks of Hydrogen Bonds with Standard Deviation', save_path=None)[source]#

Bar plot of mean break frequency with std error bars across replicates.

phenoms.plotting.plot_aggregated_heatmap(all_pivot_tables, save_path=None, figsize=(12, 8), region_str='Entire protein')[source]#

Average presence of each bond across replicates (one row heatmap).

phenoms.plotting.suggest_difference_threshold_autocorr(comparison_df, y_column='Difference_clipped', kappa=1.96)[source]#

Estimate an absolute-difference threshold from sequence structure (lag-1 autocorrelation).

Treats the per-residue difference series (in table order) as roughly AR(1); the innovation standard deviation scales local noise. Returns clip(kappa * sigma_innovation, 0.05, 0.35).

Use with plot_difference(..., diff_threshold_mode="autocorr") or call directly.

Parameters:

  • comparison_df (pd.DataFrame) – Must be ordered along sequence (e.g. from compare_two_sets).

  • y_column (str)

  • kappa (float) – Multiplier on the estimated noise scale (default ~95% under Gaussian heuristic).

Return type:

float

phenoms.plotting.plot_difference(comparison_df, x_column='Residue Number', y_column='Difference_clipped', title='Change in Protection (Set B − Set A)', diff_threshold=0.2, diff_threshold_mode='manual', impute_small_differences=True, show_labels=True, interpolate=True, interpolation_points=900, autocorr_kappa=1.96, save_path=None, figsize=(12, 8), return_meta=False)[source]#

Line plot of per-donor difference vs residue.

By default y_column="Difference_clipped" (values in [-1, 1]); use y_column="Difference" for raw donor deltas.

Parameters:

  • diff_threshold (float or None) – Used when diff_threshold_mode="manual": residues with abs(y) above this get text labels. When imputing, plotted y is set to 0 where abs(y) < threshold. Default is 0.2 (20% delta).

  • diff_threshold_mode (str) – "manual" — use diff_threshold. "autocorr" — threshold from suggest_difference_threshold_autocorr() (diff_threshold ignored except if autocorr fails).

  • impute_small_differences (bool) – If True (default), plot values with abs(y) below the effective threshold as 0 (smoothed / noise-suppressed line). If False, plot raw differences; labels still use the effective threshold when set.

  • show_labels (bool) – If True (default), add red residue-number text for residues with abs(difference) >= effective threshold.

  • interpolate (bool) – If True, draw a dashed smoothed line (visual only) using interpolation. This does not change the underlying data or thresholding.

  • interpolation_points (int) – Number of x points to draw the interpolated line.

  • autocorr_kappa (float) – Passed to autocorr threshold only.

  • return_meta (bool) – If True, return dict with effective_threshold, diff_threshold_mode, impute_small_differences.

PCA, t-SNE, Isomap on aggregated replicate H-bond data.

Use with one simulation set (replicates as points, colored by replicate or custom labels) or two sets (ComparisonSet: two groups).

phenoms.dimensionality_reduction.aggregate_replicate_data(pivot_tables_list)[source]#

One row per replicate: mean occupancy per bond across frames. Shape (n_replicates, n_bonds). Fill missing bonds with 0.

phenoms.dimensionality_reduction.run_pca(aggregated_data, n_components=2)[source]#

Standardize and run PCA. Returns (scores, explained_variance_ratio).

phenoms.dimensionality_reduction.run_tsne(aggregated_data, perplexity=2, random_state=42)[source]#

Standardize and run t-SNE. Returns 2D scores.

phenoms.dimensionality_reduction.run_isomap(aggregated_data, n_neighbors=5, n_components=2)[source]#

Standardize and run Isomap. Returns 2D scores.

phenoms.dimensionality_reduction.plot_manifold(scores, group_labels, replicate_labels=None, title='PCA', palette=None, ax=None)[source]#

Scatter plot of 2D manifold (PCA/t-SNE/Isomap) with points colored by group.

Parameters:

  • scores (np.ndarray) – (n_replicates, 2).

  • group_labels (list or array) – One label per replicate (e.g. True/False for ligand, or “no_lig”/”lig”).

  • replicate_labels (list or None) – Optional text label per point.

  • title (str)

  • palette (dict or None) – Mapping group_label -> color.

  • ax (matplotlib axes or None)

phenoms.dimensionality_reduction.run_manifold_suite(pivot_tables, group_labels, perplexity=2, n_neighbors=5, random_state=42, plot=True)[source]#

Run PCA, t-SNE, and Isomap on the same aggregated matrix (glassfrog-style workflow).

Parameters:

  • pivot_tables (list of pd.DataFrame) – Bond × frame pivots (one per replicate).

  • group_labels (list) – One label per replicate (e.g. replicate name, or True/False for two conditions).

  • perplexity – Passed to t-SNE / Isomap.

  • n_neighbors – Passed to t-SNE / Isomap.

  • random_state – Passed to t-SNE / Isomap.

  • plot (bool) – If True, show three scatter plots (PCA, t-SNE, Isomap).

Returns:

  • dict with keys ‘pca’ (scores, var_ratio), ‘tsne’ (scores), ‘isomap’ (scores),

  • and ‘aggregated_data’ (np.ndarray).

Pivot tables, bond label sorting, and bond statistics (lifetime, break frequency).

phenoms.analysis.extract_residue_numbers(bond_label)[source]#

Parse ‘Residue1 – Residue2’ into (res1, res2) as integers.

Parameters:

bond_label (str) – e.g. ‘Ala1 – Gly2’

Return type:

tuple (int, int)

phenoms.analysis.create_pivot_table(hbonds_df, bond_labels_sorted)[source]#

Pivot table: rows = bond labels (consistent order), columns = frames, values = count (0/1+).

Parameters:

  • hbonds_df (pd.DataFrame) – Must have ‘Bond Label’ and ‘Frame’.

  • bond_labels_sorted (list of str) – Full set of bond labels in desired order.

Return type:

pd.DataFrame

phenoms.analysis.calculate_bond_statistics(hbonds_pivot, threshold)[source]#

For bonds with mean occupancy > threshold, compute average lifetime and break frequency.

Parameters:

  • hbonds_pivot (pd.DataFrame) – Rows = bond labels, columns = frames, values = 0/1 (or counts).

  • threshold (float) – Keep only bonds with mean(row) > threshold.

Returns:

  • average_bond_lifetimes (pd.Series)

  • break_frequencies (pd.Series)

phenoms.analysis.fluctuating_bonds(pivot_tables, quantile=0.9, metric='variance')[source]#

Bonds that fluctuate most (high variance across frames). For single-set highlighting.

Parameters:

  • pivot_tables (list of pd.DataFrame)

  • quantile (float in (0, 1]) – Keep bonds with variance >= this quantile (e.g. 0.9 = top 10%).

  • metric (str) – ‘variance’ = variance of occupancy across frames (mean across replicates).

Returns:

Bond labels (index) with variance (or metric) value, sorted descending.

Return type:

pd.Series