diff --git a/src/classes/PPrepFourier.cpp b/src/classes/PPrepFourier.cpp index cc7a8fde1..d43399721 100644 --- a/src/classes/PPrepFourier.cpp +++ b/src/classes/PPrepFourier.cpp @@ -35,7 +35,10 @@ // Constructor //-------------------------------------------------------------------------- /** - *

Constructor. + * \brief Default constructor that initializes to default values. + * + * Sets background range to unused (-1, -1) and packing to 1 (no rebinning). + * Background values and data must be set separately using setter methods. */ PPrepFourier::PPrepFourier() { @@ -48,7 +51,15 @@ PPrepFourier::PPrepFourier() // Constructor //-------------------------------------------------------------------------- /** - *

Constructor. + * \brief Full constructor that initializes all configuration parameters. + * + * Creates a PPrepFourier instance with complete configuration. Background + * can be specified either via range (for automatic calculation) or via + * explicit values (one per data set to be added later). + * + * \param packing Rebinning factor (1=no rebinning, N=combine N bins) + * \param bkgRange Background range [start, end] in bins (-1 if not used) + * \param bkg Vector of explicit background values (one per data set) */ PPrepFourier::PPrepFourier(const Int_t packing, const Int_t *bkgRange, PDoubleVector bkg) : fPacking(packing) @@ -61,7 +72,10 @@ PPrepFourier::PPrepFourier(const Int_t packing, const Int_t *bkgRange, PDoubleVe // Destructor //-------------------------------------------------------------------------- /** - *

Destructor. + * \brief Destructor that cleans up internal data structures. + * + * Clears both raw data and processed data vectors. Note that TH1F objects + * returned by GetData() are owned by the caller and not cleaned up here. */ PPrepFourier::~PPrepFourier() { @@ -73,9 +87,14 @@ PPrepFourier::~PPrepFourier() // SetBkgRange //-------------------------------------------------------------------------- /** - *

set the background range. + * \brief Sets the background range for automatic background calculation. * - * \param bkgRange array with background range + * Specifies the bin range [start, end] for calculating background by averaging. + * Values of -1 indicate that background range is not used (explicit background + * values should be provided instead). Validates that both values are ≥-1 and + * prints warnings if invalid values are encountered. + * + * \param bkgRange Array [start, end] with background bin range (both must be ≥-1) */ void PPrepFourier::SetBkgRange(const Int_t *bkgRange) { @@ -116,12 +135,16 @@ void PPrepFourier::SetBkgRange(const Int_t *bkgRange) } //-------------------------------------------------------------------------- -// SetBkgRange +// SetBkg //-------------------------------------------------------------------------- /** - *

set the background values for all the histos. + * \brief Sets explicit background values for all data sets. * - * \param bkg vector + * Provides pre-calculated background values (one per data set) instead of + * calculating them from a background range. This allows different background + * values for each histogram. + * + * \param bkg Vector of background values (should match number of data sets) */ void PPrepFourier::SetBkg(PDoubleVector bkg) { @@ -133,9 +156,13 @@ void PPrepFourier::SetBkg(PDoubleVector bkg) // SetPacking //-------------------------------------------------------------------------- /** - *

set the packing for the histograms. + * \brief Sets the rebinning/packing factor for data reduction. * - * \param packing number to be used. + * Specifies how many adjacent bins to combine during DoPacking(). A value + * of 1 means no rebinning, 2 combines pairs of bins, etc. Invalid values + * (≤0) are rejected with a warning. + * + * \param packing Number of bins to combine (must be > 0) */ void PPrepFourier::SetPacking(const Int_t packing) { @@ -150,10 +177,13 @@ void PPrepFourier::SetPacking(const Int_t packing) // AddData //-------------------------------------------------------------------------- /** - *

add a data-set (time domain data + meta information) to the internal - * data vector. + * \brief Adds a time-domain data set to the internal collection. * - * \param data set to be added + * Stores the raw data and metadata for later processing. Multiple data sets + * can be added and will be processed together by DoBkgCorrection(), DoPacking(), + * and DoLifeTimeCorrection(). + * + * \param data musrFT_data structure containing raw histogram data and metadata */ void PPrepFourier::AddData(musrFT_data &data) { @@ -164,7 +194,17 @@ void PPrepFourier::AddData(musrFT_data &data) // DoBkgCorrection //-------------------------------------------------------------------------- /** - *

Correct the internal data sets according to a background interval given. + * \brief Applies background correction to all data sets. + * + * Subtracts background from each data point. The background can be specified + * in two ways: + * 1. Background range: Calculates average over the specified bin range + * 2. Explicit values: Uses the background values set via SetBkg() + * + * If fData is not yet initialized, calls InitData() first. If neither + * background range nor explicit values are provided, no correction is applied. + * Validates that background range is within data bounds and that the number + * of explicit background values matches the number of data sets. */ void PPrepFourier::DoBkgCorrection() { @@ -221,7 +261,14 @@ void PPrepFourier::DoBkgCorrection() // DoPacking //-------------------------------------------------------------------------- /** - *

Rebin (pack) the internal data. + * \brief Applies rebinning/packing to reduce the number of data points. + * + * Combines adjacent bins according to the packing factor to improve statistics + * and reduce data size. Bins are summed in groups of fPacking size. If + * fPacking=1, no rebinning is performed. + * + * If fData is not yet initialized, calls InitData() first. The time resolution + * should be adjusted accordingly (multiplied by fPacking) when creating histograms. */ void PPrepFourier::DoPacking() { @@ -256,11 +303,21 @@ void PPrepFourier::DoPacking() // DoLifeTimeCorrection //-------------------------------------------------------------------------- /** - *

Try to do a muon life time correction. The idea is to estimate N0 without - * any theory. This will be OK for high fields (> couple kGauss) but not so good - * for low fields. + * \brief Applies muon lifetime correction for theory-free Fourier analysis. * - * \param fudge rescaling factor for the estimated N0. Should be around 1 + * Performs a theory-free lifetime correction by: + * 1. Multiplying data by exp(t/τ_μ) to remove muon decay + * 2. Estimating N0 as the average of the corrected data + * 3. Subtracting N0 and normalizing by N0 to get asymmetry-like data + * + * This approach works well for high fields (>few kGauss) where depolarization + * is minimal, but may be less accurate for low fields where significant + * relaxation occurs during the muon lifetime. + * + * If fData is not yet initialized, calls InitData() first. Background correction + * should typically be applied before lifetime correction. + * + * \param fudge Rescaling factor for estimated N0 (typically ~1.0, allows fine-tuning) */ void PPrepFourier::DoLifeTimeCorrection(Double_t fudge) { @@ -299,9 +356,10 @@ void PPrepFourier::DoLifeTimeCorrection(Double_t fudge) // GetInfo //-------------------------------------------------------------------------- /** - *

Returns the meta information of a data set. + * \brief Returns the metadata string for a specific data set. * - * \param idx index of the object + * \param idx Data set index + * \return Metadata string from musrFT_data.info, or empty string if idx out of range */ TString PPrepFourier::GetInfo(const UInt_t idx) { @@ -317,9 +375,13 @@ TString PPrepFourier::GetInfo(const UInt_t idx) // GetDataSetTag //-------------------------------------------------------------------------- /** - *

Returns the data set tag of the object + * \brief Returns the data set tag identifier. * - * \param idx index of the object + * The data set tag is used to label and group related data sets, particularly + * for average-per-data-set operations in Fourier analysis. + * + * \param idx Data set index + * \return Data set tag value, or -1 if idx out of range */ Int_t PPrepFourier::GetDataSetTag(const UInt_t idx) { @@ -335,8 +397,16 @@ Int_t PPrepFourier::GetDataSetTag(const UInt_t idx) // GetData //-------------------------------------------------------------------------- /** - *

Creates the requested TH1F objects and returns them. The ownership is with - * the caller. + * \brief Creates ROOT histograms for all processed data sets. + * + * Converts the processed data into TH1F histograms with proper time binning. + * The time range, bin width, and histogram titles are taken from the + * musrFT_data metadata. The packing factor is applied to the time resolution. + * + * \return Vector of TH1F pointers (caller owns and must delete) + * + * \note The caller is responsible for deleting the returned histograms. + * \note Returns empty vector if no data is present. */ std::vector PPrepFourier::GetData() { @@ -402,10 +472,18 @@ std::vector PPrepFourier::GetData() // GetData //-------------------------------------------------------------------------- /** - *

Creates the requested TH1F object and returns it. The ownership is with - * the caller. + * \brief Creates a ROOT histogram for a specific processed data set. * - * \param idx index of the requested histogram + * Converts a single processed data set into a TH1F histogram with proper + * time binning. The time range, bin width, and histogram title are taken + * from the musrFT_data metadata. The packing factor is applied to the + * time resolution. + * + * \param idx Data set index + * \return TH1F pointer (caller owns and must delete), or nullptr if idx out of range + * + * \note The caller is responsible for deleting the returned histogram. + * \note Returns nullptr if no data is present or idx is out of range. */ TH1F *PPrepFourier::GetData(const UInt_t idx) { @@ -458,7 +536,14 @@ TH1F *PPrepFourier::GetData(const UInt_t idx) // InitData (private) //-------------------------------------------------------------------------- /** - *

Copy raw-data to internal data from t0 to the size of raw-data. + * \brief Initializes processed data by copying from raw data starting at t0. + * + * Creates the fData vectors from fRawData, starting from the t0 bin for each + * data set. This effectively removes pre-t0 bins and creates a working copy + * for subsequent processing (background correction, packing, lifetime correction). + * + * If t0 is negative or not set, data is copied from bin 0. This method is + * called automatically by processing methods if fData is not yet initialized. */ void PPrepFourier::InitData() { diff --git a/src/include/PPrepFourier.h b/src/include/PPrepFourier.h index c01704c31..cbfa0dba9 100644 --- a/src/include/PPrepFourier.h +++ b/src/include/PPrepFourier.h @@ -40,50 +40,168 @@ //---------------------------------------------------------------------------- /** - *

Data structure holding raw time domain uSR data together with some - * necessary meta information. + * \brief Data structure holding raw time-domain μSR data with metadata. + * + * This structure packages raw histogram data together with essential metadata + * needed for Fourier transform preparation. It includes timing information, + * t0 calibration, and time range specifications for selective data processing. + * + * \see PPrepFourier for the class that processes this data */ struct musrFT_data { - Int_t dataSetTag; ///< tag to label the data set. Needed for average-per-data-set - TString info; ///< keeps all the meta information - Double_t timeResolution; ///< time resolution in (usec) - Int_t t0; ///< keep the t0 bin - Double_t timeRange[2]; ///< time range to be used, given in (usec). - PDoubleVector rawData; ///< a single time domain data vector + Int_t dataSetTag; ///< Data set identifier tag (needed for average-per-data-set operations) + TString info; ///< Metadata string (run name, histogram info, etc.) + Double_t timeResolution; ///< Time resolution in microseconds (μs) + Int_t t0; ///< Time zero bin number (start of valid data) + Double_t timeRange[2]; ///< Time range to process: [0]=start, [1]=end in microseconds (μs) + PDoubleVector rawData; ///< Raw time-domain data vector (bin counts) }; //---------------------------------------------------------------------------- /** - *

Little helper class to prepare time-domain data for Fourier transform, without - * theory, etc. + * \brief Prepares time-domain μSR data for Fourier transformation. + * + * PPrepFourier is a utility class that processes raw time-domain μSR data + * before Fourier transformation. It performs essential preprocessing steps: + * - Background correction (using range or explicit values) + * - Data rebinning/packing for improved statistics + * - Muon lifetime correction for theory-free analysis + * - Time range selection + * + * The class handles multiple data sets simultaneously and prepares them + * for subsequent Fourier analysis without requiring theoretical fit functions. + * + * \par Usage Example: + * \code + * PPrepFourier prep(packing, bkgRange, bkgValues); + * prep.AddData(dataSet1); + * prep.AddData(dataSet2); + * prep.DoBkgCorrection(); + * prep.DoPacking(); + * prep.DoLifeTimeCorrection(1.0); + * std::vector histos = prep.GetData(); + * \endcode + * + * \see musrFT_data for the input data structure */ class PPrepFourier { public: + /// Default constructor (requires separate configuration) PPrepFourier(); + + /** + * \brief Full constructor with all configuration parameters. + * \param packing Rebinning factor (1=no rebinning, 2=combine 2 bins, etc.) + * \param bkgRange Background range [start, end] in bins (-1 if not used) + * \param bkg Vector of explicit background values (one per data set) + */ PPrepFourier(const Int_t packing, const Int_t *bkgRange, PDoubleVector bkg); + + /// Destructor virtual ~PPrepFourier(); + /** + * \brief Sets background range for automatic background calculation. + * \param bkgRange Array [start, end] specifying background bins (both ≥-1) + */ virtual void SetBkgRange(const Int_t *bkgRange); + + /** + * \brief Sets explicit background values for each data set. + * \param bkg Vector of background values (one per histogram) + */ virtual void SetBkg(PDoubleVector bkg); + + /** + * \brief Sets rebinning/packing factor for data reduction. + * \param packing Number of bins to combine (must be > 0) + */ virtual void SetPacking(const Int_t packing); + + /** + * \brief Adds a time-domain data set for processing. + * \param data musrFT_data structure containing raw data and metadata + */ virtual void AddData(musrFT_data &data); + + /** + * \brief Applies background correction to all data sets. + * + * Uses either the background range (averaged over range) or explicit + * background values. Background is subtracted from all data points. + */ virtual void DoBkgCorrection(); + + /** + * \brief Applies rebinning/packing to reduce data points. + * + * Combines adjacent bins according to the packing factor to improve + * statistics and reduce the number of data points. + */ virtual void DoPacking(); + + /** + * \brief Applies muon lifetime correction for theory-free analysis. + * \param fudge Rescaling factor for estimated N0 (typically ~1.0) + * + * Multiplies data by exp(t/τ) to remove muon decay, estimates N0 from + * the average, and normalizes to create asymmetry-like data. Works best + * for high fields (>few kGauss) where depolarization is minimal. + */ virtual void DoLifeTimeCorrection(Double_t fudge); + /** + * \brief Returns metadata string for a specific data set. + * \param idx Data set index + * \return Metadata string, or empty string if idx out of range + */ TString GetInfo(const UInt_t idx); + + /** + * \brief Returns data set tag identifier. + * \param idx Data set index + * \return Data set tag, or -1 if idx out of range + */ Int_t GetDataSetTag(const UInt_t idx); + + /** + * \brief Returns number of stored data sets. + * \return Number of data sets added via AddData() + */ UInt_t GetNoOfData() { return fRawData.size(); } + + /** + * \brief Creates ROOT histograms for all processed data sets. + * \return Vector of TH1F pointers (caller owns the histograms) + * + * Creates histograms with proper time binning, respecting time ranges + * and packing. The caller is responsible for deleting the histograms. + */ std::vector GetData(); + + /** + * \brief Creates ROOT histogram for a specific processed data set. + * \param idx Data set index + * \return TH1F pointer (caller owns), or nullptr if idx out of range + * + * Creates a histogram with proper time binning for the specified data set. + * The caller is responsible for deleting the histogram. + */ TH1F *GetData(const UInt_t idx); private: - std::vector fRawData; - std::vectorfData; - Int_t fBkgRange[2]; - PDoubleVector fBkg; - Int_t fPacking; + std::vector fRawData; ///< Raw input data sets with metadata + std::vector fData; ///< Processed data (after t0, corrections, packing) + Int_t fBkgRange[2]; ///< Background range: [0]=start bin, [1]=end bin (-1=unused) + PDoubleVector fBkg; ///< Explicit background values (one per data set) + Int_t fPacking; ///< Rebinning factor (1=no rebinning, N=combine N bins) + /** + * \brief Initializes processed data from raw data. + * + * Copies raw data to fData starting from t0 bin. This is called + * automatically by processing methods if needed. + */ virtual void InitData(); };