att.viz

Visualization utilities for ATT.

att.viz.plot_persistence_diagram(diagrams, ax=None, colormap='viridis')[source]

Plot persistence diagrams for all homology dimensions.

Parameters:
Return type:

Figure

att.viz.plot_persistence_image(images, ax=None, colormap='hot')[source]

Plot persistence images for all homology dimensions.

Parameters:
Return type:

Figure

att.viz.plot_barcode(diagrams, ax=None)[source]

Plot persistence barcodes.

Parameters:
Return type:

Figure

att.viz.plot_betti_curve(betti_curves, ax=None)[source]

Plot Betti curves.

Parameters:
Return type:

Figure

att.viz.plot_attractor_3d(cloud, color_by='time', backend='plotly')[source]

3D scatter/line plot of an attractor point cloud.

Parameters:

  • cloud ((n_points, 3+) array — uses first 3 columns)

  • color_by ("time" (color by index))

  • backend ("plotly" or "matplotlib")

att.viz.plot_surrogate_distribution(observed, surrogates, ax=None)[source]

Histogram of surrogate scores with observed score marked.

Parameters:
Return type:

Figure

att.viz.plot_benchmark_sweep(results, ax=None)[source]

Plot benchmark sweep with all methods overlaid.

Parameters:

results (pd.DataFrame with columns coupling, method, score, score_normalized)

Return type:

Figure

att.viz.plot_binding_comparison(detector)[source]

3-panel comparison: marginal X | joint (excess highlighted) | marginal Y.

Parameters:

detector (BindingDetector with fitted state)

Return type:

matplotlib Figure

att.viz.plot_binding_image(images, colormap='RdBu_r')[source]

Heatmap of residual persistence images.

Parameters:

  • images (list of (resolution, resolution) residual images, one per dimension)

  • colormap (diverging colormap (red=emergent, blue=deficit))

Return type:

matplotlib Figure

att.viz.plot_transition_timeline(detector, ground_truth=None, figsize=(12, 6))[source]

Plot topology transition timeline from a fitted TransitionDetector.

Parameters:

  • detector (TransitionDetector) – Must have been fit_transform()’d.

  • ground_truth (list of int or None) – True transition sample indices (plotted as green dotted lines).

  • figsize (tuple) – Figure size.

Return type:

matplotlib Figure

att.viz.export_to_json(results, path)[source]

Export computed results as JSON.

Parameters:
Return type:

None

att.viz.load_from_json(path)[source]

Load results from JSON.

Parameters:

path (str)

Return type:

dict

Publication-quality plotting utilities.

att.viz.plotting.plot_persistence_diagram(diagrams, ax=None, colormap='viridis')[source]

Plot persistence diagrams for all homology dimensions.

Parameters:
Return type:

Figure

att.viz.plotting.plot_persistence_image(images, ax=None, colormap='hot')[source]

Plot persistence images for all homology dimensions.

Parameters:
Return type:

Figure

att.viz.plotting.plot_barcode(diagrams, ax=None)[source]

Plot persistence barcodes.

Parameters:
Return type:

Figure

att.viz.plotting.plot_betti_curve(betti_curves, ax=None)[source]

Plot Betti curves.

Parameters:
Return type:

Figure

att.viz.plotting.plot_attractor_3d(cloud, color_by='time', backend='plotly')[source]

3D scatter/line plot of an attractor point cloud.

Parameters:

  • cloud ((n_points, 3+) array — uses first 3 columns)

  • color_by ("time" (color by index))

  • backend ("plotly" or "matplotlib")

att.viz.plotting.plot_surrogate_distribution(observed, surrogates, ax=None)[source]

Histogram of surrogate scores with observed score marked.

Parameters:
Return type:

Figure

att.viz.plotting.plot_benchmark_sweep(results, ax=None)[source]

Plot benchmark sweep with all methods overlaid.

Parameters:

results (pd.DataFrame with columns coupling, method, score, score_normalized)

Return type:

Figure

att.viz.plotting.plot_binding_comparison(detector)[source]

3-panel comparison: marginal X | joint (excess highlighted) | marginal Y.

Parameters:

detector (BindingDetector with fitted state)

Return type:

matplotlib Figure

att.viz.plotting.plot_binding_image(images, colormap='RdBu_r')[source]

Heatmap of residual persistence images.

Parameters:

  • images (list of (resolution, resolution) residual images, one per dimension)

  • colormap (diverging colormap (red=emergent, blue=deficit))

Return type:

matplotlib Figure

att.viz.plotting.export_to_json(results, path)[source]

Export computed results as JSON.

Parameters:
Return type:

None

att.viz.plotting.load_from_json(path)[source]

Load results from JSON.

Parameters:

path (str)

Return type:

dict

att.viz.plotting.plot_transition_timeline(detector, ground_truth=None, figsize=(12, 6))[source]

Plot topology transition timeline from a fitted TransitionDetector.

Parameters:

  • detector (TransitionDetector) – Must have been fit_transform()’d.

  • ground_truth (list of int or None) – True transition sample indices (plotted as green dotted lines).

  • figsize (tuple) – Figure size.

Return type:

matplotlib Figure

att.viz.plotting.plot_zscore_profile(z_scores, p_values=None, per_dim_z_scores=None, ax=None, significance_threshold=0.05)[source]

Layer-indexed z-score profile with significance shading.

Parameters:

  • z_scores ((n_layers,) aggregate z-scores.)

  • p_values ((n_layers,) p-values for significance shading.)

  • per_dim_z_scores (dict mapping dim (int) -> (n_layers,) z-scores.)

  • ax (optional axes.)

  • significance_threshold (p-value below which to shade.)

Return type:

Figure

att.viz.plotting.plot_crocker(betti_matrix, parameter_labels=None, filtration_range=None, ax=None, colormap='viridis', title=None)[source]

2D heatmap of Betti numbers (filtration scale × parameter).

Parameters:

  • betti_matrix ((n_filtration_steps, n_parameters) Betti number matrix.)

  • parameter_labels (labels for the parameter axis.)

  • filtration_range ((min, max) of filtration values.)

  • ax (Axes | None)

  • colormap (str)

  • title (str | None)

Return type:

Figure

att.viz.plotting.plot_compression_decomposition(levels, total_persistence, n_features, mean_lifetime, ax=None, title='H1 Persistence Decomposition')[source]

Dual-axis plot of feature count vs mean lifetime by difficulty.

Parameters:

  • levels (difficulty level labels.)

  • total_persistence (total persistence per level.)

  • n_features (feature count per level.)

  • mean_lifetime (mean lifetime per level.)

  • ax (Axes | None)

  • title (str)

Return type:

Figure

att.viz.plotting.plot_roc_curves(roc_data, ax=None, title='ROC Curves: Correctness Prediction')[source]

Plot ROC curves for correctness prediction.

Parameters:

  • roc_data (dict mapping label -> (fpr, tpr, auroc).)

  • ax (optional axes.)

  • title (plot title.)

Return type:

Figure

att.viz.plotting.plot_id_profile(profiles, ax=None, title='Intrinsic Dimension by Layer', method_label='TwoNN')[source]

Plot intrinsic dimension profiles across layers by difficulty level.

Parameters:

  • profiles (dict mapping level -> (n_layers,) array of ID estimates.)

  • ax (optional axes.)

  • title (plot title.)

  • method_label (label for the ID method.)

Return type:

Figure

att.viz.plotting.plot_spectral_comparison(euclidean_entropy, spectral_entropy, layer_indices, ax=None, title='Euclidean vs Spectral PH Entropy')[source]

Side-by-side comparison of Euclidean and spectral persistence entropy.

Parameters:

  • euclidean_entropy (dict mapping H-dim -> list of entropies per layer.)

  • spectral_entropy (dict mapping H-dim -> list of entropies per layer.)

  • layer_indices (list of layer index labels.)

  • ax (optional axes.)

  • title (plot title.)

Return type:

Figure

att.viz.plotting.plot_zigzag_barcode(barcodes, dim=1, level=None, ax=None, title=None, colormap='viridis')[source]

Plot zigzag persistence barcode as horizontal lifetime bars.

Parameters:

  • barcodes ((n, 2) array of (birth_layer, death_layer).)

  • dim (homology dimension (for labeling).)

  • level (difficulty level (for labeling).)

  • ax (optional matplotlib axes.)

  • title (plot title override.)

  • colormap (matplotlib colormap name.)

att.viz.plotting.plot_zigzag_comparison(results, dim=1, metric='mean_lifetime', ax=None, title='Zigzag Feature Statistics by Difficulty')[source]

Bar chart comparing zigzag statistics across difficulty levels.

Parameters:

  • results (dict mapping level (int) -> stats dict from zigzag_feature_lifetime_stats.)

  • dim (homology dimension (for labeling).)

  • metric (which stat to plot ('mean_lifetime', 'n_features', 'max_lifetime', 'n_long_lived').)

  • ax (optional axes.)

  • title (plot title.)

att.viz.plotting.plot_token_partition_topology(region_entropy, levels=None, ax=None, title='Persistence Entropy by Token Region')[source]

Grouped bar chart of persistence entropy across token regions and difficulty.

Parameters:

  • region_entropy (dict mapping region_name -> {level: list_of_entropy_values}.)

  • levels (which levels to include (default: all).)

  • ax (optional axes.)

  • title (plot title.)

att.viz.plotting.plot_cross_model_zscore(zscore_results, model_labels=None, model_colors=None, ax=None, title='Cross-Model Z-Score Profiles')[source]

Overlay z-score profiles from multiple models.

Parameters:

  • zscore_results (dict mapping model_key -> {"z_scores": array, "n_layers": int}.)

  • model_labels (optional mapping model_key -> display name.)

  • model_colors (optional mapping model_key -> color.)

  • ax (optional axes.)

  • title (plot title.)

att.viz.plotting.plot_attention_binding_heatmap(scores, levels, layer_indices, ax=None, title='Attention-Hidden Binding Score', cmap='RdYlBu_r')[source]

Heatmap of binding scores (difficulty × layer).

Parameters:

  • scores (dict mapping (level, layer) -> float or {"mean": float}.)

  • levels (list of difficulty levels.)

  • layer_indices (list of layer indices.)

  • ax (optional axes.)

  • title (plot title.)

  • cmap (colormap name.)