Diagnostic Plotting
These functions visualize an existing fit result or a stored profile scan. plot_residuals and plot_diagnostics require a FitResult (x-y Gaussian fit); profile, contour, and profile-matrix plots accept scans from both FitResult and LikelihoodFitResult.
using ScientificFitting
using CairoMakieChoose A Figure
| Question | Function | Performs optimization? |
|---|---|---|
| Where does the model miss the data? | plot_residuals | no |
| Are residual, pull, and ratio views mutually consistent? | plot_diagnostics | no |
| Is one parameter locally parabolic? | plot_profile | no |
| Is a parameter pair described by a covariance ellipse? | plot_contour | no |
| Which parameters need closer inspection? | plot_profile_matrix | yes for a fit result; no for a stored matrix |
All functions accept theme=:sans or :tex, appearance=:auto (the default, currently resolving to :light), :light, or :dark, an optional theme_override, visual token overrides through the style keyword (FitPlotStyle), and the file output keywords filename and format.
Residuals, Pulls, And Ratios
plot_residuals(result; kind=:pull)
plot_diagnostics(result)Here $y_i$ is the measured value and $f_i$ the fitted model value at $x_i$.
kind | Displayed value | Reference line |
|---|---|---|
:residual | $y_i-f_i$ with available y errors | 0 |
:pull | weighted or whitened residual coordinate | 0 |
:ratio | $y_i/f_i$ with propagated y-error ratio | 1 |
With a non-diagonal covariance, whitened coordinates are not pointwise pulls in the original measurement order (Residuals And Pulls).
Beyond the shared output and style keywords, both functions accept xlabel, color, reference_color, marker, markersize, error_whiskerwidth, axis_kwargs, scatter_kwargs, and errorbars_kwargs; plot_diagnostics also accepts reference_line_kwargs.
One-Parameter Profiles
profile_result = profile(result, i)
plot_profile(profile_result; local_sigma=result.param_stderr[i])Profile and contour scans are produced by profile and contour (Results And Diagnostics).
| Concern | Keywords |
|---|---|
| Output and style | filename, format, theme, appearance, theme_override, style |
| Labels | title, xlabel, ylabel |
| Profile | line_color, line_width, profile_label, line_kwargs |
| Local parabola | local_sigma, local_color, local_linewidth, local_linestyle, local_label, local_line_kwargs |
| Threshold | threshold_color, threshold_label, threshold_kwargs |
| Layout | show_legend, legend_position, delta_max, axis_kwargs, legend_kwargs |
delta_max changes only the displayed range. The default legend occupies a row below the data axis; legend_position=:right selects a bounded side column.
Two-Parameter Contours
contour_result = contour(result, i, j)
plot_contour(
contour_result;
local_covariance=result.param_covariance,
local_center=result.params[[i, j]],
)| Concern | Keywords |
|---|---|
| Output and style | filename, format, theme, appearance, theme_override, style |
| Labels | title, xlabel, ylabel, axis_kwargs |
| Profile regions | show_regions, show_profile_lines, level_colors, region_colors, line_color, contour_kwargs |
| Optional heatmap | show_heatmap, colormap, heatmap_kwargs |
| Local covariance | local_covariance, local_center, local_line_color, local_linewidth, local_linestyle, local_contour_kwargs |
| Legend | show_legend, legend_position, legend_kwargs |
Filled regions are the default; the common two-parameter thresholds 2.30 and 6.18 are labeled as one- and two-sigma regions. The covariance approximation is drawn separately. A heatmap is opt-in.
Profile Matrices
matrix = profile_matrix(result; parameters=[1, 2, 3])
plot_profile_matrix(matrix; parameter_names=["A", "lambda", "offset"])plot_profile_matrix(result) computes the required profile and contour refits. Its scan controls are parameters, parameter_names, npoints_profile, npoints_contour, nsigma, profile_threshold, contour_levels, adaptive, max_refinements, and max_points.
Both methods accept filename, format, theme, appearance, theme_override, style, panel_status_mode, and delta_max; the matrix method additionally accepts parameter_names to replace display labels without recomputing the scans. panel_status_mode is :issues, :all, or :none and controls labels independently of visual style.
Failure Contract
| Invalid request | Result |
|---|---|
| CairoMakie extension not loaded | ArgumentError naming CairoMakie |
| Unsupported residual kind or non-finite coordinates | ArgumentError |
| Ratio with a zero/non-finite model prediction | ArgumentError |
Non-positive local_sigma or delta_max | DomainError |
| Incompatible local covariance or contour geometry | ArgumentError |
| Invalid profile-matrix status mode or display names | ArgumentError |
API Documentation
ScientificFitting.plot_residuals — Function
plot_residuals(result; kind=:pull, theme=:sans, kwargs...)Plot residuals, pulls, or data/fit ratios for a fitted model. kind is :residual (data minus fit), :pull (the whitened residuals; for uncorrelated uncertainties, each residual divided by its uncertainty), or :ratio (data divided by fit). Use this when the main fit plot looks plausible but the noise model or model structure needs inspection. xlabel, ylabel, and title replace the generic per-kind labels with the measured quantities. Marker and error-bar defaults follow the selected plot style; explicit Makie keyword containers override them.
ScientificFitting.plot_diagnostics — Function
plot_diagnostics(result; kwargs...)Create a residual, pull, and ratio diagnostic figure. All panels inherit the selected ScientificFitting style; scatter_kwargs, errorbars_kwargs, and reference_line_kwargs provide explicit Makie overrides.
ScientificFitting.plot_profile — Function
plot_profile(profile_result; kwargs...)Plot a one-parameter profile scan, including the fitted minimum, local parabolic approximation when available, and configured threshold levels. Profile, approximation, and threshold line styles can be overridden independently without rebuilding the scan. The descriptive legend defaults to a full-width row below the data axis; legend_position=:right is an explicit alternative.
ScientificFitting.plot_contour — Function
plot_contour(contour_result; kwargs...)Plot a two-parameter profile contour with labeled confidence regions and optional local covariance overlay. Use this to detect non-elliptic likelihood geometry or strong parameter correlations. The descriptive legend defaults to a full-width row below the data axis so long statistical labels cannot compress the contour.
ScientificFitting.plot_profile_matrix — Function
plot_profile_matrix(result; parameters=nothing, kwargs...)
plot_profile_matrix(matrix_result::ProfileMatrixResult; kwargs...)Create a kafe2/Minuit-style overview matrix: profile scans on the diagonal and pairwise contours below the diagonal. This is the quick diagnostic view for correlation, non-parabolicity, active bounds, and failed refits.
Pass a precomputed ProfileMatrixResult to render an existing Makie-free diagnostic object without repeating its profile and contour refits. The render method accepts parameter_names to replace display labels without recomputing the matrix.