Constructor + * \brief Default constructor that initializes all member variables. + * + * Sets all counters and indices to default/invalid values. This constructor + * creates an invalid instance that requires proper initialization via the + * main constructor. */ PRunAsymmetryRRF::PRunAsymmetryRRF() : PRunBase() { @@ -69,12 +73,30 @@ PRunAsymmetryRRF::PRunAsymmetryRRF() : PRunBase() // Constructor //-------------------------------------------------------------------------- /** - *
Constructor + * \brief Main constructor that initializes RRF asymmetry fitting. * - * \param msrInfo pointer to the msr-file handler - * \param rawData raw run data - * \param runNo number of the run within the msr-file - * \param tag tag showing what shall be done: kFit == fitting, kView == viewing + * Performs comprehensive initialization for rotating reference frame analysis: + * 1. Validates RRF packing parameter from GLOBAL block (required for RRF) + * 2. Validates α parameter (required for asymmetry) + * 3. Validates β parameter (optional, defaults to 1) + * 4. Determines α/β configuration tag (1-4) + * 5. Calls PrepareData() to load and process histogram data with RRF transformation + * + * The α/β tag determines the asymmetry calculation method: + * - Tag 1: α=1, β=1 (no corrections) + * - Tag 2: α≠1, β=1 (forward/backward correction) + * - Tag 3: α=1, β≠1 (alternative correction) + * - Tag 4: α≠1, β≠1 (both corrections) + * + * RRF packing must be specified in the GLOBAL block (e.g., "rrf_packing 50"). + * This parameter controls the rebinning after RRF transformation and is essential + * for proper signal extraction in the rotating frame. + * + * \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 or kView) + * \param theoAsData If true, calculate theory only at data points */ PRunAsymmetryRRF::PRunAsymmetryRRF(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t runNo, EPMusrHandleTag tag, Bool_t theoAsData) : PRunBase(msrInfo, rawData, runNo, tag), fTheoAsData(theoAsData) @@ -153,7 +175,10 @@ PRunAsymmetryRRF::PRunAsymmetryRRF(PMsrHandler *msrInfo, PRunDataHandler *rawDat // Destructor //-------------------------------------------------------------------------- /** - *
Destructor. + * \brief Destructor that cleans up histogram data. + * + * Clears all four histogram vectors (forward/backward × data/errors) + * to free memory. */ PRunAsymmetryRRF::~PRunAsymmetryRRF() { @@ -167,12 +192,24 @@ PRunAsymmetryRRF::~PRunAsymmetryRRF() // CalcChiSquare (public) //-------------------------------------------------------------------------- /** - *
Calculate chi-square.
+ * \brief Calculates chi-square for RRF asymmetry fit.
*
- * return:
- * - chisq value
+ * Computes χ² by comparing the measured RRF-transformed asymmetry with theory:
+ * χ² = Σ[(A_RRF,data - A_RRF,theory)²/σ²]
*
- * \param par parameter vector iterated by minuit2
+ * The RRF asymmetry has already been calculated in PrepareData() by applying
+ * the transformation: A_RRF(t) = A(t) · 2cos(ω_RRF·t + φ_RRF)
+ *
+ * The theory function is similarly transformed and includes α/β corrections:
+ * - Tag 1 (α=β=1): A = f(t)
+ * - Tag 2 (α≠1, β=1): A = [f(t)(α+1) - (α-1)] / [(α+1) - f(t)(α-1)]
+ * - Tag 3 (α=1, β≠1): Uses β correction
+ * - Tag 4 (α≠1, β≠1): Uses both α and β corrections
+ *
+ * Supports OpenMP parallelization for faster calculation.
+ *
+ * \param par Parameter vector from MINUIT minimizer
+ * \return Chi-square value
*/
Double_t PRunAsymmetryRRF::CalcChiSquare(const std::vector Calculate expected chi-square. Currently not implemented since not clear what to be done.
+ * \brief Calculates expected chi-square value.
*
- * return:
- * - chisq value == 0.0
+ * This function is currently not implemented for RRF asymmetry fits because the expected
+ * chi-square calculation for RRF-transformed asymmetry data requires a complex statistical
+ * treatment. The RRF transformation introduces correlations between adjacent bins that
+ * complicate the expected value calculation.
*
- * \param par parameter vector iterated by minuit2
+ * \param par Parameter vector from MINUIT minimizer
+ * \return Always returns 0.0 (placeholder value)
+ *
+ * \todo Implement proper expected chi-square calculation for RRF asymmetry fits
*/
Double_t PRunAsymmetryRRF::CalcChiSquareExpected(const std::vector NOT IMPLEMENTED!!
+ * \brief Calculates maximum likelihood estimator for RRF asymmetry fit.
*
- * \param par parameter vector iterated by minuit2
+ * Maximum likelihood estimation provides an alternative to χ² minimization and can be
+ * more appropriate for low-count data. However, the proper likelihood function for
+ * RRF-transformed μSR asymmetry data is complex and not yet implemented.
+ *
+ * \param par Parameter vector from MINUIT minimizer
+ * \return Placeholder value of 1.0
+ *
+ * \todo Implement proper Poisson-based maximum likelihood for RRF asymmetry fits
*/
Double_t PRunAsymmetryRRF::CalcMaxLikelihood(const std::vector Calculate the number of fitted bins for the current fit range.
+ * \brief Returns the number of bins included in the RRF fit.
*
- * return: number of fitted bins.
+ * Calculates and returns the number of RRF-transformed data bins that fall within
+ * the current fit range. This value is used for determining degrees of freedom and
+ * is recalculated when the fit range changes (e.g., via COMMAND block).
+ *
+ * \return Number of data bins included in the fit
*/
UInt_t PRunAsymmetryRRF::GetNoOfFitBins()
{
@@ -315,15 +368,28 @@ UInt_t PRunAsymmetryRRF::GetNoOfFitBins()
// SetFitRangeBin (public)
//--------------------------------------------------------------------------
/**
- * 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.
+ * \brief Dynamically changes the fit range in bin units for RRF data.
*
- * nXY are offsets which can be used to shift, limit the fit range.
+ * Allows modification of the fit range at runtime, typically called from the COMMAND block.
+ * Supports bin-based fit ranges with optional offsets for fine-tuning.
*
- * \param fitRange string containing the necessary information.
+ * Syntax formats:
+ * - Single range: FIT_RANGE fgb[+n0] lgb[-n1]
+ * - Applied to all RUN blocks
+ * - Multiple ranges: FIT_RANGE fgb[+n00] lgb[-n01] fgb[+n10] lgb[-n11] ... fgb[+nN0] lgb[-nN1]
+ * - One pair per RUN block (N must equal number of RUN blocks)
+ *
+ * Parameters:
+ * - fgb: First good bin (start of fit range)
+ * - lgb: Last good bin (end of fit range)
+ * - +n: Positive offset to shift start forward
+ * - -n: Negative offset to shift end backward
+ *
+ * Example: "FIT_RANGE 10+5 200-10" uses bins [15, 190] for fitting
+ *
+ * Note: The bins refer to the RRF-packed data, not the original histograms.
+ *
+ * \param fitRange String containing fit range specification
*/
void PRunAsymmetryRRF::SetFitRangeBin(const TString fitRange)
{
@@ -405,7 +471,16 @@ void PRunAsymmetryRRF::SetFitRangeBin(const TString fitRange)
// CalcNoOfFitBins (public)
//--------------------------------------------------------------------------
/**
- * Calculate the number of fitted bins for the current fit range.
+ * \brief Calculates the number of bins included in the current RRF fit range.
+ *
+ * Determines fStartTimeBin and fEndTimeBin from the fit time range (fFitStartTime, fFitEndTime)
+ * and RRF-transformed data time grid. Ensures that bin indices remain within valid bounds.
+ * The result is stored in fNoOfFitBins.
+ *
+ * This calculation accounts for:
+ * - RRF-packed data time step and start time
+ * - Rounding effects (ceiling for start, floor for end)
+ * - Boundary conditions (clips to [0, RRF data size])
*/
void PRunAsymmetryRRF::CalcNoOfFitBins()
{
@@ -427,7 +502,24 @@ void PRunAsymmetryRRF::CalcNoOfFitBins()
// CalcTheory (protected)
//--------------------------------------------------------------------------
/**
- * Calculate theory for a given set of fit-parameters.
+ * \brief Calculates theoretical RRF asymmetry values for the current parameters.
+ *
+ * Computes the expected RRF asymmetry A_RRF(t) for all data points based on the current
+ * parameter values and the user-defined theory function. The calculation depends
+ * on the α/β correction mode:
+ *
+ * - Tag 1 (α=1, β=1): A(t) = f(t)
+ * - Tag 2 (α≠1, β=1): A(t) = [f(t)(α+1) - (α-1)] / [(α+1) - f(t)(α-1)]
+ * - Tag 3 (α=1, β≠1): A(t) = f(t)(β+1) / [2 - f(t)(β-1)]
+ * - Tag 4 (α≠1, β≠1): A(t) = [f(t)(αβ+1) - (α-1)] / [(α+1) - f(t)(αβ-1)]
+ *
+ * where f(t) is the raw theory function from the THEORY block.
+ *
+ * Note: The RRF transformation is applied during data preparation (PrepareViewData),
+ * not here. This function calculates the standard asymmetry theory which is then
+ * transformed to the rotating frame during visualization.
+ *
+ * The calculated values are stored in fData for plotting and comparison with measured RRF data.
*/
void PRunAsymmetryRRF::CalcTheory()
{
@@ -511,23 +603,33 @@ void PRunAsymmetryRRF::CalcTheory()
// PrepareData (protected)
//--------------------------------------------------------------------------
/**
- * Prepare data for fitting or viewing. What is already processed at this stage:
- * - get all needed forward/backward histograms
- * - get time resolution
- * - get start/stop fit time
- * - 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)
- * - subtract background
+ * \brief Main data preparation routine for RRF asymmetry fitting and viewing.
*
- * Error propagation for \f$ A_i = (f_i^{\rm c}-b_i^{\rm c})/(f_i^{\rm c}+b_i^{\rm c})\f$:
- * \f[ \Delta A_i = \pm\frac{2}{(f_i^{\rm c}+b_i^{\rm c})^2}\left[
- * (b_i^{\rm c})^2 (\Delta f_i^{\rm c})^2 +
- * (\Delta b_i^{\rm c})^2 (f_i^{\rm c})^2\right]^{1/2}\f]
+ * Performs comprehensive data preparation specifically for rotating reference frame analysis:
+ * - Loading forward/backward histograms from data files
+ * - Extracting metadata (field, energy, temperature)
+ * - Determining time resolution from data file
+ * - Validating and retrieving t0 values for all histograms
+ * - Adding multiple runs together (if addruns are specified)
+ * - Grouping multiple histograms (if grouping is specified)
+ * - Subtracting background (fixed or estimated)
+ * - Calculating standard asymmetry and error bars
+ * - NOTE: RRF transformation is NOT applied here (it's done in PrepareFitData/PrepareViewData)
*
- * return:
- * - true if everthing went smooth
- * - false, otherwise.
+ * The standard asymmetry is calculated as:
+ * \f[ A_i = \frac{f_i^{\rm c} - b_i^{\rm c}}{f_i^{\rm c} + b_i^{\rm c}} \f]
+ *
+ * Error propagation (assuming Poisson statistics):
+ * \f[ \Delta A_i = \pm\frac{2}{(f_i^{\rm c}+b_i^{\rm c})^2}\sqrt{
+ * (b_i^{\rm c})^2 (\Delta f_i^{\rm c})^2 +
+ * (f_i^{\rm c})^2 (\Delta b_i^{\rm c})^2} \f]
+ *
+ * where \f$ f_i^{\rm c} \f$ and \f$ b_i^{\rm c} \f$ are background-corrected forward and
+ * backward histograms, respectively.
+ *
+ * The RRF transformation and packing are applied later in PrepareFitData() or PrepareViewData().
+ *
+ * \return True if data preparation succeeds, false on any error
*/
Bool_t PRunAsymmetryRRF::PrepareData()
{
@@ -899,8 +1001,25 @@ Bool_t PRunAsymmetryRRF::SubtractEstimatedBkg()
// PrepareFitData (protected)
//--------------------------------------------------------------------------
/**
- * Take the pre-processed data (i.e. grouping and addrun are preformed, background correction already carried out)
- * and form the asymmetry for fitting.
+ * \brief Processes pre-grouped data and calculates RRF asymmetry for fitting.
+ *
+ * Takes forward/backward histograms (after grouping, addrun, and background correction) and
+ * performs the RRF transformation for fitting:
+ *
+ * 1. Aligns forward/backward histograms (ensures 'first good bin - t0' is identical)
+ * 2. Calculates standard asymmetry: \f$ A_i = (f_i^{\rm c}-b_i^{\rm c})/(f_i^{\rm c}+b_i^{\rm c}) \f$
+ * 3. Applies RRF transformation: \f$ A_{\rm RRF}(t) = A(t) \cdot 2\cos(\omega_{\rm RRF} t + \phi_{\rm RRF}) \f$
+ * 4. Applies RRF packing (rebinning) to reduce noise after mixing
+ * 5. Propagates errors through both transformations
+ *
+ * Error propagation for asymmetry:
+ * \f[ \delta A_i = \frac{2}{(f_i^{\rm c}+b_i^{\rm c})^2}\sqrt{(b_i^{\rm c})^2 (\delta f_i^{\rm c})^2 + (f_i^{\rm c})^2 (\delta b_i^{\rm c})^2} \f]
+ *
+ * RRF packing averages multiple bins to improve statistics after frequency mixing:
+ * - Packed value: sum of bins / packing factor
+ * - Error: \f$ \sigma_{\rm packed} = \sqrt{\sum \sigma_i^2}/N_{\rm pack} \f$
+ *
+ * \return True on success, false if data preparation fails
*/
Bool_t PRunAsymmetryRRF::PrepareFitData()
{
@@ -1015,20 +1134,29 @@ Bool_t PRunAsymmetryRRF::PrepareFitData()
// PrepareViewData (protected)
//--------------------------------------------------------------------------
/**
- * Take the pre-processed data (i.e. grouping and addrun are preformed) and form the asymmetry for view representation.
- * Before forming the asymmetry, the following checks will be performed:
- * -# check if view packing is whished.
- * -# check if data range is given, if not try to estimate one.
- * -# check that data range is present, that it makes any sense.
- * -# check that 'first good bin'-'t0' is the same for forward and backward histogram. If not adjust it.
- * -# pack data (rebin).
- * -# if packed forward size != backward size, truncate the longer one such that an asymmetry can be formed.
- * -# calculate the asymmetry: \f$ A_i = (\alpha f_i^c-b_i^c)/(\alpha \beta f_i^c+b_i^c) \f$
- * -# calculate the asymmetry errors: \f$ \delta A_i = 2 \sqrt{(b_i^c)^2 (\delta f_i^c)^2 + (\delta b_i^c)^2 (f_i^c)^2}/(f_i^c+b_i^c)^2\f$
- * -# calculate the theory vector.
+ * \brief Prepares RRF asymmetry data for plotting and visualization.
*
- * \param runData raw run data needed to perform some crosschecks
- * \param histoNo histogram number (within a run). histoNo[0]: forward histogram number, histNo[1]: backward histogram number
+ * Processes pre-grouped data for display in plots with RRF transformation and
+ * special handling for visualization. Similar to PrepareFitData but includes
+ * theory calculation with Kaiser FIR filtering for smooth RRF curves.
+ *
+ * Processing steps:
+ * 1. Validates and estimates data range if needed
+ * 2. Aligns forward/backward histogram start bins relative to t0
+ * 3. Ensures equal bin counts between forward/backward
+ * 4. Calculates standard asymmetry: \f$ A_i = (\alpha f_i^{\rm c} - b_i^{\rm c})/(\alpha \beta f_i^{\rm c} + b_i^{\rm c}) \f$
+ * 5. Applies RRF transformation: \f$ A_{\rm RRF}(t) = A(t) \cdot 2\cos(\omega_{\rm RRF} t + \phi_{\rm RRF}) \f$
+ * 6. Applies RRF packing for visualization
+ * 7. Propagates errors: \f$ \delta A_i = \frac{2}{(f_i^{\rm c}+b_i^{\rm c})^2}\sqrt{(b_i^{\rm c})^2 (\delta f_i^{\rm c})^2 + (f_i^{\rm c})^2 (\delta b_i^{\rm c})^2} \f$
+ * 8. Calculates theory curve at high resolution
+ * 9. Applies RRF transformation to theory
+ * 10. Applies Kaiser FIR filter to smooth theory curve
+ *
+ * The RRF frequency and phase are read from the PLOT block settings.
+ *
+ * \param runData Pointer to raw run data for validation and cross-checks
+ * \param histoNo Array of histogram indices: [0]=forward, [1]=backward
+ * \return True on success, false on error
*/
Bool_t PRunAsymmetryRRF::PrepareViewData(PRawRunData* runData, UInt_t histoNo[2])
{
diff --git a/src/include/PRunAsymmetryRRF.h b/src/include/PRunAsymmetryRRF.h
index 8eaa02a96..075d79ed1 100644
--- a/src/include/PRunAsymmetryRRF.h
+++ b/src/include/PRunAsymmetryRRF.h
@@ -34,55 +34,216 @@
//---------------------------------------------------------------------------
/**
- * Class handling the asymmetry fit.
+ * \brief Class for handling μSR asymmetry fits in the Rotating Reference Frame (RRF).
+ *
+ * PRunAsymmetryRRF extends PRunBase to handle asymmetry fitting where data is transformed
+ * into a rotating reference frame. This technique is particularly useful for analyzing
+ * high-frequency oscillations in μSR spectra by mixing the signal with a reference frequency.
+ *
+ * The RRF transformation:
+ * \f[ A_{\rm RRF}(t) = A(t) \cdot 2\cos(\omega_{\rm RRF} t + \phi_{\rm RRF}) \f]
+ *
+ * where:
+ * - \f$ A(t) \f$ is the standard asymmetry: \f$ A(t) = \frac{F(t) - \alpha B(t)}{F(t) + \alpha B(t)} \f$
+ * - \f$ \omega_{\rm RRF} \f$ is the RRF frequency (specified in PLOT block)
+ * - \f$ \phi_{\rm RRF} \f$ is the RRF phase (specified in PLOT block)
+ *
+ * Key features:
+ * - Transforms high-frequency oscillations to lower frequencies
+ * - Requires special RRF packing parameter from GLOBAL block
+ * - Supports α/β correction parameters (same as PRunAsymmetry)
+ * - Applies Kaiser FIR filtering to theory curves for smooth visualization
+ *
+ * The RRF technique is essential for:
+ * - High transverse field (TF) measurements
+ * - Analyzing fast precession frequencies
+ * - Improving signal-to-noise in specific frequency ranges
+ *
+ * \see PRunAsymmetry for standard (non-RRF) asymmetry fitting
+ * \see PRunBase for the base class providing common functionality
*/
class PRunAsymmetryRRF : public PRunBase
{
public:
+ /// Default constructor
PRunAsymmetryRRF();
+
+ /**
+ * \brief Main constructor for RRF 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
+ */
PRunAsymmetryRRF(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t runNo, EPMusrHandleTag tag, Bool_t theoAsData);
+
+ /// Destructor
virtual ~PRunAsymmetryRRF();
+ /**
+ * \brief Calculates chi-square for the RRF asymmetry fit.
+ * \param par Parameter vector from MINUIT
+ * \return Chi-square value
+ */
virtual Double_t CalcChiSquare(const std::vector