How ScientificFitting Works

ScientificFitting is built around one rule: statistical assumptions become explicit problem objects before a solver is selected. Reports, diagnostics, profiles, and plots then read the fitted result instead of reconstructing the analysis.

01
Define the scientific problem
Public API
observations x/y values, counts, bins, or samples
model Julia function and starting parameters
uncertainty or sampling law standard deviations, covariance, whitening, or likelihood
parameter control fixed values, bounds, priors, and constraints
normalized problem FitProblem or LikelihoodFitProblem
02
Validate before optimization
Scientific input checks
dimensions and mappings matching observations, model output, and parameter indices
finite physical inputs data, starts, bounds, errors, and model predictions
valid uncertainty structures positive σ and factorizable covariance or operator output
Invalid scientific input stops here with an actionable error.
03
Construct one objective
Statistical model
Gaussian residual cost diagonal weights, covariance factorization, or whitening operator
likelihood cost Poisson, histogram, unbinned, extended, indexed, or custom
additive parameter information Gaussian priors and correlated parameter constraints
objective C(p); bounds and fixed parameters restrict the parameter space rather than adding a penalty
04
Dispatch a compatible solver
Numerical backend
LsqFit fast path static, unconstrained Gaussian least squares
Optimization.jl path bounds, parameter-dependent uncertainty, priors, constraints, and likelihoods
An explicitly requested solver that cannot represent the problem fails instead of silently dropping statistical terms.
05
Build the fitted result
Single source of truth
minimum and parameters solver status and best-fit values
local uncertainty Jacobian/Hessian covariance and correlations
fit statistics residuals, cost, degrees of freedom (ndf), p-value, AIC/BIC where meaningful
FitResult or LikelihoodFitResult
06
Inspect and communicate
Post-fit tools
report_text reproducible numerical summary
diagnose structured findings and next actions
profile / contour controlled refits away from the minimum
plot_fit and Makie tools optional CairoMakie extension

The Four Inputs

Every ordinary fit starts with four concepts:

  • Data: measured x and y, counts, histogram bins, or indexed observations.
  • Model: a Julia function that maps data coordinates and parameters to predictions.
  • Uncertainty model: sigma_y, sigma_x, dense/sparse covariance, matrix-free static whitening (a parameter-independent covariance applied as a linear operation, never stored as a matrix; see the Glossary), named error components, Poisson counts, histogram likelihoods, or custom objectives.
  • Parameter control: starting values, bounds, fixed parameters, priors, and Gaussian parameter constraints.

Gaussian x-y workflows become a FitProblem, which retains x-y observations, model predictions, residuals, and a Gaussian uncertainty model. Count, histogram, sample, indexed, and multi-dataset likelihood workflows become a LikelihoodFitProblem, which retains a scalar $-2\log L$ objective, an optional goodness-of-fit statistic, and the number of observations; a generic likelihood need not have a y residual or a natural fit curve.

With the measured inputs model, x, y, and sigma_y from the Quickstart, the explicit core path is:

problem = FitProblem(model, x, y; p0=[1.0, 0.0], sigma_y=sigma_y)
result = fit(problem)
summary = report_text(result)

fit_model(...) performs the first two lines; after using CairoMakie, fitplot(...) adds the plotting workflow.

What Happens Internally

For Gaussian fits, the uncertainty model — pointwise $\sigma_i$, dense or sparse covariance, or a matrix-free WhiteningOperator — becomes one whitened residual cost; the derivation and worked examples are in Correlated Measurements And Whitening.

Likelihood fits minimize the appropriate $-2\log L$ objective or deviance on the scale fixed by The Cost Convention; Poisson and histogram workflows do not invent Gaussian error bars for low counts.

Backend dispatch (stage 04) follows from the problem: with the default solver=nothing, fit picks the least-squares or scalar-minimization backend automatically. An explicitly passed solver that cannot represent the problem — parameter bounds or nonlinear constraints it does not support — fails with an error before optimization instead of silently dropping those terms.

What A FitResult Contains

FitResult and LikelihoodFitResult store the numerical minimum and its statistical interpretation:

  • best-fit parameters and local covariance,
  • fitted model values and residuals,
  • chi-square, the $-2\log L$ minimum, p-value, AIC, BIC, and degrees of freedom where meaningful,
  • optimizer status and diagnostics,
  • enough problem metadata for plots, reports, profiles, contours, and downstream analysis.

Output Is Switchable

fitplot keeps output surfaces independent:

  • print_report=true prints a text report.
  • show_panel=false removes the statistics panel from a plot.
  • show_legend=false removes the legend.
  • stats_position=:right keeps results outside the data axis.
  • stats_position=:inside uses a compact in-axis box when space is limited.

diagnostic_dashboard(result) and diagnostic_dashboard_text(result) are separate and suggest what to inspect next.

Plots Stay Extensible

After using CairoMakie, plot_fit(result) returns a Makie Figure; the fragment below adds experiment-specific content without refitting and assumes the named values and reference function exist:

fig = plot_fit(result; show_panel=true, show_legend=true)
ax = fit_axis(fig)

add_vline!(ax, threshold; color=:gray40, linestyle=:dash, label="threshold")
add_curve!(ax, reference_model; color=:black, linestyle=:dot)
add_points!(ax, x_special, y_special; marker=:star5, color=:gray25)

Use this for thresholds, extrapolations, accepted regions, literature values, or derived-quantity markers.

Why Profiles and Contours Exist

Local covariance is a parabolic approximation at the minimum and can fail for weak data, bounds, nonlinear parameters, or asymmetric likelihoods; Profiles And Contours derives the nuisance-parameter refit and its thresholds. When a profile is not parabolic, or a contour does not resemble the local covariance ellipse, report profile intervals or contour regions instead of symmetric local errors.

Next useful pages: Quickstart, the worked examples, the Statistics Reference, and the Glossary.