/***************************************************************************

  PPrepFourier.h

  Author: Andreas Suter
  e-mail: andreas.suter@psi.ch

***************************************************************************/

/***************************************************************************
 *   Copyright (C) 2007-2026 by Andreas Suter                              *
 *   andreas.suter@psi.ch                                                  *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
 ***************************************************************************/

#ifndef _PPREPFOURIER_H_
#define _PPREPFOURIER_H_

#include <iostream>
#include <vector>

#include <TH1F.h>
#include <TMath.h>

#include "PMusr.h"

//----------------------------------------------------------------------------
/**
 * \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;        ///< 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)
};

//----------------------------------------------------------------------------
/**
 * \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<TH1F*> 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<TH1F*> 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<musrFT_data> fRawData;  ///< Raw input data sets with metadata
    std::vector<PDoubleVector> 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();
};

#endif // _PPREPFOURIER_H_