improve the doxygen docu of PRunListCollection.*
This commit is contained in:
@@ -35,10 +35,28 @@
|
||||
// Constructor
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Constructor.
|
||||
* \brief Constructor initializing the run collection manager.
|
||||
*
|
||||
* \param msrInfo pointer to the msr-file handler
|
||||
* \param data pointer to the run-data handler
|
||||
* Creates an empty collection ready to receive processed run objects via Add() calls.
|
||||
* The collection maintains separate lists for each fit type (single histogram, asymmetry,
|
||||
* RRF variants, etc.) and dispatches operations to the appropriate lists.
|
||||
*
|
||||
* Initialization:
|
||||
* - Stores pointers to MSR file handler and raw data handler (not owned)
|
||||
* - Sets theory calculation mode flag (for plotting vs. fitting)
|
||||
* - All run lists start empty; populated via subsequent Add() calls
|
||||
*
|
||||
* The typical workflow is:
|
||||
* 1. Create PRunListCollection
|
||||
* 2. Call Add() for each RUN block in MSR file
|
||||
* 3. Use Get*Chisq() or Get*MaximumLikelihood() during fitting
|
||||
* 4. Use Get*() accessors for visualization and analysis
|
||||
*
|
||||
* \param msrInfo Pointer to MSR file handler (must remain valid for object lifetime)
|
||||
* \param data Pointer to raw data handler for loading histogram files
|
||||
* \param theoAsData Theory calculation mode: true = at data points only, false = high-resolution grid
|
||||
*
|
||||
* \see Add() for adding processed runs to the collection
|
||||
*/
|
||||
PRunListCollection::PRunListCollection(PMsrHandler *msrInfo, PRunDataHandler *data, Bool_t theoAsData) :
|
||||
fMsrInfo(msrInfo), fData(data), fTheoAsData(theoAsData)
|
||||
@@ -49,7 +67,24 @@ PRunListCollection::PRunListCollection(PMsrHandler *msrInfo, PRunDataHandler *da
|
||||
// Destructor
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Destructor
|
||||
* \brief Destructor that cleans up all run objects.
|
||||
*
|
||||
* Systematically destroys all PRunBase-derived objects in the collection:
|
||||
* 1. Calls CleanUp() on each run object to release internal resources
|
||||
* 2. Explicitly calls destructor to free memory
|
||||
* 3. Clears the vector to release the pointer storage
|
||||
*
|
||||
* This process is repeated for all seven run type lists:
|
||||
* - Single histogram runs
|
||||
* - Single histogram RRF runs
|
||||
* - Asymmetry runs
|
||||
* - Asymmetry RRF runs
|
||||
* - β-NMR asymmetry runs
|
||||
* - μ⁻ (mu-minus) runs
|
||||
* - Non-μSR runs
|
||||
*
|
||||
* The MSR handler (fMsrInfo) and data handler (fData) are NOT deleted
|
||||
* as they are owned by the calling code.
|
||||
*/
|
||||
PRunListCollection::~PRunListCollection()
|
||||
{
|
||||
@@ -100,14 +135,35 @@ PRunListCollection::~PRunListCollection()
|
||||
// Add (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Adds a processed set of data to the handler.
|
||||
* \brief Adds a processed run to the appropriate list based on fit type.
|
||||
*
|
||||
* <b>return:</b>
|
||||
* - true if a processed data set could be added successfully
|
||||
* - false otherwise
|
||||
* Creates a new PRunBase-derived object for the specified MSR file RUN block and
|
||||
* adds it to the appropriate type-specific list. The method performs fit type
|
||||
* dispatching by:
|
||||
* 1. Reading fit type from the RUN block (if specified)
|
||||
* 2. Falling back to GLOBAL block fit type if not specified in RUN
|
||||
* 3. Creating the appropriate run object based on fit type
|
||||
* 4. Calling PrepareData() on the new object to load and process data
|
||||
* 5. Checking validity and returning success/failure status
|
||||
*
|
||||
* \param runNo msr-file run number
|
||||
* \param tag tag showing what shall be done: kFit == fitting, kView == viewing
|
||||
* Supported fit types and corresponding classes:
|
||||
* - PRUN_SINGLE_HISTO → PRunSingleHisto
|
||||
* - PRUN_SINGLE_HISTO_RRF → PRunSingleHistoRRF
|
||||
* - PRUN_ASYMMETRY → PRunAsymmetry
|
||||
* - PRUN_ASYMMETRY_RRF → PRunAsymmetryRRF
|
||||
* - PRUN_ASYMMETRY_BNMR → PRunAsymmetryBNMR
|
||||
* - PRUN_MU_MINUS → PRunMuMinus
|
||||
* - PRUN_NON_MUSR → PRunNonMusr
|
||||
*
|
||||
* If data preprocessing fails (e.g., file not found, invalid t0, theory errors),
|
||||
* the run object is still added to the list but marked as invalid, and this
|
||||
* method returns false.
|
||||
*
|
||||
* \param runNo MSR file run number (0-based index into RUN blocks)
|
||||
* \param tag Operation mode: kFit (for fitting), kView (for display/plotting)
|
||||
* \return True if run was added and initialized successfully, false if initialization failed
|
||||
*
|
||||
* \see PRunBase::PrepareData() for data preprocessing details
|
||||
*/
|
||||
Bool_t PRunListCollection::Add(Int_t runNo, EPMusrHandleTag tag)
|
||||
{
|
||||
@@ -167,15 +223,32 @@ Bool_t PRunListCollection::Add(Int_t runNo, EPMusrHandleTag tag)
|
||||
// SetFitRange (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Set the current fit range in bins. The string has the structure:
|
||||
* 'fit_range fgb0+n00 lgb0-n01 [fgb1+n10 lgb-n11 fgb2+n20 lgb2-n21 .. fgbN+nN0 lgbN-nN1]'
|
||||
* where fgb is the first good bin, lgb is the last good bin. nXY are offsets in bins.
|
||||
* N is the number of runs in the msr-file.
|
||||
* \brief Sets fit range in bin units using string specification (COMMANDS block syntax).
|
||||
*
|
||||
* <p>This means there are 2 options: (i) a globle fit range in bins for <em>all</em> runs in the
|
||||
* msr-file, or (ii) each run block in the msr-file needs its individual range.
|
||||
* Parses and applies fit range specified in bin offsets from t0 markers.
|
||||
* This method supports the COMMANDS block FIT_RANGE syntax used for dynamic
|
||||
* range adjustments during optimization.
|
||||
*
|
||||
* \param fitRange string holding the fit range(s).
|
||||
* String format:
|
||||
* - Single range: "fit_range fgb+n0 lgb-n1"
|
||||
* - Multiple ranges: "fit_range fgb0+n00 lgb0-n01 fgb1+n10 lgb1-n11 ..."
|
||||
*
|
||||
* Where:
|
||||
* - fgb = first good bin (t0 marker from MSR file)
|
||||
* - lgb = last good bin (end marker, often from data_range or automatic)
|
||||
* - nXY = offset in bins (can be positive or negative)
|
||||
*
|
||||
* Example:
|
||||
* - "fit_range fgb+10 lgb-20" → Start 10 bins after t0, end 20 bins before last good bin
|
||||
* - For multiple runs, each gets its own fgb/lgb pair in sequence
|
||||
*
|
||||
* This method broadcasts the range specification to all run objects in all lists.
|
||||
* Each run's SetFitRangeBin() method interprets the string based on its position
|
||||
* in the MSR file.
|
||||
*
|
||||
* \param fitRange String holding fit range specification in bin offsets
|
||||
*
|
||||
* \see SetFitRange(PDoublePairVector) for time-based range specification
|
||||
*/
|
||||
void PRunListCollection::SetFitRange(const TString fitRange)
|
||||
{
|
||||
@@ -199,11 +272,33 @@ void PRunListCollection::SetFitRange(const TString fitRange)
|
||||
// SetFitRange (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Set the current fit range in time. If fitRange.size()==1 the given fit range will be used for all the runs,
|
||||
* otherwise fitRange.size()==the number of runs in the msr-file, and for each run there will be an individual
|
||||
* fit range.
|
||||
* \brief Sets fit range in time units (microseconds from t0).
|
||||
*
|
||||
* \param fitRange vector holding the fit range(s).
|
||||
* Applies time-based fit ranges to all runs in the collection. This is the
|
||||
* standard method for specifying fit ranges in the MSR file FIT block or
|
||||
* during interactive range adjustments.
|
||||
*
|
||||
* Range specification modes:
|
||||
* - <b>Global range:</b> fitRange.size() == 1
|
||||
* - Same (start, end) time pair applies to all runs
|
||||
* - Example: {(0.1, 10.0)} → All runs fit from 0.1 μs to 10.0 μs after t0
|
||||
*
|
||||
* - <b>Individual ranges:</b> fitRange.size() == number of MSR file runs
|
||||
* - Each run gets its own (start, end) time pair
|
||||
* - fitRange[i] corresponds to MSR file RUN block i
|
||||
* - Example: {(0.1, 10.0), (0.2, 8.0)} → Run 0: 0.1-10.0 μs, Run 1: 0.2-8.0 μs
|
||||
*
|
||||
* Processing steps for each run:
|
||||
* 1. SetFitRange() updates internal start/end time members
|
||||
* 2. CalcNoOfFitBins() recalculates bin indices (fStartTimeBin, fEndTimeBin)
|
||||
*
|
||||
* The bin recalculation is necessary because the fit range is initially specified
|
||||
* in time but χ² calculation operates on bin indices.
|
||||
*
|
||||
* \param fitRange Vector of (start_time, end_time) pairs in microseconds (μs) from t0
|
||||
*
|
||||
* \see SetFitRange(TString) for bin-based range specification
|
||||
* \see PRunBase::CalcNoOfFitBins() for time-to-bin conversion
|
||||
*/
|
||||
void PRunListCollection::SetFitRange(const PDoublePairVector fitRange)
|
||||
{
|
||||
@@ -239,12 +334,21 @@ void PRunListCollection::SetFitRange(const PDoublePairVector fitRange)
|
||||
// GetSingleHistoChisq (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Calculates chi-square of <em>all</em> single histogram runs of a msr-file.
|
||||
* \brief Calculates total χ² for all single histogram runs (global fit metric).
|
||||
*
|
||||
* <b>return:</b>
|
||||
* - chi-square of all single histogram runs of the msr-file
|
||||
* Sums the chi-squared statistic over all single histogram runs in the collection:
|
||||
* \f[ \chi^2_{\rm total} = \sum_{i=1}^{N_{\rm runs}} \chi^2_i \f]
|
||||
*
|
||||
* \param par fit parameter vector
|
||||
* where each run's χ² is:
|
||||
* \f[ \chi^2_i = \sum_{j=1}^{N_{\rm bins,i}} \frac{(y_j^{\rm data} - y_j^{\rm theory})^2}{\sigma_j^2} \f]
|
||||
*
|
||||
* This is the objective function minimized by MINUIT during global fitting of
|
||||
* multiple single histogram runs. Called repeatedly during each fit iteration.
|
||||
*
|
||||
* \param par Parameter vector from MINUIT with current parameter values
|
||||
* \return Total χ² summed over all single histogram runs
|
||||
*
|
||||
* \see PRunSingleHisto::CalcChiSquare() for per-run χ² calculation
|
||||
*/
|
||||
Double_t PRunListCollection::GetSingleHistoChisq(const std::vector<Double_t>& par) const
|
||||
{
|
||||
@@ -281,12 +385,19 @@ Double_t PRunListCollection::GetSingleHistoRRFChisq(const std::vector<Double_t>&
|
||||
// GetAsymmetryChisq (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Calculates chi-square of <em>all</em> asymmetry runs of a msr-file.
|
||||
* \brief Calculates total χ² for all asymmetry runs (global fit metric).
|
||||
*
|
||||
* <b>return:</b>
|
||||
* - chi-square of all asymmetry runs of the msr-file
|
||||
* Sums the chi-squared statistic over all asymmetry runs in the collection.
|
||||
* For asymmetry fits, χ² is calculated from the asymmetry values:
|
||||
* \f[ A_i = \frac{F_i - \alpha B_i}{F_i + \alpha B_i} \f]
|
||||
*
|
||||
* \param par fit parameter vector
|
||||
* with proper error propagation. This is the objective function for global
|
||||
* asymmetry fits involving multiple runs (e.g., temperature or field scans).
|
||||
*
|
||||
* \param par Parameter vector from MINUIT with current parameter values
|
||||
* \return Total χ² summed over all asymmetry runs
|
||||
*
|
||||
* \see PRunAsymmetry::CalcChiSquare() for per-run asymmetry χ² calculation
|
||||
*/
|
||||
Double_t PRunListCollection::GetAsymmetryChisq(const std::vector<Double_t>& par) const
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user