From 27b3b317bafeef02020c3f606d8793ac4a1f46ca Mon Sep 17 00:00:00 2001 From: Andreas Suter Date: Sat, 15 Nov 2025 08:42:21 +0100 Subject: [PATCH] improve the doxygen docu of PRunNonMusr.* --- src/classes/PRunNonMusr.cpp | 199 +++++++++++++++-- src/include/PRunNonMusr.h | 419 +++++++++++++++++++++++++++++++++++- 2 files changed, 589 insertions(+), 29 deletions(-) diff --git a/src/classes/PRunNonMusr.cpp b/src/classes/PRunNonMusr.cpp index fa6b50f68..f1e4f81ed 100644 --- a/src/classes/PRunNonMusr.cpp +++ b/src/classes/PRunNonMusr.cpp @@ -35,7 +35,21 @@ // Constructor //-------------------------------------------------------------------------- /** - *

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 //-------------------------------------------------------------------------- /** - *

Constructor + * \brief Main constructor initializing a non-μSR run from MSR file and x-y data. * - * \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 general curve fitting: + * + * 1. Base Class Initialization: + * - Calls PRunBase constructor with MSR/data handlers + * - Initializes theory engine and parameter mappings + * - Sets up FUNCTIONS block evaluation + * + * 2. Raw Data Loading: + * - 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. Data Preparation: + * - 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 //-------------------------------------------------------------------------- /** - *

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 //-------------------------------------------------------------------------- /** - *

Calculate chi-square. + * \brief Calculates χ² between non-μSR x-y data and theory. * - * return: - * - chisq value + * Computes the chi-squared statistic for general x-y data: + * \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. Evaluate FUNCTIONS block: + * - Loop over user-defined functions + * - Compute function values using current parameters + * - Store in fFuncValues for use by theory + * + * 2. Calculate χ² sum: + * - 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& par) { @@ -122,12 +211,26 @@ Double_t PRunNonMusr::CalcChiSquare(const std::vector& par) // CalcChiSquareExpected (public) //-------------------------------------------------------------------------- /** - *

Calculate expected chi-square. Currently not implemented since not clear what to be done. + * \brief Calculates expected χ² (NOT IMPLEMENTED for non-μSR). * - * return: - * - chisq value == 0.0 + * This method is not implemented because the concept of "expected χ²" requires + * 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& par) { @@ -140,12 +243,32 @@ Double_t PRunNonMusr::CalcChiSquareExpected(const std::vector& par) // CalcMaxLikelihood //-------------------------------------------------------------------------- /** - *

Calculate log maximum-likelihood. Currently not implemented since not clear what to be done. + * \brief Calculates maximum likelihood (NOT IMPLEMENTED for non-μSR). * - * return: - * - log maximum-likelihood value == 1.0 + * Maximum likelihood fitting is not implemented for general x-y data because: * - * \param par parameter vector iterated by minuit2 + * 1. Distribution-dependent: 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. Gaussian case equivalence: If errors are Gaussian, maximum likelihood + * is mathematically equivalent to χ² minimization (already implemented). + * + * 3. Implementation complexity: 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& par) { @@ -158,7 +281,20 @@ Double_t PRunNonMusr::CalcMaxLikelihood(const std::vector& par) // CalcTheory //-------------------------------------------------------------------------- /** - *

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) //-------------------------------------------------------------------------- /** - *

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. * - * return: 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() { diff --git a/src/include/PRunNonMusr.h b/src/include/PRunNonMusr.h index 1196c649c..a1d3d60c0 100644 --- a/src/include/PRunNonMusr.h +++ b/src/include/PRunNonMusr.h @@ -34,41 +34,446 @@ #include "PRunBase.h" /** - *

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: + * - General time-series data: Any x vs. y measurements + * - Non-μSR physics: Other experimental data (e.g., optical, electrical, thermal) + * - Reusing μSR theory functions: Apply exponentials, oscillations, relaxations to non-μSR data + * - Custom data analysis: Fit arbitrary functional forms to experimental data + * - Method validation: 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: + * - x-axis: Independent variable (time, temperature, field, voltage, etc.) + * - y-axis: Dependent variable (signal, counts, current, etc.) + * - Errors: Optional error bars on y-values + * - No histograms: Data is already processed, not raw detector counts + * - No t0: No time-zero concept (not time-differential μSR) + * - No asymmetry: Direct fitting of y vs. x + * + * \section nonmusr_input Data Input Formats + * + * Non-μSR data can be loaded from: + * - ASCII files: Space/tab-separated columns (x, y, err) + * - DB files: Database format with metadata + * - MuSonRoot files: 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: + * - Exponentials: decay, growth, stretched exponentials + * - Oscillations: cosine, sine, damped oscillations + * - Relaxations: static/dynamic Gaussian/Lorentzian Kubo-Toyabe + * - Polynomials: backgrounds, baselines + * - User functions: Custom C++ functions + * + * Theory is evaluated at the x-values from the data file. + * + * \section nonmusr_differences Key Differences from μSR Fits + * + * + * + * + * + * + * + * + * + * + *
FeatureμSR FitsNon-μSR Fits
Data typeRaw histogramsProcessed x-y pairs
Time zero (t0)RequiredNot applicable
BackgroundEstimated/subtractedIncluded in y-data
AsymmetryCalculatedNot applicable
PackingRebin histogramsAverage x-y points
Fit rangeTime (μs)x-axis units (arbitrary)
ADDRUNSupportedNOT supported
+ * + * \section nonmusr_limitations Limitations + * + * - No ADDRUN: Cannot combine multiple non-μSR data sets + * - No maximum likelihood: Only χ² fitting supported (not implemented for non-μSR) + * - No expected χ²: Not implemented (unclear definition for general data) + * - Simple error handling: Assumes independent Gaussian errors + * + * \section nonmusr_workflow Analysis Workflow + * + * 1. Prepare Data: Format as x-y(-error) columns in ASCII/DB file + * 2. Create MSR File: Specify file, fit type (12), xy-data indices, fit range + * 3. Define Theory: Use standard THEORY block functions + * 4. Run Fit: musrfit performs χ² minimization via MINUIT + * 5. Analyze Results: 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. Base Class Initialization: + * - Calls PRunBase constructor with MSR/data handlers + * - Initializes theory engine + * + * 2. Raw Data Loading: + * - Retrieves raw data using run name from MSR file + * - Validates data was successfully loaded + * - Marks run invalid if data cannot be loaded + * + * 3. Data Preparation: + * - 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& 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& 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& 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 - 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 fNoOfFitBins; ///< Number of x-y points within fit range (fFitStartTime ≤ x ≤ fFitEndTime) - 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_