fitting.amares

fitting.amares

Functions¶

Name	Description
fit_amares	Apply AMARES time-domain fitting to an N-dimensional signal.

fit_amares¶

fitting.amares.fit_amares(
    da,
    prior_knowledge,
    dim=DIMS.time,
    mhz=None,
    sw=None,
    deadtime=None,
    carrier=None,
    g_global=0.0,
    method='least_squares',
    initialize_with_lm=False,
    num_workers=1,
    init_fid=None,
    verbose=False,
)

Apply AMARES time-domain fitting to an N-dimensional signal.

This function isolates the stateful pyAMARES API to perform parallelized batch fitting across spatial or repetition dimensions. It automatically scans the dataset to initialize the fitting template using the voxel with the highest Signal-to-Noise Ratio (SNR), ensuring robust prior knowledge instantiation.

AMARES fits in the time domain. Following the domain-preserving contract, a spectrum handed to fit_amares is round-tripped through the FID for the fit and the returned time-domain variables (data, fit, residuals) are restored to the representation that was passed in (ppm in -> ppm out); a FID is fitted and returned as-is. The quantified parameters are domain-independent.

Robustness: the FID is normalized by a single global factor before fitting — so pyAMARES’s magnitude-derived optimizer tolerance behaves at any signal scale (a Bruker-scale FID no longer “converges” on the prior) — and the fitted amplitudes are rescaled back into the input units. A voxel with no fitted value is recorded as NaN — never a spurious zero — for both an empty (no-signal) spectrum and a failed fit; the fit_status variable (0=fitted, 1=no_signal, 2=failed) tells the two apart. Empty spectra are skipped rather than fitted, so an MRSI grid costs only its signal-bearing voxels — and when just one of them has signal, the fit runs in-process rather than starting a worker pool it cannot use.

Parameters¶

Name	Type	Description	Default
da	xr.DataArray	Input data. A FID with the specified time dimension, or a complex spectrum (`frequency`/`chemical_shift`) that is converted to a FID for the fit.	required
prior_knowledge	Mapping \| pandas.DataFrame \| str \| Path	The prior-knowledge constraints, either in memory or on disk. A mapping of peak name to parameters is built and validated via :func:`~xmris.fitting.build_prior_knowledge` (phase bounds, peak-name and tie-order traps handled for you); a `str`/`Path` is a pyAMARES CSV/XLSX file used directly; a DataFrame in pyAMARES’s positional layout is accepted as-is.	required
dim	str	The time dimension along which to fit, by default `DIMS.time`.	`DIMS.time`
mhz	float	Spectrometer frequency in MHz. If None, read from `da.attrs['reference_frequency']`.	`None`
sw	float	Spectral width in Hz. If None, calculated from the `dim` coordinate spacing.	`None`
deadtime	float	Acquisition time origin in seconds. If None, taken from the first `dim` coordinate value (the single source of truth for the time axis).	`None`
carrier	float	Transmitter carrier position on the absolute ppm scale. Prior-knowledge and reported chemical shifts are then read and returned as absolute/literature ppm (e.g. PCr at 0, γ-ATP at -2.5). If None, taken from `da.attrs['carrier_ppm']` (default 0.0 — shifts are carrier-relative).	`None`
g_global	float or bool	Global lineshape held for every peak: 0.0 = pure Lorentzian (default), 1.0 = pure Gaussian, in between = pseudo-Voigt. Pass `False` instead to let each peak’s `g` vary, fitted from the prior-knowledge value.	`0.0`
method	(least_squares, leastsq)	Fitting method, passed through to `lmfit`. Defaults to ‘least_squares’ (SciPy’s trust-region solver), which lands in the same minimum on every run. ‘leastsq’ (Levenberg-Marquardt) is faster per fit but can settle unpredictably into a shallower second minimum on ill-conditioned multi-peak data — the same input then yields different amplitudes, with every fit reporting success.	`"least_squares"`
initialize_with_lm	bool	Run an internal Levenberg-Marquardt initializer before fitting. Defaults to False (True can diverge on real data).	`False`
num_workers	int	Size of the worker pool. Defaults to 1 — every spectrum is fitted in-process, which beats starting a pool until roughly 64 short fits in a fresh process (nearer 8 if the same session fits repeatedly, since the pool is then started only once). Pass a positive count, or joblib’s negative spellings (`-1` every core, `-2` all but one), to opt in. Whatever you ask for is capped at the number of spectra that actually have signal, and a pool that resolves to one worker collapses to the in-process loop rather than paying a startup it cannot use.	`1`
init_fid	np.ndarray	A 1D complex array to use as the template for pyAMARES initialization. If None, the function automatically selects the spectrum with the highest SNR.	`None`
verbose	bool	If True, sets logging level to INFO and prints progress. Default is False.	`False`

Returns¶

Name	Type	Description
	xr.Dataset	A dataset containing the original data, the fitted model, the residuals, and the quantified parameters (amplitude, chem_shift, linewidth, phase, CRLB, SNR) mapped across the original dimensions and the new `metabolite` dimension. It also carries a per-spectrum `fit_status` flag (0=fitted, 1=no_signal, 2=failed).