Processing 2D NMR data#
Use the plugin’s reader to load the 2D dataset. The acquisition and quadrature determine which operations are available. See Quadrature and metadata for the supported conventions and Processing, validation, and qualification for the distinction between runtime checks and qualification against reference data.
Process the direct dimension (F2) before the indirect dimension (F1) for supported paired acquisitions. The plugin uses the acquisition metadata to select the quadrature convention and check the transform order. When processing explicitly on a supported dataset, you can inspect the mixed-domain result after F2 before transforming F1.
Transform F2 and F1#
Transform the direct time axis x first when working step by step.
For paired acquisitions, retain both complex branches through the
indirect transform. The examples below show how to select a workflow
for an acquisition whose mode is known. Replace the example paths with
your own data.
[1]:
import spectrochempy as scp
QF magnitude#
QF records one trace per F1 increment. There is no cosine/sine pair to combine. For the supported Bruker COSY replay, transform the complex data in F2 and F1, then take the magnitude. A cosine at frequency f contributes at both +f and −f. Magnitude display does not recover the missing sign of the indirect frequency.
[ ]:
fid = scp.nmr.read_topspin("path/to/qf-cosy/ser")
spectrum = scp.nmr.Experiment(fid).process(replay="topspin")
States#
States records two traces per increment, a cosine branch C and a sine
branch S. After F2, combine the real parts as
C.real + 1j * S.real and the imaginary parts as
C.imag + 1j * S.imag. Transform these two complex sequences in F1.
For example, if the two F2 values at a given point are 3 + 4j and
5 + 6j, the F1 inputs are 3 + 5j and 4 + 6j.
The plugin handles the branch order and Fourier sign.
[ ]:
fid = scp.nmr.read_topspin("path/to/states/ser", remove_digital_filter=True)
f2 = fid.fft(dim="x")
spectrum = f2.fft(dim="y")
States-TPPI#
The same two branches are acquired, but their signs alternate between
successive F1 increments. Undo the alternation by multiplying both
reconstructed sequences by +1, −1, +1, −1 before the F1 FFT.
At an odd increment, the example States inputs 3 + 5j and
4 + 6j would be stored as -3 - 5j and -4 - 6j.
The plugin applies the sign correction when the mode is States-TPPI.
[ ]:
fid = scp.nmr.read_topspin("path/to/states-tppi/ser", remove_digital_filter=True)
spectrum = fid.fft(dim="x").fft(dim="y")
Echo/anti-echo#
Echo/anti-echo records two coherence pathways in each increment. For the
Bruker Rance–Kay profile, the plugin first forms E - A and
1j * (E + A) from the two stored branches. For instance,
E = 2 + 3j and A = 1 + 1j give 1 + 2j and -4 + 3j.
After F2, the two reconstructed branches are cross-paired by real and
imaginary parts as for States and transformed along F1.
[ ]:
fid = scp.nmr.read_topspin("path/to/echo-antiecho/ser")
spectrum = scp.nmr.Experiment(fid).process(
echo_antiecho="bruker-rance-kay", digital_filter="phase"
)
TPPI#
Native Agilent TPPI records one trace per increment and advances the phase systematically with F1 evolution time. After F2, the real and imaginary parts of the traces form separate real-valued F1 sequences. Each sequence is zero-filled from N to 2N points, and the F1 transform retains bins 0 through N−1. For N=128, each real transform therefore uses 256 points and keeps 128 bins. See the Agilent TPPI section below for the frequency calibration.
[ ]:
fid = scp.nmr.read_agilent("path/to/tppi.fid")
spectrum = scp.nmr.Experiment(fid).process()
The gallery example reconstructs a simulated resonance in all five modes. To inspect a complete COSY plane, load the processed Bruker gossypol spectrum from the NMRPipe example. Start the positive contours at 0.3% of the maximum and double each successive level to show weak cross-peaks alongside the diagonal.
[2]:
path = scp.preferences.datadir / "nmrdata/nmrpipe/nmrpipe_2d_cosy_example.ft2"
cosy = scp.nmr.read(path, protocol="interop")
first_level = 0.003 * cosy.max()
levels = [first_level * 2**index for index in range(8)]
_ = cosy.plot(method="contour", levels=levels, figsize=(6, 6))
See Fourier transformation in NMR for the core FFT and magnitude operations.
A direct FFT uses the supplied samples, including the original group delay
when reading a Bruker SER without import correction. TopSpin XFB replay applies
the recorded correction for supported acquisitions. For echo/anti-echo,
Experiment.process(echo_antiecho="bruker-rance-kay", digital_filter="phase")
compensates the digital-filter delay in F2. Use digital_filter="time" for
time-domain correction instead. The ordinary QF, States, and States-TPPI
FFT workflows transform the supplied traces without filter correction.
For these workflows, or for a direct FFT script that used the former
import correction, pass remove_digital_filter=True to the reader.
Here x and y are the direct and indirect dimensions of the
imported FID. Keep both quadrature branches through the indirect FFT.
Select the desired spectral component before plotting or extracting a
1D slice.
Use Analyzing NMR spectra to find and integrate cross-peaks in a processed spectrum.
For a supported uniform Bruker SER acquisition, use the recorded TopSpin processing parameters explicitly:
[ ]:
fid = scp.nmr.read_topspin(
"path/to/experiment/ser", remove_digital_filter=False, remove_dc_offset=False
)
spectrum = scp.nmr.Experiment(fid).process(replay="topspin")
XFB replay supports indirect QF magnitude, States-TPPI, and echo/anti-echo
with direct DQD. Use the raw SER from the same experiment as the recorded TopSpin processing
settings. The XFB qualification notes list the
supported settings. The ordinary Experiment.process() path
applies SpectroChemPy’s processing sequence to supported acquisitions.
For the underlying dataset, plotting, and general processing API, see the NMR plugin overview in the SpectroChemPy core documentation.
Extracting spectral components#
Use an Experiment to extract real 2D planes with the original F1 and F2
coordinates and intensity units.
[ ]:
experiment = scp.nmr.Experiment(spectrum)
rr = experiment.rr() # or experiment.RR
ri = experiment.RI
ir = experiment.IR
ii = experiment.II
The names follow the TopSpin files 2rr, 2ri, 2ir and 2ii.
In this convention the first letter refers to F2 and the second to F1.
A real-only spectrum exposes RR. Requesting a component absent from the
spectrum raises an error.
TopSpin-style slice and baseline commands#
Wrap a single dataset in Experiment. These
commands return new datasets in memory. They use TopSpin numbering, so row
or column 1 corresponds to index 0 in SpectroChemPy.
[ ]:
fid = scp.nmr.Experiment(fid).rser(1)
experiment = scp.nmr.Experiment(spectrum)
row = experiment.rsr(1)
column = experiment.rsc(1)
For a plain F1 × F2 matrix, rser(1) and rsr(1) select
dataset[0, :].squeeze("y"). For a real spectrum, rsc(1) selects
dataset[:, 0].squeeze("x"). In a paired acquisition, rser() numbers the
two stored traces of each F1 increment consecutively. With four spectral
components, rsr() keeps the complex F2 trace from the F1-real channel, and
rsc() builds a complex F1 trace from the F2-real components. After an
F2-only transform, rsc() returns an F1 time trace with the acquisition
convention still encoded.
Use wsr() or wsc() to replace a trace in a copy of the spectrum.
The replacement must have the same coordinate grid and units.
[ ]:
row = experiment.rsr(1)
adjusted = row.pk(phc0=10.0)
updated = experiment.wsr(1, adjusted)
On a real matrix the corresponding assignment is updated[0, :] = adjusted
or updated[:, 0] = adjusted, using a copy of the original spectrum.
On a Bruker four-component spectrum, wsr() replaces the selected row in
2rr and 2ir, and wsc() replaces the selected column in 2rr
and 2ri.
Use abs2() to fit a polynomial separately along each F2 row and
abs1() to fit along each F1 column of a fully transformed spectrum.
Both correct only the real-real plane, as in TopSpin. The default polynomial
degree is 5. Set limits to correct a specific interval and ranges to
identify peak-free regions for the fit. Both take values in the units of
the selected axis. By default the fit iteratively excludes positive and negative peaks
using each trace’s residual noise estimate.
[ ]:
corrected = experiment.abs2(
order=1, limits=(20.0, 65.0), ranges=[(21.0, 24.0), (61.0, 64.0)]
)
corrected = scp.nmr.Experiment(corrected).abs1(order=1)
The fit excludes masked points, including when fit ranges are supplied. A correction interval requires a strictly monotonic axis. Automatic fit-point selection can differ from TopSpin’s peak-region selection.
Agilent TPPI#
For a native Agilent acquisition identified as TPPI, use
Experiment(fid).process(). The result contains four planes in F1, F2
component order (rr, ri, ir, ii). The direct transform
uses the sample convention of var2pipe -noaswap followed by
FT -nodf. In F1 the real and imaginary parts of F2 each form a
real sequence. Each sequence is zero-filled from N to 2N, transformed,
and reduced to bins 0 through N−1. This retains DC and excludes Nyquist.
The F1 bin spacing is the acquisition width divided by 2N. The displayed
half-band follows the carrier convention of NMRPipe
TP → ZF -size 2N → FT -real, with the carrier halfway between its
two central bins.
The default axes are carrier-relative Hz. To obtain ppm, pass the
observation frequency in MHz and carrier in ppm explicitly for each
dimension, in F1 then F2 order. For the historical Agilent
agilent_2d_tppi NMRPipe conversion the values are:
[ ]:
spectrum = scp.nmr.Experiment(fid).process(
tppi_reference=((125.681, 101.274), (125.681, 101.274))
)
Use the values from the reference for your acquisition. The Agilent reader can lack the F1 observation frequency.
Automatic phase correction along F2#
For a series of complex F2 spectra, apk2d() estimates a common phase
from the first row by default. Pass reference_row to select another row
using TopSpin’s 1-based numbering. Use per_row=True when the phase varies
across the series. Inspect individual estimates when the signal becomes
weak, especially at high diffusion weightings. The estimator uses the same options as scp.nmr.apk().
[ ]:
phased = scp.nmr.Experiment(series).apk2d(reference_row=1, order=0) # noqa: F821
For MQMAS, pass the complex result of xf2(). The common phase applies
to both States branches. The output can go directly to xfshear().
An unsuccessful estimate raises an error identifying the row.