improve the doxygen docu of PRunAsymmetry.*.
This commit is contained in:
@@ -34,57 +34,250 @@
|
||||
|
||||
//---------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Class handling the asymmetry fit.
|
||||
* \brief Class for handling standard μSR asymmetry fits.
|
||||
*
|
||||
* PRunAsymmetry implements asymmetry fitting for conventional μSR experiments,
|
||||
* where the asymmetry is calculated from forward and backward detector histograms:
|
||||
*
|
||||
* \f[ A(t) = \frac{F(t) - \alpha B(t)}{F(t) + \alpha B(t)} \f]
|
||||
*
|
||||
* The class supports various configurations:
|
||||
* - α and β parameters (detector efficiency corrections)
|
||||
* - Background subtraction (fixed or estimated)
|
||||
* - Bin packing for improved statistics
|
||||
* - Rotating reference frame (RRF) data handling
|
||||
* - Multiple histogram grouping and run adding
|
||||
*
|
||||
* The α/β parameter configurations are:
|
||||
* - Tag 1: α = β = 1 (no corrections)
|
||||
* - Tag 2: α ≠ 1, β = 1 (forward/backward asymmetry correction)
|
||||
* - Tag 3: α = 1, β ≠ 1 (alternative correction)
|
||||
* - Tag 4: α ≠ 1, β ≠ 1 (both corrections active)
|
||||
*
|
||||
* \see PRunBase for the base class providing common functionality
|
||||
* \see PRunAsymmetryBNMR for β-NMR asymmetry (helicity-dependent)
|
||||
* \see PRunSingleHisto for single histogram fits
|
||||
*/
|
||||
class PRunAsymmetry : public PRunBase
|
||||
{
|
||||
public:
|
||||
/// Default constructor
|
||||
PRunAsymmetry();
|
||||
|
||||
/**
|
||||
* \brief Main constructor for μSR asymmetry fitting.
|
||||
* \param msrInfo Pointer to MSR file handler
|
||||
* \param rawData Pointer to raw run data handler
|
||||
* \param runNo Run number within the MSR file
|
||||
* \param tag Operation mode (kFit for fitting, kView for viewing)
|
||||
* \param theoAsData If true, calculate theory only at data points; if false, calculate additional points for Fourier
|
||||
*/
|
||||
PRunAsymmetry(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t runNo, EPMusrHandleTag tag, Bool_t theoAsData);
|
||||
|
||||
/// Destructor
|
||||
virtual ~PRunAsymmetry();
|
||||
|
||||
/**
|
||||
* \brief Calculates chi-square for the current parameter set.
|
||||
* \param par Parameter vector from MINUIT
|
||||
* \return Chi-square value
|
||||
*/
|
||||
virtual Double_t CalcChiSquare(const std::vector<Double_t>& par);
|
||||
|
||||
/**
|
||||
* \brief Calculates expected chi-square (for statistical analysis).
|
||||
* \param par Parameter vector from MINUIT
|
||||
* \return Expected chi-square value
|
||||
*/
|
||||
virtual Double_t CalcChiSquareExpected(const std::vector<Double_t>& par);
|
||||
|
||||
/**
|
||||
* \brief Calculates maximum likelihood estimator.
|
||||
* \param par Parameter vector from MINUIT
|
||||
* \return Maximum likelihood value
|
||||
*/
|
||||
virtual Double_t CalcMaxLikelihood(const std::vector<Double_t>& par);
|
||||
|
||||
/**
|
||||
* \brief Calculates theoretical asymmetry function.
|
||||
*
|
||||
* Computes the theory values for the μSR asymmetry based on the
|
||||
* current parameters and fit function.
|
||||
*/
|
||||
virtual void CalcTheory();
|
||||
|
||||
/**
|
||||
* \brief Returns the number of bins used in the fit.
|
||||
* \return Number of fit bins
|
||||
*/
|
||||
virtual UInt_t GetNoOfFitBins();
|
||||
|
||||
/**
|
||||
* \brief Sets the fit range in bins.
|
||||
* \param fitRange Fit range string (format depends on configuration)
|
||||
*/
|
||||
virtual void SetFitRangeBin(const TString fitRange);
|
||||
|
||||
/**
|
||||
* \brief Returns the first bin used in the fit.
|
||||
* \return Start time bin index
|
||||
*/
|
||||
virtual Int_t GetStartTimeBin() { return fStartTimeBin; }
|
||||
|
||||
/**
|
||||
* \brief Returns the last bin used in the fit.
|
||||
* \return End time bin index
|
||||
*/
|
||||
virtual Int_t GetEndTimeBin() { return fEndTimeBin; }
|
||||
|
||||
/**
|
||||
* \brief Returns the packing factor.
|
||||
* \return Number of bins combined (1 = no packing)
|
||||
*/
|
||||
virtual Int_t GetPacking() { return fPacking; }
|
||||
|
||||
/**
|
||||
* \brief Calculates the number of bins to be fitted.
|
||||
*
|
||||
* Determines fNoOfFitBins based on the fit range and data availability.
|
||||
*/
|
||||
virtual void CalcNoOfFitBins();
|
||||
|
||||
protected:
|
||||
/**
|
||||
* \brief Prepares all data for fitting or viewing.
|
||||
* \return True on success, false on error
|
||||
*
|
||||
* Main data preparation routine that handles background subtraction,
|
||||
* packing, and asymmetry calculation from forward/backward histograms.
|
||||
*/
|
||||
virtual Bool_t PrepareData();
|
||||
|
||||
/**
|
||||
* \brief Prepares data specifically for fitting.
|
||||
* \return True on success, false on error
|
||||
*
|
||||
* Sets up data structures for the fitting process, including determining
|
||||
* fit ranges and calculating the number of fit bins.
|
||||
*/
|
||||
virtual Bool_t PrepareFitData();
|
||||
|
||||
/**
|
||||
* \brief Prepares data for viewing/plotting.
|
||||
* \param runData Pointer to raw run data
|
||||
* \param histoNo Array of histogram numbers [0]=forward, [1]=backward
|
||||
* \return True on success, false on error
|
||||
*/
|
||||
virtual Bool_t PrepareViewData(PRawRunData* runData, UInt_t histoNo[2]);
|
||||
|
||||
/**
|
||||
* \brief Prepares rotating reference frame (RRF) data for viewing.
|
||||
* \param runData Pointer to raw run data
|
||||
* \param histoNo Array of histogram numbers [0]=forward, [1]=backward
|
||||
* \return True on success, false on error
|
||||
*
|
||||
* Special handling for RRF data where asymmetry is calculated in a
|
||||
* rotating coordinate frame.
|
||||
*/
|
||||
virtual Bool_t PrepareRRFViewData(PRawRunData* runData, UInt_t histoNo[2]);
|
||||
|
||||
private:
|
||||
UInt_t fAlphaBetaTag; ///< \f$ 1 \to \alpha = \beta = 1\f$; \f$ 2 \to \alpha \neq 1, \beta = 1\f$; \f$ 3 \to \alpha = 1, \beta \neq 1\f$; \f$ 4 \to \alpha \neq 1, \beta \neq 1\f$.
|
||||
UInt_t fNoOfFitBins; ///< number of bins to be be fitted
|
||||
Int_t fPacking; ///< packing for this particular run. Either given in the RUN- or GLOBAL-block.
|
||||
Bool_t fTheoAsData; ///< true=only calculate the theory points at the data points, false=calculate more points for the theory as compared to data are calculated which lead to 'nicer' Fouriers
|
||||
UInt_t fAlphaBetaTag; ///< Tag indicating α/β configuration: 1=both unity, 2=α free/β unity, 3=α unity/β free, 4=both free
|
||||
UInt_t fNoOfFitBins; ///< Number of bins included in the fit
|
||||
Int_t fPacking; ///< Bin packing factor from RUN or GLOBAL block
|
||||
Bool_t fTheoAsData; ///< If true, theory calculated only at data points; if false, extra points for nicer Fourier transforms
|
||||
|
||||
PDoubleVector fForward; ///< forward histo data
|
||||
PDoubleVector fForwardErr; ///< forward histo errors
|
||||
PDoubleVector fBackward; ///< backward histo data
|
||||
PDoubleVector fBackwardErr; ///< backward histo errors
|
||||
PDoubleVector fForward; ///< Forward detector histogram data
|
||||
PDoubleVector fForwardErr; ///< Forward detector histogram errors
|
||||
PDoubleVector fBackward; ///< Backward detector histogram data
|
||||
PDoubleVector fBackwardErr; ///< Backward detector histogram errors
|
||||
|
||||
Int_t fGoodBins[4]; ///< keep first/last good bins. 0=fgb, 1=lgb (forward); 2=fgb, 3=lgb (backward)
|
||||
Int_t fGoodBins[4]; ///< Good bin boundaries: [0]=forward first, [1]=forward last, [2]=backward first, [3]=backward last
|
||||
|
||||
Int_t fStartTimeBin; ///< bin at which the fit starts
|
||||
Int_t fEndTimeBin; ///< bin at which the fit ends
|
||||
Int_t fStartTimeBin; ///< First bin index for fitting
|
||||
Int_t fEndTimeBin; ///< Last bin index for fitting
|
||||
|
||||
/**
|
||||
* \brief Subtracts fixed background from histograms.
|
||||
*
|
||||
* Subtracts user-specified fixed background values from forward and backward histograms.
|
||||
* Background values are read from the MSR file (e.g., "backgr.fix 2 3" for forward/backward).
|
||||
*
|
||||
* Error propagation:
|
||||
* \f[ \Delta f_i^{\rm c} = \pm\sqrt{(\Delta f_i)^2 + (\Delta \mathrm{bkg})^2} = \pm\sqrt{f_i + \mathrm{bkg}} \f]
|
||||
*
|
||||
* where \f$ f_i^{\rm c} \f$ is the background-corrected histogram, \f$ f_i \f$ is the raw histogram,
|
||||
* and \f$ \mathrm{bkg} \f$ is the fixed background value.
|
||||
*
|
||||
* \return True on success, false if background values are missing
|
||||
*/
|
||||
Bool_t SubtractFixBkg();
|
||||
|
||||
/**
|
||||
* \brief Estimates and subtracts background from histograms.
|
||||
*
|
||||
* Calculates background from a specified bin range (typically before t0) and subtracts it
|
||||
* from forward and backward histograms. The background range is adjusted to align with
|
||||
* accelerator beam cycles when applicable (PSI, RAL, TRIUMF).
|
||||
*
|
||||
* Background calculation:
|
||||
* \f[ \mathrm{bkg} = \frac{1}{N}\sum_{i=0}^N f_i \f]
|
||||
*
|
||||
* Error propagation:
|
||||
* \f[ \Delta f_i^{\rm c} = \pm\sqrt{(\Delta f_i)^2 + (\Delta \mathrm{bkg})^2} = \pm\sqrt{f_i + (\Delta \mathrm{bkg})^2} \f]
|
||||
*
|
||||
* where \f$ N \f$ is the number of background bins and
|
||||
* \f[ \Delta \mathrm{bkg} = \pm\frac{1}{N}\sqrt{\sum_{i=0}^N f_i} \f]
|
||||
*
|
||||
* \return True on success, false if background range is out of bounds
|
||||
*/
|
||||
Bool_t SubtractEstimatedBkg();
|
||||
|
||||
/**
|
||||
* \brief Retrieves proper t0 values for all histograms.
|
||||
*
|
||||
* Determines t0 (time zero) values for forward and backward histograms from:
|
||||
* 1. Individual RUN block t0 entries
|
||||
* 2. GLOBAL block t0 values (fallback)
|
||||
* 3. Data file t0 values (final fallback)
|
||||
*
|
||||
* Also handles addT0 corrections for runs to be added together. The t0 values
|
||||
* are critical for proper alignment of histograms in time.
|
||||
*
|
||||
* \param runData Pointer to raw run data containing histogram information
|
||||
* \param globalBlock Pointer to global MSR block with default t0 values
|
||||
* \param forwardHisto Vector of forward histogram indices
|
||||
* \param backwardHistoNo Vector of backward histogram indices
|
||||
* \return True on success, false if t0 values cannot be determined
|
||||
*/
|
||||
virtual Bool_t GetProperT0(PRawRunData* runData, PMsrGlobalBlock *globalBlock, PUIntVector &forwardHisto, PUIntVector &backwardHistoNo);
|
||||
|
||||
/**
|
||||
* \brief Retrieves proper data range for histograms.
|
||||
*
|
||||
* Determines the "good bins" range for data analysis from:
|
||||
* 1. Individual RUN block data range settings
|
||||
* 2. GLOBAL block data range (fallback)
|
||||
* 3. Full histogram range (final fallback)
|
||||
*
|
||||
* The good bins define which portion of the histograms contains valid data,
|
||||
* excluding noisy or problematic regions at the start/end.
|
||||
*
|
||||
* \param runData Pointer to raw run data
|
||||
* \param histoNo Array of histogram numbers [0]=forward, [1]=backward
|
||||
* \return True on success, false on error
|
||||
*/
|
||||
virtual Bool_t GetProperDataRange(PRawRunData* runData, UInt_t histoNo[2]);
|
||||
|
||||
/**
|
||||
* \brief Determines the proper fit range from global block.
|
||||
*
|
||||
* Extracts fit range settings from the GLOBAL block if not specified in the RUN block.
|
||||
* The fit range defines the time window used for χ² minimization, specified either in
|
||||
* time units (μs) or bin numbers.
|
||||
*
|
||||
* \param globalBlock Pointer to global MSR block containing default fit range
|
||||
*/
|
||||
virtual void GetProperFitRange(PMsrGlobalBlock *globalBlock);
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user