Results And Diagnostics

predict(result::FitResult, x=result.problem.x; uncertainty=false)

Evaluate the fitted model on finite 1D coordinates x, without a plotting backend. With uncertainty=true, return (mean, sigma), where sigma is the local standard uncertainty of the fitted mean: sqrt(diag(J * Cov(p) * J')). It excludes new-observation noise and is not a predictive interval for future measurements. Nonlinear/asymmetric uncertainty may require profile inference.

The model Jacobian follows result.problem.derivatives; an explicitly supplied analytic Jacobian takes precedence. Invalid local covariance raises an error instead of silently drawing a zero-width band.

FitResult

Result of a Gaussian/least-squares style fit. It stores the normalized FitProblem, solver options and status, fitted parameters, local covariance and correlation estimates, fitted model values, residuals, weighted residuals, the residual Jacobian, statistics, and diagnostics.

residuals is y - model_y (data minus model). weighted_residuals is the whitened residual vector: the data block is W * (y - model_y) with W'W = inv(C) for the observation covariance C, followed by one appended entry per parameter prior and per parameter-constraint component, so its length can exceed length(y). For a non-diagonal covariance the data-block entries depend on the whitening factorization and are not per-point pulls. jacobian is the Jacobian of weighted_residuals with respect to the full parameter vector, evaluated at params: the residual Jacobian, not the model Jacobian supplied via the jacobian keyword. For a parameter-independent covariance its data rows equal -W * dmodel/dp; with parameter-dependent covariance it also differentiates through the whitening.

The parameter covariance is a local quadratic approximation. For nonlinear models, active bounds, weak data, or asymmetric likelihoods, inspect profile(...) or contour(...) before treating symmetric errors as final. backend records which solver path produced the result. iterations is missing when a backend does not expose an iteration count; ScientificFitting never substitutes the configured iteration limit for an unknown value. solver_result retains FitSolverResult for fits solved through the generic scalar-objective solver interface, including native status and the free-to-full parameter map. It is nothing for the specialized LsqFit path and when every parameter is fixed.

LikelihoodFitResult

Result of a likelihood or custom-objective fit. It mirrors the parameter, covariance, statistics, and diagnostics fields of FitResult, but stores a LikelihoodFitProblem instead of x-y residual data. plot_fit, plot_residuals, and plot_diagnostics require the x-y data of a FitResult and do not accept a LikelihoodFitResult; the profile-based plots (plot_profile, plot_contour, plot_profile_matrix) remain available.

iterations is missing when the selected optimizer does not expose an iteration count. solver_result retains the FitSolverResult and its native details; it is nothing when every parameter is fixed. Native solver coordinates follow solver_result.parameter_indices, not necessarily the full model vector.

FitStatistics

Goodness-of-fit and information-criterion summary for a fit. cost names the resolved objective and cost_min is its minimized value. ndf is the number of observations (data points plus parameter-prior and parameter-constraint terms) minus the number of free parameters. pvalue is the upper-tail probability of chi2 under a chi-square distribution with ndf degrees of freedom. minus2loglik_min, AIC, and BIC have their standard likelihood interpretation only when the objective uses a consistently normalized -2 log(L) convention; a custom loss may provide only arithmetic summaries. chi2, chi2_ndf, and pvalue are NaN when no chi-square-like goodness-of-fit statistic exists.

FitDiagnostics

Numerical and statistical diagnostics stored with every fit result. It contains covariance/Hessian condition numbers, active-bound indices, and structured DiagnosticFindings used by diagnose and diagnostic plots.

profile(result, index; values=nothing, npoints=61, nsigma=3,
        threshold=1.0, adaptive=false, max_refinements=3,
        max_points=241, on_failure=:inf)

Profile the fitted cost function in one parameter by fixing that parameter to grid values and re-minimizing all remaining free parameters.

The automatic grid intersects best_value +/- nsigma * result.param_stderr[index] with the parameter bounds. Without a positive finite standard error, the substitute scale 0.1 * max(abs(best_value), 1) replaces it, so the scan spans +/- nsigma times that heuristic scale: a search range, not an uncertainty. Use explicit values for scientifically chosen ranges. Explicit values are not clipped: infeasible points still follow on_failure. A bound is not substituted for a missing threshold crossing.

threshold is the delta-cost value targeted by adaptive refinement and recorded in the result; it does not affect a plain grid scan.

With adaptive=true, ScientificFitting refines grid intervals that bracket the requested profile threshold. This improves interval extraction without forcing a dense grid over the full scan range. max_refinements bounds the number of refinement rounds and max_points caps the total number of grid points. on_failure=:inf records failed refits as infinite cost so diagnostics can expose them; :throw stops at the first failure.

Returns a ProfileResult.

profile_interval(result, index; threshold=1.0, npoints=121, nsigma=5,
                 values=nothing, adaptive=true, max_refinements=3,
                 max_points=241)
profile_interval(profile_result::ProfileResult)

Compute a profile-based asymmetric interval by finding the profile-cost crossings at delta_cost = threshold. For one parameter, threshold = 1 gives the asymptotic 68.27% (1-sigma) interval; use threshold = n^2 for an n-sigma interval (for example 4 for 2 sigma). Explicit values replace the automatic nsigma range. A crossing that is not bracketed is returned as NaN; inspect diagnose(interval.profile_result) before reporting the interval.

The ProfileResult method extracts threshold crossings from an existing scan without running more fits; the best value and threshold are those stored in the scan. A failed grid point stops that side's search; crossings are never interpolated across gaps.

Returns a ProfileInterval.

contour(result, i, j; xvalues=nothing, yvalues=nothing, npoints=31,
        nsigma=3, levels=[2.30, 6.18], adaptive=false,
        max_refinements=2, max_points=2601, on_failure=:inf)

Compute a two-parameter profile-likelihood contour grid. At each grid point, parameters i and j are fixed and all remaining free parameters are re-minimized.

levels are thresholds on the scaled delta_cost (the same scale convention as ProfileResult). The defaults 2.30 and 6.18 are the chi-square quantiles for 2 degrees of freedom, enclosing asymptotic 68.27% and 95.45% joint confidence for the parameter pair; they are the two-parameter analogues of the one-parameter delta_cost = 1 and 4 cuts. See the Profiles And Contours section of the statistics reference.

Automatic axes respect parameter bounds, as in profile. Explicit xvalues and yvalues remain unchanged, including infeasible points.

With adaptive=true, ScientificFitting refines grid cells whose corner values bracket a requested contour level. This concentrates expensive refits near meaningful contour geometry instead of spreading them uniformly across the full rectangle. max_refinements bounds the number of refinement rounds and max_points caps the total number of grid cells (x-axis points times y-axis points). on_failure=:inf preserves failed cells for diagnostics; :throw stops at the first failed refit.

Returns a ContourResult.

profile_matrix(result; parameters=nothing, parameter_names=nothing,
               npoints_profile=61, npoints_contour=25, nsigma=3,
               profile_threshold=1.0, contour_levels=[2.30, 6.18],
               adaptive=false, max_refinements=2, max_points=1200,
               profile_tolerance=0.25, contour_tolerance=0.5)

Compute a multi-parameter profile/contour diagnostic matrix without loading Makie. Diagonal entries are one-parameter profile scans; lower-triangle entries are two-parameter profile contours. Each panel is diagnosed against the local covariance approximation when local errors or covariance entries are finite. Without local errors, grids use profile's heuristic scale; for controlled ranges, compute individual profiles/contours with explicit grid values.

contour_levels follows the same convention as contour; the defaults mark the asymptotic 68.27% and 95.45% two-parameter regions. max_points caps each panel's refined grid: the number of scan points for a profile, the total number of grid cells for a contour. profile_tolerance and contour_tolerance are the maximum allowed delta-cost deviations from the local parabola/ellipse before a panel is flagged; see diagnose.

Use this when a fit has several correlated or nonlinear parameters and you need a quick, machine-readable answer to: "Are local symmetric covariance errors enough, or do I need profile/contour intervals?"

ProfileResult

One-dimensional profile scan of the fitted cost function. values are the fixed parameter values, cost_values are the raw refitted objective values, and delta_cost is measured relative to the original fit minimum. When the fit applied scale_covariance (chi2/ndf) scaling, delta_cost is divided by that same factor, so threshold=1 always marks the one-sigma cut consistent with param_stderr. The threshold field records the interval threshold requested by profile. parameter_index is the index of the profiled parameter in the fit's parameter vector; best_value is that parameter's value at the fit minimum.

ProfileInterval

Asymmetric interval extracted from a ProfileResult. lower and upper are the threshold crossings; uncertainty_minus = best_value - lower and uncertainty_plus = upper - best_value are both non-negative distances from the best-fit parameter value. Non-finite fields indicate that the scan did not bracket the requested threshold. parameter_index is the profiled parameter's index, threshold repeats the delta-cost threshold of the scan, and profile_result stores the underlying ProfileResult (use it with diagnose).

ContourResult

Two-parameter profile-contour scan. x_values and y_values define the scan grid for parameter_indices; delta_cost stores the refitted cost increase relative to the best fit, divided by the fit's applied covariance scale (the same convention as ProfileResult), and levels stores the requested contour thresholds (delta-cost levels; see contour). cost_values holds the raw refitted objective values on the same grid. Both matrices are indexed [ix, iy]: rows follow x_values, columns follow y_values.

ProfileMatrixResult

Makie-free diagnostic overview for several fitted parameters. It stores the one-parameter profiles, pairwise contours, per-panel diagnostic reports, the best values, local standard errors, and local covariance/correlation submatrix of the selected parameters, and a combined diagnostic report. Plotting is intentionally separate: plot_profile_matrix(matrix_result) renders this object without repeating any profile or contour refits. Contour and status keys are parameter-index pairs (i, j) with i the x-axis parameter and j the y-axis parameter, i preceding j in parameters; diagonal profile panels use (i, i). panel_status maps each key to :ok, :review, or :stop.

DiagnosticFinding

One structured diagnostic issue or note. Each finding has a severity (:info, :warning, or :critical), a stable machine-readable code, reader-facing title, concrete evidence, and a recommended next action.

DiagnosticReport

Structured diagnostic report returned by diagnose(result). It keeps the full list of findings plus a short summary suitable for notebook output or a lab log. Use diagnose_text(report) for a plain-text representation.

DiagnosticDashboard

Summary returned by diagnostic_dashboard(...): the underlying report, an overall status (:ok, :review, or :stop), per-severity finding counts, and deduplicated recommended next actions.

diagnose(result)

Return a DiagnosticReport for a fit result. Each finding carries a severity, a code, numeric evidence, and a recommended action; the report's summary reflects only the checks that ran.

For a FitResult, the report combines the findings recorded at fit time with parameter-correlation, goodness-of-fit, and residual-pattern checks (largest pull against a Bonferroni limit, a sign-runs test, and lag-1 autocorrelation). For any other result with a diagnostics field, such as a LikelihoodFitResult, the residual-pattern checks are omitted because there are no x-y residuals; the correlation check runs only when the result has a param_correlation field, and the goodness-of-fit checks only when its stats is a FitStatistics. A result without a diagnostics field throws an ArgumentError.

diagnose(profile_result::ProfileResult; local_sigma=nothing, tolerance=0.25)
diagnose(contour_result::ContourResult; local_covariance=nothing,
         local_center=nothing, tolerance=0.5)
diagnose(matrix_result::ProfileMatrixResult)

Diagnose already computed profile and contour scans. With local_sigma, a one-parameter profile is compared to the local covariance parabola; with local_covariance, a two-parameter contour grid is compared to the local covariance ellipse used by symmetric Gaussian error propagation. This is the machine-readable counterpart of overlaying both curves in plot_profile or plot_contour.

local_sigma is the parameter's local standard error (result.param_stderr[index]). tolerance is the maximum allowed absolute deviation, in delta-cost units, between the scan and the local parabola ((value - best_value) / local_sigma)^2 (or the local covariance ellipse) near the minimum before :profile_not_parabolic or :contour_not_elliptic is reported. local_center is the ellipse center; it defaults to the scanned grid minimum.

diagnose(matrix_result) returns the combined report precomputed by profile_matrix without new refits. Each method returns a DiagnosticReport.

diagnose_text(report::DiagnosticReport)
diagnose_text(result)

Render structured diagnostics as plain text. Passing a fit result first calls diagnose(result). Use this for terminal output, notebook logs, and documentation snapshots where Makie should not be required.

diagnostic_dashboard(result_or_report; max_actions=5)

Create a compact dashboard from diagnose(...) findings. The dashboard does not add new statistical tests; it summarizes the current findings into a lab workflow status and prioritized next actions. max_actions limits the number of prioritized next actions; duplicate recommendations are dropped and higher severities come first.

The status field of the returned dashboard is:

• :ok: no current warnings or critical findings,
• :review: warnings exist and should be inspected before using the result,
• :stop: at least one critical finding exists and must be fixed before the result is used for conclusions.

diagnostic_dashboard_text(dashboard::DiagnosticDashboard)
diagnostic_dashboard_text(result; max_actions=5)

Render a compact diagnostic dashboard as plain text. The output contains an overall status, severity counts, and prioritized next actions. max_actions is forwarded to diagnostic_dashboard.

ParameterEstimate

One fitted parameter as stored in a FitReport. It records the public name, best-fit value, symmetric display uncertainty, asymmetric lower/upper uncertainties when available, and whether the parameter was fixed rather than fitted. index is the position in the fit's parameter vector. For a fixed parameter, the uncertainties are the user-declared values from FixedParameter, not fit results.

FitReport

Serializable summary returned by fit_report(result). It separates parameter estimates, statistics, covariance/correlation matrices, solver status, and diagnostics from the full fit object so reports can be printed, tested, or exported without depending on Makie.

fit_report(result; parameter_names=nothing, errors=:local,
           profile_threshold=1.0, profile_npoints=121,
           profile_nsigma=5)

Return an extractable report object for a fit result. Parameters are available as report.parameters[i].value and report.parameters[i].uncertainty. report.statistics has cost, cost_min, minus2loglik_min, chi2, chi2_ndf, ndf, pvalue, aic, and bic.

Use errors=:profile to compute profile-based asymmetric uncertainties. This re-runs fits and can be expensive. The keywords map to profile_interval's threshold, npoints, and nsigma: profile_threshold is the delta-cost level whose crossings define the interval, on the scale where 1.0 is the one-sigma (68.3%) cut consistent with param_stderr (use k^2 for a k-sigma interval); profile_npoints sets the scan grid size per parameter; profile_nsigma sets the scan half-width in units of the local standard error. All three are ignored for errors=:local. A side where the scan does not cross the threshold within its range stays NaN; it is never silently replaced with the local symmetric error.

report_text(report::FitReport; sigdigits=6)
report_text(result; parameter_names=nothing, sigdigits=6, kwargs...)

Render a FitReport or fit result as plain text. The result method first calls fit_report, so keyword arguments such as errors=:profile are forwarded to the report builder.

Parameter lines round to the uncertainty: the error keeps two significant digits and the value is cut at the same decimal place (15.56 +/- 0.11). The result panels of the plot functions follow the same rule. sigdigits controls the statistics lines, and parameter lines fall back to it when the uncertainty has no compact fixed-point form (non-finite, zero, below 1e-6, or at 1e5 and above).