Spectrum1D #

Object to copy history to.

Center of the region to suppress (in spectrum frequency units).

Full width of the region to suppress (in spectrum frequency units).

Suppression method enum.

Self (mutated in-place) for method chaining.

If the region is entirely outside the spectrum range.

The shift the sample's solvent predicts for the observed nucleus, in ppm.

PPM searched either side of expected_ppm for the line's actual position.

The component that was subtracted, or None when no solvent line was

found or the spectrum was already suppressed.

If the spectrum has no reference frequency, so no ppm position can be located on its axis.

Predefined solvent enum value

Target nucleus (defaults to 1H)

PPM range to search for solvent peak

Self with shifted frequencies

If solvent/nucleus combination not found or no peak in window

The PPM value where the peak should be placed

PPM range around target to search for peak

If True, use weighted centroid instead of maximum

Self with shifted frequencies

If reference_frequency_hz is not set or no peak found

The current PPM value of the clicked position

The PPM value it should be shifted to

Self with shifted frequencies

If reference_frequency_hz is not set

Reference spectrum to align to.

Self with shifted frequencies.

If the spectra have different lengths.

Frequency of the harmonics to mask.

Cutoff threshold of the cosine wave (higher = thinner mask). Defaults to 0.99.

Central frequency to split the spectrum with.

Inverse cosine distance. The lower the score the higher the spectrum's symmetry rate.

Minimum peak distance (in Hz). If None, auto ~1% span.

Minimum peak height as a ratio of the maximum height (0-1). IGNORED ENTIRELY when adaptive=True, which takes no parameters at all.

Minimum prominence as a ratio of the maximum height (0-1). When adaptive=False this defaults to None, meaning NO prominence filter is applied at all and every local maximum above min_height_ratio is reported. IGNORED when adaptive=True.

If True, work on |z| else on Re(z).

If True, run AUTO MODE: a statistically calibrated threshold pass followed by Richardson-Lucy deconvolution against the measured lineshape (see :func:tqt_nmr.analysis.peak_detection.detect_peak_indices_auto). It takes NO parameters — every quantity it needs is measured on the trace — so min_height_ratio, prominence, min_distance_hz and snr_threshold are all ignored. Not configurable by design.

DEPRECATED and ignored.

Which detector auto mode runs. Only meaningful with adaptive=True; the manual path always uses the fixed ratios above. "ml" (the default) is a learned model that finds shoulders and merged components a threshold pass cannot and is unaffected by line broadening; it requires a phased spectrum, since it detects inverted lines too and dispersive input yields peaks in the wrong places rather than none. "deconv" is the threshold pass plus deconvolution described under adaptive.

The learned detector's operating point. Lower favours recall, higher favours precision. None uses the model's own default. Ignored unless mode="ml".

Center of the search region (in spectrum units). If None and peaks provided, calculated from peaks.

Width of search region on each side of center.

Minimum peak height as ratio of tallest peak in region.

Analysis method: "structure" (default), "deconvolution", or "fast" (alias "pascal").

Number of bootstrap iterations for uncertainty estimation. Use "auto" for SNR-adaptive (default: SNR > 100 uses analytical, SNR 30-100 uses 50 iterations, SNR < 30 uses 200).

BIC improvement threshold for peak count selection.

Pre-detected peaks to use instead of re-detecting. When provided, the "fast" method uses these directly. For "structure"/"deconvolution", center_frequency and search_width are derived from peaks if not specified.

MultipletAnalysis with pattern, coupling constants, and confidence.

For deconvolution/structure methods, includes uncertainties and fit metrics.

Hierarchical clustering linkage method ('single', 'average', 'complete', 'ward'). Default: 'single'.

Analysis method for pattern classification within each group: - "structure" (default): constrained J-pattern fit of the group's region, seeded by the group's peaks; reports J uncertainties. - "fast" (alias: "pascal"): position-only classification, no spectral fit. Cheap; use when the peak list is already reliable. - "deconvolution": peak-count selection, then the same constrained fit.

The lines to group and classify. Pass an already-detected (and possibly user-edited) peak list here to have grouping see exactly that list. Default (None) runs auto-mode detection.

Allow a group to gain a line the detector did not pick, when the observed intensities are better explained by a pattern with one terminal line unobserved AND the trace holds the predicted intensity there. Off by default: an inferred line is a conclusion, not a measurement. Inferred lines are marked PeakOrigin.INFERRED, carry the PREDICTED height and no area, and are excluded from the group's measured arrays, so no integral or peak count changes either way.

MultipletGroupsAnalysis with all detected groups.

The group to complete.

Every detected line in the spectrum. Offered as neighbours in full, not just this group's: a line outside the group still puts its tail on the candidate position, and subtracting only the group's own lines reads an adjacent multiplet's flank as confirmation.

Spectrum frequency axis, Hz.

Real trace on that axis.

Fallback FWHM when this group's own lines report none, Hz.

The detector's own height gate.

Whether inference was asked for at all.

Appended to with whatever is found, so the caller can gather every group's inferred lines without a separate step.

List of peaks to integrate (from find_peaks())

Width of integration region on each side of peak (in spectrum units). If None, auto-calculates from the peak's half-width at half-height times width_multiplier.

Index of peak to normalize to 1.00. If None, no normalization.

If True, integrate |z|, else integrate Re(z).

Integration half-window in multiples of the peak's HWHM. A Lorentzian carries a heavy tail, so a narrow window introduces a systematic, linewidth-dependent quantitation bias: +/-1 HWHM captures 50% of the area, +/-20 (the default) ~97%. Reduce only for crowded spectra where neighbouring peaks would overlap the window.

List of IntegrationResult with area and bounds for each peak.

List of peaks (from find_peaks(), ideally with group_id set)

Which group to normalize to 1.00.

If True, integrate |z|, else integrate Re(z).

If peaks lack group_id, group by proximity (Hz).

List of ShiftIntegrationResult, one per chemical shift group.

Minimum frequency (Hz)

Maximum frequency (Hz)

Number of peaks to fit (auto-detect if None)

Bootstrap iterations for uncertainty

DeconvolutionResult with fitted peaks and uncertainties

Optional (f_min, f_max) to restrict signal calculation. If None, uses entire spectrum.

Signal-to-noise ratio (linear scale)

Baseline correction method: - "arpls" (default): asymmetrically reweighted penalised least squares, restricted to a signal-free mask and fitted on an extrapolated extension of the trace. - "airpls": adaptive iteratively reweighted penalised least squares. Tends to inflate peak amplitudes; prefer "arpls". - "asls": asymmetric least squares with asymmetry and a length-normalised lambda. - "masked_poly": polynomial of order poly_order fitted to the signal-free mask across the whole spectrum. - "snip": iterative peak clipping, for wide-line spectra. - "polynomial": polynomial fitted to the spectrum edges only. - "als": fixed-iteration asymmetric least squares over the signal-free mask, with als_lambda iterations of als_iterations. - "valley": interpolation through the minima between peaks. - "edge": constant offset from the mean of the two edge medians. - "median": constant offset from the median of both edge regions.

Fraction of each spectrum edge used by the edge-anchored methods ("edge", "median", "polynomial").

Polynomial order for "polynomial" and "masked_poly".

Whittaker smoothness as log10(lambda) quoted at 16384 points; the applied lambda is scaled by (N / 16384) ** 4 so the physical smoothing width is independent of spectrum length. Useful range 7-12.

Asymmetry parameter p for "asls".

Maximum reweighting iterations for the Whittaker methods.

Relative convergence tolerance for the Whittaker methods.

Signal-mask threshold in robust noise sigma; points with |y - median| > mask_sigma * sigma are excluded from the fit.

Smoothness parameter for "als", quoted at 16384 points and scaled by (N / 16384) ** 4.

Asymmetry parameter for "als".

Iteration count for "als"; must be >= 1.

Minimum valley prominence as a fraction of max|y|.

Rescale the corrected spectrum so its integral matches the input integral. The scale factor is unbounded when the corrected integral is small, so quantitative work must leave this off.

Clamp negative values to zero before rescaling. Clipping makes the residual noise one-sided instead of zero-mean, which invalidates downstream noise/SNR estimates and biases integrals upward.

How to baseline-correct the dispersion (imaginary) channel: - "auto" (default): apply the same constant offset for the "edge" and "median" methods, and leave the dispersion channel untouched for every other method. Only a constant offset is well defined on a bipolar lineshape; anything else rotates the spectrum's phase. - "same": apply the absorption-channel method to the imaginary part. - "polynomial": use the edge-anchored polynomial fit. - "none": leave the imaginary part untouched.

Permit poly_order above MAX_SAFE_EDGE_POLY_ORDER for the edge-only "polynomial" method instead of clamping it with a warning.

Additional parameters (ignored for compatibility)

Self

If method is not a supported baseline method.

Objective used by strategy="multistart", and by the seeded strategy's fallback when the spectrum has too few resolved multiplets.

Width of the ROI for the peak_minima objective, in points.

Whether to also return the applied phases: (p0, p1) for a first-order model, (p0, p1, p2) when a second-order model is selected.

Whether to log the optimisation process.

Try multiple starting points. Accepted by strategy="multistart" only.

Explicit zero-order starting points in degrees, defaulting to 8 points spanning 0-315 deg. Accepted by strategy="multistart" only.

Explicit first-order starting points in degrees, defaulting to (0.0,). Accepted by strategy="multistart" only.

Which algorithm to use.

• "seeded" (default): measure the phase at the peaks and regress it.
• "multistart": multi-start Nelder-Mead over p0_starts x p1_starts, ranked by :func:phase_objective.

Model order for the seeded strategy -- 1, 2, "auto", or None to take it from NUCLEI_PHASE_ORDER.

Self if return_phases=False (default), otherwise (Self, phases).

If a multi-start-only argument is supplied to the seeded strategy.

If the model order is not recognised.

Zero-order phase correction (degrees)

First-order phase correction (degrees)

Manual phase correction method

Second-order phase correction (degrees). Supported by "linear".

Self

New spectrum in PPM units (or copy if already in PPM)

If reference frequency is not set

Standard deviation for Gaussian kernel

Whether to preserve total integral

Self

Minimum frequency (in spectrum's current units)

Maximum frequency (in spectrum's current units)

A new, trimmed spectrum (the original is left unchanged).

Centering method ("max" or "centroid")

Self

Target frequency unit.

Reference frequency in Hz, required when converting to or from PPM. If omitted, the spectrum's own reference_frequency_hz is used.

If a PPM conversion is requested and no reference frequency is available from either source.

Normalization method: - "max": Divide by maximum absolute value - "rms": Divide by RMS value - "unit": Divide by L2 norm

Self for method chaining

Time unit for the output signal (default: MICROSECOND)

Carrier offset in Hz. If provided, this offset is subtracted from frequencies before inverse FFT and stored in the output signal.

If True, return only the first half of the signal. Useful when the spectrum produces a mirrored/symmetric signal after IFFT.

Whether the frequency axis holds only non-negative frequencies (as produced by Signal1D.to_spectrum(fft_method="real"), which is the default). If None, detected from the fft_method metadata entry, falling back to inspecting the axis. One-sided spectra are inverted with irfft; two-sided (fftshift-ordered) spectra with ifftshift + ifft. Inverting a one-sided spectrum with plain ifft yields meaningless output.

Whether to undo the forward transform's first-point halving (doubling fid[0]) so the roundtrip is lossless. If None, read from the first_point_scale metadata flag recorded by to_spectrum.

Time-domain signal