API: GUI2D

Seconds allowed when continuing an unfinished fit at the user's request.

Seconds a cluster may take before its fit is stopped, keeping the window responsive.

METHYL_K

Prefactor K (s⁻²) in eq 1 relating η to S²τc for an ideal methyl group, so that S²τc = η / K. Assumes the H–H vector is perpendicular to the methyl 3-fold axis (θ = 90°, [P₂(cosθ)]² = 1/4) and r_HH = 1.813 Å:

K = (9/40)·(μ₀/4π)²·γ_H⁴·ℏ² / r_HH⁶  ≈ 3.61×10⁹ s⁻²

giving S²τc (ns) ≈ 0.277·η for η in s⁻¹.

The lineshape parameters of a peak: where it is, and how broad it is in each dimension.

Standard amino acid one-letter codes.

CCRExperiment

Cross-correlated relaxation experiment with decay and buildup spectra.

Fields

• specdata: Spectral data and metadata
• peaks: Observable list of peaks
• isbuildup: Vector of booleans indicating buildup (true) or decay (false) spectra
• T: Relaxation time constant in seconds
• issymmetric: Whether symmetric reconversion is used (pairs of experiments)

CCRExperiment(decay_expts, buildup_expts, T)

Create CCR experiment from lists of decay and buildup experiment files.

Arguments

• decay_expts: Vector of file paths to decay experiments
• buildup_expts: Vector of file paths to buildup experiments
• T: Relaxation time constant in seconds

For symmetric reconversion, provide pairs of experiments (2 decay + 2 buildup). For standard CCR, provide single experiments (1 decay + 1 buildup).

CESTExperiment <: FixedPeakExperiment

Chemical Exchange Saturation Transfer experiment with reference and saturation spectra.

Fields

• specdata: Spectral data and metadata
• peaks: Observable list of peaks
• frequencies: Vector of saturation frequencies in ppm

CESTExperiment(inputfilename; B1, Tsat, offsets, skipplanes, prompt)

Create CEST experiment from a pseudo-3D input file where the first plane is the reference and the remaining planes are saturation spectra at different frequencies.

CPMGExperiment <: FixedPeakExperiment

CPMG experiment with reference plane and relaxation planes.

Fields

• specdata: Spectral data and metadata
• peaks: Observable list of peaks
• vCPMG: Vector of CPMG frequencies in Hz (zero for reference)
• Trelax: Relaxation time in seconds

CPMGExperiment(inputfilename, Trelax, vCPMG; skipplanes=Int[])

Create CPMG experiment from a pseudo-3D input file. Zero frequency in vCPMG indicates the reference plane.

Abstract type representing an NMR experiment.

Subtypes must inherit from either FixedPeakExperiment or MovingPeakExperiment. See guide for implementing new experiment types.

Thrown inside a fit whose inputs have changed, or which the user cancelled.

FitGroup

Planes of a cluster sharing one grid and one mask, and so one design matrix, whose column p is peak p at unit amplitude over the masked points. grid spans the bounding box of the mask, z holds the observed points of each plane, and active marks the planes that constrain the lineshapes; a skipped plane still has its amplitudes measured, at the shapes the others determined.

Thrown inside a fit that has run past its time budget.

HetNOEExperiment

Heteronuclear NOE experiment with reference and saturated spectra.

Fields

• specdata: Spectral data and metadata
• peaks: Observable list of peaks
• saturation: Vector of booleans indicating saturated spectra

HetNOEExperiment(planefilenames, saturation)

Create hetNOE experiment from a list of input planes and a list of true/false values indicating where saturation has been applied.

IntensityExperiment <: FixedPeakExperiment

Generic experiment for measurement of intensity modulations across 2D spectra.

Fields

• specdata: Spectral data and metadata
• peaks: Observable list of peaks

LPREExperiment

Longitudinal and transverse paramagnetic relaxation enhancement experiment.

Fields

• specdata: Spectral data and metadata
• peaks: Observable list of peaks
• concentrations: Paramagnetic agent concentration of each spectrum, 0 or 1 for a pair
• paired: Whether the spectra are diamagnetic/paramagnetic pairs, so that Γ is in s⁻¹
• expttype: Either :hsqc or :hmqc
• Trelax: Transverse ¹H time outside acquisition and t₁ (s)
• recoverytimes: Time the ¹H magnetisation recovers before each scan (s)

LPREExperiment(diamagnetic, paramagnetic; type, recycledelays=nothing, Trelax=:auto,
               prompt=isinteractive())
LPREExperiment(inputfilenames; concentrations, type, recycledelays=nothing,
               Trelax=:auto, skipplanes=Int[], prompt=isinteractive())

Create an LPRE experiment from lists of diamagnetic and paramagnetic spectra, or from one list at the given paramagnetic agent concentrations. See lpre2d.

MethylCCRModel <: ParametricModel

Ratio model (eq 7) for methyl CCR buildup/decay analysis. Named to disambiguate from the single-delay CCRExperiment/ccr2d analysis. Carries the fixed prefactor C and the N relaxation delays times; func(T, p) evaluates eq 7 with p = [η, δ].

MovingExperiment <: MovingPeakExperiment

Generic experiment for measurement of peak positions that change across a series of 2D spectra. Unlike IntensityExperiment, where each peak sits at one chemical shift and only its amplitude is read out, here each peak's position (and linewidth) is an independent fit parameter in every plane. This is the common core for titrations, coupling-constant and RDC measurements: the spectrum fit recovers a per-plane position trajectory, and a postfit model turns that trajectory into a physical quantity.

Fields

• specdata: Spectral data and metadata
• peaks: Observable list of peaks (each holds per-plane :x, :y, :R2x, :R2y, :amp)
• x: Per-plane independent variable (e.g. ligand concentration); defaults to plane index
• model: Postfit model relating the position trajectory to the independent variable
• visualisation: Strategy for the per-peak plot panel

PREExperiment

Paramagnetic relaxation enhancement experiment.

Fields

• specdata: Spectral data and metadata
• peaks: Observable list of peaks
• concentrations: Paramagnetic agent concentration of each spectrum, [0, 1] for a pair
• paired: Whether the spectra are a diamagnetic/paramagnetic pair, so that Γ₂ is in s⁻¹
• expttype: Either :hsqc or :hmqc
• Trelax: Transverse ¹H time outside acquisition and t₁ (s)

PREExperiment(diamagnetic, paramagnetic; type, Trelax=:auto)
PREExperiment(inputfilenames; concentrations, type, Trelax=:auto, skipplanes=Int[])

Create a PRE experiment from a diamagnetic/paramagnetic pair of spectra, or from a series of spectra at the given paramagnetic agent concentrations. See pre2d.

PlaneGrid

The chemical shifts of one plane within a fitting window, with the axes that convert them to frequencies and carry the apodisation.

RDCModel

Derive a scalar coupling J and residual dipolar coupling D (both in Hz) from the peak position difference between paired component spectra. isotropic/aligned are the plane indices of the two components in each condition; couplingdim is the dimension the splitting is measured in; scale is the fraction of the coupling the measured separation represents (1 for IPAP, 0.5 for HSQC/TROSY); gammasign flips the sign for a negative-γ nucleus (¹⁵N).

ResidueLabel

Parsed representation of a peak label.

Fields

• resnum: residue number (negative for non-standard residue types, e.g. the default unassigned X# peaks; 0 if the label contains no digits)
• onelettercode: residue one-letter code ('?' if none could be identified)
• atom: atom name (uppercase, verbatim), or "" for backbone amides

ShapeFit

Peak shapes in fit coordinates. Positions are fitted as offsets from their starting point in units of the fitting radius, bounded by ±1, and linewidths as they are. A chemical shift of order a hundred ppm would otherwise set the scale of the relative convergence tolerance.

SummaryDataset

A named collection of SummaryPoints for one parameter, from one source (experiment or file).

SummaryPoint

One peak's contribution to a summary plot: identity plus a single value and its uncertainty.

TitrationModel

Fit a single-site (1:1) binding isotherm to a titration series, deriving a global dissociation constant Kd (shared by all residues) together with per-residue, per-dimension free and bound chemical shifts (δfree, δbound).

The bound fraction in each plane is computed from the ligand concentration (expt.x) and, if available, the protein concentration (protein, one per plane). With protein concentrations the exact 1:1 quadratic is used; with ligand concentrations only, the hyperbolic f = [L]/(Kd + [L]) approximation (ligand ≈ free) is used. The two are consistent in the limit [P] → 0.

Fields

• protein: Per-plane total protein concentration, or nothing when only ligand concentrations were supplied.
• weights: (wx, wy) dimension weights for the combined CSP (Williamson 2013); the default (1.0, 0.14) assumes the F1 (x) axis is ¹H and the F2 (y) axis is ¹⁵N.

Drop unassigned peaks (resnum ≤ 0), unless that would leave nothing to plot.

Rows of a series.csv belonging to each peak's first plane, in file order.

Value/uncertainty for param from a live peak (post-fit params first, then raw).

RDC summary: residual dipolar coupling D (Hz) against residue number.

_readtable(file) -> (header, rows)

Read a results.csv: skip blank and #-comment lines, take the first remaining line as the (comma- or whitespace-separated) header, the rest as rows of strings.

Titration summary: three stacked panels of the fitted saturation perturbation against residue number — ΔδX (= δbound − δfree, x dim), ΔδN (y dim, assuming ¹⁵N) and the weighted combination |Δδ|. Values are the extrapolated full-saturation CSPs from the global fit, so the experiment must have been fitted.

add_moving_overlays!(g, state, expt::MovingPeakExperiment)

Add the moving-peak overlays to the contour panel:

• a faint polyline tracing each peak's fitted position across all planes (the trajectory), so the walk is visible at a glance;
• a toggleable "Context" overlay drawing every other plane's contours faintly behind the current one, for orienting peaks that move a long way. Each plane gets its own colour from a fixed rainbow sequence (plane 1 red, plane 2 orange, …) so the direction of travel is visible at a glance; the current plane is excluded since it is already drawn, in full colour, by the main contour plot.

addandtrackpeak!(expt, initialposition, label="")

Add a peak at initialposition and track it across every plane by following the local maximum: the current plane is anchored at the click, then the position is propagated outward in both directions, each plane seeded from its neighbour's tracked position. The subsequent fit then refines each plane within its radius. Good for non-crowded series (titrations); for crowded regions, add with A and adjust planes by hand instead.

addlinepeak!(expt, a, b, label="")

Add a peak placed, in each plane, at the maximum along the line from a to b (see linemaximum). The fit then refines each plane within its radius.

Add peak to experiment, setting up per-plane position, linewidth and amplitude parameters.

Add peak to experiment, setting up type-specific parameters.

Add peak to experiment, setting up type-specific parameters.

Add peak to experiment, setting up type-specific parameters.

Add peak to experiment, setting up type-specific parameters.

Add peak to experiment, setting up type-specific parameters.

Add peak to experiment, setting up type-specific parameters.

Least-squares amplitudes, one column per plane, tolerating coincident peaks.

Return formatted text describing experiment.

Return formatted text describing experiment.

Return formatted text describing experiment.

Return formatted text describing experiment.

asexptpath(x)

Coerce an experiment identifier (or a collection of them) to the path-string form the file loaders expect: an integer becomes its Bruker experiment number as a string (e.g. 1 -> "1", loaded relative to the working directory, as for the 1D functions' own exptno arguments), broadcasting elementwise over a collection of them (e.g. 1:11 -> ["1", ..., "11"]); anything else (a string, or an existing collection of strings) passes through unchanged.

available_params(source) -> Vector{Symbol}

Parameters that can be plotted from a live experiment (post-fit and raw parameter keys) or a saved file (value columns, excluding identity columns).

average_displacements(expt) -> (dx, dy) | nothing

Mean per-plane position displacement of the already-fitted peaks, relative to the current plane (so dx/dy are zero at that plane). Used to seed a new peak's planes with the common motion pattern. Returns nothing if no peak has been fitted yet.

backup_file(filepath::AbstractString)

Create a backup of an existing file by appending '.old'.

batchupdate(f, expt)

Call f() with the masking, clustering and fitting that follow each change to the peaks held back, then do them once. Adding a peak list one peak at a time would otherwise redo all three, and start and abandon a fit, for every peak.

Begin a guided add at the current plane, marking it immediately at pos.

Begin marking a line at pos.

bumpradius!(expt, idx, key)

Widen or narrow peak idx's radii by one step, x with the left and right arrows and y with up and down, giving it radii of its own.

Abort the guided add and return to the original plane.

Abandon the line being marked.

ccr2d(decay_expts, buildup_expts, T; skipplanes=nothing, prompt=isinteractive())
    -> CCRExperiment

Start interactive GUI for analysing 2D measurements of cross-correlated relaxation data.

Fits intensities of peaks in a series of 2D spectra to a model of the form:

tanh(η * T) = I_buildup / I_decay

or

tanh(η * T) = sqrt((I_buildup1 * I_buildup2) / (I_decay1 * I_decay2))

Arguments

• decay_expts: List of NMR data files for decay experiments
• buildup_expts: List of NMR data files for buildup experiments
• T: Relaxation time constant (in seconds)

Example:

ccr2d("decay_expt", "buildup_expt", 0.08)    # single decay and buildup experiment

ccr2d(["decay_expt1", "decay_expt2"],        # symmetric reconversion experiments
      ["buildup_expt1", "buildup_expt2"], 0.08)

Experiments can also be given as Bruker experiment numbers, individually or as a list/range (e.g. 1:3). If T is omitted you are asked for it.

skipplanes lists planes (1-based, decay and buildup interleaved in the order given) left out of the ratio; at least one decay and one buildup plane must remain, and a symmetric measurement with a plane skipped is reduced to the ratio of the mean intensities. The window blocks until it is closed, and the analysis is returned (see results).

cest2d(inputfilename; B1, Tsat, offsets, skipplanes=nothing, prompt=isinteractive())
    -> CESTExperiment

Start interactive GUI for analysing 2D CEST (Chemical Exchange Saturation Transfer) data. The window blocks until it is closed, and the analysis is returned (see results).

Each parameter is taken from its keyword if given, else from the pulse-sequence annotations (cest.power with the reference pulse of cest.channel, cest.duration, cest.offset), else for the offsets from the fq3list, and otherwise you are asked for it.

Arguments

• inputfilename: NMR data file as a processed data directory containing pseudo-3D data where the first plane is the reference spectrum and subsequent planes are the saturation spectra
• B1: Saturation field strength in Hz
• Tsat: Saturation time in seconds
• offsets: Saturation offsets in ppm, one per plane including the reference
• skipplanes: Planes (1-based) left out of the fitting. The reference, plane 1, cannot be skipped.

Example:

cest2d("path/to/expno/pdata/1"; B1=15, Tsat=0.3)

checklength(values, n, name) -> values

values, checked to give one per plane.

Check the sequence type and that the concentrations give one per spectrum, and two or more.

checkskipplanes(skipplanes, n) -> Vector{Int}

The planes to skip, checked to lie within 1:n and to leave at least one plane to fit. nothing skips none.

checktouched!(expt)

Update which clusters have been modified.

choosepeaklist() -> Union{String,Nothing}

A peak list chosen in a file dialog, or "" for none. On Linux the dialog is not opened, and nothing is returned: the GTK it uses can abort Julia when the system's GTK settings schema lacks a key it expects (show-type-column), so a warning says how to load a list instead.

Update experiment with non-overlapping clusters for fitting (e.g. [[1], [2, 3]])

Write a shape fit into peaks: their shapes in plane i, and their amplitudes.

Write a model fit into peaks.

commitondefocus!(tb::Textbox)

Commit tb's displayed text to stored_string when it loses focus. Makie's Textbox only commits on Enter; clicking away otherwise leaves the typed text on screen without ever applying it to stored_string (and hence to whatever listens on it).

continuefit!(expt; budget=CONTINUE_TIME_BUDGET)

Fit the peaks still awaiting a fit, if any, as an ordinary fit. Otherwise refit the peaks whose last fit was stopped before it finished (see iscontinuable), starting from where it stopped, with budget seconds per cluster. Returns the fit's task, or nothing where there is nothing to fit, which the status line then reports.

convergefit!(expt; maxrounds=100)

Fit the peaks awaiting a fit, then continue the stopped fits without a time limit, round after round, until none is left stopped short. It also ends when a round no longer moves any position or linewidth, after maxrounds rounds, or when the fit is cancelled with Esc or superseded by a change to the peaks.

coordinatename(model) -> Symbol

What the per-plane x of an experiment fitted with model actually is. The generic fallback is the uninformative :x, which is the honest answer for a model fitted against whatever the caller supplied (modelfit2d).

Inverse of a symmetric positive-definite matrix, or NaNs where it is singular.

cpmg2d(inputfilename; Trelax, vCPMG, skipplanes=nothing, prompt=isinteractive())
cpmg2d(inputfilename; Trelax, ncyc, skipplanes=nothing, prompt=isinteractive())
    -> CPMGExperiment

Start interactive GUI for analysing 2D CPMG relaxation dispersion data. The window blocks until it is closed, and the analysis is returned (see results).

The CPMG frequencies are taken from vCPMG, else from ncyc, else from the cycle numbers in the vclist; Trelax is taken from its keyword. Anything missing is asked for.

Arguments

• inputfilename: NMR data file as a processed data directory containing pseudo-3D data where the first plane is the reference spectrum and subsequent planes are the saturation spectra
• Trelax: Relaxation time in seconds
• vCPMG: list of CPMG frequencies in Hz, use zero for reference spectrum
• ncyc: list of CPMG cycle numbers, use zero for reference spectrum. When provided, vCPMG is calculated as ncyc/Trelax
• skipplanes: Planes (1-based) left out of the fitting. At least one reference plane must remain.

Examples:

# Direct specification of CPMG frequencies
cpmg2d("path/to/expno"; Trelax=0.04, vCPMG=[0, 25, 50, 75, 100])

# Using cycle numbers (vCPMG calculated automatically)
ncyc = [0, 1, 2, 3, 4]
cpmg2d("path/to/expno"; Trelax=0.04, ncyc=ncyc)

# Cycle numbers from the vclist
cpmg2d("path/to/expno"; Trelax=0.04)

deleteallpeaks!(expt)

Remove all peaks from the experiment.

deletepeak!(expt, idx)

Delete peak idx. Updates clusters automatically.

Delete the selected peak, if there is one, and say which in the status line.

derivedkeys(expt) -> Vector{Symbol}

Derived parameter names for results.csv, the experiment's primaryparam first and anything global left out.

The column of the design matrix of group for one peak of shape φp.

designmatrix(group, φ) -> Matrix

The design matrix of group for peak shapes φ (x, y, R2x and R2y of each peak in turn).

displaygrid(peak, expt, i) -> (xi, yi, grid)

The rows xi and columns yi of plane i within twice the radii of where peak was placed, and their grid: its mask, and the window of its radii about any position the fit can reach, which the cross-sections show.

Follow the cursor with the free end of the line being marked.

Convert a cross-correlated relaxation rate η (s⁻¹) to S²τc in ns (eq 1).

Return formatted text describing experiment.

Return formatted text describing experiment.

extract_residue_number(label)::Int

Residue number for label (see parse_label). Negative for non-standard residue types; 0 if no digits are present.

Fill every not-yet-marked plane with pos, then finish.

Create the peak from the marked positions, return to the original plane, leave :adding.

Finish the line at pos and add a peak along it.

fit!(expt; warm=false)

Fit every touched cluster in the background, then the post-fits, then notify the peaks once.

A newer fit, a change to the peaks, switching fitting off or closing the window supersedes this one: it stops at its next step and commits nothing. A cluster that runs past its time budget keeps its previous values and is marked :timeout; warm=true continues such clusters from their last values with a longer budget (see continuefit!).

fit2d(inputfilenames; skipplanes=nothing) -> IntensityExperiment

Start an interactive GUI for peak analysis of a single 2D spectrum or a series of 2D spectra. Each peak is fitted to a 2D Lorentzian lineshape; no physical model is applied to the amplitudes across spectra.

Use this function to measure peak positions, linewidths, and amplitudes for downstream analysis, or when none of the built-in physical models (relaxation2d, recovery2d, modelfit2d) are appropriate. The window blocks until it is closed, and the analysis is returned (see results).

Arguments

• inputfilenames: A single path string or vector of path strings pointing to processed Bruker data directories (e.g. "expno/pdata/1"). Bruker experiment numbers work too.
• skipplanes: Planes (1-based) left out of the lineshape fit. They are still displayed, and their amplitudes still measured.

Example

# Single spectrum
fit2d("109/pdata/1")

# Series of spectra (e.g. titration or temperature series)
fit2d(["11/pdata/1", "12/pdata/1", "13/pdata/1"])

fitcheck(expt, generation, budget) -> Function

A check for a fit started at generation: it throws FitCancelled once the fit has been superseded and FitTimeout once budget seconds have passed. Single-threaded, it also yields so that the window can register a cancellation.

fitcluster!(peaks, expt, check; warm=false) -> Symbol

Fit one cluster of overlapping peaks and write the results into them, returning how the fit ended. A fixed-peak series is fitted jointly across its planes, sharing one set of shapes; a moving-peak series is fitted plane by plane, since its shapes change from one to the next.

fitclusters!(expt, clusters, generation, budget; warm=false) -> Vector{Symbol}

Fit each cluster (a vector of peaks), in parallel when Julia has more than one thread, and return how each ended, :cancelled included. Progress is published to state[:fitprogress].

Call this from the main thread. The worker threads only compute and write into the peaks' parameter arrays; every observable, and so every plot, is updated from the calling task, since GLMakie cannot update a plot from another thread.

fitgroups(expt, masks, planes; skip=Set{Int}()) -> Vector{FitGroup}

Gather planes into groups sharing a grid and a mask, given each plane's cluster mask.

fitmodel(peaks, groups, expt, check; warm=false) -> NamedTuple

Fit peaks across every unskipped plane of groups with one amplitude each, returning the fitted parameters φ and their errors, the amplitudes a, and for every peak (row) and plane (column) its linewidths, its fitted height and its height measured at those linewidths, each with an error. Errors come from the covariance of the full problem, amplitudes included, σ²(JᵀJ)⁻¹.

fitshapes(peaks, groups, i, check; warm=false) -> NamedTuple

Fit the shapes of peaks in plane i (the shared shapes of a fixed-peak series, or one plane of a moving-peak series) to groups, returning the shapes φ and their errors, each plane's amplitudes and errors, and the fit's status. A cold start begins from the placed positions and the initial linewidths, a warm one from the last fitted values. check is called at every step and throws to stop the fit; nothing is written to the peaks here.

fitstatus(peak) -> Symbol

How the last lineshape fit of peak ended: :unfitted, :converged, :maxiter (stopped at the iteration limit), :bound (a position or linewidth finished on its limit) or :timeout (stopped at the time limit, leaving the previous values in place).

fittedamplitudes(peak, expt) -> Vector{Float64}

The model evaluated at each plane's own coordinate, for the amp_fit column of series.csv, so that a residual is a subtraction. NaN (written NA) for every plane where nothing was fitted through the amplitudes themselves: a heteronuclear NOE, a CCR rate and a CEST profile are fitted from ratios or from transformed intensities, so no curve passes through the amplitudes to report.

format_param(peak, param, slice, value_type) -> String

Format a parameter value, returning "NA" if not found.

Format a post-fit parameter value/uncertainty, returning "NA" if absent.

get_titration_data(peak, expt) -> (obsX, obsY, fitX, fitY)

Per-dimension Δδ-vs-concentration points for the highlighted residue: observed points (obsX/obsY) and the fitted binding curve (fitX/fitY, empty until the global fit runs). The Y series (F2 dimension) is divided by the standard heteronuclear scaling factor (_yshiftscalefactor, 10 for ¹⁵N / 4 for ¹³C) so it can be overlaid on the same axis as X.

globalparams(expt) -> Vector{Symbol}

Derived parameters fitted once across every peak rather than per peak, and so belonging in global.csv. A titration's Kd is fitted globally and then copied onto every peak, so writing it in results.csv would repeat one number down a column.

Declared beside the postfitglobal! that computes it - see globalparams(::TitrationModel) in expt-moving.jl.

globaltable(expt) -> (header, rows)

Column names and rows for global.csv: the parameters globalparams names, read from the first peak that carries them, since a global fit gives every peak the same value.

gui!(expt; peaklist=nothing, call=nothing) -> expt

Open the analysis window for expt, loading the peaks in the file peaklist if one is given, and wait until it is closed, returning expt with its fitted peaks (see results and planeresults). call is the AnalysisCall the entry point recorded, written to summary.txt so the analysis can be repeated.

has_atom_labels(labels)::Bool

true if any label in the iterable carries an atom name (e.g. methyls such as "I13CD1"), used to decide between scatter and bar summary plots.

headercolumns(filepath) -> Dict{String,Int} or nothing

The column positions of filepath's header row, lowercased and with units stripped, or nothing where the first non-comment line is data rather than a header (a hand-made label x y list).

hetnoe2d(reference, saturated; skipplanes=nothing) -> HetNOEExperiment

Start interactive GUI for analysing 2D heteronuclear NOE data.

reference and saturated can each be a single filename or a list of filenames — Bruker experiment numbers work too, individually or as a list/range. When lists are provided, results are averaged across all pairs.

Examples

# Single reference / saturated pair
hetnoe2d("expno1/pdata/231", "expno1/pdata/232")

# Multiple pairs (results are averaged across pairs)
hetnoe2d(
    ["expno1/pdata/231", "expno2/pdata/231"],  # references
    ["expno1/pdata/232", "expno2/pdata/232"],  # saturated
)

# Bruker experiment numbers
hetnoe2d(1, 2)

skipplanes lists planes (1-based, counting reference and saturated planes in the order they are interleaved) left out of the averages; at least one of each must remain. The window blocks until it is closed, and the analysis is returned (see results).

Where peak was placed, one Point2f for every plane or one per plane.

initialslice(expt) -> Int

The plane the window opens on: the first, unless the experiment says otherwise.

Heights relative to the diamagnetic reference, a series for each paramagnetic plane.

Whether the last fit of peak was stopped before it finished, so continuing it helps.

Whether the line has been dragged out further than half a fitting radius.

issparkylist(filepath) -> Bool

Whether filepath looks like a Sparky peak list: a whitespace-delimited file whose first non-comment line names an Assignment column.

Whether one of the window's text boxes has the keyboard, so keys are text, not commands.

Whether the last fit of peak ended anywhere other than a converged optimum.

linemaximum(expt, i, a, b) -> (x, y)

The most intense grid point of plane i along the line from a to b, sampled finely enough to visit every grid point the line crosses.

lpre2d(diamagnetic, paramagnetic; type, recycledelays=nothing, Trelax=:auto,
       peaklist=nothing, prompt=isinteractive()) -> LPREExperiment
lpre2d(inputfilenames; concentrations, type, recycledelays=nothing, Trelax=:auto,
       skipplanes=nothing, peaklist=nothing, prompt=isinteractive()) -> LPREExperiment

Start an interactive GUI for analysing longitudinal and transverse ¹H paramagnetic relaxation enhancements together, from diamagnetic and paramagnetic spectra recorded at a series of recycle delays. Every peak is fitted across all the spectra at once, with one diamagnetic amplitude, linewidths and R₁, and the enhancements Γ₁ and Γ₂. Γ₂ is then free of the bias that incomplete recovery gives at short delays.

Give lists of diamagnetic and paramagnetic spectra for a spin-labelled or metal-tagged protein, and Γ₁ and Γ₂ are in s⁻¹. Give one list with its concentrations for a solvent PRE, and they are in s⁻¹ per unit of concentration, in whatever unit you used.

Arguments

• diamagnetic, paramagnetic: lists of processed Bruker data directories, or experiment numbers, one per recycle delay.
• inputfilenames: a list of processed data directories, or experiment numbers.
• concentrations: the paramagnetic agent concentration of each spectrum, 0 for the diamagnetic reference.
• type: :hsqc or :hmqc, as for pre2d.
• recycledelays: the time (s) the ¹H magnetisation recovers between scans, one per spectrum (diamagnetic first), or for two lists one list applied to both. Used exactly as given. By default each spectrum's d1 plus its acquisition time.
• Trelax: the transfer time, as for pre2d.

Examples

# Spin-labelled protein, nine recycle delays each
lpre2d(10:2:26, 11:2:27; type=:hmqc)

# Solvent PRE with 2 mM Gd, nine delays without and nine with
lpre2d([10:18; 103:111]; concentrations=[fill(0, 9); fill(2, 9)], type=:hmqc)

Each peak is plotted as its height against recovery time, a series and fitted curve for each concentration. The summary plots Γ₂, Γ₁, the height in each paramagnetic spectrum relative to the diamagnetic one at the same delay, and the diamagnetic R₂ and R₁ against residue number. The window blocks until it is closed, and the analysis is returned (see results).

Generate adjacency matrix for peak overlap

Record pos for the plane currently being marked and advance (or finish).

mask!(expt::Experiment)

Calculate masks for all peaks and update specdata.

mask(peaks, expt) -> Vector{BitMatrix}

The mask of a cluster of peaks, one matrix per plane. Planes sharing a grid in a fixed-peak experiment share one matrix.

maxR2(axis, δ, radius) -> Float64

The broadest linewidth the fitting window can determine: a Lorentzian whose full width at half height, R2/π, spans twice the window (four radii). Anything broader is barely curved across the window, so widening the radius is what allows a broader line.

methylccr2d(buildupexpt, decayexpt, T=nothing; C=3/4, skipplanes=nothing,
            prompt=isinteractive()) -> IntensityExperiment

Start an interactive GUI for methyl ¹H–¹H cross-correlated relaxation analysis.

For each peak, the ratio of buildup to decay intensities |Iₐ/I_b| is measured across a series of relaxation delays T and fitted to eq 7 with two parameters: the cross-correlated relaxation rate η (s⁻¹) and a coupling term δ (< 0). The fitted η is converted to the methyl order parameter × tumbling time S²τc (ns) via eq 1 (ideal methyl geometry), which is the parameter shown in the summary plot. The window blocks until it is closed, and the analysis is returned (see results).

Arguments

• buildupexpt: buildup series (Iₐ) — a single pseudo-3D path string, or a Vector{String} of per-delay 2D data directories. Bruker experiment numbers work too, individually or as a list/range.
• decayexpt: decay series (I_b), in the same form as buildupexpt.
• T: vector of relaxation delays in seconds, or a path string to a text file of delays (one per line; lines beginning with # are ignored). Each series must have one plane per delay. If omitted, the delays are read from the buildup series' annotations or vdlist, or asked for.

Keyword Arguments

• C: fixed prefactor in eq 7. 3/4 (default) for triple-quantum (TQ); 1/2 for double-quantum (DQ).
• skipplanes: optional list of delay indices (1-based, into T) to exclude from the fitting, in both series. Skipped points appear as open grey markers.
• prompt: Whether to ask for delays that cannot be found (default: when interactive).

Example

# buildup and decay each as a pseudo-3D dataset
methylccr2d("11/pdata/1", "12/pdata/1", [0.001, 0.002, 0.004, 0.006, 0.010])

# double-quantum variant
methylccr2d("11/pdata/1", "12/pdata/1", "vdlist.txt"; C=1/2)

modelfit2d(inputfilenames, xvalues, equation, parameters, xlabel="x";
           skipplanes=nothing, prompt=isinteractive())

Create an intensity analysis experiment with fitting to a custom equation. The window blocks until it is closed, and the analysis is returned (see results).

Arguments

• inputfilenames: String or vector of strings giving the input data files.
• xvalues: Vector of Float64 giving the x values for fitting, or string giving a filename from which to read the x values. nothing asks for them.
• equation: String giving the model equation to fit, e.g. "A*sin(J*x)"
• parameters: Vector of parameter name-value pairs giving initial parameter values, e.g. ["A"=>40., "J"=>0.5]
• skipplanes: Planes (1-based) to exclude from the fitting.

Example: J-modulation

modelfit2d(["112","113","114","115"],
    [0.1, 0.2, 0.3, 0.4],
    "A*sin(J*x)",
    ["A"=>40., "J"=>0.5])

modelparameters(expt) -> Vector{NamedTuple}

The parameters fitted for every peak besides its position and diamagnetic linewidths, each as (key, label, initial, lower, upper, scale). scale is the size of a typical value, so that a rate per unit concentration is fitted on the same footing whatever the unit.

Fit coordinates for peaks: positions and linewidths as ShapeFit, then the model.

movepeak!(expt, idx, newpos)

Move peak idx to newpos. Updates clusters automatically.

v, or nothing where it is empty, so that an unused option is left out of a call record.

notice!(expt, text)

Show text in the status line until the peaks are next changed or fitted.

Say in the status line that the newest peak was added, and how.

npeaks(expt::Experiment)

Number of peaks currently in the experiment.

nslices(expt::Experiment)

Number of spectra in the experiment.

A summary panel of one parameter of peaks, from their fitted values.

paramunit(expt, name) -> String

ASCII unit for a fitted or derived parameter, as it appears in a column header. Experiment-dispatched, so an experiment introducing its own parameters declares their units in its own expt-*.jl rather than here; the default falls back to the shared table above and then to no unit.

parse_label(label)::ResidueLabel

Best-effort parse of a peak label into residue number, one-letter code, and atom name. Handles, e.g.:

• Amides: "G10", reversed "7A"
• Methyls/sidechains: "I13CD1", "L26CD1"/"L26CD2", "V70CG1", "M98CE"
• Nucleic-acid atoms: "A12C8", "G5C1'"
• Non-standard/unassigned: "X99" → resnum -99

This function is deliberately permissive: it never throws. Unrecognised input simply yields a best guess (e.g. ResidueLabel(0, '?', "") for an empty or number-less label). Parsing is metadata only and must never block fitting, saving, or loading — users may use any labelling convention they like.

parse_radius_comment!(expt, line)

If line records an X/Y fitting radius (as written by writeresults!, e.g. # X radius / ppm: 0.04), apply it to the experiment, and return what it recorded as (x, y), each nothing where absent. Generic to all 2D experiments.

peakcolour(peak) -> Symbol

Red while a peak awaits fitting, orange where its last fit stopped short of a converged optimum, blue once fitted.

Return formatted text describing peak idx.

Return formatted text describing peak idx.

Return formatted text describing peak idx.

Generic handler for peak info text

Return formatted text describing peak idx.

Return formatted text describing peak idx.

peaklisttable(expt) -> (header, rows)

Column names and rows for peaklist.csv: where the user put each peak, as opposed to where the fit moved it to. One row per peak, or one row per peak per plane where the positions were placed plane by plane.

The distinction matters because these are different things with different lives. A peak list is an input: you pick it once, reuse it on another dataset, hand it to a colleague, or import it from elsewhere. A fitted position is an output of one particular fit. Reading back the fitted positions as the next run's starting point - which is what loading results.csv used to do - conflates the two, and for a moving-peak experiment there is no single fitted position to read.

plane is left blank for a peak whose initial position is one value for the whole experiment, meaning the row applies to every plane, and carries the plane number where the peak was tracked across them. The radii are per-peak and repeat down that peak's rows.

peakmodel(expt::LPREExperiment, cond, R2x, R2y, (R1, Γ1, Γ2)) -> (R2x, R2y, height)

The transverse model of transverseplane, with the height scaled by the recovery of the ¹H magnetisation from saturation, 1 - exp(-(R₁ + Γ₁c)τ), after a recovery time τ (Pintacuda & Otting, J. Am. Chem. Soc. 124, 372 (2002)). R₁ and Γ₁ are therefore apparent rates for the sequence used, which a selective or band-selective sequence makes faster.

peakshape(grid, x0, y0, R2x, R2y) -> Matrix

A unit-amplitude peak at every point of grid.

peaktrack2d(inputfilenames; skipplanes=nothing) -> MovingExperiment

Start an interactive GUI for analysing a series of 2D spectra in which peak positions change from plane to plane (e.g. a titration, or a coupling-constant / RDC measurement). Each peak is fitted to a 2D Lorentzian lineshape independently in every plane, so its position and linewidth are free to move; no physical model is applied to the trajectory.

Use this to measure how peak positions and linewidths evolve across a series for downstream analysis, or as the basis for the position-based physical models (titration, coupling).

The window blocks until it is closed, and the analysis is returned (see results).

Arguments

• inputfilenames: A single path string (pseudo-3D dataset) or a vector of path strings (one file per plane) pointing to processed Bruker data directories. Bruker experiment numbers work too, individually or as a list/range (e.g. 1:11), resolved relative to the working directory.
• skipplanes: Planes (1-based) marked as skipped. They are still fitted and displayed.

Example

peaktrack2d(["11/pdata/1", "12/pdata/1", "13/pdata/1"])
peaktrack2d(1:11)

See also titration2d for fitting binding isotherms to a titration series.

One entry for each kind of peak whose fit is not finished, saying what finishes it.

planedesign(expt, group, i, φ; scaled=true) -> Matrix

The design matrix of plane i of group: column p is peak p with the linewidths it has in that plane, at its diamagnetic height (scaled) or at unit height.

planeresults(expt) -> Vector{NamedTuple}

One row per peak per plane: its label, the plane, the fitstatus, the plane's coordinates (a delay, an offset, a concentration...) and the fitted amplitude, position and linewidths there, each as a value ± error. The counterpart of series.csv.

Linewidths and relative height in plane i of a peak with fit parameters φp.

Where plane i came from. One file per plane for a multi-file experiment; the same pseudo-3D dataset for every plane otherwise.

planevalues(f, specdata) -> Vector or nothing

f(spec) for each spectrum behind specdata, concatenated into one value per plane, or nothing if any spectrum has none.

Fitted position of peak, one Point2f for every plane or one per plane.

Calculate final parameters after fitting.

Computes CCR rate η from the model:

• Single experiments: tanh(η * T) = Ibuildup / Idecay
• Symmetric (pairs): tanh(η * T) = sqrt((Ibuildup1 * Ibuildup2) / (Idecay1 * Idecay2))

Calculate final parameters after fitting.

Calculate final parameters after fitting.

Calculate final parameters after fitting.

Calculate final parameters after fitting.

pre2d(diamagnetic, paramagnetic; type, Trelax=:auto, peaklist=nothing) -> PREExperiment
pre2d(inputfilenames; concentrations, type, Trelax=:auto, skipplanes=nothing,
      peaklist=nothing) -> PREExperiment

Start an interactive GUI for analysing ¹H transverse paramagnetic relaxation enhancement (PRE) experiments. Every peak is fitted across all the spectra at once, with one diamagnetic amplitude and linewidths, and the PRE rate Γ₂ accounting for both the line broadening and the intensity lost during the coherence transfer delays.

Give a diamagnetic and a paramagnetic spectrum for a spin-labelled or metal-tagged protein, and Γ₂ is in s⁻¹. Give a series of spectra with their concentrations for a solvent PRE, and Γ₂ is in s⁻¹ per unit of concentration, in whatever unit you used.

Arguments

• diamagnetic, paramagnetic: processed Bruker data directories, or experiment numbers.
• inputfilenames: a list of processed data directories, or experiment numbers, one per concentration point.
• concentrations: the paramagnetic agent concentration of each spectrum, 0 for the diamagnetic reference.
• type: :hsqc or :hmqc. In an HMQC, ¹H is transverse during t₁ as well, so the PRE also broadens the indirect dimension.
• Trelax: the time (s) for which ¹H magnetisation is transverse outside the acquisition and t₁, during which the PRE attenuates the signal. :auto takes 1/¹J, the total of the transfer delays in a plain HSQC or HMQC, with ¹J = 92 Hz for ¹⁵N and 125 Hz (methyl) for ¹³C. Give the time explicitly for a sensitivity-enhanced or other sequence.

Examples

# Spin-labelled protein: diamagnetic and paramagnetic samples
pre2d("diamagnetic/pdata/1", "paramagnetic/pdata/1"; type=:hsqc)

# Methyl HMQC, with experiment numbers and an explicit transfer time
pre2d(11, 12; type=:hmqc, Trelax=0.0089)

# Solvent PRE, concentrations in mM
pre2d([10, 11, 12, 13]; concentrations=[0, 1, 5, 10], type=:hmqc)

Each peak is plotted as cross-sections through both spectra for a pair, or as its height against concentration for a series. The summary plots Γ₂, the height in each paramagnetic spectrum relative to the diamagnetic one, and the diamagnetic linewidths against residue number. The window blocks until it is closed, and the analysis is returned (see results).

primaryparam(expt) -> Symbol

The experiment's primary derived (post-fit) result. It is written first among the derived columns in results.csv and is the default parameter plotted by summaryplot. Defaults to :amp (peak amplitude) for experiments that derive no post-fit parameters (e.g. plain fit2d).

Close the GUI window, deferred so the click/keypress event finishes first.

The radii of peak idx for the info panel, where it has radii of its own.

rdc2d(; isotropic, aligned, components=("a","b"), coupling=nothing, scale=1)

Interactive measurement of one-bond couplings and residual dipolar couplings from paired 2D spectra. Supply the two doublet-component spectra (already combined, e.g. IPAP α/β, or HSQC/TROSY) for each condition:

rdc2d(isotropic = ["iso_a/pdata/1", "iso_b/pdata/1"],
      aligned   = ["aln_a/pdata/1", "aln_b/pdata/1"])

The four spectra become the planes of a peak-tracking experiment. Track each residue's peak across the planes (T) or add and adjust by hand (A); the per-residue postfit then reports

J   = sep(isotropic) / scale
J+D = sep(aligned)   / scale
D   = (J+D) − J

where sep is the position difference between the two components in the coupling dimension (converted to Hz). scale is 1 for IPAP and 0.5 for HSQC/TROSY (the separation is then half the coupling). components names the two, for the component column of series.csv, e.g. ("TROSY", "anti-TROSY"). coupling selects the dimension (:F1/:F2); it defaults to the heteronuclear dimension, and the sign is flipped automatically for ¹⁵N (so J ≈ −93 Hz). List the two components in the same order for both conditions; if J comes out with the wrong sign, swap the pair. Each component can also be given as a Bruker experiment number.

readpeaklist!(expt, filepath::AbstractString)

Read a peak list and add the peaks to expt. Only the label, x and y columns are used — every other column (resnum, resname, atom, linewidths, amplitudes, derived parameters …) is ignored, since the residue number and atom are re-derived from the label.

Two layouts are accepted:

• With a header row (e.g. the program's own results.csv): the first non-comment line contains a label column name, and x/y are located by name, so column order and extra columns don't matter.
• Without a header (a hand-made list): values are read positionally as label x y from the first three columns, so no exact column names are needed.

Fields may be comma- or whitespace-separated. Lines beginning with # are comments. A malformed line is skipped with a warning rather than aborting the load — any labelling convention is tolerated.

readsparkylist!(expt, filepath) -> Int

Import a Sparky peak list, adding its peaks to expt.

Sparky names its dimensions w1, w2 in the spectrum's own order, which for a ¹⁵N-HSQC conventionally puts the indirect dimension first - the opposite way round from this program, whose x is the direct dimension. Reading the columns in order would therefore transpose every peak, so which column goes to which axis is decided by sparkyaxisorder from where the shifts actually fall, and only falls back to the convention when that cannot tell.

The assignment string becomes the peak label unchanged: Sparky's G10N-G10H and a plain G10 both survive a round trip, and parse_label already derives the residue number and atom from whatever form it is given.

readtrackedpeaks!(expt, filepath, columns) -> Int

Restore peaks from a file holding one row per peak per plane - peaklist.csv, or a series.csv read as a fallback. Each peak is added at its first row's position and the whole trajectory is then set on it, so hand-tracking survives a save and reload.

A peaklist.csv row whose plane is blank means one position for every plane, so such a peak is added with a single position rather than a trajectory; that is also what a hand-made list or an imported Sparky list produces.

A peak whose xradius and yradius differ from the default radii recorded in the file's comments keeps them as radii of its own.

readvalues(x) -> Vector{Float64}

Values given as a vector, a number, or the path of a file holding one per line (lines beginning with # are comments), or a vector mixing these.

recovery2d(inputfilenames; relaxationtimes, ncyc, cycletime, skipplanes, prompt)
recovery2d(inputfilenames, relaxationtimes; kwargs...)

Start an interactive GUI for measuring longitudinal relaxation from an inversion recovery or saturation recovery experiment. Peak amplitudes are fitted to a magnetisation recovery model:

\[I(\tau) = A\left(1 - C\exp(-R\tau)\right)\]

where $R$ is the recovery rate (s⁻¹), $A$ is the equilibrium amplitude, and $C$ is the recovery factor. For an ideal inversion recovery experiment $C = 2$; for saturation recovery $C = 1$. The window blocks until it is closed, and the analysis is returned (see results).

The delays are resolved as for relaxation2d, whose keyword arguments this shares.

Example

t = [0.1, 0.2, 0.4, 0.7, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0]
recovery2d("33/pdata/1"; relaxationtimes=t)

# Reading delays from a file
recovery2d("33/pdata/1"; relaxationtimes="vdlist.txt")

recoverytimes(spectra, recycledelays; prompt) -> Vector{Float64}

recycledelays exactly as given, or else each spectrum's d1 plus its acquisition time, TD/(2 SW_h) in the directly detected dimension, during which the ¹H magnetisation also recovers. Asked for where the acquisition parameters are missing.

relativeintensity(peak, expt, i) -> Measurement or nothing

The height of peak in paramagnetic plane i relative to its mean height in the diamagnetic planes it is compared with (see referenceplanes), or nothing where there are none.

relaxation2d(inputfilenames; relaxationtimes, ncyc, cycletime, skipplanes, prompt)
relaxation2d(inputfilenames, relaxationtimes; kwargs...)

Start an interactive GUI for measuring R1 or R2 relaxation rates from a series of 2D spectra. Peak amplitudes are fitted to a mono-exponential decay:

\[I(\tau) = A \exp(-R\tau)\]

where $R$ is the relaxation rate (s⁻¹) and $A$ is the peak amplitude. The software does not distinguish R1 from R2 — the appropriate interpretation depends on the experiment. The window blocks until it is closed, and the analysis is returned (see results).

The delays are taken from relaxationtimes if given; else from the loop counts ncyc times the loop duration cycletime; else from the relaxation.duration annotation; else from the vdlist; else from the vclist times cycletime; and if none of those is available you are asked for them, as you are for a cycletime that is needed and not given.

Arguments

• inputfilenames: A single path string (pseudo-3D dataset) or vector of path strings (one file per delay) pointing to processed Bruker data directories. Bruker experiment numbers work too.

Keyword Arguments

• relaxationtimes: Delays in seconds, one per plane, or the path of a text file holding one per line (lines beginning with # are ignored).
• ncyc: Loop counts, one per plane, or the path of a file holding them, for an experiment whose delay is a number of loops of fixed duration.
• cycletime: The duration in seconds of one loop, which multiplies ncyc or the vclist.
• skipplanes: Planes (1-based) to exclude from the fitting. All spectra are still loaded and displayed; skipped planes appear as open grey markers in the peak plot and are not used when fitting R or A. The full list of relaxation times must still be provided, including those for skipped planes.
• peaklist: A peak list to load as the window opens, such as a saved peaklist.csv. Every 2D routine takes this.
• prompt: Whether to ask for anything that cannot be found (default: when interactive).

Example

relaxation2d(["11/pdata/1", "12/pdata/1", "13/pdata/1", "14/pdata/1"];
             relaxationtimes=[0.010, 0.030, 0.060, 0.100])

# A pseudo-3D dataset whose delays are in its vdlist or annotations
relaxation2d("11/pdata/1")

# A CPMG-type R2 experiment counting loops in a vclist, each 16 ms long
relaxation2d("12/pdata/1"; cycletime=0.016)

# Omit the 3rd plane (e.g. corrupted or duplicate delay) from the fit
relaxation2d("11/pdata/1"; skipplanes=[3])

relaxationdelays(specdata; relaxationtimes, ncyc, cycletime, prompt) -> Vector{Float64}

One relaxation delay per plane, in seconds: relaxationtimes if given; else the loop counts ncyc times the duration of one loop, cycletime; else the relaxation.duration annotation; else the vdlist; else the vclist times cycletime; else asked for. Where a loop duration is needed and not given, it is asked for.

Return peak idx to the experiment's default radii.

Comment lines heading every CSV: the experiment description plus the fitting radii, which readpeaklist! reads back.

results(expt) -> Vector{NamedTuple}

One row per peak, sorted by residue number: its label, resnum and fitstatus, and every parameter derived from it, each as a value ± error. The per-peak counterpart of results.csv, as returned by every 2D analysis when its window closes.

Example

expt = relaxation2d("11/pdata/1")
r = results(expt)
[row.R for row in r]          # relaxation rates, with their errors

resultstable(expt) -> (header, rows)

Column names and rows for results.csv: one row per peak, its identity and the parameters derived from the fit. This is the table to plot against residue number.

Positions and linewidths are not here. They are per-plane quantities that happen to take one value per plane when the peaks are fixed, so they live in series.csv whether or not they move, and the layout is the same either way.

samegrid(expt, i, j) -> Bool

Whether planes i and j share chemical shifts, frequencies and apodisation, so that a peak has the same shape in both.

Name => total concentration for the sample components defined on spec, or an empty Dict when spec carries no sample component metadata (e.g. a plane of a pseudo-3D dataset).

save_cluster_plots!(expt, folder)

Save one zoomed contour plot per cluster of overlapping peaks (first plane only). Axis limits are set to include only the peaks in that cluster plus padding.

Files are named cluster_LABEL.pdf (single peak) or cluster_LABEL1-LABEL2.pdf (overlapping peaks).

save_summary_plot!(expt, folder)

Write summary.pdf to folder using the experiment's default summary parameter. Skipped when there are no peaks.

seriescoordinates(expt) -> Vector{Pair{Symbol,Any}}

What distinguishes one plane from another, as name => values. A vector gives one entry per plane; a scalar is a setting constant across the experiment (a saturation time, a CPMG relaxation delay) and is repeated down the rows.

Named per quantity rather than reduced to one x column, so that a saved file says what its planes actually were. This is the same hook Exchange1D defines for the same reason.

The two generic experiment types differ only by the model fitted, so they delegate to a second method dispatching on that: rdc2d needs two keys where a titration needs one.

The planes drawn as one series in a peak plot, by concentration, as label => planes.

seriestable(expt) -> (header, rows)

Column names and rows for series.csv: one row per peak per plane, with the plane's coordinates and everything measured there - the amplitude, the position and the linewidths. A fixed-peak experiment simply repeats its one position down the rows.

plane is always written and is load-bearing where the planes share one file: every row of a pseudo-3D experiment has the same source, and the plane index is then the only thing telling two rows apart.

setperplane!(peak, param, values)

Write a per-plane parameter from a loaded results file, setting both the fitted value and the initial value in every plane (so the loaded positions display immediately and seed any refit).

setradius!(peak, xradius, yradius)

Give peak radii of its own, which changing the experiment's default radii then leaves alone.

Position and linewidths of peak in plane i, as (x, y, R2x, R2y).

simulate!(z, peak, expt)

Add peak, at its fitted amplitudes, to every plane of z. Its shape is computed once for each run of planes sharing a grid, rather than once per plane.

simulate!(expt::Experiment)

Simulate all peaks in the experiment and update specdata.

skipset(expt) -> Set{Int}

Planes excluded from fitting the lineshapes and from the model fitted after them. They are still displayed, and their amplitudes still measured.

Return descriptive text for slice idx.

Return descriptive text for slice idx.

Return descriptive text for slice idx.

Generic label for spectum slices

Return descriptive text for slice idx.

Return descriptive text for slice idx.

Sort peaks by residue number (positive ascending first, then unassigned).

The distinct spectra behind the planes of specdata, in order.

sparkyaxisorder(expt, entries) -> Bool

Whether a Sparky list's w1 belongs on this experiment's x (direct) axis rather than its y axis - true for a list written the opposite way round from the usual convention.

Decided by counting how many peaks land inside both axes' actual chemical-shift ranges each way round, because that is the thing that is really being asked and it needs no metadata beyond the spectrum itself. A tie (including the degenerate case of two dimensions covering similar ranges, as in a NOESY) keeps Sparky's convention of w1 on the indirect axis.

splitfields(line)

Split a data line into fields, accepting either comma-separated (the format written by writeresults!) or whitespace-separated values. Surrounding whitespace on each field is stripped.

A warning for the info panel where peak idx's last fit did not converge.

statustext(expt) -> Observable{String}

The status line: what the window is doing or waiting for, the outcome of the last command, and what is left to fit, with the key that fits it.

stripunit(name) -> String

A column name with its parenthesised unit removed: "x (ppm)" → "x". Column headers carry units (see docs/src/advanced/conventions.md), so anything locating a column by name strips them first.

summary_dataset(expt, param; name, include_unassigned) -> SummaryDataset

Collect param (default: the experiment's primaryparam) for every peak in a live experiment.

summary_dataset(path, param; name, include_unassigned) -> SummaryDataset

Read param from a saved results.csv (or a folder containing one). The label, residue number and atom are re-derived from each row's label.

summaryplot(source; param=<default>, ylabel, title, size, include_unassigned)
summaryplot(source1, source2, ...; kwargs...)

Plot a fitted parameter against residue number.

source may be a live experiment, a saved results.csv (or its folder), or a vector of any of these (which gives vertically stacked panels). Multiple sources may also be passed as separate positional arguments instead of a vector.

param selects which parameter to plot:

• omitted/nothing → each source's own default (its primaryparam or first derived column), so a mix of experiment types — e.g. relaxation and hetNOE — each plot their own result;
• a single Symbol → the same parameter for every source;
• a vector → one parameter per source (a nothing entry uses that source's default).

ylabel likewise may be a single label applied to all panels or a vector of per-panel labels; by default each panel is labelled from its parameter.

size sets the figure size in pixels, e.g. size=(800, 400).

• Backbone/amide labels → a scatter of value vs residue number with error bars.
• Any atom-typed labels (e.g. methyls I13CD1, L26CD2) → a bar plot ordered by (residue, atom) with peak labels as ticks, so stereospecific pairs don't overlap. Decided per panel.
• Unassigned peaks (the default X# names) are omitted unless every peak is unassigned, or include_unassigned=true.

Uses whichever Makie backend is active and returns the Figure, so the result displays interactively under GLMakie and can be saved with save("summary.pdf", fig) under CairoMakie.

summaryplot(expt::MovingExperiment; weights=(1.0, 0.14), title, size, include_unassigned)

Default summary for a moving-peak experiment: combined chemical-shift perturbation Δδ against residue number, with one series per plane beyond the first (each plane's shift is measured relative to plane 1).

Δδ = √((w₁·Δδx)² + (w₂·Δδy)²), with weights weighting the two dimensions. The default (1.0, 0.14) assumes the F1 (x) axis is ¹H and the F2 (y) axis is ¹⁵N (Williamson 2013); pass weights to suit other nuclei (e.g. (1.0, 0.25) for ¹³C).

summaryplot(expt::ParamagneticExperiment; title, size, include_unassigned)

Stacked panels against residue number: the fitted rates, each peak's height in every paramagnetic plane relative to the diamagnetic reference, and the diamagnetic relaxation rates. Pass param to plot a single parameter instead, as for any other experiment.

titration2d(inputfilenames; L0=nothing, P0=nothing, weights=(1.0, 0.14),
            skipplanes=nothing, prompt=isinteractive()) -> MovingExperiment

Interactive analysis of a 2D titration series, fitting a global binding isotherm to the chemical-shift perturbations. Built on peaktrack2d: track each residue's peak across the planes (T) or add and adjust by hand (A), and the fit recovers a single Kd shared by all residues plus per-residue free/bound shifts in each dimension.

Arguments

• inputfilenames: A single path string (pseudo-3D dataset) or a vector of path strings (one file per plane) pointing to processed Bruker data directories. Bruker experiment numbers work too, individually or as a list/range (e.g. 1:11), resolved relative to the working directory.
• L0: Total ligand concentration in each plane (one per plane). If omitted, it is read from each plane's NMR sample metadata (see titrationconcentrations), and if that metadata isn't available either you are asked for it.
• P0: Total protein concentration in each plane (one per plane), or nothing. When given (explicitly, or found in sample metadata), the exact 1:1 binding equation is used, accounting for protein concentration and dilution; otherwise the hyperbolic (ligand ≈ free) approximation is used. Kd is reported in the same concentration units as L0/P0.
• weights: (wx, wy) weighting of the two dimensions for the combined CSP |Δδ|; the default assumes ¹H (x) / ¹⁵N (y).
• skipplanes: Planes (1-based) left out of the binding isotherm fit. They are still fitted and displayed.
• prompt: Whether to ask for concentrations that cannot be found (default: when interactive).

The window blocks until it is closed, and the analysis is returned (see results).

Results

• The per-residue panel shows ΔδX and ΔδY together on a single axis (referenced to the fitted δfree), with the fitted binding curves overlaid. ΔδY is divided by the standard scaling factor for its nucleus (10 for ¹⁵N, 4 for ¹³C) so it sits on the same ppm scale as ΔδX.
• The global Kd is reported in the results panel.
• The summary plot shows ΔδX, ΔδN and the combined |Δδ| (saturation CSP = δbound − δfree) against residue number.

Example

titration2d(files)                                    # concentrations from sample metadata
titration2d(files; L0=ligand_concs)                   # ligand concentrations only
titration2d(files; L0=ligand_concs, P0=protein_concs) # exact 1:1, accounts for dilution
titration2d(1:11)                                     # Bruker experiment numbers

titrationconcentrations(nmrdata; prompt=true) -> (L0, P0)

Derive per-plane ligand (L0) and protein (P0) concentration vectors from each plane's sample metadata (see above for the inference rule). Returns (nothing, nothing) when no plane carries any sample concentration metadata. P0 alone comes back nothing if the protein's concentration isn't defined on every plane (the hyperbolic ligand ≈ free approximation is then used instead of the exact 1:1 equation) — as with exchange1d's _prompt_concentrations!, a molecule missing from only some planes' sample metadata is warned about rather than silently treated as zero or silently dropped. The resolved per-plane concentrations are printed as a table (in the same style as exchange1d's parameter tables) so they can be checked at a glance. Where the roles are ambiguous, the user is asked, or with prompt=false an error is raised.

Mark peak idx and the rest of its cluster as needing a refit.

trackmaximum(expt, i, xc, yc) -> (x, y)

Position of the most intense point in plane i within the peak radius of (xc, yc). Used to follow a peak from plane to plane during tracking; returns (xc, yc) unchanged if the search window falls off the spectrum.

transfertime(Trelax, spec) -> Float64

Trelax in seconds, or for :auto the 1/¹J for the heteronucleus in F2 of spec: two INEPTs of 1/(2J) in an HSQC, or the two 1/(2J) delays either side of t₁ in an HMQC.

The diamagnetic linewidths, a series for each dimension.

transverseplane(expt, c, R2x, R2y, Γ2) -> (R2x, R2y, height)

Linewidths and relative peak height at paramagnetic concentration c. Γ₂c adds to the ¹H linewidth (and in an HMQC to the multiple-quantum linewidth in F2), and the height falls by the broadening and by exp(-Γ₂c Trelax) during the transfer delays, giving Ipara/Idia = R₂ exp(-Γ₂t)/(R₂ + Γ₂) for an HSQC (Battiste & Wagner, Biochemistry 39, 5355 (2000); Iwahara, Tang & Clore, J. Magn. Reson. 184, 185 (2007)).

uncertainties(groups, f, θ, check) -> (σθ, amps, σamps)

Standard errors of the shapes and of every plane's amplitudes, from the covariance of the full problem, σ²(JᵀJ)⁻¹ with σ² estimated from the residuals. The amplitude blocks of JᵀJ are small and independent, so the shape covariance is the inverse of their Schur complement, S = Σᵢ Dᵢᵀ(I − A(AᵀA)⁻¹Aᵀ)Dᵢ over the active planes, where Dᵢ is the derivative of A·aᵢ with respect to the shapes.

An amplitude's error has two parts: that of the linear least-squares step at the fitted shapes, σ²(AᵀA)⁻¹, which reflects the peak's shape, its overlap with its neighbours and the residual σ²; and that carried from the shapes, σ²(AᵀA)⁻¹AᵀDᵢS⁻¹DᵢᵀA(AᵀA)⁻¹. Where several planes share the shapes, the second is left out: since Dᵢ ∝ aᵢ it is an error in scale common to every plane, proportional to each amplitude, which cancels in a ratio or a rate fitted across the series, and which a fit treating the amplitudes as independent would otherwise count once per plane. Where a plane has shapes of its own (a moving peak, or a single spectrum) both are kept. amps and σamps map each plane to one value per peak. Errors are NaN where the data do not determine them. check is called as in fitshapes, so that this phase can also be stopped.

Value and error of par in plane i, as a Measurement.

writereproduce(io, expt, folder)

The Reproduce: block of summary.txt: the call that produced the analysis, its parameters as resolved, with the peaklist.csv saved in folder to load. Pasted back into Julia it reopens the window with the same peaks and radii, and the fit repeats. Nothing is written where the call was not recorded.

writeresults!(expt, folder) -> String

Write peaklist.csv (what was picked), series.csv, results.csv and global.csv (each where there is anything to put in it) and one peaks/<label>.csv per peak into folder, and return the path of the series file. The per-peak files hold that peak's own rows of series.csv, so the data behind each plot sits beside it under the same basename.

results.csv is skipped by an experiment that derives nothing per peak (fit2d, peaktrack2d): it would carry peak labels and no values.

writesummary(filepath, expt) -> String

Write summary.txt: the experiment description, the fitting radii, and the headline parameter for every peak, rounded for reading rather than written at full precision.