Internals

half-width (ppm) of the region around a filtered solvent left out of automatic phasing

systematic phase uncertainty assumed for an edge observation (degrees)

abs(spec::NMRData)

Return the magnitude of each point of a multicomplex spectrum, as Float64 data.

phase of a pole (radians); zero for a positive absorption line

complex(spec::NMRData)

Convert a first-order multicomplex spectrum (Multicomplex{T,1,2}) to Julia Complex{T}.

stack(expts::Vector{NMRData})

Combine a collection of equally-sized NMRData into one larger array, by arranging them along a new dimension, of type UnknownDimension.

Throws a DimensionMismatch if data are not of compatible shapes.

realest(spec::NMRData)

The real spectrum: the purely real component of every point of a multicomplex spectrum, real in every dimension, as an NMRData with Float64 elements. This is the final step of a processing pipeline.

real and imag act elementwise as defined by MulticomplexNumbers: they take the coefficients of the highest-order imaginary unit, so for 2D data real(spec) is still complex in the direct dimension. For 1D data real and realest agree.

acquisition time (s) after t = 0 for a time dimension, used as the default window tmax

least-squares complex amplitudes cₖ such that x[n] ≈ Σ cₖ·polesₖ^(n-1)

_apply_indirect_referencing(spec, referenced_dims; aqueous=:auto)

Apply indirect referencing using Xi ratios to all frequency dimensions not in referenced_dims.

The effective 1H frequency is back-calculated from the referenced dimension(s), and Xi ratios are used to calculate the expected frequencies for other nuclei.

optimal zero-order phase (radians, modulo π) for first-order phase p1r

_buildfreqdim(d::TimeDimension, di, n) -> FrequencyDimension

Construct the FrequencyDimension (F1Dim…F4Dim, chosen by the array position di) produced by Fourier transforming time dimension d to n points. The chemical-shift axis is computed from :bf, :swhz and :offsetppm, decreasing (high ppm first) to match the convention used elsewhere in NMRTools. All time-dimension metadata is carried over, including :mcindex.

_buildtimedim(d::FrequencyDimension, di, n) -> TimeDimension

Inverse of _buildfreqdim: construct the TimeDimension (T1Dim…T4Dim, chosen by the array position di) obtained by inverse Fourier transforming frequency dimension d to n points.

_edgeobservations(s, poles, δ, bf, edges, noise) -> Vector{NamedTuple}

Phase observations from the two edges of the complex trace s: for each edge, the region of edges × the spectrum (at least 16 points) at that end, excluding points within four linewidths of a pole. The observation is the phase at which the real part of the region's sum vanishes, with the region's centre as a fraction from the first point and the signal-to-noise ratio of the sum.

evaluate Σ cₖ·polesₖ^(n-1) over the index range ns, iterating the powers

extend a time dimension to n points, continuing the time axis at the same dwell

_fourierdims(spec) -> Vector{Int}

Return the array-dimension indices of every dimension that carries an :mcindex (i.e. the TimeDimensions / FrequencyDimensions that participate in Fourier transformation). Non-Fourier axes such as TrelaxDim or X2Dim have :mcindex == nothing and are skipped.

array-dimension indices of the Fourier dimensions that are already in the frequency domain

amplitude-weighted chemical shift of a group of poles

digital-filter group delay (points) still to be removed from a dimension by ft; 0 if none

_groupintegralphases(s, groups, δ, bf) -> Vector{Float64}

Phase of each line group measured from the spectrum: the integral of the complex trace s over a window centred on the group, extending four times its largest linewidth beyond its outer lines but no more than halfway to the neighbouring groups, less a straight complex baseline through the means of the window's outer points (which removes the tails of distant lines).

wrap an angle to (-π/2, π/2]: the residual of a phase taken modulo π

_hankelpoles(x, K; L=0) -> Vector{Complex}

Estimate up to K signal poles zₖ of the complex vector x by ESPRIT: SVD of the Hankel matrix, then the eigenvalues of the shift-invariance operator on the truncated left singular subspace. L (Hankel rows) is capped at _HANKEL_LMAX; the model order K sets the eigenproblem size.

_hsvdsubtract(x; dt, targethz, bandhz, ncoef) -> Vector{Complex}

Fit x with ncoef damped exponentials and subtract those whose frequency lies within bandhz of targethz (both in Hz). Frequency-selective solvent/peak removal.

_lineshape(ω, R2, ωaxis, window, complexity)

Internal function to calculate a resonance lineshape with frequency ω and relaxation rate R2, calculated at frequencies ωaxis and with apodization according to the specified window function.

_lowpassestimate(data, di, w, fl) -> Array

Low-pass estimate of data along array dimension di by a moving average with (relative) weights w over a ±fl window, truncated and renormalised at the edges. Real-weighted, so it works directly on multicomplex arrays.

relative weights of a symmetric low-pass window of half-width fl (:boxcar/:sine/:sine²)

_lpcoefficients(x, order, direction) -> Vector{Complex}

Least-squares LP coefficients a of the given order for complex vector x. For :forward, x[n] ≈ Σⱼ aⱼ x[n-j]; for :backward, x[n] ≈ Σⱼ aⱼ x[n+j]. Solved by QR (D \ d).

_lpextrapolate(x, a, npred, direction) -> Vector{Complex}

Extend x by npred points by iterating the LP recurrence with coefficients a: :forward appends Σⱼ aⱼ x[end-j+1], :backward prepends Σⱼ aⱼ x[j].

_lpmatrix(mat; npred, order, direction, rootfix, pool, nselect) -> Matrix

Extend every column of mat by npred points. With pool (default), one shared set of coefficients is estimated from the nselect highest-energy columns and applied to all columns by recurrence; otherwise each column is fitted independently (matching nmrglue).

_lppredict(x; npred, order, direction, rootfix) -> Vector{Complex}

Linear-prediction extension of x by npred points, extrapolating by recurrence. Forward extension uses the Zhu–Bax backward-fit-and-reflect coefficients (stable); backward extension uses a direct backward fit with root reflection.

_lprepair(x; nrepair, order, rootfix) -> Vector{Complex}

Replace the first nrepair points of x by backward prediction from the remaining points (length unchanged).

_maptransform(A, di, mcindex, matkernel) -> Array{<:Multicomplex}

Apply the matrix kernel matkernel — mapping the (L, ncols) complex matrix of imₖ-plane vectors (one per column) to a (L2, ncols) matrix, possibly with L2 ≠ L — to the multicomplex array A along array dimension di, where mcindex is that dimension's imaginary unit. Uses the same zero-copy reinterpretation as _mcfft!; a fresh output array is built so the kernel is free to change the length along di.

_mcfft!(A, unit, di; inverse=false)

In-place Fourier transform of a multicomplex array A along array dimension di, treating the imaginary unit unit (the dimension's :mcindex) as the complex i. Reinterprets the multicomplex memory as Complex (via MulticomplexNumbers' unsafe reinterpretation, exactly as its FFTW extension does), applies FFTW.fft!/ifft!, then reinterprets back. ifft! includes the 1/N normalisation so that _mcfft!(inverse=true) inverts _mcfft!.

wrap a per-column complex-vector kernel f as a matrix kernel

_perdim(setting, di)

The value of a processing setting for array dimension di: setting itself, or, if it is a dictionary, its entry for di keyed by dimension number or dimension type (T1Dim and F1Dim both mean dimension 1). Returns default when a dictionary has no entry.

_phasegroups(poles, bf, coupling, maxwidthratio) -> Vector{Vector{Pole}}

Group poles (sorted by decreasing shift) for phasing: drop poles broader than maxwidthratio times the SNR-weighted median linewidth that have a narrower pole within their linewidth, then merge neighbours closer than coupling Hz plus their mean linewidth. bf is the spectrometer frequency (Hz).

_phaseobservations(spec, di; snr, coupling, maxwidthratio, kw...) -> NamedTuple or nothing

Line groups of the trace of spec along array dimension di (see _referencetrace), with the phase of each from the integral of the trace, its position as a fraction from the first point, and its signal-to-noise ratio. nothing if no lines are found. Other keywords are passed to estimatepoles.

_phasetraces(spec, di; maxtraces=64, factor=8) -> (traces, exclude)

1D traces along array dimension di from which its phase is estimated, and chemical-shift intervals along di to leave out of them.

When another dimension of spec is a frequency dimension, the traces pass through the strongest cross peaks. Peaks are local maxima of the magnitude (the largest over the components) that stand out by more than factor times the noise of their own point along di, measured as the median absolute deviation over the other dimensions. Scaling by this local noise suppresses ridges along the other dimensions, such as t₁ noise from a residual solvent signal. Points along di whose median magnitude over the other dimensions is far above the typical one are such ridges, and are returned in exclude. At most maxtraces traces are used, one per position in the other dimensions.

The components of a trace that are real and imaginary in the other dimensions' imaginary units all share the phase of its lines along di, differing only by real factors that depend on how the other dimensions are phased. Each trace is the real combination of these components with the most signal (the leading eigenvector of their real Gram matrix, with a non-negative weight on the component real in every other unit), so it does not depend on the phases of the other dimensions. Traces through the peaks also keep apart lines that would overlap in a projection.

Otherwise (for 1D data and for series such as pseudo-2D experiments), or when no cross peak is found, the spectrum itself is returned, and its phase is estimated from _referencetrace.

0-based fractional point index at which the dimension axis equals pivot

coefficients (descending, leading first) of ∏(z − rₖ)

roots of the monic-normalised polynomial with descending coefficients pc

shared extension coefficients for direction (Zhu–Bax for forward), pooled over columns

stacked least-squares LP coefficients (order m, direction fitdir) from columns sel of mat

_rebuilddims(spec, newdata, newdims)

Rebuild spec with new data and dimensions, going through the NMRData(A, dims; …) constructor so that DimensionalData's format runs on the new dimensions (a plain rebuild bypasses formatting and leaves freshly-built dimensions as unformatted AutoLookups).

_reference_with_offset(spec, dim_no, offset; indirect=true, aqueous=:auto)

Internal function to apply a reference offset and optionally indirect referencing.

_referencetrace(spec, di) -> Vector{ComplexF64}

Complex trace along array dimension di of spec, in the imaginary unit given by that dimension's :mcindex. Other imaginary units take their real component. Other dimensions are reduced so that every signal contributes: a time dimension contributes its first point, a frequency dimension is summed over the points that carry signal (see _signalindices), and any other dimension is summed.

A frequency dimension is not summed over all its points: that sum is its first time point, which is dominated by the solvent and baseline rather than the cross peaks, and it adds the noise of every point while signal comes from only a few.

_reflectroots(a, direction) -> Vector{Complex}

Stabilise LP coefficients a by reflecting the roots of the prediction polynomial across the unit circle: for :forward extension, roots with |z|>1 (growing) are mapped to 1/conj(z) (inside); for :backward, roots with |z|<1 are pushed outside. Coefficients are rebuilt from the reflected roots.

_removegroupdelay!(A, unit, di, g)

Remove a digital-filter group delay of g points from the spectrum A (immediately after the FFT along array dimension di, before fftshift) by multiplying by the linear phase ramp exp(2πi·g·k/N), with k the signed frequency index. This is the Fourier shift theorem: it moves the time origin forward by g points, so build-up points stored before t = 0 end up at negative time, as in TopSpin and NMRPipe.

return a copy of a dimension tuple with the di-th element replaced by newdim

reshape a vector v so it broadcasts along array dimension di of an nd-dimensional array

weighted doubled-angle resultant for first-order phase p1r (radians)

ranges of consecutive true values in a boolean vector

_scanp1(φ, f, w, p1range, p1expected, λ) -> Float64

First-order phase (radians) maximising the doubled-angle resultant within p1range (degrees), less a penalty λ/nₑ·((p1 − p1expected)/180)², where nₑ = (Σw)²/Σw² is the effective number of groups. The caller scales λ by the observed phase scatter, so the penalty acts as a prior whose influence falls as the fit becomes better determined.

indices of the nselect highest-energy columns of mat (or all, if fewer)

_setdimmetadata(spec, di, pairs...)

Return spec with the metadata of dimension di updated by pairs (key => value). The dimension is rebuilt with a copy of its metadata, so the input spectrum is left unchanged.

resolve a shift spec (:carrier or a ppm value) to a frequency offset (Hz) from the carrier

move the time origin of A along di forward by g points (a circular shift, by Fourier transform)

_signalindices(v, j; factor=3) -> Vector{Int}

Indices along dimension j of the array v at which the largest magnitude over the other dimensions exceeds factor times its median. Most points of a frequency dimension carry only noise, so the median measures the noise maximum and the selected points are those with peaks. All indices are returned if none qualify.

_tracenoise(s; blocksize=64, q=0.2) -> Float64

rms noise (per real component) of a complex trace. The trace is split into blocks (at most blocksize points, fewer for short traces, so that there are at least 16), a straight line is removed from the real and imaginary parts of each block, and the noise is taken from a low quantile q of the block standard deviations, so that blocks containing signal (including the dispersive tails of an unphased spectrum) do not inflate it.

apodize, zero-fill and Fourier transform each Fourier time dimension, as in autoprocess

whether to apply solvent suppression: solvent is true, a shift, or :auto for ¹H in H₂O

copy of spec with its own metadata and a fresh noise estimate

wrap an angle in degrees to (-180, 180]

_zhubaxforward(x, order, rootfix) -> Vector{Complex}

Forward-extension LP coefficients by the Zhu–Bax scheme: fit backward LP, treat the roots of its prediction polynomial (Σⱼ bⱼwʲ = 1) as the candidate poles, reflect any with |z|>1 to 1/conj(z) so the forward extrapolation cannot grow, and rebuild forward coefficients. This separates signal poles (inside the unit circle) from noise poles more cleanly than a direct forward fit, and is the variant NMR usually prefers. With rootfix=false, falls back to a plain forward least-squares fit.

NMRExperiment(experimentfolder::String) -> NMRExperiment

Construct a metadata-only descriptor from a Bruker NMR experiment folder. Reads acqus, title, and pulse programme (text files only) — no binary data loaded. Annotations are parsed from the pulse programme YAML but parameter references are not resolved (full resolution happens in loadnmr).

See also: scanexperiments, loadnmr.

NMRSample(path::String) -> NMRSample

Load an NMR sample JSON file and return an NMRSample descriptor.

hz(f::FQList, ax::FrequencyDimension)

Return frequency list values as offsets relative to the spectrometer frequency, in Hz.

See also: ppm

hz(f::FQList)

Return frequency list values as offsets relative to the spectrometer carrier frequency, in Hz, using the reference frequencies (:bf, :sfo) stored on the list. Throws an error if no reference is attached — see withreference.

See also: ppm

ppm(f::FQList, ax::FrequencyDimension)

Return frequency list values in ppm (in absolute terms, i.e. relative to 0 ppm).

See also: hz

ppm(f::FQList)

Return frequency list values in ppm (in absolute terms, i.e. relative to 0 ppm), using the reference frequencies (:bf, :sfo) stored on the list. Throws an error if no reference is attached — see withreference.

See also: hz

_addsampleinfo_metadata!(md::Dict{Symbol,Any})

Search for a matching sample JSON in the experiment parent directory and store the result as an NMRSample under md[:sample]. Operates on a raw metadata dict.

_annotate_metadata!(md::Dict{Symbol,Any})

Parse pulse programme annotations from a raw metadata dict and store them under :annotations. Only parses the raw YAML — skips parameter resolution and programmatic list expansion, which require loaded data. Suitable for use with NMRExperiment descriptors.

_apply_dimension_annotations(spec::NMRData) -> NMRData

Apply semantic dimension types based on the dimensions array in annotations. The dimensions array provides explicit ordering - index i in the array corresponds to dimension i in the data. Returns new NMRData with updated dimensions.

_buildchannels(acqusdic) -> Dict{Symbol,Any}

Build a dictionary of spectrometer channels from a parsed acqus dictionary, keyed by channel label (:f1…:f8). Each entry is itself a dictionary describing the nucleus and frequencies on that channel, independent of which dimensions were detected. Only channels with an assigned nucleus (nucN present and not "off") are included.

Frequencies (:bf, :sfo) are in Hz — replacefrequencies! has already run by the time the acqus dictionary is built.

_copyparameters(src, dest)

Copy the parameter files of experiment folder src into dest: every regular file except the binary data (fid, ser), plus the lists folder. Processed data (pdata) are not copied.

_directcomplex(raw, td) -> Array{ComplexF64}

Trim the direct-dimension padding (to td real points) and deinterleave the real/imaginary points into a complex array — the im1 quadrature of the directly detected dimension — with td÷2 points along the direct axis.

_find_dimension_path(key, annotations, prefix="")

Find the dotted path to a key in the annotations dictionary. Returns the path that should match entries in the dimensions array.

_find_frequency_dim_for_channels(spec, channel) -> Union{Int, Nothing}

Find the frequency dimension index that corresponds to the given channel. Channel can be "f1", "f2", etc. or a nucleus string like "1H", "19F".

Bruker FnMODE for a quadrature scheme

_groupdelay(acqusdic) -> Float64

The Bruker digital-filter group delay (points) of the direct dimension: the number of points of filter build-up ("lead-in") that precede time zero in the stored FID. The data are not modified; the lead-in stays in the FID at negative times and ft removes the delay with a linear phase ramp after the Fourier transform. Which value applies is set by the acquisition parameters:

• DIGMOD = 0 (analogue filtering): no group delay.
• DSPFVS 20–23: GRPDLY. For baseopt acquisitions (DIGMOD = 3) it is an integer and the spectrometer has already corrected the initial points of the FID.
• DSPFVS 10–19 (older data): the delay should be looked up from DECIM and DSPFVS. This is not implemented; GRPDLY is used if valid, otherwise no delay is applied, with a warning.
• DSPFVS outside 10–23: not a firmware version Bruker defines. TopSpin's cryoproc1d, for example, sets DSPFVS = 0 after rewriting the FID with its start removed: the filter build-up and some points after time zero. The number of points removed is found by comparing TD in acqu (the original) and acqus; the points beyond GRPDLY were after time zero, so the stored FID starts that many dwells after t = 0. This is returned as a negative delay, so that ft restores the time origin. A warning reports the missing points. If acqu does not show how many were removed, no delay is applied.

_indirectstorageorder(acqusdic, ndim) -> Vector{Int}

Return the acqus-file indices (2:ndim) of the indirect dimensions, ordered from the fastest-varying (innermost) loop to the slowest (outermost) as stored in the ser file. For 3D this depends on the Bruker AQSEQ parameter: AQSEQ=0 (3-2-1) nests acqu2s inside acqu3s; AQSEQ=1 (3-1-2) swaps them. 1D/2D have a single (or no) indirect dimension.

_is_programmatic_pattern(value) -> Bool

Check if a value is a programmatic list pattern. Must be a Dict with either:

• "type" key and either "step" or "end" key (linear/log patterns)
• "counter" and "scale" keys (counter-based pattern)

baseopt acquisition (DIGMOD = 3): the spectrometer has corrected the initial points of the FID

assemble the top-level NMRData metadata from the loaded text metadata and the constructed dims

_minimalacqus(dest, spec, axisdims, tds)

Write minimal acqus/acqu2s/… files into dest describing spec. axisdims are the dimensions in storage order (direct first) and tds the corresponding TD values (points on disk).

_modifiedfidoffset(acqusdic, expfolder) -> Int

For a FID rewritten with its start removed (for example by cryoproc1d), the number of complex points after time zero that were removed: the drop in TD from acqu (the original) to acqus, less the group delay GRPDLY. Zero if this cannot be determined.

_patchjdx(text, pairs) -> String

Set single-valued parameters in the text of a JCAMP-DX parameter file, replacing the existing ##$KEY= value line or inserting one before ##END=.

_pdatafiles(ndim)

Names of the pdata files of an ndim-dimensional spectrum, in the order of the multicomplex components: file k (counting from 0) has an i for each set bit of k, the direct dimension first, so 2ir is the coefficient of im1.

procs parameters for dimension d of size n

_readfid(datafile, acqusdic, nrows) -> Matrix

Read a raw Bruker fid/ser file into a (paddedtd, nrows) matrix of the on-disk numeric type, handling endianness (BYTORDA) and data type (DTYPA). The directly-detected dimension is zero-padded on disk to a block boundary; the padded row length is recovered from the file size and the number of stored FIDs (nrows), so no block-size assumption is needed. Padding is trimmed by the caller.

_recombine_axis(y, k, scheme) -> Array{<:Multicomplex}

Recombine the interleaved real/imaginary records of a phase-sensitive indirect dimension (array axis k) into an extra multicomplex order, halving that axis. scheme selects States, States-TPPI or echo/anti-echo (Rance–Kay) recombination. The new imaginary unit encodes that dimension's quadrature.

_resolve_parameter(param_str::String, spec::NMRData) -> Union{Nothing, Any}

Attempt to resolve a parameter string using the acqus data. Returns the resolved value or nothing if not a recognized parameter.

Handles parameter patterns (case-insensitive):

• Indexed parameters: p1, pl1, d20, cnst8, gpz6, etc.
• Nucleus assignments: f1, f2, f3, f4
• Any other parameter names that exist in acqus (including lists)

_resolve_programmatic_pattern(key, pattern, root_annotations, spec, dimensions)

Resolve a single programmatic list pattern to a vector.

_resolve_programmatic_recursive!(obj, root_annotations, spec, dimensions)

Recursively traverse annotations to find and resolve programmatic list patterns.

scale the t = 0 point of each axis in axistype_pairs (point firstindex[axis], default 1); returns the factor used for each axis

_setmcindex!(spec)

Link each frequency dimension of a loaded spectrum to its imaginary unit (:mcindex), in order: im1 for the direct dimension, im2 for the next frequency dimension, and so on, matching the components of data loaded with allcomponents=true and spectra produced by ft.

source Bruker experiment folder of spec, or nothing if unknown or missing

_splitunit(y, k, scheme) -> Array

Inverse of _recombine_axis: split the highest imaginary unit of y back into interleaved real/imaginary records along array axis k, doubling that axis.

_timedim(aq, di, mcindex) -> TimeDimension

Construct the TimeDimension at array position di (naming it T1Dim…T4Dim) from a Bruker acquisition-parameter dictionary aq (acqus, acqu2s, …), linking it to imaginary unit mcindex. Frequencies are already in Hz (replacefrequencies! has run). The time axis is t = ((0:td-1) .- delay) / sw, so points of digital-filter lead-in (delay points) have negative times.

window function → (WDW, LB, SSB) procs parameters

write a minimal JCAMP-DX parameter file from key => value pairs (keys as Bruker names)

write a pdata title file from the spectrum's title or label

addsampleinfo(expt::NMRData) -> NMRData

Search for and load sample metadata from JSON files in the experiment folder. Returns the NMRData object with sample information added to metadata under :sample as an NMRSample.

Sample files are JSON files following the schema at https://github.com/waudbylab/nmr-sample-schema. The function matches samples based on creation/ejection timestamps against the experiment date.

Examples

spec = loadnmr("experiment/1/pdata/1")
spec = addsampleinfo(spec)  # Load matching sample metadata
sample(spec, "notes")  # Access sample information

See also sample, hassample.

annotate(spec::NMRData) -> NMRData

Parse pulse programme annotations and store them in the spectrum metadata. Returns the NMRData object with annotations added to metadata.

Annotations are embedded within pulse programme comments marked with ;@ at the start of lines, following YAML format with schema version 0.0.2.

Examples

spec = loadnmr("experiment/1/pdata/1")
spec = annotate(spec)  # Parse and store annotations
annotations(spec, "title")  # Access parsed annotations

See also annotations, hasannotations.

getformat(filename)

Take an input filename and return either :ucsf, :nmrpipe, :pdata (bruker processed), :bruker_fid (raw fid/ser, handled by loadfid), or :unknown after checking whether the filename matches any known format.

loadnmrpipe1d(filename, md, mdax)

Return an NMRData array containing spectrum and associated metadata.

loadnmrpipe2d(filename, md, mdax)

Return NMRData containing spectrum and associated metadata.

loadnmrpipe3d(filename, md, mdax)

Return NMRData containing spectrum and associated metadata.

loadpdata(filename, allcomponents=false)

Load processed Bruker NMR data from a pdata folder.

Arguments

• filename: Path to a pdata directory or a file within it
• allcomponents: If true, returns Multicomplex data with all components, one imaginary unit per frequency dimension (im1 for the direct dimension), for example 2rr + 2ir*im1 + 2ri*im2 + 2ii*im1*im2 for 2D data (TopSpin's 2ir is imaginary in the direct dimension, 2ri in the indirect one). Default is false (returns real data only).

Imaginary components are conjugated relative to TopSpin's files, so that loaded data follow the same convention as spectra produced by ft: TopSpin's PHC0/PHC1 applied with phase give the same spectrum.

parse_annotations(content::String) -> Dict{String, Any}

Parse pulse programme annotations from content string. Annotations are embedded within pulse programme comments marked with ;@ at the start of lines.

The function:

1. Filters out lines starting with ;@
2. Strips the ;@ prefix from each line
3. Parses the resulting YAML document into a dictionary

parsefqlist(lines)

Return contents of the specified fqlist.

fqlists can have several different formats:

first line | reference | unit

         | sfo         | Hz

sfo hz | sfo | Hz sfo ppm | sfo | ppm bf hz | bf | Hz bf ppm | bf | ppm p | sfo | ppm P | bf | ppm

parsenmrpipeheader(header)

Pass a 512 x 4 byte array containing an nmrPipe header file, and returns dictionaries of metadata. The nmrPipe header format is defined in fdatap.h.

Return values

• md: dictionary of spectrum metadata
• mdax: array of dictionaries containing axis metadata

Examples

md, mdax = parsenmrpipeheader(header)

Example lines to parse: define list<gradient> EA=<EA> define list<gradient> EA3 = { 1.0000 0.8750 } define list<pulse> taulist = <$VPLIST> define list<power> powerlist = <$VALIST> define list<gradient> diff=<Difframp> define list<frequency> F19sat = <$FQ1LIST>

NB gradient files have weird syntax!!

parse ucsf axis header into a dictionary

parse ucsf file header into a dictionary

return valist contents as Powers

return vdlist contents in seconds

return vplist contents in seconds

replacedurations!(dic)

Ensure all durations in the acqus dictionary are in seconds.

replacepowers!(dic)

Ensure all powers in the acqus dictionary are stored as Power types.

resolve_parameter_references!(annotations::Dict{String, Any}, spec::NMRData)

Recursively traverse the annotations dictionary and resolve parameter references. References are bare parameter names like p1, pl1, d20, VALIST, etc.

Parameters are resolved using the acqus() function to get values from the acqus file.

Arguments

• annotations::Dict{String, Any}: Annotations dictionary to modify in-place
• spec::NMRData: NMRData object containing acqus metadata

Examples

# Before resolution: {"pulse": "p1", "power": "pl1", "duration": "VDLIST"}
# After resolution: {"pulse": 9.2, "power": Power(...), "duration": [0.01, 0.02, ...]}

resolve_programmatic_lists!(annotations::Dict{String, Any}, spec::NMRData)

Resolve programmatic list patterns in annotations to actual vectors.

Programmatic lists are specified as dictionaries with one of two patterns:

Pattern 1: Type-based (linear/log)

• type: "linear" or "log" (logarithmic)
• start: starting value
• step: step size (for linear with start/step)
• end: ending value (for linear or log with start/end)

Pattern 2: Counter-based

• counter: array of values (typically integers from a loop counter)
• scale: scale factor to multiply each counter element by

For type-based patterns, the function:

1. Identifies fields containing programmatic list patterns ({type, start, step/end})
2. Finds the dimension number for that field from the dimensions annotation
3. Gets the number of points in that dimension
4. Replaces the pattern with a correctly sized vector

For counter-based patterns, the function:

1. Multiplies each element of the counter array by the scale value
2. Returns the resulting vector

Examples

# Linear spacing with start/step
# {type: linear, start: p9, step: p9} with 10 points → [p9, 2*p9, 3*p9, ...]

# Linear spacing with start/end
# {type: linear, start: 0.001, end: 0.1} with 10 points → [0.001, 0.012, ..., 0.1]

# Logarithmic spacing with start/end
# {type: log, start: 0.001, end: 0.1} with 10 points → [0.001, 0.0016, ..., 0.1]

# Counter-based pattern
# {counter: [0, 1, 2, 3], scale: 0.01} → [0.0, 0.01, 0.02, 0.03]

parsetopspinversion(acqusfilename)

Return the TopSpin version as a VersionNumber (e.g. v"4.2.0").

This is obtained from the end of the first line of the acqus file, e.g.

##TITLE= Parameter file, TopSpin 4.2.0
##TITLE= Parameter file, TOPSPIN		Version 2.1
##TITLE= Parameter file, TOPSPIN		Version 3.2

Migrate NMR sample metadata to the latest schema version.

Call loadsample(path, migrationspath=MIGRATIONSPATH[]) to load a JSON file and apply migrations. It returns the migrated data as a Dict.

Call updatetolatestschema!(data) with a parsed JSON Dict. It modifies the dict in place and returns it.

The migration patch file is expected at current/patch.json relative to this module. Override by setting MIGRATIONSPATH[] or passing migrationspath.

loadsample(path, migrations_path=MIGRATIONS_PATH[]) -> Dict

Load a JSON file from the given path and apply migrations to update it to the latest schema version. Returns the migrated data as a Dict.

updatetolatestschema!(data, migrations_path=MIGRATIONS_PATH[]) -> Dict

Apply migrations to the given data Dict to update it to the latest schema version. The data is modified in place and returned. Migrations are loaded from the given migrationspath (default is MIGRATIONSPATH[]).