improve the doxygen docu of PRunNonMusr.*
This commit is contained in:
@@ -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
|
||||
* \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. <b>Base Class Initialization:</b>
|
||||
* - 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>
|
||||
* - 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. <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>
|
||||
* - 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<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>
|
||||
* - 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. <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()
|
||||
{
|
||||
|
||||
@@ -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
|
||||
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_
|
||||
|
||||
Reference in New Issue
Block a user