Global fit wizard

The current ordinary model’s fixed time response applies throughout screening, candidates, and phase application. An analysis with a different response cannot be applied to the current setup. Reopen the wizard and analyse again after changing Time response; separation remains supplied context, outside the sharing and candidate tables.

The global fit wizard is the analogue of Fit wizard for an ordered series of runs — a longitudinal-field decoupling series, a temperature scan, a fallback run-order sweep — where the experiment is set up so that one common composite model should describe every dataset, with each parameter either shared globally across the series or free per run. The textbook use is a longitudinal-field (LF) decoupling series where the field-distribution width \(\Delta\) is shared across runs and the applied field \(B_L\) is local to each run (LF decoupling and static-vs-dynamic field distributions), but the same workflow applies to any ordered sweep you expect a single model family to fit — an Oscillatory * Exponential + Constant precession signal followed through one magnetic phase, say. Where the model qualitatively changes across the series — a paramagnetic component appearing through a transition, oscillations collapsing into a relaxation — the wizard partitions the series into phases at the transition and fits each phase under its own template and global/local assignment, instead of forcing one model across a break it was never going to describe; see Phases: transitions and the penalty path below.

The wizard is a five-step window, Scope → Screen → Compare → Phases → Apply, laid out as a stepper across the top so that what each stage does, and what comes next, is always in view. Scope reviews the series and chooses which model families to consider; Screen fits each family to every run independently and ranks the families; Compare holds the coupled global fits of the families you shortlisted, one row per sharing pattern, and sets two of them side by side; Phases partitions the series at a transition when the model changes along it; and Apply reviews exactly what will be handed to the global-fit tab before it is handed over. It differs from the single-spectrum wizard in one important way: it drives a two-stage screening-then-optimisation workflow rather than a single recommendation, and you choose on the Screen step which families earn the expensive coupled fits.

The reason for the two stages is cost. Screening builds a ranked table from independent single-dataset fits across the whole series — fast, and enough to see at a glance which candidate families look promising. The coupled global optimisation, which actually enforces the shared-parameter constraints, then runs only for the families you tick. Keeping the stages on separate steps makes it obvious which results are still only single-fit screening and which have been optimised under parameter sharing. The coupled step is where the wizard pays for itself: sharing a parameter usually tightens the uncertainties on the common quantities (typically the field-distribution widths and amplitudes) below what any single-run fit can achieve, and it cleans up the per-run trends in the local parameters by suppressing the noise that arises when each run independently re-optimises an otherwise common quantity. It is also a useful cross-check on a series you have already fit by hand — the screening stage should recover the same model family you converged on.

What a series fit is for is usually the trend: parameters that can be followed along the temperature or field axis, with error bars small against their variation. The best fit in the statistical sense is often not that fit. With thousands of points per run, freeing a parameter on every run almost always lowers an information criterion, and the parameters then trade against each other run by run — an amplitude against a background, an amplitude against a rate — and stop being trackable. By default the wizard therefore recommends the sharing pattern whose per-run parameters trend best among the patterns that fit adequately (see What “trends best” and “fits adequately” mean). The information-criterion ranking remains available as the other objective; the Recommend switch on the Scope step chooses between them.

Once the wizard has applied a model, Fitting engine covers running and refining the coupled fit and Assessing a Fit covers judging the result. For the single-spectrum version of the same guided approach, see Fit wizard.

The guided journey

Open the wizard from the global-fit tab with a run series selected. It uses the datasets, bunching, and fit range the tab is using at the time you open it, so candidates are compared on exactly the points a manual global fit would use. Completed wizard states are cached with the tab context and persisted in project files, so reopening the wizard on an unchanged series skips straight to the last result — the Compare step when coupled fits have been optimised, the Screen step otherwise — rather than rebuilding an unchanged screening table or rerunning finished optimisations.

Each step in the stepper shows its number, its title, and a one-line summary of where it stands, and its disc marks its state:

  • done — a green ✓: the step’s work is finished;

  • current — a filled disc on a highlighted tile: the step on screen;

  • ready — an outlined disc: the step’s inputs exist and it has not run (Compare reads “Next: optimise the shortlist” once screening is done);

  • stale — an amber “!”: the step’s results no longer match the scope, or were optimised for the other objective (see Scope: review the series and choose scope below);

  • running — a turning arc: an analysis for this step is in progress (“Screening…”, “Optimising the shortlist…”, or “Optimising phases…”);

  • skipped — a dashed disc: the step does not apply to this series (Phases reads “No transition found”).

Done, stale, ready, and running steps are clickable, so you can move back to Scope to widen the search, or leave a long run and read an earlier step while it goes; a pending step waits for its inputs. The summaries follow the analysis: Scope names the field direction and the number of models (“Longitudinal · 31 models”), Screen names the leading family (”Title leads”), Compare counts what was optimised (“2 sharing ladders climbed”, or “8 role splits optimised” under the statistical objective), Phases states the selected partition (“1 transition · 21 ± 3 K”), and Apply names what it holds (“Pick a model first”, “Ready: title”, and “Applied: title” once it is applied).

An analysis shows its progress inside the step it feeds: screening in Screen, the coupled optimisation of the shortlist in Compare, and the per-phase optimisation in Phases. The block carries a bold header, a short decision trail whose steps light up as the core reports progress, a collapsed Live log that captures every progress message in full, and Cancel, which stops a long run cleanly and returns you to the step you started it from. When the run finishes, the header, the trail, and Cancel go and the block collapses to a Run log disclosure that keeps the log. You can work in the main window while the analysis runs; if it ends up in front of the wizard, the wizard returns to the front by itself as soon as the analysis finishes.

Scope: review the series and choose scope

Global Fit Wizard Scope step — series overview, the model family picker with a Longitudinal answer, and the Run screening button

The Scope step on a four-field Ag longitudinal-field decoupling series. The Series table lists each run as soon as the context arrives; the classification columns stay — until screening runs. Below it, the Scope section holds the model family picker: the files record no field direction, so the series was answered “Longitudinal”, and because run 5201 sits at 0 G the zero-field models stay in the screen too. Beneath the picker are the collapsed “Guide the search (optional)” section, the search settings, and the primary “Run screening” button.

The Series table lists one row per dataset with its Run, Field (G), and Temperature (K) filled immediately — no need to run screening first. Three further columns summarise the same deterministic fingerprint hints the single-spectrum wizard uses — whether oscillations look resolved (Osc.), whether the shape looks Kubo-Toyabe-like (KT-like), and whether the envelope suggests more than one relaxation rate (Multi-rate) — alongside a per-run Confidence grade and Recommendation. These are computed during screening, so they read — until you run it; afterwards the rows reorder to follow the inferred sweep axis.

The wizard infers one dominant sweep axis from the run metadata: a field sweep, a temperature sweep, or a fallback run-order series when neither field nor temperature varies. A temperature scan through a single magnetic phase is handled exactly like the field series shown here, with Temperature (K) as the axis. If both field and temperature vary materially, the wizard reports that it cannot make an automatic recommendation for that mixed grid.

The Scope section holds the model family picker, the same control the single-spectrum wizard shows on its welcome page; Choosing which models to screen describes it in full. From top to bottom it asks for the Field direction, offers the Looking for (optional) physics chips, lays out one card per model family with a pill per model, and ends with a footer that counts the models to be screened (“Will screen N of M models”), names the slow ones, and offers Leave out slow models. It is resolved over the whole series, so a model is offered when it applies to any run — a temperature series crossing a transition keeps both its ordered-state and paramagnetic families. A slow tag marks the models whose screening fits are expected to take more than 5 s per run on this computer at the series’ median run length (see which models are slow). Screening a series times its fits as well, so a series analysis refines the estimates for both wizards.

The direction row matters most on a series. When the files record no direction, every geometry is screened, which on a long series is the slow path. Answering the question saves the answer on every run whose file records none (“Set by you — saved on the 4 runs that record none.”), keeps it in the project, and never overrides a direction a file records; when some files record one, the note says how many do not, and when all of them do, the row reads “Recorded: …” instead. On an LF decoupling series like the one above, a Longitudinal answer also lets the wizard hold \(B_L\) at each run’s recorded field rather than fitting it (see The applied field is not a fitted parameter).

Changing the picker, including the direction, after screening has run marks the results stale. An amber banner reads “Scope changed since the last analysis, so these results are stale. Run screening again to refresh them.”, and the stepper marks Screen, Compare, and Phases with “!”. Their results stay viewable — click a stale step to read it — but Optimise N families → and the Transitions actions wait until Run screening refreshes them. A change made while an analysis is running cancels that run and discards its result. Changing the scope back to the one the results were screened under and pressing Run screening restores them at once, without screening again. Changing the Ranking Metric re-ranks the existing results in place and needs no new screening.

The collapsed Guide the search (optional) section is where you tell the wizard what you already know physically before the expensive search starts. Leave it closed and the defaults apply; open it to review the combined parameter list and set an expected role and bounds for each parameter:

  • amplitude-like parameters start as Global with positive bounds

  • rate-like parameters start as Local with positive bounds

  • background-like terms stay Global unless you change them

These choices set the initial expectations and the bounds honoured during both screening seeding and coupled optimisation. They do not force the final recommendation unless you mark a parameter Fixed; a fixed parameter is left untouched throughout. Invalid bounds are reported inline and stop the run before any fitting starts.

The Search settings row starts with Recommend, which sets what the coupled optimisation is for:

  • Best for trending (the default) — “Recommends the sharing pattern whose per-run parameters vary most cleanly along the series, among the models that fit adequately.” The Compare step then lists each model’s sharing ladder (see What “trends best” and “fits adequately” mean).

  • Best statistical fit — “Recommends the model and sharing pattern with the best information criterion.” The Compare step then lists the role splits of the separable role search (see How the role search works).

Screening is the same under either, so changing Recommend never asks for a new screening. Fits that were already optimised keep saying what they were optimised for: a banner reads, for example, “These fits were optimised as “Best for trending”. Optimise the shortlist on the Screen step again, and the phases on the Phases step, to rank them as “Best statistical fit”.”, and the stepper marks Compare and Phases with “!” until you do. Their results stay viewable and can still be applied. Switching back restores them at once. The choice is stored with the result, as the metric is.

Beside it are the ranking metric (AICc by default; see Ranking metrics) and the single optimisation mode, reached by the primary Run screening button.

Screen: rank the families and pick a shortlist

Global Fit Wizard Screen step mid-screening — the stepper marks Screen running above the decision trail and the Live log

Screening in progress on the Screen step: the stepper marks the step “Screening…”, the first steps of the trail are done, per-run screening is active, and the Live log is expanded to show every progress message inline.

Run screening opens the Screen step and runs the screen there. Its trail reads the series conditions, chooses candidate families, screens each run independently, and ranks the candidates across the series. When it finishes, the step shows the family leaderboard.

Global Fit Wizard Screen step — the family leaderboard with per-run reduced chi-squared cells beside a preview of the leading family's fits

The Screen step after screening the Ag decoupling series with three Kubo–Toyabe models and the generic relaxation families in scope. Only three families survive to be scored. Longitudinal-field KT + Constant leads with every run’s χ²ᵣ graded good. The dynamic and broadened KT families trail by about 6 and 12 AICc units; the leading two lie within Δ ≤ 10 and are ticked. On the right, the leader’s per-run fits sit above their residual strips.

The leaderboard has one row per screened family, best first. Each row carries:

  • a tick box that puts the family on the shortlist for coupled optimisation;

  • the family’s title;

  • a bar for its difference from the best row on the ranking metric — the column header names it, “ΔAICc from best” — with the best row reading best;

  • one cell per run holding that run’s reduced chi-squared \(\chi^2_\nu\) from the family’s own single-run fit, graded good (\(\chi^2_\nu \le 1.5\), green), fair (\(\le 5\), amber), or poor (above 5, red);

  • a status badge: Not optimised, Running, Optimised, or Failed.

The per-run cells show at a glance where a family fails — a Kubo–Toyabe dip the model cannot follow at low field, say — which a single series-wide score hides. Above eight runs the numbers no longer fit legibly, so the cells become a heat strip of graded squares, headed “χ²ᵣ per run, first → last: hover a square for its value”. A long board shows the ticked rows, the selected row, and the next three by rank; Show all N families lists the rest.

Click a row to preview that family’s per-run fits on the right: every run drawn with its fitted curve, colour-graded along the sweep axis, above one strip per run of normalised residuals \((y - f(t))/\sigma\) clipped at \(\pm 4\sigma\), labelled with the run’s \(\chi^2_\nu\). These are screening fits: a good row means the family looks promising when each dataset is fit on its own, not that it has survived coupled global fitting.

When screening finishes, the wizard pre-ticks the families within \(\Delta \le 10\) of the best on the ranking metric, up to three. The threshold follows Burnham and Anderson’s rule of thumb that a model more than 10 information units behind the best has essentially no support; the cap of three bounds the cost of the coupled fits that follow. Tick or untick any row, then press Optimise N families → (the count follows your ticks) to run their coupled fits; when several are ticked the wizard optimises them independently and, where it is safe to do so, in parallel. The collapsed Details section holds the raw screening table — Screening Score, AIC, AICc, BIC, Status, and the parameter counts — and the Candidate portfolio: every candidate family with its category, parameter count, and rationale.

Compare: candidate A against candidate B

The optimisation runs in the Compare step and lands there when it finishes; until one has run, the step reads “Optimise the shortlist on the Screen step first.” with a Go to Screen button. What the step lists depends on Recommend: sharing ladders under Best for trending, role splits under Best statistical fit. The comparison itself — pick A, pin B, read them side by side — is the same under both, and is described first.

Click a row to make it candidate A; Pin as B on any other row overlays it as candidate B, and Unpin B clears it. The recommended row starts as A. On the right, both are drawn over the data — A solid, B dashed, one colour per run along the sweep axis — above one residual strip per run, A in the run colour over B in grey, with each run’s \(\chi^2_\nu\) for A and B at the strip’s end (“χ²ᵣ A · B”); a series longer than twelve runs shows twelve strips spread along it. Below, a parameter table sets A beside B: a shared parameter as one value with its uncertainty, a local one as its per-run values, and a note column that flags a global both candidates share when the two values differ by two standard deviations or more (“differs by 3.1σ”), together with either side’s parameter flags. Continue with A → takes A to the Apply step.

Every row also carries the warnings the fit earned: the residual gate’s failing check with its runs spelled out (for example “runs-test z score suggests structure (-2.32) (run 5204)”), and parameter flags, each naming the runs that earned it — a value “at lower bound” or “at upper bound” (a plain fact — a rate pinned at zero is often physical), “not finite”, or “poorly determined” (its uncertainty exceeds its magnitude). A row shows at most three warning lines and hides the rest behind “+*k* more”.

Best statistical fit: the role splits

Global Fit Wizard Compare step under Best statistical fit — optimised role splits of the LF Kubo-Toyabe model, with the shared-Delta split as A and a per-run-Delta split pinned as B

The Compare step under Best statistical fit after a coupled optimisation of Longitudinal-field KT + Constant on an Ag decoupling series at 0, 5, 10 and 25 G. A is the recommended split, with Δ shared and \(B_L\) per run. B, pinned dashed, frees Δ per run as well. It fits every run as closely by eye and passes every check, but its three extra parameters buy nothing: it scores +4.0 AICc. The trend plot follows Δ: A’s shared value is one line across the series, and B’s per-run values sit on it within their errors.

Under Best statistical fit the optimised candidates are grouped by model, best first, with one row per Global/Local split — a single template usually yields several, since the role search scores neighbouring assignments exactly — and every row is in view. In place of a cost and a trend, each row carries:

  • a bar for its difference from the best optimised split on the ranking metric (the caption above the list names the metric, “Role splits · ΔAICc from best”);

  • an evidence weight, the Akaike weight on the ranking metric, \(w_i \propto \exp(-\Delta_i/2)\), normalised over the optimised splits — the relative support each split has among those fitted, read as a percentage (a sliver of support reads <1%);

  • a gate badge, Pass when every run’s residuals pass the automatic checks and Warn otherwise.

Click the row of a parameter that is local to A or B in the parameter table to plot it against the sweep axis beside the table — A filled, B hollow and dashed, and a shared value drawn as one line with its \(\pm1\sigma\) band. In the LF decoupling example, the local \(B_L\) tracks the applied field — exactly the shared-\(\Delta\), local-\(B_L\) structure the model expresses.

Here the collapsed Details section holds the raw optimised table and the Parameter roles for A: for each non-fixed parameter, the score with it kept Global, the score with it made Local, and the difference. These recommendations discourage overfitting: a model with more local parameters usually fits better in raw \(\chi^2\), so the wizard only recommends Local when the penalised information criterion improves enough to overcome the extra flexibility.

Apply: review what the global-fit tab receives

Global Fit Wizard Apply step — the dynamic Kubo-Toyabe model, its Global, Local and Fixed parameter roles, the exempt run left out of the coupled fit, and the starting values from run 6101's fit

The Apply step after Continue with A → on the recommended rung of the hopping scan: the model, the parameter roles the global-fit tab will set, the run left out of the coupled fit, and the starting values from the first coupled run’s fit, above Apply to the global fit tab.

Choosing a model and committing it are separate acts, so Apply reviews exactly what will be handed over before anything changes: the model’s title, its parameter roles (Global, Local, and Fixed, as the global-fit tab will set them), the Starting values (“From run N’s fit; local parameters start there on every run.”), any series warnings, and a collapsed Why these roles? section — the cost, the trend qualities, and the findings of a ladder rung, or the role search’s rationale for each parameter of a role split. Apply to the global fit tab then updates the tab’s composite function, parameter values, bounds, and Global or Local roles directly, reusing the already-computed fit bundle so the plots and parameter views refresh immediately without rerunning the fit. Afterwards the step’s summary reads “Applied: title”. To apply a different row, go back to Compare, make it A, and continue again.

A rung is applied as it was fitted. When it shares one total amplitude and leaves the fractions local (see What “trends best” and “fits adequately” mean), the tab receives the model written that way — its signal terms in a fraction group — with the total Global and the fraction Local. When it exempts runs, those runs are left out of the coupled series: a parameter of the global-fit tab is Global, Local, or Fixed, and “shared, except on these runs” is none of the three. Apply says so before you commit — “Run 6104 is left out of the coupled fit: it keeps its own amplitude, which the series does not share. It stays in the data group, unticked.” — and the tab’s results card repeats it afterwards. The exempt runs remain members of the series’ data group and appear unticked in the tab’s member list, so the recorded series lists them as excluded and the tab’s own fit over the remaining runs starts from the rung’s pattern and values. Tick a run again to bring it back; the shared amplitude then has to describe it too.

When the answer is a partition instead (see Phases: transitions and the penalty path), Apply reviews the phases — the partition’s summary sentence and one entry per phase with its range, template, Global and Local parameters, and its cost and trend quality (or its confidence, under the statistical objective), with the runs each phase leaves out — and offers Apply phases.

Phases: transitions and the penalty path

Global Fit Wizard Phases step — the Transitions card with the penalty path table and one rung row per phase, beside the series overlay coloured by phase and the trace strip with the boundary marked

The Phases step after optimising a synthetic two-phase temperature scan: the Transitions card shows the penalty path (0 and 1 breaks, the elbow pre-selected and verified) above one row per phase with its sharing pattern, cost, and trend quality. The second phase is picked, so the overlay, coloured by phase, draws its coupled fit over its four runs. The strip beneath traces the precession frequency through the ordered phase and the relaxation rate above it, with the boundary dashed.

A temperature or field series can cross one or more transitions, and the model that describes the runs on one side does not describe the runs on the other — oscillations collapsing into a relaxation, a paramagnetic component appearing above an ordering temperature. Rather than fit the whole series under one template and hope the residuals stay clean, the wizard partitions the series into phases — contiguous runs along the sweep axis, each with its own template and its own Global/Local assignment — and fits each phase independently. A break between two phases is always a change of model family — damped oscillation, single relaxation, multi-rate relaxation, Kubo-Toyabe — never a change of template within a family, of Global/Local split, or of parameter values. Which template a phase uses (two damped lines or one, an exponential or a Gaussian envelope) and which of its parameters are shared are decided by the coupled fit within the phase; a global parameter that drifts smoothly along the whole series has exactly two honest representations, Global or Local, and can never be approximated by inserting breaks.

An oscillation that dies out is a change of family too. A damped-cosine template is read as oscillatory on a run only while at least one of its line amplitudes is measured — larger than twice its own fitted uncertainty — so on the runs where every line has collapsed into the envelope the template is describing relaxation, is not offered as an oscillatory phase there, and the wizard places a break where the lines stopped rather than carrying one oscillatory phase across them.

The Phases step is active whenever the series alphabet’s per-run scores support a partition. Before screening it reads “Not screened yet”; when the series has no penalty path (fewer than six runs), or the path’s own pick has no break, the step is skipped and reads “No transition found”. Otherwise it holds the Transitions card beside an overlay of the series coloured by phase. The card states the whole penalty path — the best partition of the series with exactly \(0, 1, 2, \dots\) breaks — as one row per solution, in a table with Breaks, Boundaries, Gain, and Status columns; a solution with nothing to show on a column (no boundary at zero breaks, no gain at the top of the path) reads —. Gain is the drop in total BIC against the solution with one fewer break — its column header carries the tooltip “ΔBIC against the solution with one fewer break.” The path’s own recommendation — the elbow, the largest number of breaks whose marginal gain still clears a fixed penalty floor — is pre-selected and marked elbow in Status; once a row’s phases have been fitted exactly it additionally reads verified, and a phase too short to fit on its own is named directly (excluded: run 706, or excluded: runs 706, 707 for more than one). A short summary above the table states the selected row in plain language — "2 transitions found: 16.5 ± 0.5 K and 28.5 ± 0.5 K.", or "No transitions found: one phase describes the whole series." when the elbow sits at zero breaks — with an excluded phase named in the same sentence: " Run 706 is excluded from the global fit: it looks like a different phase." A footnote below the table reads “Transitions are scored with BIC; the ranking metric applies within a phase.” — the partition is always scored with BIC (a structural change between nested model families is nearly free under AIC’s flatter penalty, so AIC/AICc would frequently see no elbow at all) whatever ranking metric you have selected; that metric still decides which candidate wins inside each phase. Selecting a row recolours the overlay by phase, and the stepper’s summary follows it (“1 transition · 21 ± 3 K”).

A phase must span at least three runs. A shorter run of leftover points is admitted only at either end of the series, where it is scored at its own per-run cost plus the usual break penalty and reported as excluded rather than forced into its neighbour’s fit; an interior run that does not fit its neighbours is a per-run gate failure instead (see When to trust the recommendation below), never silently dropped from the middle of a phase. A break’s position is reported as the midpoint between the two adjacent runs, with a half-gap uncertainty of half their separation — a break between runs at 15 K and 18 K reports as \(16.5 \pm 1.5\) K.

Selecting a row with at least one break enables Optimize phases, which runs the coupled search independently on each phase of that solution (plus the neighbouring solutions and shifted breaks the wizard checks to confirm the elbow, at no extra cost to you beyond the wait) — the break-free row is the ordinary series-wide answer that Optimise N families → on the Screen step already produces, so it carries no separate action here. The run shows in the Phases step under “Optimizing each phase…”, stepping from “Preparing the series screening table…” through “Optimising each phase…”, which becomes “Optimising phase i of N…” once individual phases start; the status line reads “Running the coupled global optimisation once per phase. Progress is streamed to the live log.”

What each phase’s answer is follows Recommend. Under Best for trending the sharing ladders are climbed on each phase’s own runs, and a phase’s answer is its best pre-selected rung among the models that fit that phase about as well as its best one. Once the run finishes, one row per phase appears beneath the card, headed by the phase’s ordinal, range, and template, and built like a rung row of the Compare step: the role chips, the Cost and Trend bars, and the ladder’s findings. Only the answer is kept for a phase, not its whole ladder, so there is nothing to unfold here; to see a phase’s other rungs, select its runs and run the wizard on them as a series. Click a row to draw that phase’s coupled fit over its runs, with residual strips. Beneath the overlay, a strip traces every parameter a phase leaves local, each phase in its own colour, with the boundaries dashed — the piecewise trend across the transition. The breaks themselves are still placed by BIC on the phases’ best fits: a rung may cost up to 2σ and a model up to 3 %, which on real point counts is more than a break is worth, so scoring breaks by the answer would let the objective move them.

Under Best statistical fit a strip of phase chips appears beneath the table instead, one per phase, each naming its ordinal and range, its template, its Global/Local split (Global: A_1, A_bg · Local: Lambda), and a confidence line (“High confidence”, or “Medium confidence — check the warnings”). Click a chip to draw that phase’s coupled fit.

The verified row’s Apply phases button opens the Apply step to review the phases; its own Apply phases then creates one nested data group per phase under the series group (see Phases within a group in GUI usage), records one global-fit series per phase (see Phase-owned series in Parameter trending), and binds the global-fit tab to the first phase. A run that a phase’s rung exempts stays in that phase’s group and is left out of its series, as for a series-wide rung. The main window’s status bar confirms what was created, e.g. “Applied 2 phases under Runs 901-906 (2 transition(s)).”, and names any runs left out.

How the role search works

This section describes the search behind Best statistical fit. Once a template is selected for coupled optimisation — for the whole series, or for one phase of a partition — the wizard still has to decide, for every promotable parameter, whether it is shared (Global) or free per run (Local). This is the role search, and it is now separable: every effort tier resolves to the same engine, so there is exactly one honest optimisation mode rather than a slider that trades accuracy for speed.

The separable search never pays to discover the all-local answer: \(G\) independent per-run fits already are the all-local assignment, so it is assembled directly from the phase’s own per-run results — no joint fit. A full-covariance surrogate (a generalised-least-squares collapse of the per-run values and covariances) then scores every sharing pattern at once and hands back a warm start for it — pooled shared values, plus each run’s conditional local values. Backward elimination walks from all-local, promoting one parameter to Global at a time — cheapest by the surrogate first — with one exact, warm-started coupled fit per step, and stops as soon as a step no longer improves the information criterion; a handful of the most promising templates race through this together, so a template that falls behind early keeps its free all-local score rather than being fitted further for no benefit. Once elimination stops, the winner’s single-flip neighbourhood (every parameter toggled once from the winning assignment) is fitted too, so the per-parameter Global/Local recommendations in the Compare step’s Details are exact rather than inferred from the path taken to reach them. Every one of these fits runs at the series’ own search resolution (the coarsest rebinning any run’s own analysis chose); in a series-wide search only the winner, and its flip-neighbourhood, are refitted once more at full resolution for the numbers you actually see. A phase (see Phases: transitions and the penalty path) is reported at the search resolution instead — every row of the penalty path is then scored on the same points, and the fit you apply from a phase seeds the Batch tab’s own global fit, which runs on the native record. The whole search costs on the order of \(P\) coupled fits per template, where the previous exhaustive search cost \(2^P\).

Each of those coupled fits is solved by a sparse least-squares minimiser rather than by Minuit. A coupled node’s Jacobian is arrow-shaped — every residual depends on the shared parameters and on exactly one run’s local ones — so the solver is told that pattern up front and evaluates one finite-difference column for the same local across every run at once. The cost of a Jacobian then grows with the per-run parameter count rather than with \(n_\text{global} + n_\text{local}\,G\). On a wide node — a twelve-run phase with nine free parameters per run over a couple of hundred thousand points — that is the difference between minutes per fit and seconds, and the equivalent Minuit problem over ninety-odd parameters may not converge at all. The fitted values, \(\chi^2\) and parameter uncertainties are the same quantities Minuit reports (the uncertainties come from the Gauss–Newton curvature at the solution, which for a \(\chi^2\) cost is Minuit’s own convention), so nothing about the ranking or the reported numbers changes — only how long the search takes. Asymmetric MINOS intervals are the one thing this solver cannot produce; the wizard does not request them.

The exhaustive “wavefront” search that enumerates every \(2^P\) role assignment has not gone away — it is retained behind the lower-level search_engine="exhaustive" argument as the harness referee the separable engine is measured against, and it remains reachable through the same argument for the small set of callers that still want it explicitly. It is never reached from the GUI or from effort_tier. tools/global_wizard_harness.py --engine {separable,exhaustive} runs either engine against the frozen golden-verdict baseline; acceptance for a candidate is at least 95% verdict agreement with the frozen (exhaustive) baseline, with every disagreement inside the harness’s IC-gap tolerance — measured at 100% agreement on the harness’s case set.

Ranking metrics

Candidates are ranked, and can be reranked, with the same three information criteria as the single-spectrum wizard:

\[\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 total number of free global parameters plus the run-specific local parameters, and \(n\) is the total number of fitted points across the selected datasets. Screening rows and coupled rows both aggregate the objective, free columns and samples over the series before computing the criterion. A shared column counts once and a local column once per run; fixed and constrained followers do not count. AICc is unavailable when \(n-k-1\leq0\) or the sample count is unknown. Unavailable rows are excluded under that metric; AIC is never substituted. If every fitted row is excluded, the message is “No fitted candidate can be ranked by AICc.”

AICc is the conventional small-sample correction, with the Gaussian assumptions described in Fit wizard. AICc is the default; BIC applies a stronger complexity penalty and usually favours simpler descriptions. Changing the metric reranks the already-computed rows without rerunning the analysis — rebuilding the screening table is only required if the selected datasets, model, bounds, or expected roles change.

The metric ranks the Screen step under either objective, and with it the shortlist. Under Best statistical fit it also ranks the Compare step. Under Best for trending the Compare step is ordered by trend quality and the metric only breaks ties between rungs that trend equally well; a rung’s exempt runs each count one extra fitted parameter per shared amplitude.

When to trust the recommendation

The wizard states its recommendation plainly, but it is a decision aid, not a verdict to accept unread. Its confidence is worth calibrating against what the gate logic actually checks.

Under Best for trending the status line states the recommendation in one sentence — “Recommended for its trends: model, with these shared across the series and those varying from run to run.” — and then one sentence for each thing to know about it: the runs that keep their own amplitude, an end block the amplitude could not be shared through, a pattern that is hard to justify, passes that disagree, the runs on which the model leaves structured residuals (“review them before applying”), and a model that fits about as well and is listed to compare. A recommendation with only its first sentence is the one to trust with least reservation. Each further sentence is a caveat, not a veto: the wizard recommends a pattern whenever some model could be fitted on every run, because an imperfect model with its faults named is a better starting point than no recommendation. Read the trace strip first. If a parameter there does something the physics does not lead you to expect, unfold the ladder and pin the rung below as B: the two traces side by side show whether the feature belongs to the data or to the sharing.

Under Best statistical fit the recommended candidate is the best-scoring optimised candidate whose residuals pass every automatic residual check on every run. When the top two are within a small score margin the wizard presents them as a comparable pair and prefers the simpler one as the starting A on the Compare step; the status line then adds “with a similarly scoring alternative to inspect”, and pinning the runner-up as B sets the two side by side. A clean recommendation means every run’s residuals look unstructured under the shared-parameter fit.

Two softer outcomes deserve a closer look. A recommendation can carry a series-level caveat: every run clears its own residual gate, but the spectra change abruptly somewhere along the series, and the status line names where. Treat it as a lead: the per-run fits are sound, but the series may hold a transition that one model should not be fitted through. A per-run gate failure is different, and under the statistical ranking it still blocks — it means the model does not fit some runs — where the trend objective names the runs and recommends anyway.

The per-run readouts in the Scope step’s Series table carry the same honesty. A run whose best single fit shows no significant structure — its winner cannot beat a flat or plain-exponential baseline by a clear margin — is flagged with an unmissable series-level banner naming the affected runs. This is a per-run statement, not a series-wide verdict: it is entirely normal for most of a temperature scan to show clean structure while a handful of runs near a transition, or at the noisy end of a decoupling series, do not. It usually means the data there are well described by a plain relaxation, and forcing the richer global model onto those runs would be over-fitting.

In every case the honest move is the same: before applying, read A’s residual strips and flags on the Compare step, pin its nearest rival as B, read the cost or the parameter-sharing diagnostics in Details, and check that the local-parameter trends behave the way the physics leads you to expect.

Programmatic global fitting

This wizard is the asymmetry-domain shared-parameter workflow, driven from the GUI. To share fit-function parameters across runs programmatically, use the count-domain API fit_grouped_series(relationship="global", ...) — see Cross-run global fits from the API in Grouped time-domain fitting.

Calling the global wizard from a script

build_global_fit_wizard_screening_recommendation starts by analysing every dataset in the series with the single-run Fit Wizard — the same tiered family screen, peak analysis and damped-line scan build_fit_wizard_recommendation() performs on one spectrum. The series’ candidate list is then the union of the templates those per-run analyses assessed, so a model that describes only part of a temperature series (a heavily damped pair below a transition, say) is considered for the whole series instead of being averaged away. A few runs are analysed side by side, in sweep-axis order, sharing one pool of worker processes: each analysis spends much of its time in stages that use one core (spectral detection, the pattern search, the tier gating), so overlapping them lets one run’s fitting use the workers another run’s serial stages leave idle. That pool is opened once for the whole of this phase and serves the scoring pass below as well.

Each analysis is also started from the fitted values of the nearest run that has already finished — an extra first attempt per candidate, tried ahead of the seed ladder. When that warm attempt and the plain seed both converge to the same minimum, the rest of the ladder is skipped: a fitted answer for the same model on a neighbouring run agreeing with a cold start leaves the remaining seeds nothing to find. They are climbed as usual when neither converges or when the two land in different minima, and the top-ranked candidates are re-fitted from the full ladder afterwards either way, so the ranking the recommendation rests on is never the short ladder’s.

A candidate no partition of the series could ever select is then dropped from the list before any scoring: one whose bare χ² on every run already exceeds some one other candidate’s information criterion there cannot win a segment under any sharing, whatever the segment. A candidate a run’s own analysis recommended, or scored comparable, is never dropped this way.

Histogram observations use the same counts-first preparation as the single-run wizard, preserving base and toolbar merges and selected crop membership. Captured sample, held-period, and reference counts and supplied variances have owned read-only storage. Later edits through original array aliases leave cached analyses and reconstructed curves stable; reduce edited inputs again and rerun the wizard to analyse a new observation. G+R pools prepared counts before background, binning, and one ratio; G−R bins independently prepared sets on common native support before differencing. Curve-only, rotated, and unresolved historical/custom observations retain independent-curve means. Search decimation, common-resolution completion, and curve reconstruction use that same observation contract; coarse search winners are refitted at the existing final resolution before their scores enter the final leaderboard. Per-run preparation precedes worker fan-out, so candidate tasks carry fit arrays and lightweight provenance rather than detector, reference, or period arrays.

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.

These remain asymmetry-domain fits with conditional point errors and centre-point model evaluation; TF alpha/beta count calibration stays separate. Internal spectral diagnostics preserve uniform curves and prepare nonuniform captured histograms on separate Fixed native bins (factor 1, merge 1) over exactly the retained native support. Original base/toolbar/crop/merge selections resolve before that grid is chosen; discarded incomplete tails stay excluded. Screening, completion, rescue and reconstruction retain the fitted observations and scores. Residual spectra evaluate the same model/parameters on the separate count view; original RMS/runs and residual times/errors stay with the fit. Nonuniform original residuals have no acquisition-lag autocorrelation. The residual-gate cell shows Unavailable when a measurement is missing; it cannot establish a passing model-evidence gate. The result records the separate view, policy, source observation, interval/support and recipe. Curve-only nonuniform inputs and sampled-only trends cannot supply this replay. See Fourier analysis and Fit wizard for the diagnostic support rule, unavailable cases and compared-program limits. Saved historical scores load without automatic fitting, FFT regeneration or reinterpretation; missing historical diagnostic provenance remains unknown.

Every remaining run is then scored against every candidate at one common rebinning factor — the smallest any run’s own analysis chose — so the fit costs and point counts can be aggregated before applying a criterion’s penalty. The separately named partition BIC charges each shared column \(\ln N\) for the phase’s total samples, and each local column \(\ln n_r\) for its run. With all columns local this equals the sum of the per-run BICs; it differs from the series-total BIC used by the leaderboard. The cells a run’s own analysis already holds at that factor and observation identity are kept; the rest are fitted, warm-started from that run’s or a sibling run’s values. A cell started from that run’s own values for the same model at another binning is the same data and the same model at a different sampling — the same minimum by construction — so it is fitted once, from those values. A cell started from a sibling run’s values is a different record, so it gets the plain seed alongside the warm one.

On a long series this legitimately runs for many minutes before it returns; each completed analysis and each completed score row is reported through progress_callback so you can see it advancing rather than guessing whether it has stalled. Pass a cancel_callback if you need to be able to stop it — it is polled several times a second throughout, including while fits are running in worker processes.

The scoring pass fans out one task per cell — one run, one candidate — across the same process pool, so the if __name__ == "__main__": rule in Calling the wizard from a script applies here too: an unguarded script degrades to serial execution with a SpawnUnsafeWarning rather than crashing.

A cached single-run analysis is reused instead of repeated when it answers the same question — same candidate scope, same user-declared frequencies, and the same observation, resolved reduction context, support, and preparation contract. That is what the Fit tabs’ own wizard results give the global wizard: analyse a run once in the Fit Wizard and the series analysis does not pay for it again.

The two stages behind that call are also available separately, for a caller that wants to reuse phase 1 across several screening calls (a scope sweep, say) instead of paying for it every time: build_or_complete_single_fit_wizard_recommendations_for_global_portfolio() returns a GlobalFitWizardScreeningTable — its portfolio, the completed recommendations_by_run, the runs’ own single_fit_recommendations_by_run, the generated_run_numbers, and the series_rebin_factor. Pass that portfolio (together with the single_fit_recommendations_by_run that covers it) into build_global_fit_wizard_screening_recommendation(..., portfolio=..., single_fit_recommendations_by_run=...) and phase 1 is skipped entirely.

Every screening recommendation also carries a partition_path — the whole penalty path over 0, 1, 2, … structural breaks along the series (None on a series of fewer than six runs, where a partition is not attempted); see Phases: transitions and the penalty path above for what the path means. partition_path.selected_k is the pre-selected elbow, and transitions_summary(partition_path.solutions[k], recommendation.series_axis_label) renders the same plain sentence the Phases step’s Transitions card shows for that row. Passing a partition_path together with a partition_k into build_global_fit_wizard_recommendation switches it from one series-wide answer to one answer per phase of that solution — the two arguments are refused unless given together, since a bare index does not name a path. The result’s phase_assessments then maps (partition_k, segment_index) to a GlobalCandidateAssessment, and recommended_partition_k records which solution was optimised.

build_global_fit_wizard_recommendation takes an objective, a SelectionObjective, and the recommendation it returns records which one it was ranked for. TREND is the default. It asks which fit lets the parameters be followed along the series: for every candidate whose independent per-run fits come within 3 % in \(\chi^2_r\) of the best candidate’s, the wizard fits a ladder of sharing patterns — the background shared, then the amplitudes, then one further parameter at a time — and keeps a parameter shared only while the fit stays adequate, which means that \(\chi^2_r\) rises by no more than two of its own standard deviations, \(\sqrt{2/\nu}\), for the series and for every run. The recommended candidate is the adequate pattern whose remaining local parameters trend best. Each candidate of such a recommendation carries a rung: its cost in those standard deviations, the trend quality of each local parameter, the runs that keep their own value of a shared amplitude (also given by exemptions), and the block of runs at one end of the series through which the amplitude could not be shared. A run that fails its residual gate does not veto a recommendation under this objective; the summary names it. STATISTICAL is the role search and information-criterion ranking described on the rest of this page, and is what the search_engine and effort_tier arguments apply to. One call computes one objective, and merging a result of one objective into a recommendation of the other replaces its optimised candidates.

tools/global_wizard_harness.py --engine {separable,exhaustive} is the regression check for the role search itself; see How the role search works above for what the two engines are and the acceptance bar between them. --objective trend runs the trend objective on its own planted cases instead.

Screening never sets recommended_key. That is deliberate — a pre-screen score comes from independent per-dataset fits, which are not evidence about a coupled global fit — but it means a script that reads recommended_key alone gets None from a perfectly good screen. Read the ranked table instead (sorted_prescreen_assessments()), or read summary, which now names how many candidates scored and which one ranks first, and says explicitly when a screen scored nothing — the failure case that used to be indistinguishable from an ordinary one.

Buying a cheaper answer: effort tiers

Scoring cost is (candidates × datasets × per-fit cost), and the candidate list a broad scope produces includes numerically integrated dynamic Kubo-Toyabe models that can cost an order of magnitude more than the rest of the list combined. On a fourteen-dataset series that is the difference between a screen that returns and one that does not.

effort_tier controls it. It narrows the series’ candidate list after the per-run analyses have produced it, so it buys a cheaper scoring pass, not a cheaper per-run analysis:

EffortTier.LOW

Scores a small set of the cheapest, most parsimonious candidates. Coarse, and fast enough to be interactive.

EffortTier.BALANCED

Drops only the numerically expensive candidates.

EffortTier.THOROUGH / EffortTier.EXHAUSTIVE (the default)

Score the whole candidate list, exactly as before.

Candidates a run’s peak search positively identified — a multiplet pattern match, or a multiplet model built from that run’s detected lines — are never dropped: those come from the data, so removing them would change the answer rather than coarsen it. Whatever is skipped is announced through progress_callback and listed in instrumentation["screening_skipped_template_keys"], so a coarser answer always says what it was coarsened by.

This tier only ever narrows the screening candidate list. The coupled optimisation that follows — deciding which parameters of the surviving candidate are Global versus Local — is a separate stage with its own, single engine at every tier; see How the role search works above.

Timing: telling “slow” apart from “hung”

Both wizards fill in a standard timing block when you pass an instrumentation dict, and emit structured per-stage events to a stage_callback:

from asymmetry.core.fitting.global_fit_wizard import (
    build_global_fit_wizard_screening_recommendation,
)
from asymmetry.core.fitting.wizard_scope import EffortTier

def main():
    instrumentation = {}
    events = []
    recommendation = build_global_fit_wizard_screening_recommendation(
        datasets,
        effort_tier=EffortTier.BALANCED,
        instrumentation=instrumentation,
        stage_callback=events.append,
    )
    timing = instrumentation["timing"]
    print(timing["elapsed_seconds"], timing["cpu_seconds"], timing["cpu_cores"])
    for stage in timing["stages"]:
        print(stage["stage"], stage["elapsed_seconds"], stage["cpu_cores"])

if __name__ == "__main__":
    main()

cpu_seconds covers this process and its reaped pool workers, so cpu_cores is what distinguishes a slow computation (several cores busy) from a stalled one (near zero) — the question that otherwise sends a caller to the process table. Each stage_callback event carries the stage name, a start/item/end marker, items done and total, and the elapsed and CPU time so far, which is what you want a timeout to watch: absence of progress rather than total runtime.

Compared with other programs

The count-packing comparison with WiMDA 1.326, musrfit 1.12.1, and documented Mantid muon preprocessing concerns the prepared observations. It does not establish an equivalent global model-search algorithm. See Binning and timestamps for sources, versions, and numerical limits.

References

  • R. Killick, P. Fearnhead, and I. A. Eckley, J. Am. Stat. Assoc. 107, 1590 (2012) — optimal partitioning of a series with a penalised cost, the basis of the penalty path.

  • N. R. Zhang and D. O. Siegmund, Biometrics 63, 22 (2007) — a BIC-type criterion for choosing the number of change points.

  • K. P. Burnham and D. R. Anderson, Model Selection and Multimodel Inference: A Practical Information-Theoretic Approach, 2nd ed. (Springer, New York, 2002) — Akaike weights and the rule of thumb that a model more than 10 information units behind the best has essentially no support.