Inspect#

Block 5 — what the search learned. See the guide.

Sampler accessors#

ThompsonSampler.get_diagnostics()[source]#

Return per-cycle diagnostics trajectory as a DataFrame.

Requires track_diagnostics=True in config.

Returns strategy-specific schemas:

  • TopTwoSelection: 12-column TT-TS schema with disagreement EMA, adaptive heated_scale, and GMIC per component.

  • RouletteWheelSelection: 18-column GMIC schema with full temperature pipeline (base_temp, cats_multiplier, final_temperature).

  • BayesUCBSelection: 18-column IPR schema with participation ratio, SNR dampening, and observation-gated weights.

All schemas share current_cycle, component_idx and criticality columns, so downstream analysis functions work across strategies. Strategies without component state (Greedy, UCB, EpsilonGreedy) record nothing.

Returns an empty DataFrame with just those three shared columns if diagnostics were not tracked or the strategy records no state.

Return type:

DataFrame

ThompsonSampler.get_posterior_landscape()[source]#

Return per-reagent posterior state for all components.

Each row contains:

  • component_idx – component index (0-based)

  • reagent_name – reagent identifier

  • mean – posterior mean

  • std – posterior standard deviation

  • n_samples – number of observations

Works regardless of track_diagnostics setting.

Return type:

DataFrame

ThompsonSampler.get_sar_summary()[source]#

Strategy-agnostic post-hoc SAR assessment from final posteriors.

Works for ANY strategy — computes entropy-based concentration from the current posterior state. Uses the same z-score softmax approach as CATS _calculate_criticality() so that the post-hoc concentration and CATS criticality are directly comparable.

When track_diagnostics=True and the strategy supports get_component_state() (CATS strategies), convergence dynamics are also included.

Returns:

  • components – list of per-component dicts

  • landscape_type – “structured_SAR” / “diffuse_SAR” / “mixed” / “insufficient_data”

  • summary_text – human-readable 2-3 sentence assessment

  • convergence_dynamics – (only with CATS + track_diagnostics) per-component convergence info

Return type:

Dict with keys

Analysis functions#

Pure Polars in, Polars out — usable on saved diagnostics without a sampler.

Pure analysis functions for CATS diagnostics.

All functions operate on Polars DataFrames and have no dependency on the ThompsonSampler or strategy objects. This makes them usable in notebooks, scripts, and post-hoc analysis pipelines.

TACTICS.thompson_sampling.diagnostics.compute_posterior_entropy(landscape_df, mode='maximize', criticality_metric='ipr', n_adaptive_sharpening=True)[source]#

Compute per-component entropy metrics from a posterior landscape.

Uses z-score softmax (same as CATS _calculate_criticality()) to convert posterior means into a probability distribution, then measures concentration via IPR (default) or Shannon entropy.

Parameters:

  • landscape_df (DataFrame) – DataFrame from sampler.get_posterior_landscape() with columns component_idx, reagent_name, mean, std, n_samples.

  • mode (str) – “maximize” or “minimize” — determines sign convention.

  • criticality_metric (str) – “ipr” or “shannon” — metric for concentration.

  • n_adaptive_sharpening (bool) – Apply sqrt(log(N)) sharpening when using IPR.

Returns:

component_idx, n_active, entropy, normalized_entropy, concentration, snr.

Return type:

DataFrame with one row per component

TACTICS.thompson_sampling.diagnostics.compute_convergence_point(diagnostics_df, threshold=0.3, stability_window=5)[source]#

Find the cycle at which each component first reaches stable convergence.

A component is considered converged at cycle c if criticality > threshold for all cycles from c through c + stability_window - 1.

Parameters:

  • diagnostics_df (DataFrame) – Enhanced diagnostics DataFrame (must have current_cycle, component_idx, criticality columns).

  • threshold (float) – Criticality threshold for “structured” (default 0.3).

  • stability_window (int) – Number of consecutive cycles above threshold required for stability (default 5).

Returns:

DataFrame with component_idx, cycle_first_above, cycle_stable.

Return type:

DataFrame

TACTICS.thompson_sampling.diagnostics.compare_trajectory_vs_snapshot(diagnostics_df, landscape_df, mode='maximize')[source]#

Compare CATS trajectory information with a post-hoc snapshot.

Shows what the trajectory reveals that the static snapshot doesn’t: convergence timing, stability, and whether the final state was reached early or late.

Parameters:

  • diagnostics_df (DataFrame) – Enhanced diagnostics DataFrame from sampler.get_diagnostics().

  • landscape_df (DataFrame) – Posterior landscape from sampler.get_posterior_landscape().

  • mode (str) – “maximize” or “minimize”.

Returns:

component_idx, snapshot_concentration, trajectory_final_criticality, cycle_first_above, cycle_stable, trajectory_adds_info (bool).

Return type:

DataFrame with per-component comparison

TACTICS.thompson_sampling.diagnostics.compute_disagreement_convergence(diagnostics_df, stability_window=10, low_threshold=0.3, high_threshold=0.8)[source]#

Analyze per-component disagreement EMA convergence from TT-TS diagnostics.

Identifies when each component’s disagreement rate stabilizes, indicating that TT-TS has resolved uncertainty about reagent rankings.

Parameters:

  • diagnostics_df (DataFrame) – TT-TS diagnostics DataFrame (must have current_cycle, component_idx, disagreement_ema).

  • stability_window (int) – Consecutive cycles within threshold band for stability (default 10).

  • low_threshold (float) – Disagreement below this means component is well-resolved (default 0.3).

  • high_threshold (float) – Disagreement above this means component is saturated / exploration is random (default 0.8).

Returns:

DataFrame with component_idx, final_disagreement, cycle_below_low, cycle_stable_low, mean_disagreement, regime (“resolved” / “saturated” / “exploring”).

Return type:

DataFrame

TACTICS.thompson_sampling.diagnostics.compute_scale_adaptation(diagnostics_df)[source]#

Summarize per-component adaptive heated_scale evolution from TT-TS diagnostics.

Parameters:

diagnostics_df (DataFrame) – TT-TS diagnostics DataFrame (must have current_cycle, component_idx, heated_scale).

Returns:

DataFrame with component_idx, initial_scale, final_scale, min_scale, max_scale, scale_range, adaptation_direction (“decayed” / “grew” / “stable”).

Return type:

DataFrame

TACTICS.thompson_sampling.diagnostics.format_sar_report(summary)[source]#

Format a get_sar_summary() dict into a publication-ready text block.

Parameters:

summary (Dict[str, Any]) – Dict returned by ThompsonSampler.get_sar_summary().

Returns:

Multi-line string suitable for inclusion in a manuscript or notebook.

Return type:

str