Files
muSRFlow/docs/source/parameters-plots.rst

280 lines
14 KiB
ReStructuredText

Parameters and parameter plots
==============================
The **Parameters** tab shows the numerical model: one row per fitted
parameter, per data set, with starting values, steps, and limits. Fitting
feeds the measured values back, and the same table drives the interactive
parameter plots.
.. figure:: images/parameters-tab.png
:alt: Parameters tab with editable starting values, error or step fields, bounds, and the Plot parameters button.
:width: 100%
Example parameter table before fitting, for the same run and model as
:doc:`getting-started`. These are initial values, not measured results;
the Error column contains starting steps at this stage.
The parameter table
-------------------
The table is rebuilt automatically whenever the model changes (a new
component, a new run, a constraint). Rows are keyed to the model:
* Single-run fit: one row per parameter of the selected model.
* Multi-run fit: a row per parameter per data set, each named by its run
(for example ``Lam_2255``), plus the parameters you choose to share.
Rows follow the physical role of each parameter: the initial asymmetry first,
then the relaxation/lineshape parameters, then the precession frequency, then
the phase, then the asymmetry alphas and group ratios, and finally the
detector normalization/background parameters. This ordering is what ends up in
the generated ``FITPARAMETER`` block and therefore in the ``*_par.dat`` columns
from ``msr2data``. A parameter introduced through a constraint (for example
``Bfield = gamma_mu * Frq``) is placed with the built-in parameter it is linked
to; when it is linked to several parameters it takes the highest-priority
(lowest) rank among them. An order imported from an existing MSR file always
overrides this physical sequence.
For each parameter the columns are the **starting value**, the **step**, and
the **lower/upper limits**. Edit any of them directly. Run-scoped parameters
are matched to their data set by the run suffix, so a per-run starting value
only affects that run. The values in this table are the starting values used
for the next fit; after a fit they are replaced by the fitted results, and
the fit uncertainties are available in the parameter plots as error bars.
The **Shared** column
~~~~~~~~~~~~~~~~~~~~~
In a multi-run fit the table also has a **Shared** column in the first row of
each parameter. Tick it to keep a single shared starting value, step and
limits for all runs instead of a separate per-run copy. This is equivalent
to the musrfit ``GLOBAL`` parameter mechanism.
Sharing any parameter takes the fit out of the independent-series route, so
the per-run refit/skip action chips disappear (see :doc:`runs-fitting`).
The parameter plot still works.
Selecting parameters for plotting
---------------------------------
Click a parameter name to select or deselect it for plotting:
* **Click** -- toggle that single parameter.
* **Ctrl / Cmd-click** -- add an individual parameter without changing the
rest of the selection.
* **Shift-click** -- select a contiguous range of parameters.
* **Long-press (touch)** -- on mobile/tablet, long-press a parameter name to
add or remove it from the selection without clearing others (multi-select).
The selection state is shown in the row. Then use the **Plot parameters...**
button at the top of the parameter table to open the plot window. If the
parameter table is not yet populated (no fit run yet and no file loaded), the
plot can still build the parameter data inline from the table -- the button
stays enabled whenever the table is built.
The Choose X axis dialog
------------------------
The dialog lists the parameter data columns and asks which one to use as the
common X axis. Each selected parameter becomes a Y series.
The dialog also offers the **Layout** of the plot window:
* **Auto** -- one parameter per panel. Up to three parameters share a single
column; beyond that the panels grow toward a square grid (two parameters
in two columns, three in three, and four or more arranged as the closest
square grid).
* **Single row** -- all parameters side by side in one row.
* **Single column** -- all parameters stacked in one column.
The layout choice is remembered for the next plot. The window opens with the
chosen arrangement, and the **Plot options** panel lets you re-arrange the
panels afterwards.
The parameter-plot window
-------------------------
The window shows one panel per data set / parameter as arranged by the
layout choice. Panels share the chosen X axis. The toolbar holds:
* **Refresh** -- reread the current parameter-data file and redraw every
visible panel. Use this after a new fit to update the numbers.
* **Data...** -- change the data set loaded in the *active* panel.
* **Add data set...** -- choose one or more parameter-data files and overlay
them onto *every* panel at once. Each file keeps one colour from the
**Palette**, and every panel plots the parameters it already shows for
each newly added file, so a scan can be compared against the current one
across the whole window with a distinct colour. The Y-axis label stays on
the active panel's parameter rather than reverting to a generic label.
Adding files this way is the same overlay mechanism as **Overlay data
sets** in *Plot options*; the toolbar shortcut just applies the additions
to all panels instead of the active one.
Overlaid curves get a *smart legend* label that says which physical state
each scan represents instead of only a file name. The label is derived from
the data set's own scan variable and its constant coordinate: an energy scan
(``dataE`` varying) is tagged with its fixed temperature (``(T = 300 K)``), a
temperature scan with its fixed energy for LE-µSR (``(E = 12 keV)``) or with
its field for bulk µSR (``(B = 100 G)``), and a field scan with its fixed
temperature. When no fixed coordinate is present the plain file label is used.
You can also rename a legend entry directly in the plot; a Refresh then keeps
your name instead of rebuilding the default.
* **Plot options** -- expand the layout, X, parameter, style, and displayed
series controls for the active panel.
Plot options
~~~~~~~~~~~~
* **Layout** -- the concrete panel grid (for example ``1 x 1`` ... ``3 x 3``
and larger grids as the panel count needs). Changing it adds or hides
panels; new panels start empty and clone the sync settings of the current
panel.
* **Panel indicator** -- which panel is active (``Panel 1/3``). Click a
panel to activate it before changing its panel-specific settings.
* **Data set** -- the data source shown in the active panel.
* **X** -- the X column for the active panel.
* **Parameter** -- add a Y parameter to the active panel. Serial chips
underneath list the current Y series; click the ``x`` on a chip to remove
that series.
* **Style** -- ``Scatter``, ``Lines + markers``, or ``Lines``.
* **Palette** -- the base colour palette (``Default``, ``Bold``,
``Pastel``, ``Monochrome``) used to assign each overlaid data set its
default colour. Changing it restyles every panel.
* **X title / Y title** -- override the automatic axis label of the active
panel; leave empty to keep the automatic label.
.. _Remembered plot configurations:
Remembered plot configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The full window state is remembered per data source: the panel arrangement,
the X column, the template, the palette, the per-series styles (including the
error-bar caps setting), and the overlay files. A configuration is keyed by the
data source *and* the parameter set it plots, so each parameter selection has
its own remembered configuration.
Restoring a configuration is always an explicit choice, never something that
happens behind your back:
* The **Choose X axis** dialog appears every time you plot parameters.
* If a remembered configuration matches the parameters you selected (the same
set, in any order), a **Configuration** dropdown appears in the dialog. The
most recent matching configuration is preselected; the dialog shows exactly
what will be restored, and you press **Plot** to confirm.
* Choosing **From scratch** in the dropdown (or having no matching
configuration) starts a normal new window from the X axis and layout choices
on the dialog.
Matching is exact: a saved configuration for three parameters never shows up
for a one-parameter request, even if that one parameter is part of the three.
* State is keyed by the data source, so ``scanA_par.dat`` keeps its own styles
and layout while other files (and their overlay sets) remember theirs
independently.
* Up to eight data sources are remembered; adding a new one forgets the
oldest. Each source keeps at most one configuration per parameter set (the
newest wins) and a handful of parameter sets in total.
* **Forget plot configuration** in **Plot options** clears the remembered state
for the data source shown in the active panel, so the **Choose X axis**
dialog offers no configuration next time.
* The remembered configuration of the current data source is carried in
configuration share links, so a colleague restoring your link gets the same
plot window -- see :doc:`configuration-sharing`. When a real fit produced the
parameter table, the table itself is embedded in the link (inline text) and a
web restoration renders the identical plot immediately, without needing a
local or server-side fit.
* Uploaded files keep only their identity, not their contents: if the original
file cannot be read again (for example it was deleted), the restored plot
degrades gracefully and the dialog is offered instead.
Overlay data sets (multiple files in one panel)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Panels can plot several ``*.dat`` files at once so scans can be compared on
one set of axes. Open **Plot options** and use **Overlay data sets > Add
file...** to choose extra parameter-data files (on the desktop this is a
native multi-select dialog; on the web it is the browser's multi-file
picker). Each file becomes a row with a checkbox:
* checked rows are drawn on top of the panel's main data set;
* the colour swatch shows the default trace colour for that file, assigned
from the **Palette**;
* files are identified by their resolved path or blob identity, so picking
the same file twice keeps one entry -- and one user-adjusted style;
* the X axis is aligned across files **by column name** -- a file that does
not contain the panel's X column is skipped and named in a striped note
under the panel;
* in overlay mode each file's traces share its colour, and legend entries
are prefixed with the file name (``scanB_par.dat: λ₁``).
Growing the layout clones the active panel, so expanding a ``1 x 1`` grid to
``2 x 1`` carries the overlay files into the new panel. Unchecking a row
removes that file from the active panel only; the file stays available in the
list for other panels.
Worked example: energy scan at two temperatures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See :doc:`lem2025-singlehist-example` for the complete illustrated walkthrough
and reproducible results. It uses **new single-histogram fits** of LEM 2025
runs 1014-1027 (blue, 3.8 K) and 1033-1045 (red, 10 K), not the older
asymmetry-fit reference tables.
.. figure:: images/lem2025-singlehist-comparison.png
:alt: Actual muSRFlow comparison of field, sigma and initial asymmetry versus energy, with blue and red data sets and fit error bars.
:width: 75%
Three vertically stacked panels from the application, using the newly
fitted single-histogram tables. Both data sets are overlaid in each panel.
The example chapter explains the model, histogram grouping, uncertainties
and limitations; results are in
``docs/examples/lem2025-singlehist-energy-scan``.
Editing trace styles
~~~~~~~~~~~~~~~~~~~~
Click any marker directly in a plot panel to open a small style editor near
the pointer:
* **This trace / This data set** -- whether the change applies to the clicked
(file, parameter) series only, or to every trace of that data set (all
panels showing it). Choosing **This data set** unifies the whole file and
clears any per-panel trace styling left behind, so those panels no longer
shadow the new style.
* colour swatches, marker **symbol**, **size**, and **opacity**;
* **Error-bar caps** -- error bars are plain vertical lines unless the
checkbox is ticked, which draws the cross-bars at both ends;
* **Apply** -- commit the staged choices and redraw the affected panels;
**Close** hides the editor, and ESC (or ``Q``) dismisses it;
* **Reset** -- restore the file's default colouring for that scope.
Trace-level edits are keyed by (data set, panel, parameter), so they survive
panel re-layouts but never leak onto other panels. Data-set-level edits are
shared: recolour ``scanA_par.dat`` once, and every panel that shows it
updates. ``Esc`` (or ``Q``) closes the editor; the title bar is a drag
handle so the panel can be repositioned within the parameter-plot window.
Template and series presets
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The **Template** dropdown applies a predefined multi-panel arrangement that
maps recognised parameter names to roles. For example the ``tf-scan``
template lays out three panels -- amplitude, damping, and frequency -- above
one another. Parameters that cannot be matched to the data are omitted
rather than guessed; unmatched panels stay empty.
Keyboard shortcuts
~~~~~~~~~~~~~~~~~~
With a panel focused (and not while typing in a field), the shortcut keys are:
* ``u`` -- reset the active panel to its automatic X and Y ranges.
* ``Q`` or ``Esc`` -- close the plot window.
The plotly mode bar at the top-right of each panel provides zoom, pan, box
select, and download, and a custom button toggles each axis between linear
and logarithmic. Trace colours are assigned automatically per series --
clicking a marker opens the style editor described above to change them.