1D Experiments

The 1D routines analyse a series of 1D spectra recorded as a single pseudo-2D experiment: a relaxation decay, a diffusion ramp, a nutation calibration, a reaction followed over time. Each is a single function that you call from the Julia prompt with the experiment folder. Every one of them works the same way:

1. It reads the experiment and asks about anything it needs and cannot work out for itself.
2. It opens a window showing your spectra, with an integration region you position over the signal you care about.
3. It fits as you work, so you can see immediately whether the region you have chosen gives a sensible result.
4. It saves the fit, the numbers and a results file to a folder when you press Save.

<!– TODO screenshot (1): docs/src/assets/analysis1d-window.png The relaxation1d window in a typical state: spectra overlaid on the left with one shaded integration region and the noise marker, the fitted decay below it, and the results panel on the right. This is the page's lead image. –>

Which routine to use

Chemical exchange experiments have their own routines: see R1ρ Relaxation Dispersion and Exchange Fitting.

Your first analysis

Start Julia, move to your data, and call the routine for your experiment:

using NMRAnalysis

cd("/Users/chris/NMR/my_dataset")
results = relaxation1d("11")

The routine reads experiment 11, asks about anything it needs (see Where the parameters come from below), and opens the analysis window. Position the region over your signal, check the fit, press Save, and close the window. results then holds the fitted parameters.

Where the parameters come from

Every analysis needs to know something beyond the spectra themselves: the relaxation delays, the gradient strengths, which model to fit. Each routine looks for each of these in the same order and stops at the first one that answers:

Nothing is required to be annotated. Annotations, where a pulse sequence carries them, simply save you from being asked. Anything you pass as an argument is taken as given and is not asked about, so a working analysis can always be turned into a script that repeats itself without any typing.

In a script, or anywhere else that is not an interactive Julia session, no question is ever asked. A value that has a sensible default takes it; one that does not raises an error naming the argument to pass instead. Force either behaviour with the prompt keyword:

relaxation1d("11"; prompt=false)   # never ask; error if something is missing

Using the analysis window

The window has three parts. On the left, your spectra are overlaid in grey with the current one picked out in colour, and below them the fit for whichever region is selected. On the right are the controls and a panel giving the fitted numbers.

The shaded regions are what get integrated. The selected one is orange and the rest are blue; whichever the cursor is over becomes the selected one. The purple marker is where the noise is measured. It always uses the same width as the region being integrated, which is what makes it a direct estimate of that region's uncertainty, so put it somewhere with no signal in any spectrum.

Mouse

Keyboard

The background turns yellow while you are dragging out a new region, and blue while you are typing a name. Press escape to cancel a rename.

Buttons

The text box beside Save names the output folder, relative to your working directory. It defaults to out.

Suggested workflow

1. Step to a spectrum where the signal is clear. For an inversion recovery, that is usually the last one.
2. Drag the region over the signal you want, and resize it to cover the whole peak.
3. Drag the noise marker to an empty part of the spectrum.
4. Check the fit below. The points should sit on the line, and the error bars should look like the scatter.
5. Add further regions with A if you want more than one signal, and name them with R.
6. Press Save, then close the window.

What gets saved

Save writes these files into the output folder. An existing folder of the same name is moved aside to <name>_previous first, so each save starts clean and a region you deleted since the last one does not leave its plot behind:

out/
  summary.txt
  regionlist.csv
  results.csv
  series.csv
  fit.pdf
  regions/
    signal.csv
    signal.pdf

Every CSV carries the experiment details as # comment lines above an ordinary header row, so they open directly in a spreadsheet or pandas.

regionlist.csv is what you picked, kept apart from what was fitted, so it can be reused on another dataset or edited by hand:

label,lo (ppm),hi (ppm)
signal,7.91,8.51
noise,-1.30,-0.70

The noise marker travels as a region named noise, as wide as the widest signal region; only its centre is read back. Load restores the regions and the noise position from this file, so a session with several named regions can be picked up again later rather than picked out by hand.

series.csv is the data behind the fit, one row per measurement:

source,label,time (s),I,I_err,I_fit
11/pdata/1,signal,0.010,9188.2,12.4,9188.9
11/pdata/1,signal,0.030,8737.1,12.4,8740.3
11/pdata/1,signal,0.060,8107.6,12.4,8104.0

I_fit is the fitted curve at the measured points, so a residual is a subtraction. For a kinetics experiment, where nothing is fitted, this file is the result. For everything else it is the decay or buildup the fitted parameters came from, which is what you want if you would rather plot or fit it yourself.

Units appear in the column headers in ASCII (R (s-1), tauc (ns)), and an uncertainty column repeats the unit of the value it belongs to. Numbers are written at full precision; summary.txt is where they are rounded. See Output and Interface Conventions for the full rules.

Repeating an analysis

Each routine returns a vector of results, one per region and series, whether you used the window or not. They print as one line each rather than dumping their contents:

julia> results = relaxation1d("11")
1-element Vector{RegionResult}:
 signal: A = 9421.0 ± 12.0, R = 0.866 ± 0.025

julia> param(results[1], :R)     # the fitted rate, with its uncertainty
0.866 ± 0.025

param reads both the fitted parameters and anything derived from them, so param(r, :tauc) and param(r, :rH) work the same way.

To repeat an analysis without the window at all, pass the region you settled on as an integration triple. This is the same triple the exchange routines use, so a region chosen once can serve a whole set of experiments:

relaxation1d("11"; integration=(peakppm=8.2, noiseppm=-1.0, ppmwidth=0.5))

pickregion opens the region-picking window on its own, with no fitting, and returns that triple.

Uncertainties

Intensities are divided by the spectrum's own noise level when the data is loaded, so the numbers in the window are in units of signal to noise. The uncertainty on an integrated region is measured separately, and directly: the same width of spectrum is integrated at the noise marker in every spectrum of the series, and the standard deviation of those integrals is taken. That is why the noise marker matters, and why it tracks the width of the region it is estimating noise for.

This assumes a flat baseline under the noise marker. If the fitted uncertainties look implausible, that is the first thing to check.

Automatic dispatch

Where a pulse sequence carries the annotations for it, analyse will recognise the experiment and call the right routine for you:

analyse("11")

This works today for nutation calibrations and for R1 and R2 relaxation experiments. Several nutation calibrations selected together are analysed as one calibration curve rather than one at a time. Diffusion and TRACT are called directly.