Summary
For Gaussian, Lorentzian and Voigt peaks, the public parameter named amp/amplitude currently represents an integrated area even though users and downstream interfaces naturally read it as peak height. This makes the numerical value depend on sigma, gives it compound units, and creates inconsistent behavior across fitting, signal creation and pulse measurements.
Define amplitude as the signed peak height above y0 for all three equal-width models, version every durable parameter representation affected by that semantic change, and reject historical unversioned values until the caller explicitly converts them.
Current behavior
The historical Gaussian and Lorentzian formulas normalize amp by a width-dependent area factor. A value displayed as amplitude therefore changes meaning when sigma changes and is not expressed in the signal's Y unit. The historical Voigt conversion follows the same area-oriented contract.
Creation parameters and persisted fit_params do not carry a structural version or an explicit parameterization marker. Renaming amp to amplitude without validating the raw payload would be unsafe because guidata deserialization supplies defaults for missing renamed fields and ignores unknown fields.
Proposed contract
amplitude is signed peak height above y0.- Gaussian:
y0 + amplitude * exp(-0.5 * ((x - x0) / sigma) ** 2).
- Lorentzian:
y0 + amplitude / (1 + ((x - x0) / sigma) ** 2).
- Voigt: normalize the profile by its value at the center so
f(x0) == y0 + amplitude exactly.
- Keep explicit
area_from_amplitude(amplitude, sigma) and amplitude_from_area(area, sigma) helpers for scientific conversions.
- Peak widths and relative-level offsets must be derived from each model rather than reusing Gaussian identities for Lorentzian or Voigt peaks.
Persistence and compatibility
- Introduce
FIT_PARAMS_VERSION = 2, CREATION_PARAMS_VERSION = 2 and PEAK_PARAMETERIZATION = "height".
- Versioned peak fit dictionaries use
amplitude/amplitude_N, include fit_params_version: 2 and include peak_parameterization: "height".
- Versioned peak creation payloads include
creation_params_version: 2 and peak_parameterization: "height".
- Historical unversioned
amp/amp_N and creation field a values are treated as integrated areas.
- Historical payloads raise a dedicated
LegacyPeakParameterizationError during validation or evaluation. No alias may reinterpret an old area as a new height.
- Provide non-mutating conversion helpers that preserve unrelated metadata and convert each area using the corresponding model and
sigma.
- Reject future versions, contradictory markers, legacy keys in v2, missing required parameters and non-contiguous multi-peak indices.
- Preserve signal X/Y samples during metadata conversion; conversion authorizes future reuse of parameters but never regenerates historical data implicitly.
Related issues
Summary
For Gaussian, Lorentzian and Voigt peaks, the public parameter named
amp/amplitude currently represents an integrated area even though users and downstream interfaces naturally read it as peak height. This makes the numerical value depend onsigma, gives it compound units, and creates inconsistent behavior across fitting, signal creation and pulse measurements.Define amplitude as the signed peak height above
y0for all three equal-width models, version every durable parameter representation affected by that semantic change, and reject historical unversioned values until the caller explicitly converts them.Current behavior
The historical Gaussian and Lorentzian formulas normalize
ampby a width-dependent area factor. A value displayed as amplitude therefore changes meaning whensigmachanges and is not expressed in the signal's Y unit. The historical Voigt conversion follows the same area-oriented contract.Creation parameters and persisted
fit_paramsdo not carry a structural version or an explicit parameterization marker. Renamingamptoamplitudewithout validating the raw payload would be unsafe because guidata deserialization supplies defaults for missing renamed fields and ignores unknown fields.Proposed contract
amplitudeis signed peak height abovey0.y0 + amplitude * exp(-0.5 * ((x - x0) / sigma) ** 2).y0 + amplitude / (1 + ((x - x0) / sigma) ** 2).f(x0) == y0 + amplitudeexactly.area_from_amplitude(amplitude, sigma)andamplitude_from_area(area, sigma)helpers for scientific conversions.Persistence and compatibility
FIT_PARAMS_VERSION = 2,CREATION_PARAMS_VERSION = 2andPEAK_PARAMETERIZATION = "height".amplitude/amplitude_N, includefit_params_version: 2and includepeak_parameterization: "height".creation_params_version: 2andpeak_parameterization: "height".amp/amp_Nand creation fieldavalues are treated as integrated areas.LegacyPeakParameterizationErrorduring validation or evaluation. No alias may reinterpret an old area as a new height.sigma.Related issues