Deborah.RebekahMiriam.HeatmapsRebekahMiriam

build_nlsolve_grids(
    nlsolve_status::Dict,
    labels::Vector{String},
    trains::Vector{String},
    solver_name::AbstractString;
    default_converged::Bool = false,
    default_residual::Float64 = NaN,
    default_iterations::Int = -1
) -> Tuple{Array{Bool,2}, Array{Float64,2}, Array{Int,2}}

Construct 2D grids of NLsolve.jl outcomes for a given solver_name, shaped as (length(labels), length(trains)) to match your heatmap conventions.

• conv_arr[i,j] is true if the solver converged for (labels[i], trains[j]).
• resn_arr[i,j] is the corresponding residual norm (Float64).
• iter_arr[i,j] is the number of iterations (Int).

If a cell is missing (no file, no solver section, or missing fields), the default_converged, default_residual, and default_iterations values are used.

collect_available_solvers(
    nlsolve_status::Dict
) -> Vector{String}

Return a sorted list of all solver names present within the nested nlsolve_status dictionary structure.

This function scans every (label, train) entry and collects the keys of each solver section (e.g., "Broyden", "TrustRegion", "Newton"), ensuring uniqueness and alphabetic order.

Typical usage:

available = collect_available_solvers(nlsolve_status)
println_benji(available)
# → ["Broyden", "Newton", "TrustRegion"]

Arguments

• nlsolve_status::Dict: Nested dictionary of NLsolve.jl results, where each

(label, train) cell contains a dictionary of solver names mapped to NamedTuples of outcome data.

Returns

• A sorted Vector{String} listing all solver names that appear in the given nlsolve_status dictionary.

overlay_nlsolve_marks!(
    ax,
    conv_arr::Array{Bool,2},
    iter_arr::Array{Int,2};
    iter_threshold::Int = 10,
    color::AbstractString = "white",
    lw::Real = 0.8,
    pad::Float64 = 0.48
) -> Nothing

Overlay per-cell convergence marks on an existing heatmap (typically the ERR panel in render_overlap_and_error_heatmaps).

For each cell (i,j) this function draws:

• a red X if the corresponding NLsolve.jl call did not converge, and
• a single diagonal segment (top-right → bottom-left) if it converged but required at least iter_threshold iterations.

Cells that converged with fewer than iter_threshold iterations are left unmarked.

The coordinates are assumed to match the usual imshow/text convention used in render_overlap_and_error_heatmaps, i.e. cell centers located at (j-1, i-1).

Arguments

• ax: PyPlot axes object on which to draw the marks. This should be the same axis that already displays the heatmap (e.g., the ERR panel).
• conv_arr::Array{Bool,2}: Boolean matrix encoding NLsolve.jl convergence status:
  • true → solver converged,
  • false → solver failed to converge.
• iter_arr::Array{Int,2}: Integer matrix with the same shape as conv_arr, holding the number of iterations used for each solve.

Keyword Arguments

• iter_threshold::Int = 10: Minimum iteration count to trigger a “slow convergence” mark. Cells with conv_arr[i,j] == true and iter_arr[i,j] ≥ iter_threshold receive a single diagonal segment.
• color::AbstractString = "white": Color of the diagonal mark used for “slow but converged” cells.
• lw::Real = 0.8: Line width for both X-marks and diagonal segments.
• pad::Float64 = 0.48: Half-length of each line segment inside a cell. The segment endpoints are placed at (cx ± pad, cy ± pad) where (cx, cy) = (j-1, i-1) is the cell center.

Behavior

• For !conv_arr[i,j]:
  • Draw two red diagonals across the cell, forming an X.
• For conv_arr[i,j] && iter_arr[i,j] ≥ iter_threshold:
  • Draw a single diagonal (top-right → bottom-left) in color.
• For other cells:
  • No overlay is drawn.

Returns

• Nothing (modifies ax in place as a side effect).

Notes

• This function assumes that the heatmap pixels align with integer grid cells as in imshow(...; origin="lower") with tick/label logic matching render_overlap_and_error_heatmaps.
• For best visibility, call overlay_nlsolve_marks! after rendering the base heatmap but before calling tight_layout/savefig, so that marks are included in the final layout.

render_bhattacharyya_heatmap(
    bc_arr::Array{Float64, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    key::Symbol,
    pred_tag::Symbol,
    keyword::String,
    overall_name::String,
    figs_dir::String;
    key_tex::String = "",
    save_file::Bool = false,
    annotate::Bool = true,
    cmap_name::String = "viridis",
    levels::Vector{Float64} = [0.6, 0.8, 0.9],
    draw_contours::Bool = true
) -> Nothing

Render a single heatmap for the Bhattacharyya coefficient ($\mathrm{BC}$ in $[0,1]$) for a given observable, method, and interpolation origin (keyword).

• Colormap spans 0.0 (worst) to 1.0 (best).
• Optional numeric annotations per cell.
• Optional contour lines at given levels.

Arguments

• bc_arr::Array{Float64,2}: $\mathrm{BC}$ matrix in $[0,1]$.
• N_lb_arr::Vector{Int} : $y$-axis tick labels (LBP $\%$).
• N_tr_arr::Vector{Int} : $x$-axis tick labels (TRP $\%$).
• key::Symbol : Observable symbol (e.g., :kurt, :cond).
• pred_tag::Symbol : Prediction method (e.g., :RWP1, :RWP2).
• keyword::String : Interpolation origin cumulant identifier (e.g., "skew", "kurt").
• overall_name::String : Suffix used in the output filename.
• figs_dir::String : Output directory to save the figure.

Keywords

• key_tex::String="" : $\LaTeX$ label for $y$-axis title part.
• save_file::Bool=false : If true, saves a cropped PDF into figs_dir.
• annotate::Bool=true : Print $\mathrm{BC}$ values in each cell.
• cmap_name::String="viridis" : Matplotlib colormap name.
• levels::Vector{Float64}=[0.6,0.8,0.9] : Contour levels for $\mathrm{BC}$.
• draw_contours::Bool=true : Draw contour overlays if true.

Side Effects

• Displays the formatted figure.
• If save_file=true, writes heatmap_bc_<key>_<keyword>_<pred_tag>_<overall_name>.pdf to figs_dir.

render_bhattacharyya_heatmap_for_measurements(
    bc_arr::Array{Float64, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    key::Symbol,
    pred_tag::Symbol,
    keyword::String,
    overall_name::String,
    figs_dir::String;
    key_tex::String = "",
    save_file::Bool = false,
    annotate::Bool = true,
    cmap_name::String = "viridis",
    levels::Vector{Float64} = [0.6, 0.8, 0.9],
    draw_contours::Bool = true
) -> Nothing

Render a single-panel heatmap of the Bhattacharyya coefficient ($\mathrm{BC}$ in $[0,1]$) for a measurement-based evaluation at a fixed $\kappa$ for single ensemble.

• Title shows the kappa token as $\kappa = \texttt{0.<keyword>}$.
• Colormap fixed to $[0,1]$ across figures for comparability.
• Optional per-cell annotations and contour overlays.

Arguments

• bc_arr::Array{Float64,2} : $\mathrm{BC}$ matrix (LB $\times$ TR grid), values expected in $[0,1]$.
• N_lb_arr::Vector{Int} : $y$-axis tick labels (LB percentages).
• N_tr_arr::Vector{Int} : $x$-axis tick labels (TR percentages).
• key::Symbol : Observable (e.g., :trM1, :Q2).
• pred_tag::Symbol : Method/tag (e.g., :T_P1, :Q_P2).
• keyword::String : $\kappa$ token (e.g., "13580") rendered as "$\kappa = \texttt{0.<keyword>}$".
• overall_name::String : Suffix for output file.
• figs_dir::String : Output directory.

Keywords

• key_tex::String="" : Optional $\LaTeX$ label for $y$-axis/title left part.
• save_file::Bool=false : If true, saves/crops PDF.
• annotate::Bool=true : Print numeric $\mathrm{BC}$ per cell.
• cmap_name::String="viridis" : Matplotlib colormap name.
• levels::Vector{Float64}=[0.6,0.8,0.9] : Contour levels.
• draw_contours::Bool=true : Draw contour overlays.

Side Effects

• Displays the figure.
• If save_file=true, writes heatmap_bc_<key>_<keyword>_<pred_tag>_<overall_name>.pdf.

render_jsd_heatmap(
    jsd_arr::Array{Float64, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    key::Symbol,
    pred_tag::Symbol,
    keyword::String,
    overall_name::String,
    figs_dir::String;
    key_tex::String = "",
    save_file::Bool = false,
    annotate::Bool = true,
    cmap_name::String = "bwr",
    levels::Vector{Float64} = [0.2, 0.4, 0.6, 0.8],
    draw_contours::Bool = false
) -> Nothing

Render a single heatmap for the Jensen-Shannon divergence ($\mathrm{JSD}$ in $[0,1]$) for a given observable, method, and interpolation origin (keyword).

• Lower is better (0 = identical, 1 = worst).
• Colormap spans 0.0 to 1.0.
• Optional numeric annotations per cell.
• Optional contour lines at given levels.

Arguments

• jsd_arr::Array{Float64,2}: $\mathrm{JSD}$ matrix in $[0,1]$.
• N_lb_arr::Vector{Int} : $y$-axis tick labels (LBP $\%$).
• N_tr_arr::Vector{Int} : $x$-axis tick labels (TRP $\%$).
• key::Symbol : Observable (e.g., :kurt, :cond).
• pred_tag::Symbol : Prediction method (e.g., :RWP1, :RWP2).
• keyword::String : Interpolation origin cumulant identifier (e.g., "skew", "kurt").
• overall_name::String : Suffix used in the output filename.
• figs_dir::String : Output directory to save the figure.

Keywords

• key_tex::String="" : $\LaTeX$ label for y-axis title part.
• save_file::Bool=false : If true, saves a cropped PDF into figs_dir.
• annotate::Bool=true : Print $\mathrm{JSD}$ values in each cell.
• cmap_name::String="bwr" : Matplotlib colormap (default mirrors your BC function).
• levels::Vector{Float64}=[0.2,0.4,0.6,0.8] : Contour levels for $\mathrm{JSD}$.
• draw_contours::Bool=false : Draw contour overlays if true.

Side Effects

• Displays the formatted figure.
• If save_file=true, writes heatmap_jsd_<key>_<keyword>_<pred_tag>_<overall_name>.pdf to figs_dir.

render_jsd_heatmap_for_measurements(
    jsd_arr::Array{Float64, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    key::Symbol,
    pred_tag::Symbol,
    keyword::String,
    overall_name::String,
    figs_dir::String;
    key_tex::String = "",
    save_file::Bool = false,
    annotate::Bool = true,
    cmap_name::String = "viridis",
    levels::Vector{Float64} = [0.2, 0.4, 0.6, 0.8],
    draw_contours::Bool = true
) -> Nothing

Render a single-panel heatmap of the Jensen-Shannon divergence ($\mathrm{JSD}$ in $[0,1]$) for a measurement-based evaluation at a fixed κ (no interpolation).

• Title shows the kappa token as "$\kappa = \texttt{0.<keyword>}$".
• Lower is better (0 = identical, 1 = worst).
• Colormap fixed to [0,1] across figures for comparability.
• Optional per-cell annotations and contour overlays.

Arguments

• jsd_arr::Array{Float64,2} : $\mathrm{JSD}$ matrix (LB $\times$ TR grid) in $[0,1]$.
• N_lb_arr::Vector{Int} : $y$-axis tick labels (LB percentages).
• N_tr_arr::Vector{Int} : $x$-axis tick labels (TR percentages).
• key::Symbol : Observable (e.g., :trM1, :Q2).
• pred_tag::Symbol : Method/tag (e.g., :T_P1, :Q_P2).
• keyword::String : $\kappa$ token (e.g., "13580") rendered as "$\kappa = \texttt{0.<keyword>}$".
• overall_name::String : Suffix for output file.
• figs_dir::String : Output directory.

Keywords

• key_tex::String="" : Optional $\LaTeX$ label for $y$-axis/title left part.
• save_file::Bool=false : If true, saves/crops PDF.
• annotate::Bool=true : Print numeric $\mathrm{JSD}$ per cell.
• cmap_name::String="viridis" : Matplotlib colormap name.
• levels::Vector{Float64}=[0.2,0.4,0.6,0.8] : Contour levels.
• draw_contours::Bool=true : Draw contour overlays.

Side Effects

• Displays the figure.
• If save_file=true, writes heatmap_jsd_<key>_<keyword>_<pred_tag>_<overall_name>.pdf.

render_nlsolve_convergence_heatmap(
    conv_arr::Array{Bool, 2},
    resn_arr::Array{Float64, 2},
    iter_arr::Array{Int, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    solver_name::AbstractString,
    overall_name::AbstractString,
    figs_dir::AbstractString;
    save_file::Bool = false,
    show_all_residuals::Bool = false,
    iter_threshold::Int = 10
) -> Nothing

Render an NLsolve.jl convergence heatmap across labeled (LBP) and training (TRP) percentage grids.

Visualization rules:

• Cell color encodes convergence: white (true) vs black (false).
• Residual norms are printed in white text on failed (black) cells. When show_all_residuals=true, residuals are printed on all cells (in white), remaining invisible on white cells by design.
• If a cell converged and iterations ≥ iter_threshold, the iteration count is annotated in black text inside the white cell.

Arguments

• conv_arr: Boolean matrix of convergence results.
• resn_arr: Matrix of residual norms, same shape as conv_arr.
• iter_arr: Matrix of iteration counts, same shape as conv_arr.
• N_lb_arr, N_tr_arr: Axis tick values for LBP% ($y$) and TRP% ($x$).
• solver_name: Solver identifier (e.g., "nlsolve_f_solver_FULL-LBOG-ULOG").
• overall_name: Suffix used in the output filename.
• figs_dir: Directory to save the figure.

Keywords

• save_file: If true, saves as PDF and crops with pdfcrop if available.
• show_all_residuals: If true, prints residuals on all cells; otherwise only on failed cells.
• iter_threshold: Minimum iteration count that triggers iteration annotation on converged cells.

Returns

Nothing. Displays (and optionally saves) the rendered heatmap.

render_overlap_and_error_heatmaps(
    chk_arr::Array{Int, 2},
    err_arr::Array{Float64, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    key::Symbol,
    pred_tag::Symbol,
    keyword::String,
    overall_name::String,
    figs_dir::String;
    key_tex::String = "",
    save_file::Bool = false
) -> Nothing

Render CHK and ERR heatmaps for a specific observable, method, and interpolation origin.

This function displays two side-by-side heatmaps using PyPlot.jl:

• Left: CHK matrix (categorical values 0, 1, 2 rendered as black-gray-white).
• Right: ERR matrix (real-valued error ratios with color scale from 1.0 to 7.0). Values outside this range are explicitly labeled on the plot.

Each heatmap uses N_lb_arr (labeled set percentages) on the $y$-axis and N_tr_arr (training set percentages) on the $x$-axis. Axis ticks are $\LaTeX$-formatted, and colorbars are included for both subplots.

The title of the CHK panel reflects the observable key and the interpolation origin keyword.

Arguments

• chk_arr::Array{Int,2}: Matrix of overlap quality indicators (0, 1, or 2).
• err_arr::Array{Float64,2}: Matrix of error ratios for the same grid.
• N_lb_arr::Vector{Int}: Labeled set percentage values for $y$-axis ticks.
• N_tr_arr::Vector{Int}: Training set percentage values for $x$-axis ticks.
• key::Symbol: Target observable being evaluated (e.g., :kurt, :cond).
• pred_tag::Symbol: Identifier for the prediction method (e.g., :RWP1, :RWP2).
• keyword::String: Indicates the origin cumulant used to determine the interpolation point. For example, "skew" or "kurt" means that the interpolation target $\kappa_t$ was selected based on the behavior of the skewness or kurtosis, respectively. Once $\kappa_t$ is determined using this origin cumulant, a different cumulant–such as the condensate—may be evaluated at that same point. In other words, keyword identifies which cumulant guided the interpolation, even though the reported result may pertain to a different observable.
• overall_name::String: Suffix string used for naming the saved figure.
• figs_dir::String: Directory to save the output figure.

Keyword Arguments

• key_tex::String = "": Optional $\LaTeX$ string for labeling the CHK subplot.
• save_file::Bool = false: If true, saves the figure as a PDF and crops it using pdfcrop if available.

Side Effects

• Displays a formatted figure using PyPlot.jl.
• If save_file=true, writes heatmap_<key>_<keyword>_<pred_tag>_<overall_name>.pdf to figs_dir.

render_overlap_and_error_heatmaps_for_measurements(
    chk_arr::Array{Int, 2},
    err_arr::Array{Float64, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    key::Symbol,
    pred_tag::Symbol,
    keyword::String,
    overall_name::String,
    figs_dir::String;
    key_tex::String = "",
    save_file::Bool = false
) -> Nothing

Render CHK and ERR heatmaps for a measurement-based evaluation at a fixed $\kappa$ at the single ensemble.

This variant mirrors render_overlap_and_error_heatmaps but interprets keyword as a kappa token string (e.g., "13580"). The CHK panel title displays this as $\kappa = \texttt{0.<keyword>}$ (e.g., $\kappa = 0.13580$), indicating that both CHK and ERR are evaluated at that specific measurement point.

Two side-by-side heatmaps are produced using PyPlot.jl:

• Left: CHK matrix (categorical values 0, 1, 2 rendered as black-gray-white).
• Right: ERR matrix (error ratios) with a color scale from 1.0 to 7.0. Values are overlaid as text for readability.

Axes:

• $y$-axis: N_lb_arr (labeled-set percentages),
• $x$-axis: N_tr_arr (training-set percentages).

Both subplots include ticks and colorbars.

Arguments

• chk_arr::Array{Int,2}: Overlap quality map (0, 1, 2) on the (LB, TR) grid.
• err_arr::Array{Float64,2}: Error-ratio map on the same grid.
• N_lb_arr::Vector{Int}: $y$-axis tick values (LB percentages).
• N_tr_arr::Vector{Int}: $x$-axis tick values (TR percentages).
• key::Symbol: Observable being plotted (e.g., :trM1, :Q2).
• pred_tag::Symbol: Method/tag being visualized (e.g., :T_P1, :Q_P2).
• keyword::String: $\kappa$ token (e.g., "13580") used for lookup in summaries and rendered as "$\kappa = \texttt{0.<keyword>}$".
• overall_name::String: Suffix used in the output filename.
• figs_dir::String: Directory to write the figure file.

Keyword Arguments

• key_tex::String = "": Optional $\LaTeX$ label for the CHK subplot (e.g., pretty-printed observable name).
• save_file::Bool = false: If true, saves heatmap_<key>_<keyword>_<pred_tag>_<overall_name>.pdf to figs_dir and, if available, crops it with pdfcrop.

Side Effects

• Displays the figure via PyPlot.jl.
• Optionally writes a cropped PDF to disk when save_file=true.

Notes

• This function is intended for the measurement pipeline where results are indexed by discrete $\kappa$ values of single ensemble Ensure that keyword matches the kappa token used in the summary dictionaries (e.g., "13580").
• Color scale for ERR is fixed to [1.0, 7.0]; text annotations show the numeric values inside cells.

render_overlap_type_b_and_error_heatmaps(
    ovl_arr::Array{Float64, 2},
    err_arr::Array{Float64, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    key::Symbol,
    pred_tag::Symbol,
    keyword::String,
    overall_name::String,
    figs_dir::String;
    key_tex::String = "",
    save_file::Bool = false,
    vmax_ovl::Float64 = 3.0
) -> Nothing

Render Type-B distance (ovl_arr) and ERR heatmaps for a specific observable, method, and interpolation origin.

Left panel visualizes the Type-B distance (continuous) defined as

\[d = \frac{\lvert \mu_{\text{orig}} - \mu_{\text{pred}} \rvert}{\max(\sigma_{\text{orig}}, \sigma_{\text{floor}})}.\]

Color map is tuned so that:

• $d = 0$ → white,
• $d \approx 1$ → vivid color (attention threshold),
• $1 - \texttt{vmax\_ovl}$ → smoothly intensifying,
• $d > \texttt{vmax\_ovl}$ → shown with an extended colorbar (triangle) yet numbers are still annotated.

Right panel is the same ERR heatmap as before ($[1.0,7.0]$ by default).

Both panels place N_lb_arr on the y-axis and N_tr_arr on the x-axis. Cell values are annotated.

Arguments

• ovl_arr: Type-B distance matrix (Float64).
• err_arr: Error-ratio matrix (Float64).
• N_lb_arr, N_tr_arr: Percent tick lists for $y$/$x$ axes.
• key, pred_tag, keyword: Labels for titles/filenames.
• overall_name, figs_dir: Suffix and output directory.

Keywords

• key_tex: Optional $\LaTeX$ label for the left subplot title.
• save_file: If true, save PDF and crop via pdfcrop if available.
• vmax_ovl: Upper bound for Type-B color scaling (default 3.0).

Side Effects

• Displays a figure via PyPlot.jl.
• If save_file=true, writes heatmap_typeB_<key>_<keyword>_<pred_tag>_<overall_name>.pdf.

render_overlap_type_b_and_error_heatmaps_for_measurements(
    ovl_arr::Array{Float64, 2},
    err_arr::Array{Float64, 2},
    N_lb_arr::Vector{Int},
    N_tr_arr::Vector{Int},
    key::Symbol,
    pred_tag::Symbol,
    keyword::String,
    overall_name::String,
    figs_dir::String;
    key_tex::String = "",
    save_file::Bool = false,
    vmax_ovl::Float64 = 3.0
) -> Nothing

Render Type-B distance (ovl_arr) and ERR heatmaps for a measurement-based evaluation at a fixed $\kappa$ within a single ensemble.

This mirrors render_overlap_and_error_heatmaps_for_measurements but uses a continuous Type-B metric on the left panel:

\[d \equiv \frac{|\mu_{\text{orig}} - \mu_{\text{pred}}|} {\max(\sigma_{\text{orig}}, \sigma_{\text{floor}})}.\]

Color mapping is tuned for rapid visual assessment:

• $d = 0$ → white,
• $d \approx 1$ → vivid color (attention threshold),
• $1 - \texttt{vmax\_ovl}$ → smoothly intensifying,
• $d > \texttt{vmax\_ovl}$ → shown via extended colorbar (triangle), with numeric annotations retained.

The title shows the kappa token as $\kappa = \texttt{0.<keyword>}$ (e.g., 0.13580).

Arguments

• ovl_arr: Type-B distance matrix (Float64) on the (LB, TR) grid.
• err_arr: Error-ratio matrix (Float64) on the same grid.
• N_lb_arr, N_tr_arr: Percent tick lists for $y$/$x$ axes.
• key, pred_tag: Observable/method labels.
• keyword: Kappa token string (e.g., "13580") rendered as $\kappa = \texttt{0.<keyword>}$.
• overall_name, figs_dir: Suffix and output directory for the saved figure.

Keywords

• key_tex: Optional \LaTeX label prefix for the left subplot title.
• save_file: If true, saves heatmap_typeB_<key>_<keyword>_<pred_tag>_<overall_name>.pdf and crops with pdfcrop if available.
• vmax_ovl: Upper bound for Type-B color scaling (default 3.0).

Side Effects

• Displays the figure via PyPlot.jl; optionally writes a cropped PDF.

Notes

• Designed for the measurement pipeline where results are indexed by discrete $\kappa$ values.
• The ERR panel uses the fixed range $[1.0, 7.0]$ with per-cell numeric overlays.

sci_round(
    x::Real
) -> String

Convert a floating-point number x into a simplified scientific-notation string without any fractional part in the mantissa.

The mantissa is rounded to the nearest integer and followed by the exponent in $\texttt{e} \pm \texttt{n}$ format. This produces compact expressions like "2e-13" instead of "2.1e-13" or "1.0e-13".

• If x = 2.1e-13, returns "2e-13".
• If x = 3.5e-13, returns "4e-13".
• If x = -9.8e5, returns "-1e+6".
• If x = 0, returns "0".

Returns

A String representing the integer-rounded scientific notation of x.