improve the doxygen docu of PRunNonMusr.*

src/classes/PRunNonMusr.cpp

@@ -35,7 +35,21 @@
 // Constructor
 //--------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * \brief Default constructor creating an empty, invalid non-μSR run object.
+ *
+ * Initializes all member variables to default/safe values:
+ * - fNoOfFitBins = 0 (no bins to fit)
+ * - fPacking = 1 (no data averaging)
+ * - fStartTimeBin = 0 (first data point)
+ * - fEndTimeBin = 0 (no range)
+ * - fHandleTag = kEmpty (uninitialized)
+ * - fRawRunData = nullptr (no data loaded)
+ *
+ * This constructor is needed for creating vectors of PRunNonMusr objects.
+ * The resulting object cannot be used until properly initialized via the
+ * main constructor.
+ *
+ * \see PRunNonMusr(PMsrHandler*, PRunDataHandler*, UInt_t, EPMusrHandleTag, Bool_t)
  */
 PRunNonMusr::PRunNonMusr() : PRunBase()
 {
@@ -53,12 +67,48 @@ PRunNonMusr::PRunNonMusr() : PRunBase()
 // Constructor
 //--------------------------------------------------------------------------
 /**
- * <p>Constructor
+ * \brief Main constructor initializing a non-μSR run from MSR file and x-y data.
  *
- * \param msrInfo pointer to the msr-file handler
+ * Performs comprehensive initialization for general curve fitting:
- * \param rawData raw run data
+ *
- * \param runNo number of the run within the msr-file
+ * 1. <b>Base Class Initialization:</b>
- * \param tag tag showing what shall be done: kFit == fitting, kView == viewing
+ *    - Calls PRunBase constructor with MSR/data handlers
+ *    - Initializes theory engine and parameter mappings
+ *    - Sets up FUNCTIONS block evaluation
+ *
+ * 2. <b>Raw Data Loading:</b>
+ *    - Retrieves raw x-y data using run name from MSR file
+ *    - Calls fRawData->GetRunData(*runName)
+ *    - Validates data was successfully loaded
+ *    - If loading fails → marks run invalid, prints error
+ *
+ * 3. <b>Data Preparation:</b>
+ *    - Calls PrepareData() to process x-y data
+ *    - Extracts x-y columns based on MSR file specification
+ *    - Applies packing to average data points
+ *    - Sets up fit range boundaries
+ *    - If preparation fails → marks run invalid
+ *
+ * The object is marked as invalid (fValid=false) if:
+ * - Raw data file cannot be loaded (file not found, wrong format, etc.)
+ * - PrepareData() fails (invalid column indices, missing packing, etc.)
+ *
+ * Key features for non-μSR:
+ * - No histogram processing (data is already x-y pairs)
+ * - No time-zero determination (not time-differential)
+ * - No background subtraction (included in y-data)
+ * - No asymmetry calculation (direct y vs. x fitting)
+ *
+ * \param msrInfo Pointer to MSR file handler (must remain valid for object lifetime)
+ * \param rawData Pointer to raw data handler for loading data files
+ * \param runNo Run number (0-based index in MSR file RUN blocks)
+ * \param tag Operation mode: kFit (fitting), kView (display/plotting)
+ * \param theoAsData Theory mode: true = at data x-values, false = high-resolution (minimal effect for non-μSR)
+ *
+ * \warning Always check IsValid() after construction before using for fitting
+ *
+ * \see PrepareData() for data processing details
+ * \see PRunBase constructor for base class initialization
  */
 PRunNonMusr::PRunNonMusr(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t runNo, EPMusrHandleTag tag, Bool_t theoAsData) :
   PRunBase(msrInfo, rawData, runNo, tag), fTheoAsData(theoAsData)
@@ -80,7 +130,15 @@ PRunNonMusr::PRunNonMusr(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t
 // Destructor
 //--------------------------------------------------------------------------
 /**
- * <p>Destructor
+ * \brief Destructor (no cleanup needed for non-μSR).
+ *
+ * The fRawRunData pointer is not owned by this class and is not deleted here.
+ * It is managed by the PRunDataHandler and will be cleaned up externally.
+ *
+ * Base class destructor (PRunBase) handles cleanup of:
+ * - Theory engine objects
+ * - Parameter mapping structures
+ * - Function value caches
  */
 PRunNonMusr::~PRunNonMusr()
 {
@@ -90,12 +148,43 @@ PRunNonMusr::~PRunNonMusr()
 // CalcChiSquare
 //--------------------------------------------------------------------------
 /**
- * <p>Calculate chi-square.
+ * \brief Calculates χ² between non-μSR x-y data and theory.
  *
- * <b>return:</b>
+ * Computes the chi-squared statistic for general x-y data:
- * - chisq value
+ * \f[ \chi^2 = \sum_{i={\rm start}}^{\rm end} \frac{(y_i - f(x_i))^2}{\sigma_i^2} \f]
  *
- * \param par parameter vector iterated by minuit2
+ * where:
+ * - x_i is the independent variable (arbitrary units)
+ * - y_i is the measured dependent variable
+ * - f(x_i) is the theory function evaluated at x_i
+ * - σ_i is the error on y_i (from data file)
+ *
+ * Algorithm:
+ * 1. <b>Evaluate FUNCTIONS block:</b>
+ *    - Loop over user-defined functions
+ *    - Compute function values using current parameters
+ *    - Store in fFuncValues for use by theory
+ *
+ * 2. <b>Calculate χ² sum:</b>
+ *    - Loop from fStartTimeBin to fEndTimeBin (inclusive)
+ *    - For each data point i:
+ *      a. Get x-value: x = fData.GetX()->at(i)
+ *      b. Evaluate theory at x: theo = fTheory->Func(x, par, fFuncValues)
+ *      c. Get data and error: y = fData.GetValue()->at(i), σ = fData.GetError()->at(i)
+ *      d. Compute contribution: Δχ² = (y - theo)² / σ²
+ *    - Sum all contributions
+ *
+ * Key differences from μSR fits:
+ * - x-axis is arbitrary (not necessarily time in μs)
+ * - Theory evaluated on-demand (not pre-calculated on grid)
+ * - Loop end is INCLUSIVE (i <= fEndTimeBin)
+ * - No OpenMP parallelization (simpler, smaller data sets)
+ *
+ * \param par Parameter vector from MINUIT with current parameter values
+ * \return Chi-squared value (minimize during fitting)
+ *
+ * \see CalcMaxLikelihood() - NOT IMPLEMENTED for non-μSR
+ * \see PrepareData() for x-y data loading and fit range setup
  */
 Double_t PRunNonMusr::CalcChiSquare(const std::vector<Double_t>& par)
 {
@@ -122,12 +211,26 @@ Double_t PRunNonMusr::CalcChiSquare(const std::vector<Double_t>& par)
 // CalcChiSquareExpected (public)
 //--------------------------------------------------------------------------
 /**
- * <p>Calculate expected chi-square. Currently not implemented since not clear what to be done.
+ * \brief Calculates expected χ² (NOT IMPLEMENTED for non-μSR).
  *
- * <b>return:</b>
+ * This method is not implemented because the concept of "expected χ²" requires
- * - chisq value == 0.0
+ * knowledge of the underlying statistical distribution of the data, which is
+ * not well-defined for general x-y data.
  *
- * \param par parameter vector iterated by minuit2
+ * For μSR histogram data, the expected χ² can be calculated based on Poisson
+ * statistics. For arbitrary non-μSR data, the appropriate statistical model
+ * depends on the data source:
+ * - Counting experiments → Poisson
+ * - Averaged measurements → Gaussian
+ * - Other experiments → problem-specific distributions
+ *
+ * Without knowing the data's statistical nature, a meaningful implementation
+ * cannot be provided.
+ *
+ * \param par Parameter vector from MINUIT (unused)
+ * \return Always returns 0.0
+ *
+ * \note Prints "not implemented yet" message to stdout
  */
 Double_t PRunNonMusr::CalcChiSquareExpected(const std::vector<Double_t>& par)
 {
@@ -140,12 +243,32 @@ Double_t PRunNonMusr::CalcChiSquareExpected(const std::vector<Double_t>& par)
 // CalcMaxLikelihood
 //--------------------------------------------------------------------------
 /**
- * <p>Calculate log maximum-likelihood. Currently not implemented since not clear what to be done.
+ * \brief Calculates maximum likelihood (NOT IMPLEMENTED for non-μSR).
  *
- * <b>return:</b>
+ * Maximum likelihood fitting is not implemented for general x-y data because:
- * - log maximum-likelihood value == 1.0
  *
- * \param par parameter vector iterated by minuit2
+ * 1. <b>Distribution-dependent:</b> The likelihood function depends on the
+ *    underlying statistical distribution of the data points, which varies:
+ *    - Poisson: For counting experiments (like μSR histograms)
+ *    - Gaussian: For averaged measurements with known errors
+ *    - Other: Problem-specific distributions (binomial, exponential, etc.)
+ *
+ * 2. <b>Gaussian case equivalence:</b> If errors are Gaussian, maximum likelihood
+ *    is mathematically equivalent to χ² minimization (already implemented).
+ *
+ * 3. <b>Implementation complexity:</b> Supporting arbitrary likelihood functions
+ *    would require users to specify the distribution, adding complexity without
+ *    clear benefit for most non-μSR applications.
+ *
+ * For general x-y data with Gaussian errors, use χ² fitting via CalcChiSquare().
+ * For non-Gaussian statistics, users should implement custom fitting outside musrfit.
+ *
+ * \param par Parameter vector from MINUIT (unused)
+ * \return Always returns 1.0
+ *
+ * \note Prints "not implemented yet" message to stdout
+ *
+ * \see CalcChiSquare() for standard least-squares fitting (recommended for non-μSR)
  */
 Double_t PRunNonMusr::CalcMaxLikelihood(const std::vector<Double_t>& par)
 {
@@ -158,7 +281,20 @@ Double_t PRunNonMusr::CalcMaxLikelihood(const std::vector<Double_t>& par)
 // CalcTheory
 //--------------------------------------------------------------------------
 /**
- * <p>Calculate theory for a given set of fit-parameters.
+ * \brief Evaluates theory function (empty implementation for non-μSR).
+ *
+ * For non-μSR data, theory calculation is performed on-demand within
+ * CalcChiSquare() rather than pre-calculating and storing theory values.
+ *
+ * This design choice is made because:
+ * - Theory is evaluated at arbitrary x-values from the data file
+ * - No need for high-resolution theory grid (data defines x-points)
+ * - Simpler and more efficient to evaluate during χ² loop
+ * - Avoids storing redundant theory array
+ *
+ * This empty method exists solely to satisfy the PRunBase interface requirement.
+ *
+ * \see CalcChiSquare() for on-demand theory evaluation at each data point
  */
 void PRunNonMusr::CalcTheory()
 {
@@ -168,9 +304,28 @@ void PRunNonMusr::CalcTheory()
 // GetNoOfFitBins (public)
 //--------------------------------------------------------------------------
 /**
- * <p>Calculate the number of fitted bins for the current fit range.
+ * \brief Calculates and returns the number of x-y points within the fit range.
  *
- * <b>return:</b> number of fitted bins.
+ * Counts data points where fFitStartTime ≤ x ≤ fFitEndTime (both inclusive).
+ * This count is essential for:
+ * - Degrees of freedom: ν = N_points - N_params
+ * - Reduced χ²: χ²_red = χ² / ν
+ * - Statistical quality assessment: χ²/ν ≈ 1 indicates good fit
+ *
+ * Algorithm:
+ * 1. Reset counter: fNoOfFitBins = 0
+ * 2. Loop through all x-values in fData.GetX()
+ * 3. For each x-value:
+ *    - If fFitStartTime ≤ x ≤ fFitEndTime → increment counter
+ * 4. Return final count
+ *
+ * The fit range (fFitStartTime, fFitEndTime) is specified in the MSR file
+ * RUN or GLOBAL block "fit" entry, in the same units as the x-axis data.
+ *
+ * \return Number of data points within fit range
+ *
+ * \note This method recalculates the count each time it's called (not cached),
+ *       allowing for dynamic fit range changes.
  */
 UInt_t PRunNonMusr::GetNoOfFitBins()
 {

src/include/PRunNonMusr.h

@@ -34,41 +34,446 @@
 #include "PRunBase.h"
 
 /**
- * <p>Class handling the non-muSR fit type
+ * \brief Class for fitting general x-y data sets (non-μSR time series).
+ *
+ * PRunNonMusr extends the musrfit framework to handle arbitrary x-y data that doesn't
+ * originate from μSR experiments. This allows users to leverage musrfit's powerful
+ * fitting engine, theory functions, and MINUIT interface for general curve fitting tasks.
+ *
+ * \section nonmusr_purpose Purpose and Use Cases
+ *
+ * This fit type is designed for:
+ * - <b>General time-series data:</b> Any x vs. y measurements
+ * - <b>Non-μSR physics:</b> Other experimental data (e.g., optical, electrical, thermal)
+ * - <b>Reusing μSR theory functions:</b> Apply exponentials, oscillations, relaxations to non-μSR data
+ * - <b>Custom data analysis:</b> Fit arbitrary functional forms to experimental data
+ * - <b>Method validation:</b> Test fitting procedures on simulated or benchmark data
+ *
+ * \section nonmusr_data Data Structure
+ *
+ * Unlike μSR fits, non-μSR data is provided as simple x-y pairs:
+ * - <b>x-axis:</b> Independent variable (time, temperature, field, voltage, etc.)
+ * - <b>y-axis:</b> Dependent variable (signal, counts, current, etc.)
+ * - <b>Errors:</b> Optional error bars on y-values
+ * - <b>No histograms:</b> Data is already processed, not raw detector counts
+ * - <b>No t0:</b> No time-zero concept (not time-differential μSR)
+ * - <b>No asymmetry:</b> Direct fitting of y vs. x
+ *
+ * \section nonmusr_input Data Input Formats
+ *
+ * Non-μSR data can be loaded from:
+ * - <b>ASCII files:</b> Space/tab-separated columns (x, y, err)
+ * - <b>DB files:</b> Database format with metadata
+ * - <b>MuSonRoot files:</b> Special ROOT structure for non-μSR data
+ *
+ * ASCII format example:
+ * \code
+ * # x-axis    y-axis    error
+ * 0.0         100.5     3.2
+ * 0.1         95.3      3.1
+ * 0.2         90.8      3.0
+ * ...
+ * \endcode
+ *
+ * \section nonmusr_msr MSR File Configuration
+ *
+ * Example MSR file RUN block for non-μSR data:
+ * \code
+ * RUN data/mydata.dat DB PSI MUSR-ROOT   (name beamline)
+ *   fittype         12      (NonMusr)
+ *   map             1 2     (x-index, y-index in data columns)
+ *   xy-data         0 1     (column 0 = x, column 1 = y)
+ *   packing         1       (usually 1 for pre-processed data)
+ *   fit             0.0 10.0 (fit range in x-axis units)
+ * \endcode
+ *
+ * \section nonmusr_theory Theory Functions
+ *
+ * All standard musrfit theory functions can be used:
+ * - <b>Exponentials:</b> decay, growth, stretched exponentials
+ * - <b>Oscillations:</b> cosine, sine, damped oscillations
+ * - <b>Relaxations:</b> static/dynamic Gaussian/Lorentzian Kubo-Toyabe
+ * - <b>Polynomials:</b> backgrounds, baselines
+ * - <b>User functions:</b> Custom C++ functions
+ *
+ * Theory is evaluated at the x-values from the data file.
+ *
+ * \section nonmusr_differences Key Differences from μSR Fits
+ *
+ * <table>
+ * <tr><th>Feature</th><th>μSR Fits</th><th>Non-μSR Fits</th></tr>
+ * <tr><td>Data type</td><td>Raw histograms</td><td>Processed x-y pairs</td></tr>
+ * <tr><td>Time zero (t0)</td><td>Required</td><td>Not applicable</td></tr>
+ * <tr><td>Background</td><td>Estimated/subtracted</td><td>Included in y-data</td></tr>
+ * <tr><td>Asymmetry</td><td>Calculated</td><td>Not applicable</td></tr>
+ * <tr><td>Packing</td><td>Rebin histograms</td><td>Average x-y points</td></tr>
+ * <tr><td>Fit range</td><td>Time (μs)</td><td>x-axis units (arbitrary)</td></tr>
+ * <tr><td>ADDRUN</td><td>Supported</td><td>NOT supported</td></tr>
+ * </table>
+ *
+ * \section nonmusr_limitations Limitations
+ *
+ * - <b>No ADDRUN:</b> Cannot combine multiple non-μSR data sets
+ * - <b>No maximum likelihood:</b> Only χ² fitting supported (not implemented for non-μSR)
+ * - <b>No expected χ²:</b> Not implemented (unclear definition for general data)
+ * - <b>Simple error handling:</b> Assumes independent Gaussian errors
+ *
+ * \section nonmusr_workflow Analysis Workflow
+ *
+ * 1. <b>Prepare Data:</b> Format as x-y(-error) columns in ASCII/DB file
+ * 2. <b>Create MSR File:</b> Specify file, fit type (12), xy-data indices, fit range
+ * 3. <b>Define Theory:</b> Use standard THEORY block functions
+ * 4. <b>Run Fit:</b> musrfit performs χ² minimization via MINUIT
+ * 5. <b>Analyze Results:</b> Standard parameter extraction, error analysis, plotting
+ *
+ * \see PRunSingleHisto for standard μSR single histogram fits
+ * \see PRunBase for base class interface and common functionality
  */
 class PRunNonMusr : public PRunBase
 {
   public:
+    /**
+     * \brief Default constructor creating an empty, invalid non-μSR run object.
+     *
+     * Initializes all member variables to default values:
+     * - Bin counts set to 0
+     * - Packing set to 1 (no packing for x-y data)
+     * - Handle tag set to kEmpty
+     * - Raw data pointer set to nullptr
+     *
+     * This constructor is needed for creating vectors of PRunNonMusr objects.
+     * The resulting object cannot be used until properly initialized via the main constructor.
+     */
     PRunNonMusr();
+
+    /**
+     * \brief Main constructor initializing a non-μSR run from MSR file and data.
+     *
+     * Performs initialization for general x-y data fitting:
+     *
+     * 1. <b>Base Class Initialization:</b>
+     *    - Calls PRunBase constructor with MSR/data handlers
+     *    - Initializes theory engine
+     *
+     * 2. <b>Raw Data Loading:</b>
+     *    - Retrieves raw data using run name from MSR file
+     *    - Validates data was successfully loaded
+     *    - Marks run invalid if data cannot be loaded
+     *
+     * 3. <b>Data Preparation:</b>
+     *    - Calls PrepareData() to process x-y data
+     *    - Extracts x-y columns based on map/xy-data specification
+     *    - Applies packing if specified
+     *    - Sets up fit range in x-axis units
+     *
+     * The object is marked as invalid (fValid=false) if:
+     * - Raw data file cannot be loaded
+     * - PrepareData() fails (invalid column indices, missing data, etc.)
+     *
+     * \param msrInfo Pointer to MSR file handler (must remain valid)
+     * \param rawData Pointer to raw data handler for loading data files
+     * \param runNo Run number (0-based index in MSR file RUN blocks)
+     * \param tag Operation mode: kFit (fitting), kView (display/plotting)
+     * \param theoAsData Theory mode: true = at data points, false = high-resolution
+     *
+     * \warning Check IsValid() after construction before using for fitting
+     *
+     * \see PrepareData() for data processing details
+     */
     PRunNonMusr(PMsrHandler *msrInfo, PRunDataHandler *rawData, UInt_t runNo, EPMusrHandleTag tag, Bool_t theoAsData);
+
+    /**
+     * \brief Virtual destructor (no cleanup needed for this class).
+     *
+     * Raw data pointer (fRawRunData) is not owned by this class and is not deleted.
+     * Base class destructor handles cleanup of theory objects and other shared resources.
+     */
     virtual ~PRunNonMusr();
 
+    /**
+     * \brief Calculates χ² between non-μSR data and theory.
+     *
+     * Computes the chi-squared statistic for x-y data:
+     * \f[ \chi^2 = \sum_{i={\rm start}}^{\rm end} \frac{(y_i^{\rm data} - y_i^{\rm theory})^2}{\sigma_i^2} \f]
+     *
+     * where:
+     * - y_i^data is the measured y-value at x_i
+     * - y_i^theory is the theory function evaluated at x_i
+     * - σ_i is the error on y_i (from data file or assumed)
+     * - Sum runs over all points within fit range (fFitStartTime ≤ x ≤ fFitEndTime)
+     *
+     * Algorithm:
+     * 1. Evaluate FUNCTIONS block for user-defined functions
+     * 2. Loop over data points from fStartTimeBin to fEndTimeBin
+     * 3. For each point:
+     *    - Get x-value from fData.GetX()
+     *    - Evaluate theory at that x-value: fTheory->Func(x, par, fFuncValues)
+     *    - Compute weighted squared difference
+     * 4. Sum contributions to get total χ²
+     *
+     * Unlike μSR fits, this operates on x-y data directly (not histograms).
+     * The x-axis can represent any independent variable (time, temperature, field, etc.),
+     * not just time in microseconds.
+     *
+     * \param par Parameter vector from MINUIT with current parameter values
+     * \return Chi-squared value (sum of weighted squared residuals)
+     *
+     * \note No OpenMP parallelization in this implementation (typically smaller data sets)
+     *
+     * \see CalcMaxLikelihood() - NOT IMPLEMENTED for non-μSR
+     */
     virtual Double_t CalcChiSquare(const std::vector<Double_t>& par);
+
+    /**
+     * \brief Calculates expected χ² (NOT IMPLEMENTED for non-μSR).
+     *
+     * This method is not implemented for general x-y data because the concept
+     * of "expected χ²" depends on the underlying statistical distribution,
+     * which is not well-defined for arbitrary non-μSR data (unlike Poisson-distributed
+     * histogram counts in μSR).
+     *
+     * Calling this method prints a warning message and returns 0.0.
+     *
+     * \param par Parameter vector from MINUIT
+     * \return Always returns 0.0
+     *
+     * \note Implementation would require assumptions about data statistics
+     */
     virtual Double_t CalcChiSquareExpected(const std::vector<Double_t>& par);
+
+    /**
+     * \brief Calculates maximum likelihood (NOT IMPLEMENTED for non-μSR).
+     *
+     * Maximum likelihood fitting is not implemented for general x-y data because:
+     * - The appropriate likelihood function depends on the data's statistical distribution
+     * - Unlike μSR histograms (Poisson), non-μSR data can have various error models
+     * - Gaussian errors → equivalent to χ² (no advantage)
+     * - Other distributions require user-specified likelihood functions
+     *
+     * Calling this method prints a warning message and returns 1.0.
+     *
+     * \param par Parameter vector from MINUIT
+     * \return Always returns 1.0
+     *
+     * \note Only χ² fitting is supported for non-μSR data
+     */
     virtual Double_t CalcMaxLikelihood(const std::vector<Double_t>& par);
+
+    /**
+     * \brief Evaluates theory function (empty implementation for non-μSR).
+     *
+     * For non-μSR data, theory calculation is performed directly in CalcChiSquare()
+     * rather than pre-calculating and storing theory values. This is because:
+     * - Theory is evaluated at arbitrary x-values (from data file)
+     * - No high-resolution grid needed (data already defines x-points)
+     * - Simpler to evaluate on-demand during χ² calculation
+     *
+     * This method exists to satisfy the PRunBase interface but does nothing.
+     *
+     * \see CalcChiSquare() for on-demand theory evaluation
+     */
     virtual void CalcTheory();
 
+    /**
+     * \brief Returns the number of x-y points within the fit range.
+     *
+     * Counts data points where fFitStartTime ≤ x ≤ fFitEndTime.
+     * This count is used for:
+     * - Degrees of freedom: ν = N_points - N_params
+     * - Reduced χ²: χ²_red = χ² / ν
+     * - Statistical quality assessment
+     *
+     * The method loops through all x-values in fData.GetX() and counts
+     * those within the specified fit range.
+     *
+     * \return Number of data points within fit range
+     *
+     * \see GetNoOfFitBins() implementation for counting algorithm
+     */
     virtual UInt_t GetNoOfFitBins();
 
+    /**
+     * \brief Sets fit range in bin units (NOT SUPPORTED for non-μSR).
+     *
+     * This method is not meaningful for non-μSR data because:
+     * - Fit range is specified in x-axis units (not bins)
+     * - No "first good bin" or "last good bin" concept (no t0)
+     * - x-values can be non-uniform (arbitrary spacing)
+     *
+     * This empty implementation exists to satisfy the PRunBase interface.
+     * Use SetFitRange(PDoublePairVector) in the base class instead.
+     *
+     * \param fitRange Fit range string (ignored)
+     *
+     * \see PRunBase::SetFitRange() for proper fit range specification
+     */
     virtual void SetFitRangeBin(const TString fitRange) {}
 
+    /**
+     * \brief Returns the x-axis column index from MSR file specification.
+     *
+     * Extracts the x-data column index from:
+     * - "xy-data" entry in RUN block (preferred)
+     * - "map" entry first value (fallback)
+     * - Default: 0 (first column)
+     *
+     * The index specifies which column in the data file contains the
+     * independent variable (x-axis values).
+     *
+     * \return Column index for x-axis data (0-based)
+     *
+     * \see GetYIndex() for y-axis column
+     */
     virtual UInt_t GetXIndex();
+
+    /**
+     * \brief Returns the y-axis column index from MSR file specification.
+     *
+     * Extracts the y-data column index from:
+     * - "xy-data" entry in RUN block (preferred)
+     * - "map" entry second value (fallback)
+     * - Default: 1 (second column)
+     *
+     * The index specifies which column in the data file contains the
+     * dependent variable (y-axis values to be fitted).
+     *
+     * \return Column index for y-axis data (0-based)
+     *
+     * \see GetXIndex() for x-axis column
+     */
     virtual UInt_t GetYIndex();
 
   protected:
+    /**
+     * \brief Main data preparation orchestrator for non-μSR data.
+     *
+     * Coordinates the data loading and preprocessing pipeline:
+     * 1. Checks for ADDRUN (warns if present - not supported for non-μSR)
+     * 2. Retrieves packing parameter from RUN or GLOBAL block
+     * 3. Retrieves fit range from RUN or GLOBAL block
+     * 4. Dispatches to PrepareFitData() or PrepareViewData() based on tag
+     *
+     * Key validation:
+     * - ADDRUN presence → warning (ignored)
+     * - Missing packing → error (required)
+     * - Missing fit range → acceptable (will use all data)
+     *
+     * \return True if data preparation succeeds, false on error
+     *
+     * \see PrepareFitData() for fitting mode processing
+     * \see PrepareViewData() for viewing mode processing
+     */
     virtual Bool_t PrepareData();
+
+    /**
+     * \brief Prepares x-y data for fitting.
+     *
+     * Performs data processing for curve fitting:
+     * 1. Determines x-y column indices via GetXIndex() and GetYIndex()
+     * 2. Loads x-y(-error) data from file
+     * 3. Applies packing if specified:
+     *    - packing = 1: Use data as-is (no averaging)
+     *    - packing > 1: Average consecutive points in groups of packing
+     * 4. Packing algorithm for x-values: midpoint of packed range
+     * 5. Packing algorithm for y-values: sum of packed points
+     * 6. Packing algorithm for errors: sqrt(sum of squared errors)
+     * 7. Counts bins within fit range (fFitStartTime ≤ x ≤ fFitEndTime)
+     * 8. Determines fStartTimeBin and fEndTimeBin indices
+     *
+     * Packing example (packing=3):
+     * - Raw: x=[0, 1, 2, 3, 4, 5], y=[10, 12, 11, 15, 14, 13]
+     * - Packed: x=[1, 4], y=[33, 42] (midpoint, sum)
+     *
+     * \return True on success, false if data loading fails
+     *
+     * \see PrepareViewData() for viewing mode (may differ in processing)
+     */
     virtual Bool_t PrepareFitData();
+
+    /**
+     * \brief Prepares x-y data for viewing/plotting.
+     *
+     * Similar to PrepareFitData() but optimized for visualization:
+     * - May use different packing for display
+     * - May extend beyond fit range for context
+     * - Less stringent validation
+     *
+     * The exact implementation mirrors PrepareFitData() for non-μSR,
+     * but the separation allows future customization for viewing.
+     *
+     * \return True on success, false if data loading fails
+     *
+     * \see PrepareFitData() for fitting mode processing
+     */
     virtual Bool_t PrepareViewData();
 
   private:
-    PRawRunData *fRawRunData; ///< raw run data handler
+    /**
+     * \brief Pointer to raw run data handler (not owned).
+     *
+     * Provides access to loaded x-y data from file. Retrieved via
+     * fRawData->GetRunData(*runName) during construction.
+     *
+     * Contains the fDataNonMusr structure with:
+     * - GetData(): Vector of vectors for data columns (x, y, etc.)
+     * - GetErrData(): Vector of vectors for error columns
+     *
+     * \warning Not owned by this class - do not delete
+     */
+    PRawRunData *fRawRunData;
 
-    UInt_t fNoOfFitBins;    ///< number of bins to be be fitted
+    UInt_t fNoOfFitBins;    ///< Number of x-y points within fit range (fFitStartTime ≤ x ≤ fFitEndTime)
-    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
 
-    Int_t fStartTimeBin;    ///< bin at which the fit starts
+    /**
-    Int_t fEndTimeBin;      ///< bin at which the fit ends
+     * \brief Data point averaging/grouping factor.
+     *
+     * Number of consecutive raw data points to average together:
+     * - 1: No packing (use all points as-is)
+     * - > 1: Average groups of packing points
+     *
+     * Packing reduces the number of data points, improving:
+     * - Signal-to-noise ratio (averaging reduces noise)
+     * - Fit speed (fewer points to evaluate)
+     *
+     * But decreases:
+     * - Resolution (fewer x-values)
+     *
+     * Source priority:
+     * 1. RUN block "packing" entry
+     * 2. GLOBAL block "packing" entry
+     * 3. ERROR if neither specified
+     */
+    Int_t  fPacking;
+
+    /**
+     * \brief Theory calculation mode flag.
+     *
+     * Controls theory grid resolution (currently not used for non-μSR):
+     * - true: Theory at data x-values only (efficient)
+     * - false: Theory on high-resolution grid (smooth plotting)
+     *
+     * For non-μSR, theory is always evaluated at data x-values
+     * during CalcChiSquare(), so this flag has minimal effect.
+     */
+    Bool_t fTheoAsData;
+
+    /**
+     * \brief Index of first data point in fit range.
+     *
+     * Points to the first x-y pair where x ≥ fFitStartTime.
+     * Used as loop start in CalcChiSquare().
+     */
+    Int_t fStartTimeBin;
+
+    /**
+     * \brief Index of last data point in fit range (inclusive).
+     *
+     * Points to the last x-y pair where x ≤ fFitEndTime.
+     * Used as loop end in CalcChiSquare() (inclusive: i <= fEndTimeBin).
+     *
+     * \note Unlike μSR fits, this is INCLUSIVE (≤), not exclusive (<)
+     */
+    Int_t fEndTimeBin;
 };
 
 #endif // _PRUNNONMUSR_H_