analysis-protocol — fit validation gate

This is the shareable, self-contained core of a larger experimental-data analysis protocol. Two pieces ship here:

• fit_validator.py — a mandatory validator that decides whether a peak-fitting result is trustworthy enough to become a figure or a claim.
• METHODOLOGY.md — a generic, vendor-neutral methodology reference for 12 catalyst-characterization techniques (XPS, XRD, H2-TPR, NH3-TPD, BET, CO-chemisorption, CO-DRIFTS, GC, Raman, TEM/STEM, TGA, XAS).

The original protocol also wired a private, workflow-specific methodology library (tuned per-technique parameter databases, figure standards, project configs) that is deliberately not included — only the generic engine and methodology reference are shared here.

When to use

After every lmfit (or equivalent) deconvolution — XPS, NH3-TPD, Py-DRIFTS, TPO, XRD, etc. — and before you draw the figure or write the sentence that depends on it.

How it works

fit_validator.py runs three check categories:

1. Quant (hard) — parameter pinned at its boundary, vestigial peak amplitude, residual norm over threshold, reduced chi-square over threshold.
2. Visual (hard) — raw signal vs. fitted envelope correlation, peak amplitude positivity.
3. Sanity (soft) — fitted-quantity rank vs. an expected activity/stability rank. Surfaced as a warning, never auto-corrected: it forces a human decision between "the fit is wrong" and "the fit is right but the narrative needs a different descriptor".

If quant or visual fail lists are non-empty: HARD FAIL — do not emit anything. Loosen bounds / change peak count / change peak function / expand the fit window, retry up to ~5 times, then escalate.

Usage

from fit_validator import validate_fit

report = validate_fit(
    result=lmfit_result,
    raw_y=y_raw,
    envelope_y=lmfit_result.eval(x=x_raw),
    peaks=[(p.name, p.value) for p in lmfit_result.params.values()
           if 'amplitude' in p.name],
    sample_values={"SampleA": 1.0e6, "SampleB": 1.5e6},   # optional
    expected_rank={"SampleA": 1, "SampleB": 2},            # optional
    descriptor_name="total acid site density",             # optional
)
if report['quant'] or report['visual']:
    ...  # HARD FAIL: do not output; self-iterate or escalate
else:
    for w in report['sanity_flag']:
        ...  # WARN: human review
    ...  # OK to output figure / bar / narrative

The sample_values / expected_rank / descriptor_name arguments are optional — omit them to run only the hard quant + visual gates.

Dependencies

numpy, and an lmfit (or compatible) result object exposing .params and .redchi.