Class for handling negative muon (μ⁻) histogram fits. More...

#include <PRunMuMinus.h>

Inheritance diagram for PRunMuMinus:

Collaboration diagram for PRunMuMinus:

[legend]

Public Member Functions
	PRunMuMinus ()
	Default constructor creating an empty, invalid μ⁻ run object.

	PRunMuMinus (PMsrHandler msrInfo, PRunDataHandler rawData, UInt_t runNo, EPMusrHandleTag tag, Bool_t theoAsData)
	Main constructor initializing a μ⁻ run from MSR file and raw data.

virtual	~PRunMuMinus ()
	Virtual destructor cleaning up allocated resources.

virtual Double_t	CalcChiSquare (const std::vector< Double_t > &par)
	Calculates χ² between μ⁻ data and theory (least-squares fit metric).

virtual Double_t	CalcChiSquareExpected (const std::vector< Double_t > &par)
	Calculates expected χ² based on theory predictions (statistical diagnostic).

virtual Double_t	CalcMaxLikelihood (const std::vector< Double_t > &par)
	Calculates negative log-likelihood for Poisson statistics (low-count fit metric).

virtual void	CalcTheory ()
	Evaluates theory function at all data points (or high-resolution grid).

virtual UInt_t	GetNoOfFitBins ()
	Returns the number of bins included in the fit range.

virtual void	SetFitRangeBin (const TString fitRange)
	Sets fit range using bin-offset specification (COMMANDS block syntax).

virtual Int_t	GetStartTimeBin ()
	Returns the first bin index in the fit range.

virtual Int_t	GetEndTimeBin ()
	Returns the last bin index in the fit range (exclusive).

virtual Int_t	GetPacking ()
	Returns the bin packing factor.

virtual void	CalcNoOfFitBins ()
	Calculates start/end bin indices from fit time range.

Public Member Functions inherited from PRunBase
	PRunBase ()
	Default constructor.

	PRunBase (PMsrHandler msrInfo, PRunDataHandler rawData, UInt_t runNo, EPMusrHandleTag tag)
	Constructor initializing run from MSR file and raw data.

virtual	~PRunBase ()
	Virtual destructor.

virtual void	SetFitRange (PDoublePairVector fitRange)
	Sets the fit time range for this run.

virtual UInt_t	GetRunNo ()
	Returns the run number (0-based index in MSR file).

virtual PRunData *	GetData ()
	Returns pointer to processed data container.

virtual void	CleanUp ()
	Cleans up internal data structures.

virtual Bool_t	IsValid ()
	Returns validity status of this run object.

Protected Member Functions
virtual Bool_t	PrepareData ()
	Main data preparation routine for μ⁻ fitting and viewing.

virtual Bool_t	PrepareFitData (PRawRunData *runData, const UInt_t histoNo)
	Prepares μ⁻ histogram data for fitting.

virtual Bool_t	PrepareRawViewData (PRawRunData *runData, const UInt_t histoNo)
	Prepares μ⁻ histogram data for viewing/plotting (minimal processing).

Protected Member Functions inherited from PRunBase
virtual void	DeadTimeCorrection (std::vector< PDoubleVector > &histos, PUIntVector &histoNo)
	carry out dead time correction

virtual void	CalculateKaiserFilterCoeff (Double_t wc, Double_t A, Double_t dw)
	Calculates Kaiser window FIR filter coefficients for RRF smoothing.

virtual void	FilterTheo ()
	Applies Kaiser FIR filter to theory values for RRF fits.

Private Member Functions
virtual Bool_t	GetProperT0 (PRawRunData runData, PMsrGlobalBlock globalBlock, PUIntVector &histoNo)
	Determines and validates t0 values for μ⁻ histogram.

virtual Bool_t	GetProperDataRange ()
	Determines data range (region of valid histogram data).

virtual void	GetProperFitRange (PMsrGlobalBlock *globalBlock)
	Determines fit range from MSR file settings.

Private Attributes
UInt_t	fNoOfFitBins
	Number of bins within fit range (between fStartTimeBin and fEndTimeBin)

Int_t	fPacking
	Bin packing factor (REQUIRED for μ⁻).

Bool_t	fTheoAsData
	Theory calculation mode flag.

Int_t	fGoodBins [2]
	Good bin markers for bin-based fit range specification.

PDoubleVector	fForward
	Forward detector histogram data (background-corrected, packed).

Int_t	fStartTimeBin
	First bin index in fit range (inclusive, 0-based after packing)

Int_t	fEndTimeBin
	Last bin index in fit range (exclusive: loop as i < fEndTimeBin)

Additional Inherited Members
Protected Attributes inherited from PRunBase
Bool_t	fValid
	Flag indicating if run object initialized successfully; false if any error occurred.

EPMusrHandleTag	fHandleTag
	Operation mode: kFit (fitting), kView (display only), kEmpty (uninitialized)

Int_t	fRunNo
	Run number (0-based index in MSR file RUN blocks)

PMsrHandler *	fMsrInfo
	Pointer to MSR file handler (owned externally, not deleted here)

PMsrRunBlock *	fRunInfo
	Pointer to this run's RUN block settings within fMsrInfo.

PRunDataHandler *	fRawData
	Pointer to raw data handler (owned externally, not deleted here)

PRunData	fData
	Processed data container: background-corrected, packed, with theory values.

Double_t	fTimeResolution
	Time resolution of raw histogram data in microseconds (μs), e.g., 0.01953125 μs for PSI GPS.

PMetaData	fMetaData
	Experimental metadata extracted from data file header (magnetic field, temperature, beam energy)

PDoubleVector	fT0s
	Time-zero bin values for all histograms in this run (forward, backward, etc.)

std::vector< PDoubleVector >	fAddT0s
	Time-zero bin values for additional runs to be added to main run.

Double_t	fFitStartTime
	Fit range start time in microseconds (μs) relative to t0.

Double_t	fFitEndTime
	Fit range end time in microseconds (μs) relative to t0.

PDoubleVector	fFuncValues
	Cached values of user-defined functions from FUNCTIONS block, evaluated at current parameters.

std::unique_ptr< PTheory >	fTheory
	Theory function evaluator (smart pointer, automatically deleted)

PDoubleVector	fKaiserFilter
	Kaiser window FIR filter coefficients for smoothing RRF theory curves.

Detailed Description

Class for handling negative muon (μ⁻) histogram fits.

PRunMuMinus implements single-histogram fitting specialized for negative muon measurements. Negative muons (μ⁻) have significantly different properties compared to positive muons (μ⁺), requiring dedicated handling:

Physics of Negative Muons

Key differences from μ⁺:

Charge: Negatively charged (antimuon has positive charge)
Behavior in matter: μ⁻ are captured by nuclei rather than stopping interstitially
Cascade process: μ⁻ cascade down atomic orbitals before nuclear capture
Lifetime: Effective lifetime is reduced by nuclear capture (typically ~100-1000 ns vs. 2.2 μs free lifetime)
Decay signature: Different detector response due to capture vs. decay
Applications: Elemental analysis, nuclear structure, muonic atom spectroscopy

Data Structure

Unlike asymmetry measurements, μ⁻ fits use a single forward histogram:

One detector histogram (typically forward detector)
No asymmetry calculation (no forward/backward pair)
Direct histogram fitting with background subtraction
Bin packing for improved statistics

Analysis Workflow

Data Loading: Load single histogram from data file
Background Subtraction: Remove constant or estimated background
Time-Zero Determination: Identify μ⁻ arrival time (t0)
Bin Packing: Rebin data if specified (required parameter)
Theory Calculation: Evaluate capture-modified exponential decay
Fit Metric: χ² or maximum likelihood minimization

Typical Theory Functions

Common models for μ⁻ data include:

Simple exponential: N(t) = N₀ · exp(-t/τ_eff)
With relaxation: N(t) = N₀ · exp(-t/τ_eff) · [1 + A·cos(ωt + φ)]
Multi-component: Sum of exponentials for different capture sites

where τ_eff combines free decay and nuclear capture rates:

$\frac{1}{\tau_{\rm eff}} = \frac{1}{\tau_{\mu}} + \lambda_{\rm capture}$

Example Usage

// In MSR file RUN block:
RUN data/muminus_run2425 MUD PSI MUSR-ROOT   (name beamline)
  fittype         10      (MuMinus)
  map             1       (forward histogram)
  forward         1
  packing         10      (required!)
  background      50 150  (pre-t0 background)
  data            200 2000
  t0              210.5
  fit             0.1 10.0

See also: PRunSingleHisto for standard positive muon single histogram fits; PRunBase for base class interface and common functionality

Definition at line 97 of file PRunMuMinus.h.

Constructor & Destructor Documentation

◆ PRunMuMinus() [1/2]

PRunMuMinus::PRunMuMinus ( )

Default constructor creating an empty, invalid μ⁻ run object.

Creates an uninitialized run object with all values set to defaults. This constructor is needed for creating vectors of PRunMuMinus objects but the object is not usable until properly initialized via the main constructor.

Initializes all member variables to default/invalid states:

Bin counts and indices set to -1 (invalid)
Packing set to -1 (unspecified - will cause error if used)
Theory mode set to false (high-resolution grid)
Handle tag set to kEmpty (uninitialized)

This constructor is needed for creating vectors of PRunMuMinus objects, but the resulting object cannot be used for fitting until properly initialized via the main constructor.

See also: PRunMuMinus(PMsrHandler*, PRunDataHandler*, UInt_t, EPMusrHandleTag, Bool_t)

Definition at line 64 of file PRunMuMinus.cpp.

References fEndTimeBin, fGoodBins, PRunBase::fHandleTag, fNoOfFitBins, fPacking, fStartTimeBin, fTheoAsData, kEmpty, and PRunBase::PRunBase().

◆ PRunMuMinus() [2/2]

PRunMuMinus::PRunMuMinus	(	PMsrHandler *	msrInfo,
		PRunDataHandler *	rawData,
		UInt_t	runNo,
		EPMusrHandleTag	tag,
		Bool_t	theoAsData )

Main constructor initializing a μ⁻ run from MSR file and raw data.

Performs comprehensive initialization:

Validates packing parameter (REQUIRED for μ⁻ - cannot be -1)
Initializes base class (PRunBase) with MSR and data handlers
Calls PrepareData() to load and preprocess the histogram
Validates successful initialization

The packing parameter is mandatory for μ⁻ data and is obtained from:

RUN block "packing" entry (if specified)
Falls back to GLOBAL block "packing" entry
SEVERE ERROR if neither is specified → run marked invalid

Parameters

msrInfo	Pointer to MSR file handler (must remain valid)
rawData	Pointer to raw data handler for histogram loading
runNo	Run number (0-based index in MSR file RUN blocks)
tag	Operation mode: kFit (fitting), kView (display/plotting)
theoAsData	Theory mode: true = at data points, false = high-resolution

Warning: If PrepareData() fails, the object is marked invalid (fValid=false)

Performs comprehensive initialization for negative muon analysis:

Base Class Initialization:
- Calls PRunBase constructor with MSR/data handlers
- Initializes theory engine and parameter mappings
Packing Validation (CRITICAL for μ⁻):
- Attempts to read packing from RUN block
- Falls back to GLOBAL block if not in RUN block
- SEVERE ERROR if packing == -1 (unspecified)
- Packing is MANDATORY for μ⁻ data (unlike some other fit types)
Member Initialization:
- Good bin markers set to -1 (determined later)
- Fit range bins initialized to -1 (invalid until set)
- Number of fit bins set to 0
Data Preparation:
- Calls PrepareData() to load and preprocess histogram
- If PrepareData() fails, run is marked invalid

The object is marked as invalid (fValid=false) if:

Packing parameter is missing
PrepareData() fails (file not found, invalid t0, etc.)

Parameters

msrInfo	Pointer to MSR file handler (must remain valid for object lifetime)
rawData	Pointer to raw data handler for loading histogram files
runNo	Run number (0-based index in MSR file RUN blocks)
tag	Operation mode: kFit (fitting), kView (display/plotting)
theoAsData	Theory calculation mode: true = at data points, false = high-resolution

Warning: Invalid objects should not be used for fitting. Check IsValid() after construction.

See also: PrepareData() for data preprocessing details; PRunBase constructor for base initialization

Definition at line 123 of file PRunMuMinus.cpp.

References fEndTimeBin, fGoodBins, PRunBase::fMsrInfo, fNoOfFitBins, fPacking, PRunBase::fRunInfo, fStartTimeBin, fTheoAsData, PRunBase::fValid, PrepareData(), and PRunBase::PRunBase().

◆ ~PRunMuMinus()

PRunMuMinus::~PRunMuMinus ( )

virtual

Virtual destructor cleaning up allocated resources.

Destructor cleaning up allocated resources.

Releases memory used by the forward histogram vector (fForward). Base class destructor handles cleanup of theory objects and other shared resources.

Releases memory used by the forward histogram vector. Other cleanup (theory objects, base class resources) is handled by the PRunBase destructor.

Definition at line 165 of file PRunMuMinus.cpp.

References fForward.

Member Function Documentation

◆ CalcChiSquare()

Double_t PRunMuMinus::CalcChiSquare ( const std::vector< Double_t > & par )

virtual

Calculates χ² between μ⁻ data and theory (least-squares fit metric).

Computes the chi-squared statistic for the forward histogram:

$\chi^2 = \sum_{i={\rm start}}^{\rm end} \frac{(N_i^{\rm data} - N_i^{\rm theory})^2}{\sigma_i^2}$

where:

N_i^data is the background-corrected, packed histogram count in bin i
N_i^theory is the theory prediction from THEORY block
σ_i is the propagated error (including background uncertainty)
Sum runs from fStartTimeBin to fEndTimeBin (fit range)

Implementation uses OpenMP parallelization when available for performance. Each thread processes a chunk of bins independently, with reduction for final sum.

Parameters

par	Parameter vector from MINUIT with current parameter values

Returns: Chi-squared value (lower is better; minimize during fitting)

See also: CalcMaxLikelihood() for alternative fit metric (better for low counts); CalcTheory() for theory function evaluation details

Computes the chi-squared statistic using the standard formula:

$\chi^2 = \sum_{i={\rm start}}^{\rm end} \frac{(N_i^{\rm data} - N_i^{\rm theory})^2}{\sigma_i^2}$

Algorithm:

Evaluate FUNCTIONS block for user-defined functions
Pre-calculate theory once at t=1.0 (thread-safe initialization for LF/user functions)
Loop over fit range bins (fStartTimeBin to fEndTimeBin)
For each bin:
- Calculate time from bin index
- Evaluate theory function at that time
- Compute squared difference weighted by error
Sum contributions (with OpenMP reduction if available)

OpenMP Parallelization:

When compiled with GOMP support, χ² calculation is parallelized
Loop divided into dynamic chunks for load balancing
Chunk size: (N_bins / N_processors), minimum 10 bins per chunk
Private variables per thread: i, time, diff
Reduction performed on final chisq sum

Theory Pre-calculation: The initial call to fTheory->Func(time=1.0, ...) ensures thread-safe initialization for London field (LF) and user functions that cache computationally expensive calculations per parameter set.

Parameters

par	Parameter vector from MINUIT with current parameter values

Returns: Chi-squared value (sum of weighted squared residuals)

See also: CalcMaxLikelihood() for Poisson-based alternative (better for low counts); CalcTheory() for theory evaluation without χ² calculation

Implements PRunBase.

Definition at line 207 of file PRunMuMinus.cpp.

References PRunBase::fData, fEndTimeBin, PRunBase::fFuncValues, PRunBase::fMetaData, PRunBase::fMsrInfo, PRunBase::fRunInfo, fStartTimeBin, and PRunBase::fTheory.

◆ CalcChiSquareExpected()

Double_t PRunMuMinus::CalcChiSquareExpected ( const std::vector< Double_t > & par )

virtual

Calculates expected χ² based on theory predictions (statistical diagnostic).

Calculates expected χ² assuming theory is the true distribution (diagnostic).

Computes the expected chi-squared assuming theory values are the "true" counts:

$\chi^2_{\rm expected} = \sum_{i} \frac{(N_i^{\rm data} - N_i^{\rm theory})^2}{N_i^{\rm theory}}$

This diagnostic helps evaluate:

Quality of error estimates
Poisson vs. Gaussian statistics validity
Over/under-dispersion in data

For well-estimated errors: χ²_expected ≈ number of degrees of freedom

Parameters

par	Parameter vector from MINUIT

Returns: Expected χ² value (currently returns 0.0 - placeholder implementation)

Note: Current implementation returns 0.0; full calculation performed but not returned

Computes the expected chi-squared using theory values as the expected counts:

$\chi^2_{\rm expected} = \sum_{i} \frac{(N_i^{\rm data} - N_i^{\rm theory})^2}{N_i^{\rm theory}}$

This is a statistical diagnostic for evaluating:

Quality of error estimates (if errors are correct, χ²/ν ≈ 1)
Validity of Gaussian approximation (breaks down for low counts)
Over/under-dispersion in data relative to Poisson expectations

For Poisson-distributed data with large counts:

χ²_expected ≈ number of degrees of freedom
χ²_expected / ν ≈ 1 indicates proper error estimation

Algorithm is identical to CalcChiSquare() except:

Error denominator is σ² = N_theory (Poisson variance)
Instead of using fData.GetError()->at(i)

OpenMP Parallelization: Same as CalcChiSquare()

Parameters

par	Parameter vector from MINUIT

Returns: Expected χ² value (currently returns 0.0 - calculation done but not returned)

Note: Current implementation performs the calculation but returns 0.0. The calculated value could be returned for diagnostic purposes.

See also: CalcChiSquare() for standard χ² calculation

Implements PRunBase.

Definition at line 275 of file PRunMuMinus.cpp.

References PRunBase::fData, fEndTimeBin, PRunBase::fFuncValues, PRunBase::fMetaData, PRunBase::fMsrInfo, PRunBase::fRunInfo, fStartTimeBin, and PRunBase::fTheory.

◆ CalcMaxLikelihood()

Double_t PRunMuMinus::CalcMaxLikelihood ( const std::vector< Double_t > & par )

virtual

Calculates negative log-likelihood for Poisson statistics (low-count fit metric).

Computes the maximum likelihood estimator assuming Poisson-distributed counts:

$-2\ln L = 2\sum_{i} \left[N_i^{\rm theory} - N_i^{\rm data} \ln(N_i^{\rm theory})\right]$

Maximum likelihood is superior to χ² when:

Count rates are low (< 10-20 counts per bin)
Poisson statistics dominate (Gaussian approximation invalid)
Error estimation is uncertain

The factor of 2 makes the likelihood comparable to χ² in the Gaussian limit. MINUIT minimizes this function just like χ².

Implementation details:

Uses OpenMP parallelization for performance
Handles edge cases: zero data (skips log term), negative theory (warning + skip)
Threshold: data > 10^-9 to include log term

Parameters

par	Parameter vector from MINUIT

Returns: -2×ln(L) value (lower is better; minimize during fitting)

See also: CalcChiSquare() for standard least-squares metric

Computes the maximum likelihood estimator assuming Poisson-distributed histogram counts:

$-2\ln L = 2\sum_{i} \left[N_i^{\rm theory} - N_i^{\rm data}\ln(N_i^{\rm theory})\right]$

This is derived from the Poisson probability:

$P(n|\\lambda) = \frac{\\lambda^n e^{-\\lambda}}{n!}$

Taking negative log-likelihood and multiplying by 2 gives a metric that:

Is minimized at the best-fit parameters (like χ²)
Approaches χ² in the high-count (Gaussian) limit
Handles low counts correctly (no Gaussian approximation needed)

When to use likelihood vs. χ²:

Low counts (< 10-20 per bin): Use likelihood (this method)
High counts (> 20 per bin): Either method works, χ² is faster
Uncertain errors: Use likelihood (no error estimates needed)

Algorithm:

Evaluate FUNCTIONS block
Pre-calculate theory at t=1.0 (thread-safe initialization)
Loop over fit range bins
For each bin:
- Calculate theory prediction
- Check for negative theory (warning + skip)
- Add Poisson likelihood term:
  - If data > 10^-9: (theo - data) + data·ln(data/theo)
  - If data ≈ 0: (theo - data) only (avoid log(0))
Multiply sum by 2 (convention for comparison with χ²)

Edge Case Handling:

Negative theory: Print warning, skip bin (should not happen with proper model)
Zero data: Use simplified formula without log term
Zero theory: Would cause log(0), but checked via negative theory guard

Reference: Particle Data Group (PDG), Statistics Review http://pdg.lbl.gov/index.html

Parameters

par	Parameter vector from MINUIT

Returns: -2×ln(L) value (minimize during fitting, comparable to χ²)

See also: CalcChiSquare() for standard least-squares metric

Implements PRunBase.

Definition at line 360 of file PRunMuMinus.cpp.

References PRunBase::fData, fEndTimeBin, PRunBase::fFuncValues, PRunBase::fMetaData, PRunBase::fMsrInfo, PRunBase::fRunInfo, fStartTimeBin, and PRunBase::fTheory.

◆ CalcNoOfFitBins()

void PRunMuMinus::CalcNoOfFitBins ( )

virtual

Calculates start/end bin indices from fit time range.

Converts the fit range specified in time (microseconds from t0) into bin indices accounting for:

Data time start offset
Time resolution (bin width)
Packing factor

Updates:

fStartTimeBin: First bin in fit range
fEndTimeBin: One past last bin (exclusive upper bound)
fNoOfFitBins: Count of bins in range

Called automatically when fit range is changed via SetFitRange().

See also: SetFitRange() in PRunBase for time-based range setting

Calculate the number of fitted bins for the current fit range.

Definition at line 531 of file PRunMuMinus.cpp.

References PRunBase::fData, fEndTimeBin, PRunBase::fFitEndTime, PRunBase::fFitStartTime, fNoOfFitBins, and fStartTimeBin.

Referenced by GetNoOfFitBins(), PrepareFitData(), and PrepareRawViewData().

◆ CalcTheory()

void PRunMuMinus::CalcTheory ( )

virtual

Evaluates theory function at all data points (or high-resolution grid).

Calculates the expected μ⁻ decay signal using the THEORY block functions. The theory is evaluated either:

At data point times (fTheoAsData=true): For fitting and exact comparison
On high-resolution grid (fTheoAsData=false): For smooth plotting

Theory evaluation:

Determines time grid based on fTheoAsData flag
Evaluates FUNCTIONS block (user-defined functions)
Loops over time points calling fTheory->Func(time, par, funcValues)
Stores results in fData for χ² or likelihood calculation

The theory typically models:

Exponential decay: N₀·exp(-t/τ_eff)
With modulation: N₀·exp(-t/τ_eff)·[1 + A·cos(ωt + φ)]
Multi-component captures

See also: PTheory::Func() for theory function implementation; PrepareData() for data grid setup

Calculate theory for a given set of fit-parameters.

Implements PRunBase.

Definition at line 553 of file PRunMuMinus.cpp.

References PRunBase::fData, PRunBase::fFuncValues, PRunBase::fMetaData, PRunBase::fMsrInfo, PRunBase::fRunInfo, and PRunBase::fTheory.

◆ GetEndTimeBin()

virtual Int_t PRunMuMinus::GetEndTimeBin ( )

inlinevirtual

Returns the last bin index in the fit range (exclusive).

Returns: End bin index (loop condition: i < fEndTimeBin)

Definition at line 281 of file PRunMuMinus.h.

References fEndTimeBin.

◆ GetNoOfFitBins()

UInt_t PRunMuMinus::GetNoOfFitBins ( )

virtual

Returns the number of bins included in the fit range.

Calculates and returns the count of histogram bins between fStartTimeBin and fEndTimeBin (fit range boundaries). This is used for:

Degrees of freedom: ν = N_bins - N_params
Reduced χ²: χ²_red = χ² / ν
Statistical analysis and diagnostics

Internally calls CalcNoOfFitBins() to update fNoOfFitBins.

Returns: Number of bins in fit range

See also: CalcNoOfFitBins() for bin range calculation details

Recalculates and returns the count of histogram bins between fStartTimeBin and fEndTimeBin. This count is used for:

Degrees of freedom calculation: ν = N_bins - N_params
Reduced χ²: χ²_red = χ² / ν
Statistical quality assessment

Internally calls CalcNoOfFitBins() to ensure fNoOfFitBins is up-to-date.

Returns: Number of bins within fit range (fEndTimeBin - fStartTimeBin)

See also: CalcNoOfFitBins() for bin range calculation from time range

Definition at line 428 of file PRunMuMinus.cpp.

References CalcNoOfFitBins(), and fNoOfFitBins.

◆ GetPacking()

virtual Int_t PRunMuMinus::GetPacking ( )

inlinevirtual

Returns the bin packing factor.

Returns: Packing value (number of raw bins combined into one packed bin)

Definition at line 287 of file PRunMuMinus.h.

References fPacking.

◆ GetProperDataRange()

Bool_t PRunMuMinus::GetProperDataRange ( )

privatevirtual

Determines data range (region of valid histogram data).

Establishes the data range boundaries from RUN block specification:

Start bin: First bin with valid μ⁻ data (typically after t0)
End bin: Last bin before noise/artifacts dominate

Data range is typically wider than fit range. The fit range is a subset of the data range optimized for parameter extraction.

Returns: True if valid data range determined, false if specification invalid

See also: GetProperFitRange() for fit range (subset of data range)

Get the proper data range, i.e. first/last good bin (fgb/lgb).

get fgb/lgb from the RUN block
if fgb/lgb still undefined, try to get it from the GLOBAL block
if fgb/lgb still undefined, try to estimate them.

return:

true if everthing went smooth
false, otherwise.

Definition at line 1076 of file PRunMuMinus.cpp.

References fForward, fGoodBins, PRunBase::fMsrInfo, PRunBase::fRunInfo, PRunBase::fT0s, and PRunBase::fTimeResolution.

Referenced by PrepareData().

◆ GetProperFitRange()

void PRunMuMinus::GetProperFitRange ( PMsrGlobalBlock * globalBlock )

privatevirtual

Determines fit range from MSR file settings.

Extracts fit range boundaries (time window for χ² calculation) from:

RUN block "fit" entry (if specified)
GLOBAL block "fit" entry (fallback)

Fit range format in MSR file:

Time-based: "fit 0.1 10.0" (μs from t0)
Bin-based: "fit fgb+5 lgb-10" (offsets from markers)

The fit range determines which bins contribute to χ² or likelihood. Choosing the optimal range is critical for accurate parameter extraction.

Parameters

globalBlock GLOBAL block from MSR file with default fit settings

See also: CalcNoOfFitBins() for converting time range to bin indices

Get the proper fit range. There are two possible fit range commands: fit <start> <end> given in (usec), or fit fgb+offset_0 lgb-offset_1 given in (bins), therefore it works the following way:

get fit range assuming given in time from RUN block
if fit range in RUN block is given in bins, replace start/end
if fit range is NOT given yet, try fit range assuming given in time from GLOBAL block
if fit range in GLOBAL block is given in bins, replace start/end
if still no fit range is given, use fgb/lgb.

Parameters

globalBlock pointer to the GLOBAL block information form the msr-file.

Definition at line 1151 of file PRunMuMinus.cpp.

References PRunBase::fFitEndTime, PRunBase::fFitStartTime, fGoodBins, PRunBase::fRunInfo, PRunBase::fT0s, PRunBase::fTimeResolution, PMsrGlobalBlock::GetFitRange(), PMsrGlobalBlock::GetFitRangeOffset(), PMsrGlobalBlock::IsFitRangeInBin(), PMUSR_UNDEFINED, and PMsrGlobalBlock::SetFitRange().

Referenced by PrepareData().

◆ GetProperT0()

Bool_t PRunMuMinus::GetProperT0	(	PRawRunData *	runData,
		PMsrGlobalBlock *	globalBlock,
		PUIntVector &	histoNo )

privatevirtual

Determines and validates t0 values for μ⁻ histogram.

Extracts time-zero (muon arrival time) from:

RUN block "t0" entry (if specified)
Data file header (if available)
GLOBAL block default (fallback)
Automatic determination from histogram structure (if enabled)

For μ⁻, t0 marks the start of the decay/capture signal. Validates that t0 is within reasonable bounds of the histogram.

Parameters

runData	Raw run data containing histogram and metadata
globalBlock	GLOBAL block from MSR file with default settings
histoNo	Vector of histogram indices to process

Returns: True if valid t0 found/determined, false otherwise

Get the proper t0 for the single histogram run.

the t0 vector size = number of detectors (grouping) for forward.
initialize t0's with -1
fill t0's from RUN block
if t0's are missing (i.e. t0 == -1), try to fill from the GLOBAL block.
if t0's are missing, try t0's from the data file
if t0's are missing, try to estimate them

Parameters

histoNo histogram number vector of forward; histoNo = msr-file forward + redGreen_offset - 1

return:

true if everthing went smooth
false, otherwise.

Definition at line 945 of file PRunMuMinus.cpp.

References PRunBase::fAddT0s, PRunBase::fRawData, PRunBase::fRunInfo, PRunBase::fT0s, PRawRunData::GetDataBin(), PMsrGlobalBlock::GetT0Bin(), PRawRunData::GetT0Bin(), PRawRunData::GetT0BinEstimated(), and PMsrGlobalBlock::GetT0BinSize().

Referenced by PrepareData().

◆ GetStartTimeBin()

virtual Int_t PRunMuMinus::GetStartTimeBin ( )

inlinevirtual

Returns the first bin index in the fit range.

Returns: Start bin index (0-based, after packing applied)

Definition at line 275 of file PRunMuMinus.h.

References fStartTimeBin.

◆ PrepareData()

Bool_t PRunMuMinus::PrepareData ( )

protectedvirtual

Main data preparation routine for μ⁻ fitting and viewing.

Orchestrates the complete data preprocessing pipeline:

Determines operation mode (fitting vs. viewing)
Calls PrepareFitData() or PrepareRawViewData() accordingly
Validates successful data loading and processing

This method is called once during object construction. If it returns false, the run object is marked as invalid (fValid=false).

Returns: True if data preparation succeeds, false on any error

See also: PrepareFitData() for fitting mode preprocessing; PrepareRawViewData() for viewing mode preprocessing

Prepare data for fitting or viewing. What is already processed at this stage:

get proper raw run data
get all needed forward histograms
get time resolution
get t0's and perform necessary cross checks (e.g. if t0 of msr-file (if present) are consistent with t0 of the data files, etc.)
add runs (if addruns are present)
group histograms (if grouping is present)

return:

true if everthing went smooth
false, otherwise.

Implements PRunBase.

Definition at line 596 of file PRunMuMinus.cpp.

References PRunBase::fAddT0s, fForward, PRunBase::fHandleTag, PRunBase::fMetaData, PRunBase::fMsrInfo, PRunBase::fRawData, PRunBase::fRunInfo, PRunBase::fT0s, PRunBase::fTimeResolution, PRunBase::fValid, PRawRunData::GetDataBin(), PRawRunData::GetEnergy(), PRawRunData::GetField(), PRawRunData::GetNoOfTemperatures(), GetProperDataRange(), GetProperFitRange(), GetProperT0(), PRawRunData::GetTemperature(), PRawRunData::GetTimeResolution(), PRawRunData::IsPresent(), kFit, kView, PrepareFitData(), and PrepareRawViewData().

Referenced by PRunMuMinus().

◆ PrepareFitData()

Bool_t PRunMuMinus::PrepareFitData	(	PRawRunData *	runData,
		const UInt_t	histoNo )

protectedvirtual

Prepares μ⁻ histogram data for fitting.

Performs comprehensive data preprocessing:

Loads forward histogram from data file
Extracts metadata (field, energy, temperature)
Validates and determines t0 value
Subtracts background (fixed or estimated)
Packs bins according to packing factor
Propagates errors through all transformations
Sets up time grid for theory evaluation
Establishes data/fit ranges

Background correction (if specified in RUN block):

Fixed background: Subtract constant value
Estimated background: Calculate from pre-t0 bins, subtract with error propagation

Parameters

runData	Pointer to raw run data handler containing histogram
histoNo	Histogram index in data file (from "forward" entry in RUN block)

Returns: True on success, false if data loading or preprocessing fails

See also: PrepareRawViewData() for alternative viewing mode processing

Take the pre-processed data (i.e. grouping and addrun are preformed) and form the histogram for fitting. The following steps are preformed:

get fit start/stop time
check that 'first good data bin', 'last good data bin', and 't0' make any sense
packing (i.e rebinning)

return:

true, if everything went smooth
false, otherwise

Parameters

runData	raw run data handler
histoNo	forward histogram number

Definition at line 740 of file PRunMuMinus.cpp.

References CalcNoOfFitBins(), PRunBase::fData, fForward, fGoodBins, fPacking, PRunBase::fT0s, and PRunBase::fTimeResolution.

Referenced by PrepareData().

◆ PrepareRawViewData()

Bool_t PRunMuMinus::PrepareRawViewData	(	PRawRunData *	runData,
		const UInt_t	histoNo )

protectedvirtual

Prepares μ⁻ histogram data for viewing/plotting (minimal processing).

Lighter-weight data preprocessing for visualization:

Loads forward histogram from data file
Extracts metadata
Determines t0
Sets up data range (may extend beyond fit range)
Minimal or no background subtraction
Optional packing for display

Used when tag=kView to prepare data for plotting without full fitting infrastructure. Typically displays wider time range than fit range for context.

Parameters

runData	Pointer to raw run data handler containing histogram
histoNo	Histogram index in data file

Returns: True on success, false if data loading fails

See also: PrepareFitData() for full fitting mode processing

Take the pre-processed data (i.e. grouping and addrun are preformed) and form the histogram for viewing without any life time correction.

The following steps are preformed:

check if view packing is whished.
check that 'first good data bin', 'last good data bin', and 't0' makes any sense
packing (i.e. rebinnig)
calculate theory

return:

true, if everything went smooth
false, otherwise.

Parameters

runData	raw run data handler
histoNo	forward histogram number

Definition at line 798 of file PRunMuMinus.cpp.

References CalcNoOfFitBins(), PRunBase::fData, PRunBase::fFitEndTime, PRunBase::fFitStartTime, fForward, PRunBase::fFuncValues, fGoodBins, PRunBase::fMetaData, PRunBase::fMsrInfo, fPacking, PRunBase::fRunInfo, PRunBase::fT0s, fTheoAsData, PRunBase::fTheory, and PRunBase::fTimeResolution.

Referenced by PrepareData().

◆ SetFitRangeBin()

void PRunMuMinus::SetFitRangeBin ( const TString fitRange )

virtual

Sets fit range using bin-offset specification (COMMANDS block syntax).

Parses and applies fit range specified as bin offsets from good bin markers. This supports the COMMANDS block FIT_RANGE syntax for dynamic range adjustments.

Format: "fit_range fgb+n0 lgb-n1"

fgb = first good bin (typically t0 bin)
lgb = last good bin (end of data range)
n0, n1 = offsets in bins (can be + or -)

Example: "fit_range fgb+5 lgb-10" → Start 5 bins after t0, end 10 bins before last good bin

Parameters

fitRange String with fit range specification in bin offsets

See also: SetFitRange(PDoublePairVector) in PRunBase for time-based specification

Allows to change the fit range on the fly. Used in the COMMAND block. The syntax of the string is: FIT_RANGE fgb[+n00] lgb[-n01] [fgb[+n10] lgb[-n11] ... fgb[+nN0] lgb[-nN1]]. If only one pair of fgb/lgb is given, it is used for all runs in the RUN block section. If multiple fgb/lgb's are given, the number N has to be the number of RUN blocks in the msr-file.

nXY are offsets which can be used to shift, limit the fit range.

Parameters

fitRange string containing the necessary information.

Definition at line 449 of file PRunMuMinus.cpp.

References PRunBase::fFitEndTime, PRunBase::fFitStartTime, fGoodBins, PRunBase::fRunNo, PRunBase::fT0s, and PRunBase::fTimeResolution.

Member Data Documentation

◆ fEndTimeBin

Int_t PRunMuMinus::fEndTimeBin

private

Last bin index in fit range (exclusive: loop as i < fEndTimeBin)

Definition at line 430 of file PRunMuMinus.h.

Referenced by CalcChiSquare(), CalcChiSquareExpected(), CalcMaxLikelihood(), CalcNoOfFitBins(), GetEndTimeBin(), PRunMuMinus(), and PRunMuMinus().

◆ fForward

PDoubleVector PRunMuMinus::fForward

private

Forward detector histogram data (background-corrected, packed).

Contains the processed μ⁻ decay histogram after:

Background subtraction
Bin packing
Conversion to appropriate units

This is the data fitted against theory predictions. Stored in fData.GetValue() vector for χ² calculation.

Definition at line 427 of file PRunMuMinus.h.

Referenced by GetProperDataRange(), PrepareData(), PrepareFitData(), PrepareRawViewData(), and ~PRunMuMinus().

◆ fGoodBins

Int_t PRunMuMinus::fGoodBins[2]

private

Good bin markers for bin-based fit range specification.

Stores reference bins used in COMMANDS block FIT_RANGE parsing:

fGoodBins[0]: First good bin (fgb) - typically t0 bin
fGoodBins[1]: Last good bin (lgb) - end of valid data range

Used when fit range is specified as "fgb+n0 lgb-n1" rather than absolute times. Needed because COMMANDS block can dynamically change fit range during execution.

Definition at line 414 of file PRunMuMinus.h.

Referenced by GetProperDataRange(), GetProperFitRange(), PrepareFitData(), PrepareRawViewData(), PRunMuMinus(), PRunMuMinus(), and SetFitRangeBin().

◆ fNoOfFitBins

UInt_t PRunMuMinus::fNoOfFitBins

private

Number of bins within fit range (between fStartTimeBin and fEndTimeBin)

Definition at line 376 of file PRunMuMinus.h.

Referenced by CalcNoOfFitBins(), GetNoOfFitBins(), PRunMuMinus(), and PRunMuMinus().

◆ fPacking

Int_t PRunMuMinus::fPacking

private

Bin packing factor (REQUIRED for μ⁻).

Number of consecutive raw histogram bins combined into one packed bin. Higher packing improves statistics but reduces time resolution.

Source priority:

RUN block "packing" entry
GLOBAL block "packing" entry
ERROR if neither specified (mandatory for μ⁻)

Typical values: 1 (no packing), 5, 10, 20

Definition at line 391 of file PRunMuMinus.h.

Referenced by GetPacking(), PrepareFitData(), PrepareRawViewData(), PRunMuMinus(), and PRunMuMinus().

◆ fStartTimeBin

Int_t PRunMuMinus::fStartTimeBin

private

First bin index in fit range (inclusive, 0-based after packing)

Definition at line 429 of file PRunMuMinus.h.

Referenced by CalcChiSquare(), CalcChiSquareExpected(), CalcMaxLikelihood(), CalcNoOfFitBins(), GetStartTimeBin(), PRunMuMinus(), and PRunMuMinus().

◆ fTheoAsData

Bool_t PRunMuMinus::fTheoAsData

private

Theory calculation mode flag.

Controls theory grid resolution:

true: Theory evaluated only at data point times (efficient for fitting)
false: Theory evaluated on finer grid (smooth curves for plotting/Fourier)

Set from PRunListCollection based on PLOT block settings.

Definition at line 402 of file PRunMuMinus.h.

Referenced by PrepareRawViewData(), PRunMuMinus(), and PRunMuMinus().

The documentation for this class was generated from the following files:

/workspace/LMU/musrfit/src/include/PRunMuMinus.h
/workspace/LMU/musrfit/src/classes/PRunMuMinus.cpp

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Physics of Negative Muons

Data Structure

Analysis Workflow

Typical Theory Functions

Example Usage

Constructor & Destructor Documentation

◆ PRunMuMinus() [1/2]

◆ PRunMuMinus() [2/2]

◆ ~PRunMuMinus()

Member Function Documentation

◆ CalcChiSquare()

◆ CalcChiSquareExpected()

◆ CalcMaxLikelihood()

◆ CalcNoOfFitBins()

◆ CalcTheory()

◆ GetEndTimeBin()

◆ GetNoOfFitBins()

◆ GetPacking()

◆ GetProperDataRange()

◆ GetProperFitRange()

◆ GetProperT0()

◆ GetStartTimeBin()

◆ PrepareData()

◆ PrepareFitData()

◆ PrepareRawViewData()

◆ SetFitRangeBin()

Member Data Documentation

◆ fEndTimeBin

◆ fForward

◆ fGoodBins

◆ fNoOfFitBins

◆ fPacking

◆ fStartTimeBin

◆ fTheoAsData