hqs_nmr.analysis.autoshift_tools

Tools for autoshifting the shifts.

Functions

`calculate_area`(fx, x)	Calculate the area of a function.
`calculate_center_of_mass`(spectrum, omegas)	Calculate the center of mass of the spectrum.
`calculate_cumulative_fit_scores`(fit_scores, ...)	Calculate cumulative fit scores.
`calculate_fit_scores`(reference, reference_x, ...)	Calculate fit scores between a reference and contributions summing to a signal.
`cost_int_of_diff_interpolator_inverse`(shift, ...)	Cost function as the integral of the absolute differences between reference and signal.
`cost_integral_diff_shift_adapt_eta`(...)	Integral of the absolute difference between reference and shifted and adapted signal.
`cost_integral_interpolators_list_inverse_opt`(...)	Integral of the absolute differences between reference and shifted signal.
`enforce_equal_shifts_for_equivalent_spins`(...)	Enforce equal shifts for equivalent spins.
`get_new_guess_jc_eta`(current_guess, ...)	Get new guess for jcoupling adaption.
`get_spectrum_from_interpolator_inverse`(...)	Get the spectrum from the interpolators of the inverse of the green's function.
`lorentzian`(x, x0, gamma, result)	Lorentzian function.
`lorentzian_filter`(fx, x, gamma, result)	Apply a lorentzian filter to the signal.
`new_guess_via_cumulative_fit_score`(...)	Generate a new guess based on cumulative fit scores.
`new_guess_via_step_size`(current_guess, ...)	Generate new guess by stepping from the current one.
`process_experimental_spectrum`(...)	Process experimental data.
`process_greens_function`(...)	Sum the green's function over the equivalent spins.

hqs_nmr.analysis.autoshift_tools._order_by_frequency(spectrum: ndarray, omegas: ndarray) → tuple[ndarray, ndarray]

Order spectrum by frequency.

Parameters:

spectrum (np.ndarray) – spectrum.
omegas (np.ndarray) – frequencies.

Returns:

Ordered spectrum and frequencies.

Return type:

np.ndarray

hqs_nmr.analysis.autoshift_tools._scale_fwhm(gf: ndarray, omegas: ndarray, fwhm_scale: float) → ndarray

Apply a FWHM broadening to the green’s function.

Parameters:

gf (np.ndarray) – green’s function.
omegas (np.ndarray) – frequencies.
fwhm_scale (float) – broadening scaling factor.

Returns:

Broadened green’s function.

Return type:

np.ndarray

hqs_nmr.analysis.autoshift_tools.calculate_area(fx: ndarray, x: ndarray) → float

Calculate the area of a function.

Parameters:

fx (np.ndarray) – function.
x (np.ndarray) – x-values on which the function is evaluated.

Returns:

The area of the function.

Return type:

float

hqs_nmr.analysis.autoshift_tools.calculate_center_of_mass(spectrum: ndarray, omegas: ndarray) → float

Calculate the center of mass of the spectrum.

Parameters:

spectrum (np.ndarray) – spectrum.
omegas (np.ndarray) – frequencies.

Returns:

The center of mass of the spectrum.

Return type:

float

hqs_nmr.analysis.autoshift_tools._index_bookkeeping(result_greens_function: NMRResultGreensFunction1D) → tuple[list[int], dict[int, int], dict[int, list[int]]]

Extract all indices for bookkeeping.

Finds all indices of hydrogens, groups the equivalent ones and creates the maps between these two representations.

Parameters:: result_greens_function (NMRResultGreensFunction1D) – greens function result
Returns:: indices of the hydrogens, spins to groups map and groups to spins map.
Return type:: tuple

hqs_nmr.analysis.autoshift_tools._determine_max_shifts(exchangeable_protons: list[int], groups_to_spin_map: dict[int, list[int]], max_shift_h: float, max_shift_exc: float) → ndarray

Return max allowed shift for each spin group, taking care of exchangeable protons.

Parameters:

exchangeable_protons (list[int]) – exchangeable protons indices.
groups_to_spin_map (dict[int, list[int]]) – spin groups to spins map.
max_shift_h (float) – maximum shift for hydrogens.
max_shift_exc (float) – maximum shift for exchangeable protons.

Returns:

max shift array.

Return type:

np.ndarray

hqs_nmr.analysis.autoshift_tools._resample_spectrum(spectrum: ndarray, omegas: ndarray, num_rediscretized_omegas: int, num_linear_omegas: int) → tuple[ndarray, ndarray]

Resample the spectrum to an optimized set of frequencies.

The spectrum will be resampled on a frequency grid combining a grid based on equal-area-rediscredization and a grid ensuring that no frequency step is larger than a theoretical linear grid of the specified dimension.

Parameters:

spectrum (np.ndarray) – spectrum to resample.
omegas (np.ndarray) – original reference frequencies.
num_rediscretized_omegas (int) – max total number of rediscretized frequency points.
num_linear_omegas (int) – max number of linearly discretized frequency points to ensure that the maximum ferquency step is frequency_span / num_linear_omegas.

Returns:

resampled spectrum and new frequencies.

Return type:

tuple[np.ndarray, np.ndarray]

hqs_nmr.analysis.autoshift_tools._identify_multiplets_reduced(spectrum: NMRResultSpectrum1D, spin2groups_map: dict[int, int]) → list[NMRJoinedMultiplet]

Identify spectrum multiplets and group them according to the provided spin to groups map.

Parameters:

spectrum (NMRResultSpectrum1D) – spectrum to identify multiplets from.
spin2groups_map (dict[int, int]) – map of spins to groups.

Returns:

list of multiplets grouped according to the provided map.

Return type:

list[NMRJoinedMultiplet]

hqs_nmr.analysis.autoshift_tools._get_compatible_multiplets(ref_multiplet: NMRMultiplet, ref_multiplet_cms: float, multiplets: list[NMRJoinedMultiplet], multiplets_cms: ndarray, max_shifts: ndarray) → list[NMRJoinedMultiplet]

Get compatible multiplets for a given reference multiplet.

A multiplet is considered compatible with the reference one if its center of mass is within max_shift of the reference one.

Parameters:

ref_multiplet (NMRMultiplet) – reference multiplet.
ref_multiplet_cms (float) – reference multiplet center of mass.
multiplets (list[NMRJoinedMultiplet]) – list of multiplets to check.
multiplets_cms (np.ndarray) – list of multiplets center of mass.
max_shifts (np.ndarray) – maximum shift allowed for center of mass for each multiplet.

Returns:

list of compatible joined multiplets.

Return type:

list[NMRJoinedMultiplet]

hqs_nmr.analysis.autoshift_tools._cut_out_multiplet_from_signal(signal: ndarray, frequencies: ndarray, multiplet: NMRJoinedMultiplet | NMRMultiplet, buffer: float = 0, eta: float | None = None) → tuple[ndarray, ndarray]

Single out a multiplet peak from the signal.

By “single out” it is meant to simply drop the elements from signal and frequencies that are outside of the boundaries of the given multiplet.

Parameters:

signal (np.ndarray) – signal to single out the peak from.
frequencies (np.ndarray) – frequencies of the signal.
multiplet (Union[NMRJoinedMultiplet, NMRMultiplet]) – multiplet to single out.
buffer (float) – buffer in terms of multiplet span percentage to add on either side of the singled out peak. Signal will be assumed 0 + i eta there. Defaults to 0.
eta (Optional[float]) – eta value to set in the buffer region.

Returns:

cut out signal and frequencies.

Return type:

tuple[np.ndarray, np.ndarray]

hqs_nmr.analysis.autoshift_tools._find_optimal_shifts_fwhm(cost_matrix: ndarray, shifts_matrix: ndarray, fwhm_scale_matrix: ndarray) → tuple[ndarray, ndarray]

Find optimal chemical shifts and fwhm given a cost matrix.

Parameters:

cost_matrix (np.ndarray) – cost associated with the different pairs of shifts and fwhm scales. Its row index spans the different detected experimental multiplets and its column index spans the simulated spin contributions. NaNs should be used for the cost of non-compatible experimental and simulated multiplets.
shifts_matrix (np.ndarray) – shifts that minimize the cost for the corresponding experimental multiplets and simulated spin contribution.
fwhm_scale_matrix (np.ndarray) – fwhm that minimizes the cost for the corresponding experimental multiplets and simulated spin contribution.

Returns:

optimal chemical shifts and fwhm

Return type:

tuple[np.ndarray, np.ndarray]

hqs_nmr.analysis.autoshift_tools._unreduce_shift_fwhm(shifts: ndarray, fwhm_scales: ndarray, num_isotopes: int, groups2spin_map: dict[int, list[int]]) → tuple[ndarray, ndarray]

Convert shifts and fwhm scalings from reduced space to the molecule level.

Takes the shifts and fhmw scalings in the autoshift indices and translates them to the original indices at the molecule level, so that they can be applied to the original NMR parameters.

Parameters:

shifts (np.ndarray) – original shifts for each isotope.
fwhm_scales (np.ndarray) – additional spin-dependent fwhm scales.
num_isotopes (int) – total number of isotopes.
groups2spin_map (dict[int, list[int]]) – mapping from group index to spin indices.

Returns:

shifts and fwhm scales for the molecule.

Return type:

tuple[np.ndarray, np.ndarray]

hqs_nmr.analysis.autoshift_tools.process_experimental_spectrum(experimental_spectrum: NMRSpectrum1DProtocol, num_rediscretized_omegas: int, num_linear_omegas: int, normalization: float) → tuple[ndarray, ndarray]

Process experimental data.

Order by frequency
Apply baseline corrector
Rediscretize
Normalize integral to provided value

Parameters:

experimental_spectrum (NMRSpectrum1DProtocol) – experimental spectrum to process.
num_rediscretized_omegas (int) – max number of frequencies for the resampled spectrum.
num_linear_omegas (int) – number of linear frequencies to add in the resampling.
normalization (float) – value to which to normalize the integral.

Returns:

resampled spectrum and corresponding frequencies.

Return type:

tuple[np.ndarray, np.ndarray]

hqs_nmr.analysis.autoshift_tools.process_greens_function(result_greens_function: NMRResultGreensFunction1D, groups2spin_map: dict[int, list[int]]) → tuple[ndarray, ndarray]

Sum the green’s function over the equivalent spins.

Parameters:

result_greens_function (NMRResultGreensFunction1D) – Green’s function.
groups2spin_map (dict[int, list[int]]) – map from groups to spins

Returns:

reduced green’s function and corresponding frequencies.

Return type:

tuple[np.ndarray, np.ndarray]

hqs_nmr.analysis.autoshift_tools._find_shift_cms(reference: ndarray, reference_x: ndarray, signal: ndarray, signal_x: ndarray) → float

Find the global shift via center-of-mass.

Parameters:

reference (np.ndarray) – reference spectrum.
reference_x (np.ndarray) – reference spectrum frequencies.
signal (np.ndarray) – signal to shift.
signal_x (np.ndarray) – signal frequencies.

Returns:

global shift aligning the centers of mass of signal and reference.

Return type:

float

hqs_nmr.analysis.autoshift_tools._adapt_fwhm(reference: ndarray, reference_x: ndarray, greens_function: ndarray, greens_function_x: ndarray, max_fwhm_scale: float, tolerance: float = 0.0005, max_iter: int = 20) → float

Adapt the FWHM of the spectrum (from GF) to match the reference spectrum.

Parameters:

reference (np.ndarray) – reference spectrum.
reference_x (np.ndarray) – reference spectrum frequencies.
greens_function (np.ndarray) – green’s function to adapt.
greens_function_x (np.ndarray) – green’s function frequencies.
max_fwhm_scale (float) – maximum allowed scaling for the FWHM.
tolerance (float) – tolerance for FWHM changes in consecutive loops. Defaults to 5e-4.
max_iter (int) – Maximum number of iterations for FWHM refinement. Defaults to 20.

Returns:

optimal scale to the FWHM to match the spectrum.

Return type:

float

hqs_nmr.analysis.autoshift_tools.cost_int_of_diff_interpolator_inverse(shift: float, reference: ndarray, reference_x: ndarray, signal_interpolator_inverse: Callable) → float

Cost function as the integral of the absolute differences between reference and signal.

Parameters:

shift (np.ndarray) – shift to apply to the signal interpolator.
reference (np.ndarray) – reference.
reference_x (np.ndarray) – x-values on which the reference is defined.
signal_interpolator_inverse (Callable) – callable interpolating the inverse of the signal to shift.

Returns:

integral of absolute differences between reference and signals.

Return type:

float

hqs_nmr.analysis.autoshift_tools.cost_integral_interpolators_list_inverse_opt(shifts: ndarray, reference: ndarray, reference_x: ndarray, integral_weights: ndarray, signal_interpolators_inverse_re: list[Callable], signal_interpolators_inverse_im: list[Callable], scratch1: ndarray, scratch2: ndarray, scratch3: ndarray, num_spins: float = 1) → float

Integral of the absolute differences between reference and shifted signal.

The signal is constructed from the different interpolators of the inverses of the green’s functions. These are shifted accordingly, inverted, and summed. The integral of the difference between reference and signal is calculated and normalized according to the number of spins.

This version is optimized for speed. The interpolators of the inverse green’s functions are split in real and imaginary parts. The cost function is then evaluated using three preallocated scratch arrays to avoid continuous allocation. Moreover the integral weights for the trapezoidal rule are precomputed as np.diff(reference_x) / 2 and simply dotted into y[1:] + y[:-1], again to avoid recomputing it.

Parameters:

shifts (np.ndarray) – shifts to apply to the interpolators.
reference (np.ndarray) – reference.
reference_x (np.ndarray) – x-values on which the reference is defined.
integral_weights (np.ndarray) – precomputed integrals weights defined as (reference_x[1:] - reference_x[:-1]).
signal_interpolators_inverse_re (list[Callable]) – interpolators of the real part of the inverse of the green’s function.
signal_interpolators_inverse_im (list[Callable]) – interpolators of the imaginary part of the inverse of the green’s function.
scratch1 (np.ndarray) – preallocated scratch array.
scratch2 (np.ndarray) – preallocated scratch array.
scratch3 (np.ndarray) – preallocated scratch array.
num_spins (float, optional) – normalization factor. Defaults to 1.

Returns:

integral of the absolute difference between reference and shifted signal.

Return type:

float

hqs_nmr.analysis.autoshift_tools.cost_integral_diff_shift_adapt_eta(parameters: ndarray, reference_spectrum: ndarray, reference_x: ndarray, jc_adaptation_parameters: JCouplingAdaptationParameters, normalization_factor: float) → float

Integral of the absolute difference between reference and shifted and adapted signal.

The signal is reconstructed from the information contained in the jc_adaptation_parameters. It is shifted and adjusted given the parameters. Finally, the integral of the difference between reference and reconstructed signal is returned after normalization.

Parameters:

parameters (np.ndarray) – parameters for adjusting the green’s function. The first element is the j-coupling change, the second the global broadening, the rest are the shifts for all spins.
reference_spectrum (np.ndarray) – reference spectrum to compare against.
reference_x (np.ndarray) – reference frequencies for the reference spectrum and at which the signal is reconstructed.
jc_adaptation_parameters (JCouplingAdaptationParameters) – parameters for reconstructing and
signal. (adapting the)
normalization_factor (float) – normalization factor for the integral.

Returns:

Integral of the absolute diff between reference and shifted and adapted signal.

Return type:

float

hqs_nmr.analysis.autoshift_tools.get_spectrum_from_interpolator_inverse(shifts: ndarray, signal_interpolators_inverse: list[Callable[[ndarray], ndarray]], x: ndarray) → ndarray

Get the spectrum from the interpolators of the inverse of the green’s function.

Parameters:

shifts (np.ndarray) – shifts to apply to the interpolators.
signal_interpolators_inverse (list[Callable]) – callables interpolating the inverse of the green’s functions to shift.
x (np.ndarray) – x on which to evaluate the interpolators.

Returns:

spectrum.

Return type:

np.ndarray

hqs_nmr.analysis.autoshift_tools.lorentzian(x: ndarray, x0: float, gamma: float, result: ndarray) → None

Lorentzian function.

Parameters:

x (np.ndarray) – domain on which to define the function.
x0 (float) – center of the lorentzian.
gamma (float) – width of the lorentzian.
result (np.ndarray) – preallocated result array.

hqs_nmr.analysis.autoshift_tools.lorentzian_filter(fx: ndarray, x: ndarray, gamma: float, result: ndarray) → None

Apply a lorentzian filter to the signal.

Parameters:

fx (np.ndarray) – signal to be filtered.
x (np.ndarray) – domain of the signal.
gamma (float) – lorentzian broadening.
result (np.ndarray) – preallocated array to store the result.

hqs_nmr.analysis.autoshift_tools.calculate_fit_scores(reference: ndarray, reference_x: ndarray, contributions_interpolators: list[Callable], contributions_integrals: ndarray, offsets_boundaries: ndarray, num_offsets: int = 300) → tuple[ndarray, ndarray]

Calculate fit scores between a reference and contributions summing to a signal.

Fit score is defined as:

\[K(s) = 0.5 \times (\frac{N - \int dx |R(x) - g_i(x - s)|}{c_i} + 1)\]

with $R(x)$ the reference and $N$ its integral and g_i(x) the i-th contribution and $c_i$ its integral. The fit score will be 0 if the contribution has no overlap with the reference and 1 if it is perfectly contained within the reference.

Parameters:

reference (np.ndarray) – reference.
reference_x (np.ndarray) – x-values on which the reference is defined.
contributions_interpolators (list[Callable]) – contributions’ interpolators summing up to the signal.
contributions_integrals (np.ndarray) – integrals of the contributions.
offsets_boundaries (np.ndarray) – lower and upped boundaries of the offset values on which to calculate fit scores.
num_offsets (Optional[int]) – number of offsets on which to compute the fit scores. Defaults to 300.

Returns:

fit scores and corresponding offset values for each: contribution.

Return type:

tuple[np.ndarray, np.ndarray]

hqs_nmr.analysis.autoshift_tools.calculate_cumulative_fit_scores(fit_scores: ndarray, fit_scores_domain: ndarray, power: float = 2) → ndarray

Calculate cumulative fit scores.

Calculated as .. math:

CFS(s) = \int_{-\infty}^s dt F(t)

with F(t) the fit score.

Parameters:

fit_scores (np.ndarray) – precomputed fit scores.
fit_scores_domain (np.ndarray) – domain of the fit scores.
power (float, optional) – power to which the fit scores are raised. Defaults to 2.

Returns:

Cumulative fit scores.

Return type:

np.ndarray

hqs_nmr.analysis.autoshift_tools.new_guess_via_cumulative_fit_score(current_guess: ndarray, new_guess: ndarray, cumulative_fit_score: ndarray, cfs_domain: ndarray, cfs_treshold: float) → None

Generate a new guess based on cumulative fit scores.

The idea behind this sampler is the following: starting from a current guess, generate a new one by stepping randomly from it. Instead of using a fixed step size for this random jump, use the cumulative fit scores to dynamically adapt this step size. The cumulative fit scores (see their definition in the correpsonding function) are simply the integrals of the fit scores, i.e. a measure of how much each signal overlaps with the reference. The size of each step is defined to be such that the area under a fit score curve between the current guess and the new one is of a specific size (the cfs treshold). This way we move little when we are in areas of high fit score, while we jump across areas with low fit score, since these are very likely to be the wrong places to look in.

Parameters:

current_guess (np.ndarray) – current guess.
new_guess (np.ndarray) – preallocated array for the new guess.
cumulative_fit_score (np.ndarray) – cumulative fit scores for each of the values to generate a guess for.
cfs_domain (np.ndarray) – domain on which the cumulative fit scores are evaluated.
cfs_treshold (float) – threshold of fit score integral to overcome for generating a step for each value.

hqs_nmr.analysis.autoshift_tools.new_guess_via_step_size(current_guess: ndarray, new_guess: ndarray, step_size: float, boundaries: ndarray, distribution: Literal['uniform', 'cauchy'] = 'uniform') → None

Generate new guess by stepping from the current one.

Parameters:

current_guess (np.ndarray) – current guess.
new_guess (np.ndarray) – preallocated array for the new guess.
step_size (float) – step size to use.
boundaries (np.ndarray) – boundaries of each value of the guess.
distribution (Literal["uniform", "cauchy"]) – which distribution to use for the sampling of the steps. Defaults to “uniform”.

hqs_nmr.analysis.autoshift_tools.enforce_equal_shifts_for_equivalent_spins(shifts: ndarray, equivalent_spins_list_of_arrays: list[ndarray]) → None

Enforce equal shifts for equivalent spins.

Parameters:

shifts (np.ndarray) – shifts vector.
equivalent_spins_list_of_arrays (list[np.ndarray]) – list of arrays of equivalent spins.

hqs_nmr.analysis.autoshift_tools.get_new_guess_jc_eta(current_guess: ndarray, preallocated_new_guess: ndarray, amplitude_j_coupling: float, amplitude_eta: float, amplitude_shifts: float, limits: ndarray, equivalent_spins: list[ndarray], non_reference_spins: list[int]) → None

Get new guess for jcoupling adaption.

First element is the j-coupling, the rest are the shifts.

Parameters:

current_guess (np.ndarray) – current guess.
preallocated_new_guess (np.ndarray) – preallocated array for the new guess.
amplitude_j_coupling (float) – step amplitude for j coupling.
amplitude_eta (float) – step amplitude for eta.
amplitude_shifts (float) – step amplitude for shifts.
limits (np.ndarray) – allowed range for the guess.
equivalent_spins (list[np.ndarray]) – list of arrays of equivalent spins.
non_reference_spins (list[int]) – list of non-reference spins for which the shift is zero.

hqs_nmr.analysis.autoshift_tools._broaden_gf_and_calculate_interpolators(greens_function: ndarray, omegas_gf: ndarray, broadening: float) → tuple[list[Callable], list[Callable], list[Callable]]