Fit wizard

The current ordinary model’s fixed time response also applies to fresh candidates, null baselines, retries, and dense curves. Recommendations and Apply retain it; response changes invalidate cached analysis identity. A recommendation with a different response cannot be applied; reopen the wizard and analyse again after changing Time response. Pulse settings are supplied context, not extra candidates.

The fit wizard is a guided workflow for choosing a sensible single-spectrum time-domain fit function. Open it, click Analyze, and it fingerprints the active spectrum, screens candidate model families drawn from the component library, ranks the fitted candidates with an information criterion (AICc by default), and hands you a plain-language recommendation with a confidence grade. Accepting it writes the chosen result back into the single-fit tab. The most natural use is the first pass on an unfamiliar spectrum — temperature points in the middle of a transition, a sample whose magnetic structure is not yet known, a survey of multiple compounds in a synthesis batch — but the ranking is also a useful sanity check when you already suspect a model: if the wizard does not agree with your guess, digging into the decision trail usually tells you why. For the very simplest cases (clean single-frequency transverse-field (TF) precession, an obvious single-exponential decay) building the model by hand in the fit panel remains faster.

Once the wizard has written a model into the single-fit tab, Fitting engine covers running and refining it and Assessing a Fit covers judging the result; for the same guided approach applied across a whole run series, see the Global fit wizard.

The wizard opens in a non-modal window from the single-fit tab and does not start the expensive analysis until you press Analyze. It uses the same dataset and bunching that the single-fit tab is using at the time you open it, but it analyses the whole record rather than the plot’s fit range: a heavily damped line lives in the first few tens of nanoseconds, before most fit ranges open, and a slow one needs the late tail, so cropping before looking would answer a different question from the one you asked. Applying a candidate is unaffected — the model and its fitted parameters go to the single-fit tab, which goes on fitting your range. Where that range would exclude a line the recommendation rests on, the wizard says so above the result:

The plot’s fit range starts at 1.2 µs, after the 240 MHz line (1/λ = 0.023 µs) has decayed; widen the range before applying this fit.

Completed wizard analyses are cached per dataset in the fit-panel state, reused when the wizard is reopened on the same run, persisted in project files, and consumed by the Global Fit Wizard as the screening table for ordered-series analysis. Reopening the wizard on a run it has already analysed (with nothing changed) skips straight to the result — no need to click Analyze again.

Fit Wizard result page — answer card with the recommended fit above the Compare candidates section, with the recommendation as A and a second candidate pinned as B

The wizard’s result page on a synthetic ZF Ag polycrystal dataset: the answer card gives the plain-language verdict, a confidence grade, and the data with the recommended fit overlaid. Below it, the Compare candidates section ranks every candidate and sets the recommendation (A) against a pinned alternative (B), above a decision trail whose steps expand to show the reasoning.

The two-click path

For most spectra the whole interaction is: open the wizard, click Analyze, read the answer. Everything else on the page is there for when you want to check the wizard’s working, not because you have to read it first.

  1. Open. The wizard opens on a plain explanation of what it is about to do — analyse this spectrum, fit a set of physics-motivated candidate models, and recommend one with a confidence grade, typically in about a minute — with the run number, field, temperature, and sample beside the title. Below it sits the model family picker (see Choosing which models to screen), which you can leave as it is.

  2. Analyze. Click the Analyze button. There is no surprise computation before this point.

  3. Watch the decision trail. While the analysis runs, a short list of stage headlines lights up one at a time as the wizard works through reading the run conditions, choosing physics families, searching the spectrum, fitting candidates, and weighing the winner. Cancel stays visible the whole time. The status line says you “can keep using the main window while recommendations are prepared”, and you can: if the main window ends up in front, the wizard returns to the front by itself as soon as the analysis finishes.

  4. Read the answer card. When the run finishes, the wizard shows an answer card: a plain-language verdict headline, a confidence sentence, a plot of the data with the recommended fit overlaid, and a prominent Apply this fit button. A “no significant structure” result is shown here as a legitimate outcome, not an error.

  5. Apply, or dig in. Click Apply this fit to hand the candidate to the single-fit tab. To weigh it against the other candidates first, use the Compare candidates section below the card (see Comparing candidates and applying a fit); to see the reasoning, expand any step of the decision trail beneath it.

Choosing which models to screen

Both the wizard’s running time and its answer depend on which candidate models it screens. Screening every model in the component library is safe but slow — a few numerically integrated models dominate the time — and a model that cannot describe your experiment only adds a chance of a spurious winner. The model family picker, shown open on the welcome page above Analyze, sets that list. Leave it as it is and the wizard screens every model that applies to the run; the same picker drives the Global fit wizard.

Fit Wizard welcome page — the model family picker with a Zero field answer above the Analyze button

The welcome page on the synthetic ZF Ag run. The file records no field direction, so the direction was answered “Zero field”, and the TF- and LF-only models are listed under their cards as not applying. The details panel shows the static Gaussian Kubo–Toyabe model, and the footer names the six slow models still in the screen.

From top to bottom, the picker holds:

  • Field direction. Which models apply depends first on the applied-field geometry, and the wizard reads it from the data file only — it never guesses a direction from the field magnitude. When the file records one, the row simply states it (“Recorded: Longitudinal”, for example). When it records none, as PSI ROOT files and synthetic runs often do, the note reads “The run records no field direction.” and every geometry is screened, which is the slow path. Answering Zero field, Longitudinal, or Transverse narrows the screen to that geometry’s models. The answer is saved on the run (“Set by you — saved on the run, which records none.”), kept in the project file, and re-applied when the project is reopened; it never overrides a direction the file records, and if a later file does record one, the file wins. Not recorded withdraws the answer. The answer matters beyond the screen: a Longitudinal answer lets the wizard hold \(B_L\) at the recorded field instead of fitting it (see The applied field is not a fitted parameter). A transverse- or longitudinal-field run whose setpoint is within 2 G of zero also screens the zero-field models, and at a known transverse field the muonium forms outside their validity regime are left out (the low-TF doublet above ~150 G, the Paschen-Back pair below ~1.5 kG; the exact four-frequency muonium model is never field-excluded).

  • Looking for (optional). Five chips name the physics you expect: Static magnetism, Spin dynamics, Superconductivity, F–μ–F & nuclear dipoles, and Muonium. With none selected every class is screened. Selected chips combine, so a longitudinal-field run can be screened for spin dynamics and muonium together. Generic relaxation and the constant background are always included.

  • Family cards. One card per family — Relaxation, Kubo–Toyabe, Oscillation, Muonium, Nuclear dipolar, and Background, plus Your functions when you have registered User functions. Each card has a checkbox that switches the whole family on or off, a count of its models in the screen (“5 of 5”), a one-line description of the family, and one pill per model that applies, which you click to switch that model on or off. A slow tag marks the models whose screening fits are expected to take more than 5 s per run on this computer (see which models are slow). Models that do not apply to the run are listed under the card rather than hidden — “Not ZF models: …”, or, at a known transverse field, “Outside these runs’ field range: …”.

  • Search. The box beside the direction row (“Find a model — Keren, F–μ–F, helix…”) matches a model’s readable name, its registry name, and its one-line use; matching pills are outlined and the rest dimmed.

  • Details panel. Hovering or clicking a pill shows what that model is for: its name and one-line use, the component description, the Geometries it applies in, its Fitting cost on this computer (below), and under This scope either “Included” or why it is out (for example “switched off by you”). A narrow window hides the panel; each pill’s tooltip still says what the model is for.

  • Footer. “Will screen N of M models” counts the included models out of those that apply to the run, and the line beneath names the slow ones still included. Leave out slow models drops them in one step. Once you have switched individual models on or off, Reset to suggestions appears; it discards those choices but keeps the chips and the slow switch. With nothing but the background left, the footer reads “Only the background is included — switch on a model to screen.” and Analyze stays disabled.

Which models are slow. How long a model takes to screen depends on its fits, not on the cost of one evaluation: dynamic Gaussian KT is cheap to evaluate but slow to fit. The wizard therefore times every candidate fit it runs. After each analysis it records, for each model, the fit time per 1000 fitted points, taking the median over the candidates that contain the model. Asymmetry keeps each model’s last nine records in fit_times.json in its application data folder, and takes their median as the model’s rate. A model is slow when that rate, scaled to the length of the runs in front of the picker, comes to more than 5 s per run. The length is the record as the wizard fits it: a record of more than 8192 points is rebinned first, and a series uses its median run length. The details panel shows the estimate (“Slow — ≈ 12 s per run on this computer” or “Quick — ≈ 0.4 s per run on this computer”), and the picker updates as soon as an analysis finishes.

Until a model has been timed on this computer, its declared cost decides and the panel reads “Slow (not yet timed on this computer)” or “Quick”. Nine built-in models start as slow: the two vortex-lattice models, anisotropic high-TF muonium, dynamic Gaussian and Lorentzian KT, Gaussian-broadened KT, and the dynamic, general-geometry and third-F F–μ–F models. The constant background is never timed and never slow. Leave out slow models leaves out exactly the models tagged slow. The timings belong to the computer, not to the project. They never enter a project file, and every project on the computer shares them. If the file is damaged, Asymmetry logs a warning and starts it again.

After an analysis the picker moves into the first step of the decision trail (below), where it shows the scope the result was screened under.

Seeding a peak (optional)

Below the picker, a collapsed “Guide the analysis (optional)” section holds peak seeding. Leave it closed unless you know of a line the automatic search may miss. Inside, the same time-domain and FFT plots you would see after analysis are already available, so you can seed a peak before the first run. Clicking on the FFT plot adds a user peak at that frequency (dashed red marker); clicking an existing user marker removes it. A peaks table lists every seeded and already-detected line and supports the same removal from a selected row. User peaks are treated as trusted frequencies: they seed oscillatory candidates directly and participate in pattern matching, which is the quickest way to steer the wizard when you can see a line it underrates. Naming a frequency also buys you its envelope: the same Δχ² test the damped-line scan uses is run at the frequency you clicked, and the rate it measures appears in the peaks table’s “Damping (µs⁻¹)” column and seeds the oscillator’s envelope. Because you supplied the frequency, the test no longer has to correct for having searched a whole band, so a line the blind scan declined can still be measured this way; a click on empty spectrum measures nothing and the seed stays a bare frequency. A heavily damped line that the windowed FFT plot cannot show you no longer needs seeding by hand at all — see Heavily damped lines: the matched-apodisation scan.

Changing the picker (including the field direction) or the peak seeds after an analysis has already run marks the displayed result stale — a banner says so, and the Analyze button relabels itself Re-run Analysis until you click it again.

The decision trail

Below the Compare candidates section sits the decision trail: six plain-sentence steps summarising how the wizard reached its recommendation. Each step expands to more detail; three of them expand into the same interactive panels you can reach from the welcome page, now populated with the finished analysis:

  1. Run conditions read — the field geometry the screen used, from the file or your answer (or a note that none was recorded, so every family was considered). Expands to the model family picker described above, which moves here from the welcome page; editing it marks the result stale.

  2. Physics families considered — which candidate families were screened and whether each was expanded for detailed fitting.

  3. Spectral search results — how many spectral lines and recognised patterns (a Larmor line, a muonium doublet, an F-μ-F triplet, and similar) were found. Expands to the FFT plot and peaks table, with the same click-to-seed/click-to-remove peak controls available during guidance.

  4. Candidates fitted, rejections with reasons — how many candidate models were fitted successfully, how many reference baselines were also fitted, and, in plain terms, why any candidate was rejected. Expands to the full comparison table (score, information-criterion values, residual-gate status, reduced chi-squared, and parameter count for every candidate; selecting a row makes it candidate A, exactly as clicking it in the Compare candidates section does).

  5. Winner vs null baseline and checks — the recommended candidate and whether it is decisively better than a plain-relaxation reference.

  6. Confidence statement — the same confidence sentence shown on the answer card, with any caveat spelled out in full underneath.

Expanding a step never re-runs anything; the trail (and every panel it exposes) is derived directly from the completed analysis.

The comparison table (reached from step 4) also lets you switch the ranking metric. A “Ranking metric” control on the result page reranks the already computed candidate fits immediately — it does not rerun the expensive fitting stage. Each shortlisted candidate was fitted with a deterministic multi-start strategy: five initial parameter sets around heuristic starting values, including factor-of-two perturbations, keeping the best successful result per template. The three available metrics are:

\[\mathrm{AIC} = \chi^2 + 2k\]
\[\mathrm{AICc} = \mathrm{AIC} + \frac{2k(k+1)}{n-k-1}\]
\[\mathrm{BIC} = \chi^2 + k \ln(n)\]

Here \(k\) is the number of free parameters and \(n\) is the number of fitted points. Smaller values are preferred. AICc is the default because it adds a small-sample correction when \(n\) is not large compared with \(k\). It is unavailable when \(n-k-1\leq0\) or the fitted point count is unknown; such a candidate is excluded from ranking under AICc. Another metric is never substituted. Fixed parameters, link followers and tie followers do not count toward \(k\); free auxiliary tie parameters do. If no row is rankable, the message is “No candidate could be ranked by AICc; inspect unavailable criteria and fit diagnostics before applying a model.”

Unavailable cells show “—”. Hover for the reason and recorded counts, for example “AICc undefined: n − k − 1 = 0 (n = 4 points, k = 3 free parameters)”. The CLI screening table prints n/a; its JSON candidate rows contain aicc: null and an aicc_unavailable explanation.

The correction is derived for linear Gaussian models with an estimated variance and is used here as the conventional small-sample correction [aicc_primary]. Comparisons require the same data and likelihood; a data-only additive likelihood constant cancels only under that condition. AIC is due to Akaike [aic_primary] and BIC to Schwarz [bic_primary].

The scriptable InformationCriteria value records only the finite \(-2\ln L\), free-column count and fitted sample count. Its value and unavailable_reason methods expose availability; rank returns both the ranked and excluded candidates, with reasons. A saved wizard recommendation recomputes its criteria from its fit statistics and cannot publish an undefined score as its recommendation.

BIC applies a stronger penalty to model complexity and therefore usually favours simpler descriptions.

Comparing candidates and applying a fit

A recommendation is only as good as the alternatives it beat, so the result page lets you set any candidate beside it. The Compare candidates section below the answer card is the same comparison panel the Global Fit Wizard uses in its Compare step (see Global fit wizard), here with a single run.

On the left, every candidate the wizard fitted is listed best first (the caption names the ranking metric, “Candidates · ΔAICc from best”), including the reference baselines and any disqualified candidate, marked “(baseline)” and “(disqualified)”. Each row carries a bar for its difference from the best candidate on the ranking metric, its evidence weight — the Akaike weight \(w_i \propto \exp(-\Delta_i/2)\) normalised over the list, read as a percentage — a Pass or Warn badge for the residual checks, with any failing check spelled out beneath, a “Fixed:” line naming parameters that were held fixed, and parameter flags (“at lower bound”, “at upper bound”, “not finite”, or “poorly determined”).

Click a row to make it candidate A. A starts as the recommendation, and A is what the answer card draws and what Apply this fit hands off: picking another candidate here redraws the card’s plot with that candidate’s fit and titles it with the candidate’s name. Pin as B on any other row overlays it as candidate B, and Unpin B clears it. On the right, the data are drawn with A solid and B dashed, above a strip of normalised residuals \((y - f)/\sigma\) (A in colour over B in grey, clipped at \(\pm4\sigma\), with each candidate’s \(\chi^2_\nu\) at the end, “χ²ᵣ A · B”). Below, a parameter table sets A’s fitted values beside B’s, with a note column for either side’s parameter flags. The wizard draws the fitted curve only for the candidates it answers with; the first time you pick any other candidate as A or B, its curve is built in the background and appears a moment later, while the data are shown straight away. Apply A to the fit panel at the foot of the section applies A, as Apply this fit does.

A “Show residuals” toggle under the card’s plot switches it to a residuals view for A.

Applying a candidate (from the card or from the Compare candidates section) updates the single-fit tab: the composite function is replaced with the chosen candidate, fitted parameter values are written into the parameter table, the fit summary is updated with the wizard statistics, and the rest of the GUI refreshes normally. Even if you do not apply a candidate immediately, the comparison table is preserved with the analysis; this matters for later global analysis, because the Global Fit Wizard can reuse the stored per-run tables instead of recomputing them.

If you want to reconsider from scratch, Re-analyze returns to the opening page so you can adjust the picker or the peak seeds before running again — this is a different action from Re-run Analysis, which is what the Analyze button relabels itself to after a picker or peak-seed change makes the current result stale.

Copy analysis log renders the full six-step decision trail — headline and detail bullets for every step — as plain text to the clipboard. This is the right thing to paste when asking a supervisor to sanity-check a recommendation, or when reporting an issue with the wizard: it captures exactly what the wizard considered and why, without requiring a screenshot.

Candidate families

The wizard groups the component library into families — simple relaxation, multi-rate relaxation, static nuclear fields (Kubo-Toyabe), precession signals (including vortex-lattice line shapes), muonium, and muon-fluorine bonding (μ-F / F-μ-F) — and screens them in two stages. Stage 1 fits one cheap representative per in-scope family (both exponential and Gaussian shapes for the relaxation family). A family is expanded to its full portfolio when its representative passes the residual checks, scores within a small margin of the best family, matches a recognised multiplet pattern in the detected peaks, or is pointed at by a fingerprint hint — and an accepted matched-apodisation scan line promotes the oscillatory family the same way a pattern match does. Expensive members such as the numerical F-μ-F powder averages are only ever fitted inside an expanded family, seeded from the match (a hyperfine constant from a muonium pair, a μ-F distance from a triplet). When several strong spectral lines are detected, the wizard also constructs multi-cosine candidates with one damped oscillator per line, up to three.

The applied field is not a fitted parameter

Two parameters in the component library describe the field you applied rather than anything the sample did: field, the transverse field the muonium and vortex-lattice line shapes precess in, and B_L, the longitudinal component carried by the Kubo-Toyabe family (LongitudinalFieldKT, DynamicGaussianKT, DynamicLorentzianKT, GaussianBroadenedKT, Keren) and by MuoniumLFRelax. Both are recorded in the run metadata, so the wizard seeds them from it and holds them fixed. Fitting a quantity you measured on the magnet costs a degree of freedom in every information criterion and buys nothing.

For B_L the rule follows the recorded geometry, because a magnitude alone does not say how much of the field lies along the muon spin:

  • a zero-field run pins B_L at 0, whatever magnitude the file carries. A ZF label means the magnet was nulled; a non-zero setpoint recorded beside it is a nominal or stale reading, not a longitudinal field;

  • a longitudinal-field run with a recorded setpoint pins B_L at that setpoint — including a run whose file records no direction but which you answered Longitudinal in the model family picker;

  • a field magnitude of zero (within 0.1 G) pins B_L at 0 in any geometry, recorded or not — a zero applied field has a zero longitudinal component however it is oriented;

  • a transverse setpoint, or a run whose field was never recorded, leaves B_L free. It is then seeded at a small positive field rather than at its zero lower bound: Minuit cannot start a parameter sitting on a limit, and a seed inside the decoupling window (\(\omega_0 < 0.05\,\Delta\), where the Kubo-Toyabe functions use their exact zero-field form) would leave the fit with no gradient in B_L at all.

The zero-field case is the one that used to bite. B_L was seeded but left free, so on a genuine zero-field record it started exactly on its own lower bound, the fit came back “parameters at limit, EDM above threshold”, and the wizard discarded the record’s own model in favour of whatever shape merely fitted — a stretched exponential, typically, and with High confidence.

One consequence is worth knowing when you read the comparison table. With B_L pinned at 0, LongitudinalFieldKT + Constant is the same function as StaticGKT_ZF + Constant fitted on the same three free parameters, so the two score identically. The wizard recommends the one that never carried the pinned extra and shows the other as a similarly scoring alternative.

Pinning an LF setpoint is deliberately a hard pin and not a window around the recorded value. A magnet calibrated wrongly enough to matter is a hardware problem the fit should not quietly absorb into B_L: the fix is to correct the metadata, or to untick Fix for B_L in the single-fit tab after applying the candidate, which the wizard leaves ticked exactly so you can see what it decided.

Heavily damped lines: the matched-apodisation scan

An oscillation whose envelope dies in the first few tens or hundreds of nanoseconds lives entirely in the leading fraction of the record — and every symmetric apodisation window (hann, cosine, gaussian) is zero at the first sample, so a windowed transform deletes it. That is the same trap the library’s ApodisationEarlySignalWarning exists to flag when you drive the Fourier tools yourself.

The wizard’s spectral search therefore runs a second, unwindowed pass: a matched-apodisation scan. The record is multiplied by a decaying exponential \(e^{-t/\tau}\) and transformed, once for every \(\tau\) on a geometric ladder running from about twenty time bins up to half the informative record, at roughly four rungs per decade. A line whose own envelope is \(e^{-\lambda t}\) reaches its greatest signal-to-noise on the rung where \(\tau = 1/\lambda\), because the apodisation is then a filter matched to the signal — the classical result that, for a known pulse shape in additive noise, the filter matched to that shape maximises the output signal-to-noise ratio. The rung a line peaks on therefore measures its damping instead of inferring it from a crop length somebody chose, and no crop is asked of you: the ladder replaces it. Detection runs on the whole record, truncated only at the point where the growing per-point error has made the remaining data uninformative.

A peak on the ladder is a candidate, not a line. Each candidate is tested by weighted linear least squares: the record is fitted with a dictionary of slow decays (\(e^{-\lambda_k t}\) for \(\lambda_k\) = 0, 0.3, 1, 3, and 10 μs-1), then again with an \(e^{-\lambda t}\cos\) / \(e^{-\lambda t}\sin\) pair added at the candidate’s \((f, \lambda)\), and the χ² improvement Δχ² between the two is maximised over a bounded box around the seed. Both fits are linear, so Δχ² is exact rather than the outcome of an iterative search. Acceptance is a look-elsewhere-corrected threshold,

\[\Delta\chi^2 \ge 2\ln(N_\mathrm{trials} / r),\]

where \(r\) = 0.01 is the number of false lines tolerated per record and \(N_\mathrm{trials}\) counts the independent cells the ladder searched — the same philosophy as the windowed pass’s SNR gate, applied to a statistic rather than to an amplitude ratio. An accepted line joins the nuisance basis and is subtracted from the record before the ladder is scanned again, so a strong line’s skirt cannot manufacture a second one; up to three lines are found this way, each finally re-fitted with the others held in the basis so their reported numbers are comparable.

One accepted line is enough to build candidates the earlier portfolio could not offer: a sum of damped oscillators, one per scan line and up to three, plus a slowly relaxing term and a constant, with either an exponential or a Gaussian envelope on the oscillators. A heavily damped line almost always sits on a relaxing background it decays into, and without a term for that background the fit spends an oscillator on it. Every oscillator is seeded from the measurement — frequency, envelope rate, amplitude, and phase — with rate bounds always containing \(\lambda/4\) to \(4\lambda\) and frequency bounds a few line widths wide. An accepted line also promotes the oscillatory family for detailed fitting, so these candidates are fitted whenever the scan finds anything at all; on a record where it finds nothing they never appear.

Three things to know when reading the result:

  • Scan lines are labelled damped_scan in the peaks table, and the envelope each one measured appears in its own “Damping (µs⁻¹)” column, with the amplitude, phase, and Δχ² in the row’s tooltip. On the FFT plot they carry a dashed marker and name themselves in the legend, “Matched-apodisation scan line — not expected to be visible in this windowed transform”: the plot is the windowed transform, so a scan line is legitimately absent underneath its own marker. (The older unwindowed crop ladder, whose early_fft peaks used a dotted marker, remains in the library but no longer runs as part of the search.)

  • Its numbers are not comparable with the windowed pass’s. A scan signal-to-noise is an excess over one rung’s own median-absolute-deviation noise floor, not a magnitude ratio, and Δχ² is a third scale again. Rank peaks within a pass, never across.

  • Slow lines belong to the windowed pass. Where a line is visible to both, the windowed pass wins: it looked at the whole informative record, so its frequency estimate is the better one, and the scan only ever adds lines the windowed pass missed. The scan is also deliberately blind to slow, low-Q features: a candidate completing fewer than about three cycles inside its own fitted lifetime is read as a relaxation shape rather than an oscillation and rejected, unless its envelope is faster than any relaxation the slow-decay dictionary models. That rule is what keeps a static Kubo-Toyabe minimum out — a single dip and recovery that no sum of monotonic decays reproduces, and which Δχ² alone would happily call a line.

The scan reaches envelope rates of a few hundred μs-1 on a finely binned record. The limit is the short end of the ladder, so what it can reach depends on the binning: 0.1 ns bins reach far further than 16 ns ones. Faster than that the oscillation is not recoverable at any apodisation, and the wizard simply offers no damped candidate. At the other end, a component so overdamped that it barely completes a cycle is fitted as one broad line if it is accepted at all; treat the frequency it reports as a description of that line shape rather than as a precession frequency, and check the fit overlay before reading physics into it.

The additive multi-component candidates are especially useful for spectra whose smoothed semilog envelope changes slope while remaining largely monotonic. In that situation a very low-frequency FFT peak can be a by-product of envelope shape rather than genuine precession, so the wizard distinguishes resolved oscillations from multi-rate monotonic relaxation and can try mixtures of exponential and Gaussian channels with up to three relaxing components.

If the single-fit tab already has a different composite model selected, the wizard fits that function too and keeps it as a baseline comparison, useful when you already have a hand-built function and want to see whether the wizard’s simpler portfolio explains the same spectrum comparably well.

Recommendation rules

The wizard does not claim that there is always one unquestionable winner. Its default recommendation policy is:

  1. Rank successful candidates by the selected metric, excluding null baselines and any candidate disqualified for a targeted physical reason (see Confidence and verdicts below).

  2. Break ties by preferring fewer free parameters.

  3. Break remaining ties by preferring fewer additive terms.

  4. If the top two candidates are within 2 score units, present them as a comparable pair (both have near-equal evidence weights in the Compare candidates list) and recommend the simpler one.

  5. Check the winner against a simpler null baseline. If it does not clear that bar, recommend the null instead.

  6. Otherwise recommend the winner, with a confidence tier set from the residual gate.

This keeps the default behaviour interpretable and favours models that are good enough without adding unnecessary physical parameters.

Confidence and verdicts

Every recommendation carries a confidence tier and, in the unusual case that nothing in the portfolio is worth recommending, a different kind of verdict altogether. Both are stated in plain words on the answer card, and the same wording appears (with any caveat spelled out in full) in the decision trail’s confidence step.

High confidence reads “High confidence — the recommended model describes the data cleanly.” It means the recommended candidate’s residuals pass every check in the residual gate — nothing about the fit’s mismatch with the data looks structured.

Medium confidence reads “Medium confidence — this is the best model tried, but the fit leaves patterns in the residuals. Usable; review before publishing,” followed by a caveat naming which diagnostics still show structure. It means the candidate is still the clear winner by the selected metric, but one or more residual diagnostics still show structure. Treat a Medium-confidence recommendation as usable with that caveat in mind — check the named diagnostics in the residuals view before trusting the fit for publication. Either way, High or Medium, the best-scoring candidate is recommended: the residual gate no longer removes a candidate from consideration, it only tells you how much to trust the number at the top.

What does remove a candidate from consideration is a targeted disqualifier — a check aimed at a specific, physically implausible failure mode rather than general residual shape:

  • a fitted oscillation frequency sitting at the 1/T resolution floor of the fit window, or pinned against one of its bounds — both are signs the “line” is really an artefact of a too-short window or an unconstrained fit, not a resolved frequency

  • an oscillation amplitude statistically consistent with zero — the component is present in the model but not actually needed by the data

  • a free-running oscillation frequency with no supporting line in the detected-peaks table and too few cycles inside the statistically informative part of the window to stand on its own

  • a relaxation component the data do not resolve — see Are the components actually resolved? below

A disqualified candidate is still shown in the comparison table (step 4 of the trail), with its title suffixed “(disqualified)” and the specific reason available as a tooltip on that row, but the wizard moves on to the next candidate rather than recommending it.

A recommended oscillation that clears that floor but only just — completing somewhere around two to three cycles inside the informative part of the window — keeps its computed confidence tier, but if its spectral line is also weak or missing from the detected-peaks table, the caveat notes that the oscillation sits at the edge of what the run can resolve and suggests a longer or higher-statistics measurement to confirm it. A strong, well-corroborated line at the same cycle count is not flagged.

Before settling on a winner among the surviving candidates, the wizard also checks it against two cheap null baselines that are always fitted unconditionally: a flat constant, and a plain exponential decay plus constant. These appear in the comparison table with their titles suffixed “(baseline)”. If the best candidate does not improve on the simpler of the two nulls by roughly 10 AICc units or more, the wizard concludes that the data do not carry enough structure to justify the richer model and recommends the null baseline instead — this is the wizard’s way of saying “there is nothing here worth a richer model.” The answer card shows this as its own headline, “Your data look like a simple decay — no oscillation worth fitting,” and treats it as a legitimate result rather than a failure: it usually means the spectrum is well described by a plain relaxation (or is flat within the noise), and chasing a more elaborate model would be over-fitting.

Are the components actually resolved?

A composite relaxation model will happily converge with one branch railed to a rate so fast that its 1/e time falls inside the first few time bins, or collapsed so slow that it never decays inside the fit window. Neither is a measured rate: the first is absorbing the leading bins, the second is indistinguishable from a free constant baseline. Both still buy χ², so AICc will “prefer” the extra component — which is exactly how an extra exponential ends up in a published model.

The wizard therefore checks every candidate that carries two or more relaxation rates. For each rate it asks whether the value lies inside the window the data can resolve:

  • the 1/e time must span at least a few time bins (the fast edge), and

  • the 1/e time must be no longer than the fit window (the slow edge).

The check is two-sided on purpose. A fast-edge-only rule silently admits the collapsed-to-zero branch, which is the same pathology seen from the other end.

Crucially, the verdict is not read off the fitted value alone. Where the likelihood has a flat ridge in a rate, two optimisers landing in statistically indistinguishable minima can return opposite answers on the same data — one “resolved”, one “railed”. So the wizard judges the whole Δχ² ≤ 1 neighbourhood: it pins the rate just outside each edge, re-fits everything else, and asks whether the data can tell the difference. That gives three distinct outcomes:

resolved

The rate, and every value the data cannot distinguish from it, sit inside the resolvable window.

unresolved_fast / unresolved_slow

The fitted rate itself is outside the window — railed into the leading bins, or degenerate with the baseline.

undetermined

The fitted rate is inside the window but the admissible interval reaches outside it. This is the honest third answer: the data do not determine the component either way, and neither “resolved” nor “railed” would be true.

Anything other than resolved disqualifies the candidate, with the reason carried on the row exactly like the oscillation disqualifiers above.

The same rule is available on its own for scripted analyses, where you can set the bin tolerance your binning justifies and supply your own multistart solutions as the neighbourhood instead of paying for the probe re-fits:

from asymmetry.core.fitting.resolution import assess_component_resolution

assessment = assess_component_resolution(
    fit_result,
    model,
    dataset,
    min_bins_per_e_folding=20.0,      # a rebinned corpus can justify far more
)
if not assessment.is_resolved:
    for reason in assessment.disqualification_reasons():
        print(reason)

Pass solutions=[(chi_squared, {"Lambda_1": ..., "Lambda_2": ...}), ...] to use converged multistart seeds you already have; pass probe_neighbourhood=False to fall back to the point estimate, which is cheapest and documented as optimiser-dependent.

Convergence quality

Comparing two models is only meaningful when both were searched to comparable depth. Two things guard that:

  • the Stage-2 seed ladder scales with a candidate’s rate dimensionality, so a three-rate family is not judged on the same handful of seeds that fully covers a one-rate family’s search space; the extra seeds widen the seeded rate separation, which is the dimension a multi-component fit exists to determine;

  • after ranking, the top few candidates are re-fitted with the full seed ladder. Whichever fit is better is the one reported, and the χ² gained is recorded on the assessment as refinement_delta_chi_squared, with under_converged set when it exceeds one χ² unit.

under_converged is not a warning that the reported number is wrong — the reported number is the deeper fit. It is the measured statement that this candidate’s original ranking was search-limited, and therefore that the whole table around it should be read with that in mind. Pass refine_top_candidates=0 to skip the pass.

A third thing matters on a long record: the candidates are fitted on a rebinned copy of it. A dozen multi-component fits on 105 points is minutes of arithmetic for information a coarser observation already carries, so above roughly 8 000 points the wizard rebins — never so far that the highest seeded frequency drops below eight samples per cycle — and says which record it used:

Candidates were fitted on a ×8 rebinned copy (11250 points); information criteria refer to that record.

Line detection uses its declared spectral observation, retaining the native bandwidth for captured nonuniform histograms. Candidates fit the selected rebinned observation. AIC, AICc, BIC, χ²ᵣ, RMS and runs refer to that fit; a separate residual FFT evaluates the same fitted model and parameters on the diagnostic observation. Its attribution distinguishes that view from the original residuals. The recommendation records the fit rebin factor and point count as rebin_factor and analysed_points.

For a reproducible histogram observation the wizard merges counts and their retained variance before forming asymmetry. It preserves the selected period, projection, alpha/beta, timing, good support, corrections, reference acquisition, and base binning. Toolbar merges compose with the wizard factor once; a cropped input retains its selected output-bin members before further merging. For F = [90, 1] and B = [10, 9], a factor of two gives 65.454545…%, whereas the mean of the two separate asymmetries is 0%.

The captured observation owns read-only copies of sample, held-period, and reference counts and supplied variances, together with copied settings and timing. Editing the original arrays through the scripting API leaves that observation, its cached analysis, and rebuilt curves stable. To analyse edited counts, first reduce them again to capture a new observation, then rerun the wizard.

Curves without resolved histogram context, including custom or historical curves that retain a Run, and rotated observations use the independent-curve mean. For conditional calibration errors and histogram Gaussian omission, see Calibration conditioning and Undefined and degenerate bins. Used/omitted counts and reasons travel with the core fit result through search, completion, and rebuilding; model scores count only the fitted observations. Detection keeps the full acquisition grid. When omission prevents a residual FFT or acquisition-lag autocorrelation, the diagnostic is unavailable; a valid fit remains available. No missing-bin interpolation is inserted. The single-run Details view shows unavailable and the core result explains Residual autocorrelation and FFT unavailable: Gaussian selection omits acquisition bins. Historical scores retain their recorded meaning, while numerical reuse requires the current observation policy.

The wizards still fit asymmetry with conditional Gaussian point errors; TF alpha/beta count calibration is a separate operation. Models are evaluated at the prepared timestamps, so wide bins can attenuate rapid signals.

Variable science bins with the separately labelled fixed native diagnostic FFT

The spectral plot is labelled Windowed FFT (fixed native diagnostic) when a separate native count view is used. Preparing spectral preview… runs through the existing cancellable worker preparation; redraws reuse its captured spectrum.

Spectral detection preserves uniform curves. Nonuniform Variable and Constant error histogram observations use a separate Fixed native-bin count reduction (factor 1, merge 1) over exactly their retained native support. Base/toolbar/crop/merge selections are resolved before selecting this grid; incomplete merged tails stay excluded. The captured pair, periods, balances, timing, corrections/reference and retained variances supply the same operation. Hann, early, damped-line and Burg passes share this declared view, whose actual sampling interval and informative window determine spectral bandwidth/resolution. Non-spectral fingerprint features still describe the original science curve. See Fourier analysis for the support rule and direct-FFT sampling limits.

Residual FFTs evaluate the same fitted model/parameters on that separate fixed count view. The original objective, points, scores, parameters/covariance and residual times/errors are unchanged; RMS and runs still use original residuals. The result records separate_fixed_count_reduction when that view is used. Acquisition-lag autocorrelation is unavailable for nonuniform original residuals. Omitted Gaussian observations retain the unavailable diagnostic guard above. Missing diagnostics are not evidence that a model explains the data.

A nonuniform curve-only/custom curve with an attached Run is still refused; a Run or recipe alone does not establish count replay. Uniform curve-only FFTs remain supported. A sampled detrend_curve cannot be evaluated on a different grid; supply detrend_model(time) for a fitted trend. Undefined native ratios remain unavailable rather than being filled, omitted or averaged into a spectrum. Defined zero-variance boundary ratios retain Fixed controls’ FFT support and canonical display errors; Gaussian fit selection remains separate.

Asymmetry also checks that a current assessment’s source observation is unchanged before rebuilding curves. A changed input raises Wizard observation changed; rerun the analysis before rebuilding curves. Rerun the analysis to obtain scores and curves for the edited observation; this prevents a different record from being drawn under the saved score.

Cached analyses require the same observation, reduction context, selected support, scope, frequencies, numerical preparation contract, and scientific-computation revision. Unknown or older executions cannot supply current reusable recommendations. Rebuilt curves use the same prepared grid as the fitted assessment. Saved historical results retain their values and curve-mean reconstruction semantics; opening them does not refit or relabel their scores.

Compared with other programs

WiMDA 1.326 grouping, musrfit 1.12.1 ordinary packing, and documented Mantid muon preprocessing combine counts before the F/B ratio. This comparison concerns input observations, not wizard search or ranking. See Binning and timestamps for public sources, uncertainty conventions, and matched-support limits. Mantid 6.16.1 FFT requires linear X coordinates and exposes its shift convention and full/positive-frequency outputs. musrFT 1.12.1 (708f777b, ROOT 6.40.04) supports explicit packing and Fourier controls. Matched fixed-grid 1.3 MHz controls agree within one actual frequency bin; endpoint and amplitude conventions remain distinct. Neither comparison establishes equivalent wizard ranking or spectral uncertainties. See spectral conventions.

Calling the wizard from a script

build_fit_wizard_recommendation evaluates its candidate models across a process pool. Python starts those worker processes with the spawn method, and every spawn worker begins by re-importing the calling script’s __main__ module. Put your analysis behind a guard so the workers do not re-run it:

from asymmetry.core.fitting.fit_wizard import build_fit_wizard_recommendation

def main():
    recommendation = build_fit_wizard_recommendation(dataset)
    print(recommendation.recommended_key)

if __name__ == "__main__":
    main()

Without the guard the wizard detects the situation before starting any worker, runs serially instead, and warns once with SpawnUnsafeWarning — the results are identical, only slower. Interactive sessions, python -c ... and notebooks are unaffected: there is no module for a worker to re-import, so they keep full parallelism.

Passing max_workers=1 is always a safe escape hatch — it never starts a worker process at all, and it also makes runs bit-for-bit reproducible when you need to compare two invocations exactly. The same rules apply to Global fit wizard, which uses the same machinery.

The returned FitWizardRecommendation carries the record the candidates were actually fitted on as rebin_factor and analysed_points (both described under Convergence quality), and its peak_analysis carries the matched-apodisation scan’s own result — the accepted lines with their rates, amplitudes, phases, and Δχ², together with the threshold and trial count they were judged against — as peak_analysis.damped_lines. The scan is also usable on its own:

from asymmetry.core.fitting.damped_line_scan import detect_damped_lines

analysis = detect_damped_lines(dataset.time, dataset.asymmetry, dataset.error)
for line in analysis.lines:
    print(line.frequency_mhz, line.damping_rate_per_us, line.delta_chi_squared)

measure_line_at_frequency in the same module answers the narrower question the GUI’s click-to-seed asks: given a frequency you already trust, what is its envelope?

Limitations

  • The wizard currently supports one time-domain asymmetry spectrum at a time.

  • Frequency-domain fingerprinting uses the standard FFT path only; MaxEnt is not part of the wizard workflow.

  • Analysis and fitting run on the record’s statistically informative window, not necessarily on all of it: where the per-point error has grown to several times its early-time value, the remaining data are noise that would only whiten the transform, so the window is cut there. A run whose errors do not grow that way is analysed whole.

  • The fit range set in the plot panel governs the fit you apply, not the analysis. A range that would exclude a detected damped line is flagged above the result, not corrected for you.

  • Information criteria refer to the analysed record, which on a long run is a rebinned copy (see Convergence quality).

  • max_workers bounds how many fits run at once, not how much CPU the run uses: the vortex-lattice line shapes reach a multi-threaded BLAS from inside a single fit, so even max_workers=1 can saturate the machine. Set OMP_NUM_THREADS / OPENBLAS_NUM_THREADS in the environment before starting Python if you need to bound it.

  • Recommendations are limited to models that can already be assembled from the supported composite-model components.

  • Bayesian model comparison is not part of version 1, although the comparison backend is designed so that it can be added later.

The wizard should be treated as a decision aid rather than a replacement for physical judgement. Inspect the fit overlay, residuals, and parameter values before accepting the recommendation, especially when two candidates score similarly.

Omission counts and unavailable residual diagnostics for a sparse synthetic Ag fit.

Sparse Ag control with an authored fixed-background sensitivity operation. The fit keeps usable signed observations; the display retains the full grid. Omission counts and unavailable residual diagnostics belong to the core result.

[aic_primary]

H. Akaike, IEEE Trans. Autom. Control 19, 716–723 (1974), doi:10.1109/TAC.1974.1100705.

[aicc_primary]

C. M. Hurvich and C.-L. Tsai, Biometrika 76, 297–307 (1989), doi:10.1093/biomet/76.2.297; N. Sugiura, Commun. Stat. Theory Methods 7, 13–26 (1978), doi:10.1080/03610927808827599.

[bic_primary]

G. Schwarz, Ann. Statist. 6, 461–464 (1978), doi:10.1214/aos/1176344136.