improve doxygen documentation of PRunAsymmetryBNMR.*

src/include/PRunAsymmetryBNMR.h

@@ -35,61 +35,204 @@
 
 //---------------------------------------------------------------------------
 /**
- * <p>Class handling the asymmetry fit.
+ * \brief Class for handling β-NMR asymmetry fits.
+ *
+ * PRunAsymmetryBNMR implements asymmetry fitting for β-NMR (Beta-detected
+ * Nuclear Magnetic Resonance) experiments. Unlike conventional μSR asymmetry,
+ * β-NMR requires handling of helicity-dependent data with separate positive
+ * and negative helicity histograms.
+ *
+ * The asymmetry is calculated from four histograms:
+ * - Forward positive helicity (F+)
+ * - Backward positive helicity (B+)
+ * - Forward negative helicity (F-)
+ * - Backward negative helicity (B-)
+ *
+ * The class supports various α and β parameter configurations:
+ * - Tag 1: α = β = 1 (both fixed to unity)
+ * - Tag 2: α ≠ 1, β = 1 (free α, fixed β)
+ * - Tag 3: α = 1, β ≠ 1 (fixed α, free β)
+ * - Tag 4: α ≠ 1, β ≠ 1 (both free)
+ * - Tag 5: α auto-estimated, β = 1
+ * - Tag 6: α auto-estimated, β ≠ 1
+ *
+ * \see PRunBase for the base class providing common functionality
+ * \see PRunAsymmetry for the standard μSR asymmetry implementation
  */
 class PRunAsymmetryBNMR : public PRunBase
 {
   public:
+    /// Default constructor
     PRunAsymmetryBNMR();
+
+    /**
+     * \brief Main constructor for β-NMR 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
+     */
     PRunAsymmetryBNMR(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t runNo, EPMusrHandleTag tag, Bool_t theoAsData);
+
+    /// Destructor
     virtual ~PRunAsymmetryBNMR();
 
+    /**
+     * \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 β-NMR 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 the four helicity 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]);
 
   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, 5=α estimated/β unity, 6=α estimated/β 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 fForwardp;     ///< pos hel forward histo data
-    PDoubleVector fForwardpErr;  ///< pos hel forward histo errors
-    PDoubleVector fBackwardp;    ///< pos hel backward histo data
-    PDoubleVector fBackwardpErr; ///< pos hel backward histo errors
-    PDoubleVector fForwardm;     ///< neg hel forward histo data
-    PDoubleVector fForwardmErr;  ///< neg hel forward histo errors
-    PDoubleVector fBackwardm;    ///< neg hel backward histo data
-    PDoubleVector fBackwardmErr; ///< neg hel backward histo errors
+    PDoubleVector fForwardp;     ///< Positive helicity forward histogram data
+    PDoubleVector fForwardpErr;  ///< Positive helicity forward histogram errors
+    PDoubleVector fBackwardp;    ///< Positive helicity backward histogram data
+    PDoubleVector fBackwardpErr; ///< Positive helicity backward histogram errors
+    PDoubleVector fForwardm;     ///< Negative helicity forward histogram data
+    PDoubleVector fForwardmErr;  ///< Negative helicity forward histogram errors
+    PDoubleVector fBackwardm;    ///< Negative helicity backward histogram data
+    PDoubleVector fBackwardmErr; ///< Negative helicity backward 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.
+     * \return True on success, false on error
+     */
     Bool_t SubtractFixBkg();
+
+    /**
+     * \brief Estimates and subtracts background from histograms.
+     * \return True on success, false on error
+     */
     Bool_t SubtractEstimatedBkg();
 
+    /**
+     * \brief Retrieves proper t0 values for all histograms.
+     * \param runData Pointer to raw run data
+     * \param globalBlock Pointer to global MSR block
+     * \param forwardHisto Vector of forward histogram indices
+     * \param backwardHistoNo Vector of backward histogram indices
+     * \return True on success, false on error
+     */
     virtual Bool_t GetProperT0(PRawRunData* runData, PMsrGlobalBlock *globalBlock, PUIntVector &forwardHisto, PUIntVector &backwardHistoNo);
+
+    /**
+     * \brief Retrieves proper data range for histograms.
+     * \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.
+     * \param globalBlock Pointer to global MSR block
+     */
     virtual void GetProperFitRange(PMsrGlobalBlock *globalBlock);
+
+    /**
+     * \brief Estimates α parameter from data.
+     * \return Estimated α value
+     *
+     * Calculates α based on the asymmetry ratio of forward and backward histograms.
+     */
     virtual Double_t EstimateAlpha();
 };