fitting.prior_knowledge

fitting.prior_knowledge

Build validated pyAMARES prior-knowledge tables from a friendly spec.

pyAMARES reads prior knowledge from a positional CSV/XLSX whose row order and bound syntax are easy to get subtly — and silently — wrong:

a blank phase bound becomes min = -inf in pyAMARES and trips a NaN trap in the phase wrapping, so a fit that looks configured returns garbage;
a trailing digit in a peak name is read as a J-coupling multiplet component and summed into the base peak ("ATP2" folds into "ATP");
a tie target must occupy a column to the left of the peaks referencing it, or lmfit raises UnboundLocalError partway through the fit.

build_prior_knowledge lets you name peaks and give plain numbers; it emits a correct file and refuses each trap at the door. Its output is the raw pyAMARES CSV text — save it with Path("pk.csv").write_text(...), or skip the file entirely and hand the spec straight to fit_amares(prior_knowledge=...).

The builder is dependency-light (no pyAMARES), so it is available even without the optional fitting extra installed.

Functions¶

Name	Description
build_prior_knowledge	Build a validated pyAMARES prior-knowledge CSV from a friendly spec.

build_prior_knowledge¶

fitting.prior_knowledge.build_prior_knowledge(
    peaks,
    *,
    tie_phase_to=None,
    shift_window=0.5,
)

Build a validated pyAMARES prior-knowledge CSV from a friendly spec.

Each peak is named and described with plain numbers; the trap-prone positional layout, bound syntax, and column ordering are handled for you.

Parameters¶

Name	Type	Description	Default
peaks	Mapping[str, Mapping[str, Any]]	Peaks keyed by name (letters only). Each value maps parameters to values: the required `"amplitude"` (a.u.), `"chem_shift"` (ppm — absolute literature ppm when `fit_amares` is given a `carrier`, else relative to it) and `"linewidth"` (Hz); the optional `"phase"` (degrees, default 0) and `"g"` (lineshape 0=Lorentzian..1=Gaussian, default 0); and optional `"<name>_bounds"` companions holding a `(lower, upper)` tuple (`None` opens a side). Phase is always bounded `(-180, 180)` unless overridden.	required
tie_phase_to	str	Name of an anchor peak. When given, every other peak’s phase is tied to the anchor’s (an lmfit expression), and the anchor is written first so it is defined before the peaks referencing it. Defaults to None (free phases).	`None`
shift_window	float	Half-width (ppm) of the default chemical-shift bound window placed symmetrically around each peak’s initial shift when no explicit `"chem_shift_bounds"` is given. Defaults to 0.5.	`0.5`

Returns¶

Name	Type	Description
	str	The pyAMARES prior-knowledge CSV as text. Pass the spec straight to `fit_amares(prior_knowledge=...)` to skip the file, or write this text to disk to keep a reusable, inspectable prior-knowledge file.

Raises¶

Name	Type	Description
	ValueError	If `peaks` is empty, a peak name is not letters-only, a required parameter is missing, an unknown key is present, `tie_phase_to` names a peak that is not present, or any bound has lower > upper.

Examples¶

>>> csv_text = build_prior_knowledge(
...     {
...         "PCr": {"amplitude": 10, "chem_shift": 0.0, "linewidth": 15},
...         "ATP": {"amplitude": 5, "chem_shift": -7.5, "linewidth": 20,
...                 "chem_shift_bounds": (-8.0, -7.0)},
...     }
... )