LEM single-histogram example
========================================

This worked example repeats the LEM 2025 energy scans using **single-histogram
fits**, not asymmetry fits. The original files in ``/tmp/lemfit`` were
asymmetry fits and were used only for initial parameter estimates. They were
not overwritten.

Data and model
--------------

* **Data set 1:** runs **1014-1027**, 3.8 K, blue circles.
* **Data set 2:** runs **1033-1045**, 10 K, red squares.
* Sample: 85 nm Nb/Al2O3; nominal field 100 G; energy approximately 1-18 keV.
* Fit type: **Single histogram** (``fittype 0``), groups ``21 25`` and
  ``23 27``; nominal fit interval **0-8 microseconds**, packing **100**.

Both count-histogram groups are fitted together for each physical run.
The polarization model is

.. math::

   P_j(t) = A_0 \exp[-(\sigma t)^2/2]
            \cos(2\pi\gamma_\mu B t + \phi_j).

The MSR theory is ``asymmetry``, ``simpleGss``, ``TFieldCos`` with
``fun1 = gamma_mu * par3``, where parameter 3 is ``Bfield``. Thus field is
fitted directly in G, rather than converted from a plotted frequency later.
``Sgm`` is in inverse microseconds and ``Asy`` is dimensionless.

Each group has its own phase, normalization and constant background.
``Asy``, ``Sgm`` and ``Bfield`` are common to the two groups **within one
physical run**. No parameters are shared **between physical runs**: these
are 27 independent fits, not one global fit across the energy scan.

.. note::

   No ``musrt0 -g`` correction or explicit t0/data override was applied.
   musrfit reads the LEM timing information and reports its automatic data
   range fallback (start t0 + 51 bins, end 66601). The nominal interval is
   0-8 microseconds; the fallback excludes approximately the first 10 ns.
   The retained command logs record these warnings.

Inspect the fitted run
----------------------

The screenshots below show the actual application after importing the fitted
``1014_his.msr``. The fits themselves were executed with the command-line
script described below; the screenshots do not imply a browser fit job was
executed. Importing this file also restores its recognized GUI settings.

.. figure:: images/lem2025-singlehist-runs.png
   :alt: Runs tab populated from the fitted LEM 2025 single-histogram MSR.
   :width: 100%

   Representative run 1014. Use this fit type, histogram grouping and model
   for the two run ranges. Leave cross-run Shared parameters unchecked.

.. figure:: images/lem2025-singlehist-parameters.png
   :alt: Parameter table imported from the completed single-histogram fit of run 1014.
   :width: 100%

   Fitted parameters imported from run 1014, not illustrative starting values.
   The two groups have independent nuisance parameters.

.. figure:: images/lem2025-singlehist-editor.png
   :alt: Highlighted fitted MSR for LEM run 1014 in the application editor.
   :width: 100%

   The fitted MSR is the authoritative record. Editor ownership preserves
   the imported text rather than regenerating it from an approximate model.

.. figure:: images/lem2025-singlehist-spectrum.png
   :alt: musrview plot of the two fitted histogram groups of LEM run 1014.
   :width: 100%

   Actual ``musrview 1014_his.msr --png`` output. ``PLOT 0`` contains
   ``runs 1 2`` and ``lifetimecorrection``; both histogram groups are shown.

Compare the energy scans
------------------------

1. Fit each run range independently and export one parameter table per scan.
   The supplied ``dataset1.dat`` and ``dataset2.dat`` contain the new fits.
2. Open **Parameter plots**, load the first table and add the second as an
   overlay. Select ``dataE`` (implantation energy in keV) for X.
3. Use a **3 x 1** layout, with ``Bfield``, ``Sgm`` and ``Asy`` in separate
   panels. Overlay both data sets in every panel.
4. Set data set 1 blue and data set 2 red using the marker style editor's
   **This data set** scope. Keep error bars enabled. Resize the plot window
   to give each panel approximately 4:3 proportions.

.. figure:: images/lem2025-singlehist-comparison.png
   :alt: Actual application plot of field, Gaussian sigma and initial asymmetry against energy with blue and red data sets and error bars.
   :width: 75%

   Actual muSRFlow parameter-plot window, using the newly exported tables.
   Error bars are the HESSE parameter uncertainties exported by msr2data.

All 27 fits produced finite parameters and positive uncertainties for the
three plotted quantities. Reduced chi-square ranges from **0.933 to 2.003**
(809 degrees of freedom per fit). In particular, the lowest-energy fit is
not statistically ideal: successful minimization does not establish that
one Gaussian cosine fully describes the data. Inspect residuals and fit
range dependence before drawing quantitative physical conclusions.

Reproduce and inspect
----------------------

The repository directory ``docs/examples/lem2025-singlehist-energy-scan``
contains all 27 fitted MSRs, their starting-file backups and logs, raw and
normalized msr2data tables, metadata, a fit summary and the fit script.
Raw detector data are not included. The summary records their SHA256 hashes.
The documented run used musrfit 1.12.1 with ROOT 6.38.00.

From the repository root, with musrfit, msr2data and dump_header on PATH::

   python3 docs/examples/lem2025-singlehist-energy-scan/fit_all.py \
     --data-dir /mnt/data/nemu/his/2025 \
     --work-dir /tmp/lem-singlehist-new \
     --reference-dir /tmp/lemfit

Use your own data directory containing ``lem25_his_1014.root`` etc. Choose
an empty work directory; existing results are not overwritten. The optional
reference directory supplies starting values only. Without it, the script
uses documented generic initial values, which need not reproduce the same
minimum in every case.

The fit commands are ``musrfit RUN_his.msr -e -t -u 2 -k``; each MSR contains
``MINIMIZE``, ``HESSE`` and ``SAVE``. The export commands use
``msr2data "[RUN ...]" _his data new -o datasetN.raw.dat``. Only run suffixes
in column headings are removed in ``datasetN.dat`` so both scans have matching
parameter names; numerical values and uncertainties are unchanged.

Download the tables used in the comparison:
:download:`data set 1 <../examples/lem2025-singlehist-energy-scan/dataset1.dat>`
and :download:`data set 2 <../examples/lem2025-singlehist-energy-scan/dataset2.dat>`.
