Frequency Correction API Reference

suspect.processing.frequency_correction.correct_frequency_and_phase(data, target, method='sr', axis=- 1, **kwargs)

Interface to frequency and phase correction algorithms, but returning the corrected data rather than the calculated shifts. Can be applied to multi-dimensional data to align e.g. a sequence of spectra at once.

Parameters:

  • data (MRSBase) – The data to be corrected.

  • target (MRSBase) – The reference spectrum to which data will be aligned.

  • method (str, optional) –

    The correction method to be used. Should be one of:

  • axis (int or None, optional) – The axis defining the spectral dimension.

  • kwargs – Arguments to be passed through to the method function.

Returns:

The data with corrected frequency and phase.

Return type:

MRSBase

Notes

Custom Frequency/Phase Corrections

If you have an alternative method for calculating frequency and phase shifts then you can simply pass a callable to the method parameter.

The callable is called as method(moving_data, target_data, **kwargs) where kwargs``corresponds to any other parameters that may be passed in such as `initial_guess. The method shall return a 2-tuple of floats containing the frequency shift in Hertz and the phase shift in radians between the first passed data and the second. Note that it is the measured frequency and phase shifts that should be returned, they will be negated by this function to correct the spectrum to the target.

suspect.processing.frequency_correction.rats(data, target, initial_guess=(0.0, 0.0), frequency_range=None, baseline_order=2, **kwargs)

Uses the RATS (Robust Alignment to a Target Spectrum) [1] to calculate the frequency and phase shifts between the input data and a reference spectrum. RATS operates in the frequency domain and the frequencies used to align the spectra can be specified to exclude regions where the spectra differ.

Parameters:

  • data (MRSData) – The data to be aligned to the target

  • target (MRSData) – The target data to which the moving data will be aligned

  • initial_guess (tuple) – A 2-tuple of frequency and phase shifts at which the optimisation routine will start searching. See below for more information.

  • frequency_range (tuple, slice or ndarray) – The frequency range can be specified in multiple different ways: a 2-tuple containing low and high frequency cut-offs in Hertz for the comparison, as a slice object into the spectrum (for use with the slice_ppm() function, or as an array of weights to apply to the spectrum.

  • baseline_order (int) – The order of the polynomial baseline.

Returns:

  • frequency_shift (float) – The estimated frequency shift in Hz.

  • phase_shift (float) – The estimated phase shift in radians.

Notes

Experimentally, I have found the RATS method to sometimes get stuck in local minima where the frequency shift is larger than about 6Hz. Although this can be addressed via the initial_guess parameter, when batch processing a sequence of spectra experiencing substantial drift, there is no single good value of initial_guess. In order to address this issue, this function begins by using a coarse grid based search to evaluate frequencies every 2Hz from 20Hz above the initial_guess frequency to 20Hz below. It then picks from those the frequency which gives best alignment with the target data as a starting point for the optimisation search. So far this has been very effective, but in case of discovering any problems, please raise an issue at http://github.com/openmrslab/suspect.

References

suspect.processing.frequency_correction.residual_water_alignment(data)
Parameters:

data –

suspect.processing.frequency_correction.spectral_registration(data, target, initial_guess=(0.0, 0.0), frequency_range=None, **kwargs)

Performs the spectral registration method [2] to calculate the frequency and phase shifts between the input data and the reference spectrum target. The frequency range over which the two spectra are compared can be specified to exclude regions where the spectra differ.

Parameters:

  • data (MRSData) –

  • target (MRSData) –

  • initial_guess (tuple) –

  • frequency_range (tuple, slice or ndarray) – The frequency range can be specified in multiple different ways: a 2-tuple containing low and high frequency cut-offs in Hertz for the comparison, as a slice object into the spectrum (for use with the slice_ppm() function, or as an array of weights to apply to the spectrum.

Returns:

  • frequency_shift (float) – The estimated frequency shift in Hz.

  • phase_shift (float) – The estimated phase shift in radians.

References