ramanlib.calib

Calibration utilities for RamanLib.

This module provides helpers to fit a single calibration peak (e.g., Si ~520 cm⁻¹), derive a wavenumber shift from the fitted center, and annotate an entire ramanlib.core.GroupedSpectralContainer with per-row peak centers and shifts. The outputs are designed to feed directly into your preprocessing or QA pipeline and to be visualized with ramanspy plotting.

Functions

fit_peak: Fit a single Gaussian peak in a calibration spectrum and (optionally) plot the fit.
get_wn_shift: Compute the wavenumber shift of a calibration peak relative to an expected center.
get_gsc_wn_shifts: Fit/annotate peak centers and shifts for all spectra in a container; return failing rows and (optionally) an augmented container.

Notes

The Gaussian model is a * exp(- (x - x0)^2 / (2 * sigma^2)) with parameters amplitude a, center x0 (cm⁻¹), and width sigma (cm⁻¹). The FWHM is related by FWHM = 2 * sqrt(2 * ln 2) * sigma.
Plots use ramanspy.plot.spectra() and draw a vertical marker at the fitted center.

Functions

`fit_peak`(calib[, plot])	Fit a Gaussian to a single peak in a calibration spectrum.
`get_gsc_wn_shifts`(calib_gsc, ...[, ...])	Fit calibration peaks for all spectra in a container and annotate each row.
`get_wn_shift`(calib, expected_x0_value[, plot])	Wavenumber shift relative to an expected calibration peak center.

ramanlib.calib.fit_peak(calib, plot=False)[source]

Fit a Gaussian to a single peak in a calibration spectrum.

Parameters:

calib (rp.Spectrum) – Input calibration spectrum with .spectral_axis and .spectral_data (1D arrays).
plot (bool, optional) – If True, plot the data and Gaussian fit using ramanspy on a single axis and draw a vertical line at the fitted center. Default False. (No plt.show() is called.)

Returns:

peak_center (float) – Estimated peak center x0 in cm⁻¹.
peak_height (float) – Estimated amplitude a of the Gaussian.
sigma (float) – Estimated Gaussian width σ in cm⁻¹. Related to FWHM via FWHM = 2 * sqrt(2 * ln 2) * σ.

Notes

Initial parameter guesses are derived from the maximum of the signal. The fit is performed with scipy.optimize.curve_fit().

ramanlib.calib.get_gsc_wn_shifts(calib_gsc, expected_x0_range, expected_x0_value, in_place=False, plot=False)[source]

Fit calibration peaks for all spectra in a container and annotate each row.

Two new columns are added to the container’s dataframe:

'x0_fit' : fitted peak center (cm⁻¹)
'shift' : x0_fit - expected_x0_value (cm⁻¹)

You can either modify the provided container in place (in_place=True) or return a new, augmented container (in_place=False). Rows that fail the center range check (NaN or outside expected_x0_range) are returned as a separate container in both modes.

Parameters:

calib_gsc (GroupedSpectralContainer) – Container with a 'spectrum' column of ramanspy.Spectrum.
expected_x0_range (iterable of float) – Two-element iterable [low, high] giving the valid cm⁻¹ interval for fitted centers. The values are sorted internally.
expected_x0_value (float) – Target cm⁻¹ value to calibrate to (used to compute shift).
in_place (bool, optional) – If True, annotate calib_gsc.df in place and return only the failing rows as a container. If False (default), return both the failing rows and a new, annotated container.
plot (bool, optional) – If True, plot each individual fit (may be slow). Default False.

Returns:

fail_gsc (GroupedSpectralContainer) – Container of rows that failed the range check (NaN or outside the bounds). Returned in both modes.
new_gsc (GroupedSpectralContainer) – Only when in_place=False: a new container with 'x0_fit' and 'shift' columns attached.

Raises:

ValueError – If expected_x0_range is not a 2-element iterable.

Notes

On failures/exceptions during per-row fitting, x0_fit and shift are set to NaN for that row.

Examples

>>> fail, calibrated = get_gsc_wn_shifts(gsc, expected_x0_range=[515, 530], expected_x0_value=520.7)
>>> list(calibrated.df.columns)
['spectrum', ..., 'x0_fit', 'shift']

ramanlib.calib.get_wn_shift(calib, expected_x0_value, plot=False)[source]

Wavenumber shift relative to an expected calibration peak center.

Parameters:

calib (rp.Spectrum) – Input calibration spectrum.
expected_x0_value (float) – Expected/target peak center in cm⁻¹ (e.g., 520.7 for Si).
plot (bool, optional) – If True, plot the fitted peak as in fit_peak(). Default False.

Returns:

shift – The signed shift (fitted_center - expected_x0_value) in cm⁻¹.

Return type:

float