Joint fits ========== Each ordinary time-asymmetry series retains its canonical model's :ref:`fixed time response ` in joint fitting and replay. Shared parameter columns do not estimate pulse separation. .. image:: /_generated/screenshots/joint_fit_window.png :alt: Joint-fit window with an ordered-phase and a paramagnetic-phase series ticked and a suggested shared table :width: 100% *The joint-fit window on a sample crossing a phase transition: an ordered* *phase fitted with* ``Oscillatory * Exponential + Constant`` *and a* *paramagnetic phase fitted with* ``Exponential + Constant``\ *, both ticked.* *"Suggest" has proposed the background* ``A_bg`` *as an exact, ticked match* *and the amplitude* ``A_1`` *as an unticked candidate — the two models expose* *their own amplitude as one parameter each, but that alone does not make the* *quantities the same, so the tiering leaves the decision to the user.* When to use a joint fit ------------------------ A sample measured across a phase transition often needs two different fit functions: an oscillating model in the magnetically ordered phase and a relaxing model in the paramagnetic phase above it. Some quantities are the same physical thing in both regimes — the initial asymmetry, the background, alpha, an instrumental phase — and a fit that ignores this measures them twice, independently, and then hopes the two answers agree. Until now the only way to share a parameter was the Batch tab's **Global** role, which shares a parameter across the runs of *one* series fitted with *one* model (see :ref:`global-fitting` in :doc:`fitting`). Two series with different models could not share anything: you fitted them separately and compared the numbers afterwards. A **joint fit** puts both series into one cost function, with one column for the shared quantity, so its value is estimated from every run of both series at once and its uncertainty propagates correctly into everything else. A joint fit does not replace the Global role, and it does not let you build a new model. It **composes series you have already made**: each member is an ordinary :class:`~asymmetry.core.representation.series.FitSeries` — its model, its member runs, its fit range, its parameter table — exactly as recorded from the Batch tab. The joint fit adds only a table of shared parameters and its own label. If you need to change a member's model, seeds, bounds, or fit range, edit that series on the Batch tab as you always would; the joint-fit window itself edits no recipe. The three scopes ----------------- Asymmetry now has three, deliberately distinct, notions of "one value shared across several things": * **Local** — one fitted value per run. The Batch tab's default classification for every parameter. * **Global** — one fitted value per *series*, shared across every run that series covers. Set in the Batch tab's parameter table; unchanged by anything below. * **Shared** — one fitted value across *two or more series*, set up in the joint-fit window. A shared parameter must be a **Global** parameter of every series that contributes to it — Local and Fixed rows are never offered, because they do not denote "one value for this series" in the first place. Two older words keep their existing meanings and are **not** reused here. "Linked" still means the Batch/Single tab's equality link groups (the **⇄** badge) — a per-series device that ties two parameters of the *same* run's fit together. "Global Parameter Fit" still names the separate cross-group analysis window (:doc:`gui_usage`'s Global parameter fit window) that fits a trend parameter such as λ(B) across several data groups. Neither is a joint fit, and a joint fit does not change what either of them does. Setting up a joint fit ------------------------ Open **Analysis ▸ New joint fit…** for an empty window on the active representation, or pick a recorded one from the **Analysis ▸ Joint fits** submenu (a stale entry is suffixed " (stale)"; see `Staleness and detaching`_ below). The **Series** section lists every series of the active representation, with its model, its **Fit range**, its member count and its status (how many members converged when it was last fitted, and at what time). Each member is fitted over its own range — the one set on the Batch tab when the series was recorded — so two members may cover different windows; a series recorded without a range reads "Plot's fit range" and uses the range set on the plot. Change a member's range on the Batch tab. Only a *time-domain*, run-membered series with a fit model can be a member; everything else is listed disabled, with the reason on its tooltip: * a detector-group series reads "Detector-group series", * a model-less (computed) series reads "No fit model", * a series that shares a run with one already ticked reads "Shares runs with **" — a run may belong to exactly one member, so the window prevents the overlap by disabling the conflicting row rather than letting you create a cost function that would weigh the same data twice. A **frequency**-domain representation offers no series at all: "Joint fits are available for time-domain series only" (a zero-padded Fourier spectrum's samples are correlated in a way the joint solver does not yet account for). Tick two or more eligible series. The **Shared parameters** table then grows one column per ticked series, alongside **Shared**, **Value**, **Min**, and **Max**: * **Suggest** proposes rows from the ticked series' models and their Global parameters, in two tiers: * an **exact** row — the same full parameter name, the same unit, appearing exactly once in every model, and Global in every series — is ticked by default; * a **candidate** row — the same base name at a different component index (``A_1`` here, ``A_2`` there), or the same *base* name owned by a different component type in each model — is proposed unticked, for you to judge. A row you have added by hand, or edited, survives a re-run of Suggest; only an untouched, machine-proposed row is replaced. * **Add shared parameter…** prompts for a name and adds an empty row you fill in yourself: tick a Global parameter for each contributing series from its column's dropdown (the dropdown's placeholder entry, "—", means "this series does not contribute this row"). * **Remove** drops the selected row(s). A shared row's seed and bounds come from the **first ticked series that contributes to it** (in tick order) — never averaged across contributors, since the shared value is a new fitted quantity and averaging two series' own seeds would invent a number neither of them holds. Edit the Value, Min, or Max cell directly to override. Every other seed, bound, fixed or file-pinned value, and the fit range, is read from each member's own recipe exactly as a solo Batch-tab run of that series would read it — the Batch tab's inherited single-fit seeds and its Initial-values dialog do not apply here. Each member's fitted curve is drawn over that same fit range, so a series whose range starts at 0 has its curve reach back to t = 0 even when the first data point sits later. .. _joint-fit-initial-asymmetry-caveat: **The initial-asymmetry caveat.** "Initial asymmetry" is shareable only when a model exposes it as *one* parameter — a :doc:`fraction group ` with one overall amplitude budget across its additive terms is exactly this case. A model that instead sums several independent component amplitudes has no single column that *is* the initial asymmetry; constraining that sum to a shared value is a genuine physical constraint, but it is not what a shared parameter expresses, and v1 does not offer it. This is why the suggestion above proposes ``A_1`` only as a candidate: the same name can be the sole amplitude of one model and one term among several in another. The **Label** field defaults to "Joint: ** + **", built from each ticked series' *short* name — its own label, else its data group's name, else its model's expression — rather than that series' full `` · [ · ]`` fallback name, which is what made an early build's default read as "Joint: OverhauserPowderCutoff · 0.002–0.1 µs · low + Exponential · 0.002–0.1 µs · high". Two ticked series that still resolve to the same short name (no label, no group, the same model) fall back to that series' full name so the label stays unambiguous. The field's tooltip always lists every ticked series' full name, one per line, so the full picture is one hover away even when the label itself is short. Type in the field to set your own label, which then survives further re-runs and re-suggestions. Click **Run joint fit** to fit. **Stop** cancels a running fit and leaves every member's previous results exactly as they were — nothing is recorded for a fit that did not finish, or did not converge. Results ------- A converged joint fit writes its results **onto the member series themselves**, in place, under their existing recording — a joint run does not create a new series, because the recipes did not change, only the constraint on them. Each member's per-run results carry the shared value under that series' own parameter name, so every existing consumer (the Fit Parameters panel, an export, the plot overlay) reads a jointly fitted series exactly like any other. The results card shows the combined χ²ᵣ and degrees of freedom, each shared parameter's fitted value and uncertainty, and one row per member series with its own χ²ᵣ (computed as if that series had been fitted alone) and an **Open in Batch tab** button. The Fit Parameters panel groups a joint fit's member series into their own chip-rail section, titled with the joint fit's label, ahead of the ordinary data-group sections — a joint fit can span series that belong to different groups or carry different models, so its own section is what shows "these belong to one coupled fit" without you having to infer it from a badge alone. The section header's tooltip lists every member's full name, one per line. A shared parameter is, in every contributing series, still a **Global** one, and "Global" means one value per series everywhere in the app: it gets no chip, no card, and is never plotted as a per-run trend, exactly like any other Global parameter. The footer's existing note ("** Global — held constant") names it too, and for a shared parameter that note's entry gains a suffix naming the joint fit it is shared across: "** — shared across joint fit "*