use Claude ai to generate doxygen documentation.

src/include/PRunBase.h

@@ -42,53 +42,166 @@
 
 //------------------------------------------------------------------------------------------
 /**
- * <p>The run base class is enforcing a common interface to all supported fit-types.
+ * <p>Abstract base class defining the interface for all μSR fit types.
+ *
+ * <p>PRunBase establishes a common API for processing and fitting different
+ * types of μSR data (single histogram, asymmetry, RRF, etc.). Derived classes
+ * implement specific data processing and χ² calculation for each fit type:
+ * - <b>PRunSingleHisto:</b> Single detector histogram fits
+ * - <b>PRunAsymmetry:</b> Asymmetry fits (forward - backward)
+ * - <b>PRunSingleHistoRRF:</b> Single histogram in rotating reference frame
+ * - <b>PRunAsymmetryRRF:</b> Asymmetry in rotating reference frame
+ * - <b>PRunMuMinus:</b> Negative muon fits
+ * - <b>PRunNonMusr:</b> General x-y data fits
+ *
+ * <p><b>Key responsibilities:</b>
+ * - Loading and preprocessing raw histogram data
+ * - Background subtraction and normalization
+ * - Time bin packing/rebinning
+ * - Theory evaluation at data points
+ * - χ² or maximum likelihood calculation
+ * - RRF transformations (if applicable)
+ *
+ * <p><b>Processing workflow:</b>
+ * 1. <tt>PrepareData()</tt> - Load and preprocess raw data
+ * 2. <tt>CalcTheory()</tt> - Evaluate theory function
+ * 3. <tt>CalcChiSquare()</tt> or <tt>CalcMaxLikelihood()</tt> - Compute fit metric
+ *
+ * <p><b>Design pattern:</b> Template Method - base class defines workflow,
+ * derived classes implement fit-type-specific algorithms.
  */
 class PRunBase
 {
   public:
+    /// Default constructor
     PRunBase();
+
+    /**
+     * <p>Constructor initializing run from MSR file and raw data.
+     *
+     * @param msrInfo Pointer to MSR file handler
+     * @param rawData Pointer to raw data handler
+     * @param runNo Run number (0-based index in MSR file)
+     * @param tag Operation mode (kFit, kView)
+     */
     PRunBase(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t runNo, EPMusrHandleTag tag);
+
     virtual ~PRunBase();
 
-    virtual Double_t CalcChiSquare(const std::vector<Double_t>& par) = 0; ///< pure virtual, i.e. needs to be implemented by the deriving class!!
-    virtual Double_t CalcMaxLikelihood(const std::vector<Double_t>& par) = 0; ///< pure virtual, i.e. needs to be implemented by the deriving class!!
+    /**
+     * <p>Calculates χ² between data and theory (pure virtual).
+     *
+     * <p>χ² = Σ[(data_i - theory_i)² / σ_i²] summed over all data points.
+     * This is the standard least-squares metric for fitting.
+     *
+     * @param par Vector of fit parameter values
+     * @return Chi-squared value
+     */
+    virtual Double_t CalcChiSquare(const std::vector<Double_t>& par) = 0;
+
+    /**
+     * <p>Calculates maximum likelihood (pure virtual).
+     *
+     * <p>For Poisson statistics: -2ln(L) = 2Σ[theory_i - data_i·ln(theory_i)]
+     * Better than χ² for low-count data where Gaussian approximation fails.
+     *
+     * @param par Vector of fit parameter values
+     * @return Negative 2 times log-likelihood
+     */
+    virtual Double_t CalcMaxLikelihood(const std::vector<Double_t>& par) = 0;
+
+    /**
+     * <p>Sets the fit time range for this run.
+     *
+     * <p>Updates the fitting window, useful for FIT_RANGE command which
+     * scans different time windows to find the optimal range.
+     *
+     * @param fitRange Vector of (start, end) time pairs in microseconds
+     */
     virtual void SetFitRange(PDoublePairVector fitRange);
 
-    virtual void CalcTheory() = 0; ///< pure virtual, i.e. needs to be implemented by the deriving class!!
+    /**
+     * <p>Evaluates theory function at all data points (pure virtual).
+     *
+     * <p>Uses current parameter values to calculate expected signal
+     * at each time point. Called during each fit iteration.
+     */
+    virtual void CalcTheory() = 0;
 
-    virtual UInt_t GetRunNo() { return fRunNo; } ///< returns the number of runs of the msr-file
-    virtual PRunData* GetData() { return &fData; } ///< returns the data to be fitted
+    /// Returns the run number (0-based index in MSR file)
+    /// @return Run number
+    virtual UInt_t GetRunNo() { return fRunNo; }
+
+    /// Returns pointer to processed data (background-corrected, binned)
+    /// @return Pointer to PRunData object
+    virtual PRunData* GetData() { return &fData; }
+
+    /// Cleans up internal data structures
     virtual void CleanUp();
-    virtual Bool_t IsValid() { return fValid; } ///< returns if the state is valid
+
+    /// Returns validity status of this run object
+    /// @return true if run initialized successfully
+    virtual Bool_t IsValid() { return fValid; }
 
   protected:
-    Bool_t fValid; ///< flag showing if the state of the class is valid
+    Bool_t fValid; ///< Flag showing if the run object initialized successfully
 
-    EPMusrHandleTag fHandleTag; ///< tag telling whether this is used for fit, view, ...
+    EPMusrHandleTag fHandleTag; ///< Operation mode: kFit (fitting), kView (display only)
 
-    Int_t fRunNo;               ///< number of the run within the msr-file
-    PMsrHandler      *fMsrInfo; ///< msr-file handler
-    PMsrRunBlock     *fRunInfo; ///< run info used to filter out needed infos of a run
-    PRunDataHandler  *fRawData; ///< holds the raw run data
+    Int_t fRunNo;               ///< Run number (0-based index in MSR file RUN blocks)
+    PMsrHandler      *fMsrInfo; ///< Pointer to MSR file handler
+    PMsrRunBlock     *fRunInfo; ///< Pointer to this run's RUN block settings
+    PRunDataHandler  *fRawData; ///< Pointer to raw data handler for this run
 
-    PRunData fData;             ///< data to be fitted, viewed, i.e. binned data
-    Double_t fTimeResolution;   ///< time resolution in (us)
-    PMetaData fMetaData;        ///< keeps the meta data from the data file like field, temperature, energy, ...
-    PDoubleVector fT0s;         ///< all t0 bins of a run! The derived classes will handle it.
-    std::vector<PDoubleVector> fAddT0s; ///< all t0 bins of all addrun's of a run! The derived classes will handle it.
+    PRunData fData;             ///< Processed data ready for fitting (background-corrected, packed, etc.)
+    Double_t fTimeResolution;   ///< Time resolution of raw data in microseconds (μs)
+    PMetaData fMetaData;        ///< Experimental metadata (field, temperature, energy) from data file
+    PDoubleVector fT0s;         ///< Time-zero bins for all histograms in this run
+    std::vector<PDoubleVector> fAddT0s; ///< Time-zero bins for all addrun histograms
 
-    Double_t fFitStartTime;     ///< fit start time
-    Double_t fFitEndTime;       ///< fit end time
+    Double_t fFitStartTime;     ///< Fit range start time in microseconds (μs)
+    Double_t fFitEndTime;       ///< Fit range end time in microseconds (μs)
 
-    PDoubleVector fFuncValues;  ///< is keeping the values of the functions from the FUNCTIONS block
-    std::unique_ptr<PTheory> fTheory; ///< theory needed to calculate chi-square
+    PDoubleVector fFuncValues;  ///< Values of user-defined functions from FUNCTIONS block
+    std::unique_ptr<PTheory> fTheory; ///< Theory function evaluator for χ² calculation
 
-    PDoubleVector fKaiserFilter; ///< stores the Kaiser filter vector (needed for the RRF).
+    PDoubleVector fKaiserFilter; ///< Kaiser window coefficients for RRF filtering
 
-    virtual Bool_t PrepareData() = 0; ///< pure virtual, i.e. needs to be implemented by the deriving class!!
+    /**
+     * <p>Prepares raw data for fitting (pure virtual).
+     *
+     * <p>Performs fit-type-specific preprocessing:
+     * - Background subtraction
+     * - Asymmetry calculation (if applicable)
+     * - Time bin packing/rebinning
+     * - RRF transformation (if applicable)
+     * - Error propagation
+     *
+     * <p>Called during initialization before fitting begins.
+     *
+     * @return true on success, false on error
+     */
+    virtual Bool_t PrepareData() = 0;
 
+    /**
+     * <p>Calculates Kaiser window filter coefficients for RRF.
+     *
+     * <p>The Kaiser window reduces spectral leakage when transforming
+     * to the rotating reference frame. Parameters control the trade-off
+     * between main lobe width and side lobe suppression.
+     *
+     * @param wc Cutoff frequency (normalized, 0 to π)
+     * @param A Attenuation in dB (controls side lobe level)
+     * @param dw Transition width (normalized)
+     */
     virtual void CalculateKaiserFilterCoeff(Double_t wc, Double_t A, Double_t dw);
+
+    /**
+     * <p>Applies Kaiser filter to theory values for RRF.
+     *
+     * <p>Filters the theory function in the same way data is filtered,
+     * ensuring consistent comparison between data and theory in RRF fits.
+     */
     virtual void FilterTheo();
 };