GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug module

Statistical analysis of the unified JSONL retrieval debug log.

Consumes {path_results}/debug/retrieval_debug.jsonl (produced by GUIBRUSHR/Retrieval/debug_log.py) and writes:

  • summary.txt — human-readable diagnosis (acceptance, mixing, convergence)

  • plots/*.png — matplotlib figures

  • tables/*.csv — tidy tables for further inspection

Usage

conda activate guibrushr_env
python scripts/analyze_retrieval_debug.py \
    --log /home/francesco/Scaricati/retrieval_debug.jsonl \
    --out ./analysis_latest
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.parse_jsonl(path: Path) → tuple[dict[str, list[dict[str, Any]]], dict[str, int]][source]

Stream-parse a JSONL file, bucketing records by event key.

Returns:

  • buckets (dict[event_name, list[record]])

  • stats (dict with total_lines, ok_lines, skipped_lines,) – truncated_lines.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.to_df(records: list[dict[str, Any]]) → DataFrame[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_init(df_done: DataFrame, df_miss: DataFrame) → dict[str, Any][source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_acceptance(df_accept: DataFrame, df_step_done: DataFrame, df_chain_end: DataFrame, df_core_done: DataFrame, df_setup: DataFrame, df_end: DataFrame) → dict[str, Any][source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.detect_collapse(rates: ndarray, steps: ndarray, window: int = 50) → dict[str, Any] | None[source]

Find the largest drop in a rolling window.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.detect_stuck_chains(df_chain_end: DataFrame, nthin: int, window: int = 50, thresh: float = 0.05) → list[dict[str, Any]][source]

Chains whose recent-window accept_rate dropped below thresh.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_mixing(df_proposal: DataFrame, df_accept: DataFrame, df_setup: DataFrame) → dict[str, Any][source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_convergence(df_conv_check: DataFrame, df_conv_warn: DataFrame, df_conv_update: DataFrame, df_end: DataFrame) → dict[str, Any][source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_per_chain(df_chain_end: DataFrame, df_chain_init: DataFrame, df_setup: DataFrame) → DataFrame[source]

Build a per-chain summary DataFrame.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_rejects(df_core_done: DataFrame) → dict[str, Any][source]

Aggregate reject_reasons / reject_params / reject_values per param.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_rejects_per_step(df_accept: DataFrame) → DataFrame[source]

Per-outer_step reject counts from accept events that carry reject_reason.

Returns a DataFrame with one row per outer_step and columns: outer_step, n_proposals, n_rejects_with_reason, reject_rate, rejects_by_reason (dict), rejects_by_param (dict).

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_rejects_vs_norms(df_accept: DataFrame, df_proposal: DataFrame) → dict[str, Any][source]

Join accept (carrying reject_reason) with proposal (carrying de_norm, eps_norm, dpars_norm) on (outer_step, core, chain, sub) and compute the correlation between reject rate and proposal norms across outer_steps.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_rejects_per_chain(df_chain_end: DataFrame, df_accept: DataFrame) → DataFrame[source]

Chain × param reject counts.

Prefers the per-chain reject_params field from chain_end events (written by the current worker) and falls back to grouping accept-event reject_param by chain if chain_end is older and lacks the dict.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_first_reject_step(df_accept: DataFrame) → DataFrame[source]

Earliest outer_step where each param was rejected.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_reject_correlation(df_accept: DataFrame, topk: int = 15) → DataFrame[source]

Co-rejection co-occurrence of param pairs within the same outer_step.

For each pair (a,b) returns the Jaccard similarity over the set of outer_steps in which the param was rejected at least once.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_reject_severity(values: dict[str, list[float]], registry: dict[str, dict[str, float]]) → DataFrame[source]

Per-param quantiles of signed overshoot beyond the nearest bound, normalised by the prior range width.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_reject_consistency(rejects_core: dict[str, Any], df_accept: DataFrame) → dict[str, Any][source]

Sanity check: rejects aggregated from core_done events must match rejects counted from accept events (reject_reason column).

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.build_param_registry(buckets: dict[str, list[dict[str, Any]]]) → dict[str, dict[str, float]][source]

Return {param_name: {range_min, range_max}} from the param_registry event.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.analyse_errors(df_error: DataFrame, df_retry: DataFrame, df_fatal: DataFrame) → dict[str, Any][source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_acceptance_vs_step(df_step: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_acceptance_per_chain(per_chain: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_acceptance_per_core(df_core: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_dlhood_hist(df_accept: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_gamma_dist(df_proposal: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_norms_evolution(df_proposal: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_gelmanrubin(df_conv: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_tz(df_conv: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_lhood_trajectories(df_chain_end: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_reasons(reasons: Counter, n_proposals: int, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_values_grid(values: dict[str, list[float]], counts: Counter, registry: dict[str, dict[str, float]], out: Path, topk: int = 6) → None[source]

For each of the top-K offending params, plot the histogram of proposed (rejected) values with vertical lines at range_min / range_max and an annotation showing how far outside the bounds the tail extends.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_value_overshoot(values: dict[str, list[float]], counts: Counter, registry: dict[str, dict[str, float]], out: Path, topk: int = 8) → None[source]

For each top-K offending param, plot a boxplot of the signed overshoot beyond the nearest bound, normalised by the prior range width. Positive values = overshoot above range_max; negative = undershoot below range_min. Scale: 1.0 = one full prior range past the bound.

GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_rate_per_step(df_per_step: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_rejects_by_reason_stacked(df_per_step: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_rejects_by_param_stacked(df_per_step: DataFrame, top_params: list[str], out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_vs_norm(per_step_merged: DataFrame, norm_col: str, corr: float | None, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_per_chain_heatmap(chain_param_df: DataFrame, out: Path, topk_params: int = 15) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_first_reject_step(df_first: DataFrame, out: Path, topk: int = 20) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_correlation(df_corr: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_overshoot_quantiles(df_sev: DataFrame, out: Path, topk: int = 15) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_reject_params_top(params: Counter, out: Path, topk: int = 15) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.plot_init_tentatives(df_init_done: DataFrame, out: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.run(log_path: Path, out_dir: Path) → None[source]
GUIBRUSHR.GUI.Input_Output_Panels.Input_Panels.TabPanels.Frame_Retrieval_Analysis.Tab_Analysis.FrameChainsAnalysis.analyze_retrieval_debug.main() → int[source]