LMU/musrfit
5
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 4 Activity

improve doxygen documentation of PMsr2Data.*

Browse Source
This commit is contained in:
suter_a
2025-11-14 09:11:28 +01:00
parent a40c431396
commit 5f1b4fa5f5
2 changed files with 507 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
src/include/PMsr2Data.h
View File

@@ -45,57 +45,273 @@
//-------------------------------------------------------------
/**
* <p> Class providing the necessary utilities for msr2data:
* generate new msr-files from a template, collect fit parameters from msr-files and write them to DB or plain ASCII files
* \brief Utility class for msr2data: template-based msr-file generation and parameter extraction.
*
* PMsr2Data provides comprehensive functionality for the msr2data tool, which is used to:
* - Generate new msr-files from templates by substituting run numbers
* - Extract fit parameters from analyzed msr-files
* - Write collected parameters to database (DB) or plain ASCII files
* - Support both single-run and global (multi-run) fitting workflows
*
* Key Features:
* - Template-based msr-file generation with automatic run number substitution
* - Flexible run number specification (single, range, list file, explicit list)
* - Parameter extraction from fitted msr-files
* - Multiple output formats (DB format, ASCII tables)
* - Global fitting support for combined multi-run analysis
* - XML-based configuration via startup files
*
* Implementation Note:
* This class uses std::string and standard C++ string handling exclusively
* (rather than ROOT's TString) to demonstrate modern C++ practices, though
* this occasionally requires conversions when interfacing with PMusr classes.
*
* Typical Workflow:
* 1. Create PMsr2Data object with file extension
* 2. Parse XML startup file for configuration
* 3. Set run numbers (single, range, or list)
* 4. Generate msr-files from template or extract parameters from fitted files
* 5. Write output to DB or ASCII format
*
* \see PStartupHandler for XML configuration parsing
* \see PRunDataHandler for run data management
* \see PMsrHandler for msr-file parsing and manipulation
*/
class PMsr2Data
{
public:
PMsr2Data(const std::string&); // File extension
//-----------------------------------------------------------------------
/**
* \brief Constructor that initializes the msr2data handler.
*
* \param fileExtension File extension for data files (e.g., "bin", "root", "mdu")
*/
PMsr2Data(const std::string& fileExtension);
//-----------------------------------------------------------------------
/**
* \brief Destructor that cleans up resources.
*/
~PMsr2Data();
int SetRunNumbers(unsigned int); // single run given
int SetRunNumbers(unsigned int, unsigned int); // run list specified through first and last run number
int SetRunNumbers(const std::string&); // run list file given
int SetRunNumbers(const std::vector<unsigned int>&); // explicit run list specified using [ ]
//-----------------------------------------------------------------------
/**
* \brief Sets a single run number for processing.
*
* \param runNumber Single run number to process
* \return 0 on success, non-zero on error
*/
int SetRunNumbers(unsigned int runNumber);
//-----------------------------------------------------------------------
/**
* \brief Sets a range of run numbers (from first to last, inclusive).
*
* \param firstRun First run number in the range
* \param lastRun Last run number in the range
* \return 0 on success, non-zero on error
*/
int SetRunNumbers(unsigned int firstRun, unsigned int lastRun);
//-----------------------------------------------------------------------
/**
* \brief Sets run numbers from a run list file.
*
* Reads run numbers from a text file, one run number per line.
*
* \param runListFileName Path to file containing run numbers
* \return 0 on success, non-zero on error
*/
int SetRunNumbers(const std::string& runListFileName);
//-----------------------------------------------------------------------
/**
* \brief Sets run numbers from an explicit vector.
*
* \param runVector Vector of run numbers to process
* \return 0 on success, non-zero on error
*/
int SetRunNumbers(const std::vector<unsigned int>& runVector);
//-----------------------------------------------------------------------
/**
* \brief Gets the current run number being processed.
*
* \return Current run number from the internal iterator
*/
unsigned int GetPresentRun() const;
int DetermineRunNumberDigits(unsigned int, bool) const;
//-----------------------------------------------------------------------
/**
* \brief Determines the number of digits needed for run number formatting.
*
* Analyzes run numbers to determine zero-padding requirements for
* consistent file naming.
*
* \param maxRunNumber Maximum run number to consider
* \param templateFile Whether processing a template file
* \return Number of digits needed for run number formatting
*/
int DetermineRunNumberDigits(unsigned int maxRunNumber, bool templateFile) const;
//-----------------------------------------------------------------------
/**
* \brief Validates that all run numbers are within acceptable ranges.
*
* \return 0 if all run numbers are valid, non-zero otherwise
*/
int CheckRunNumbersInRange() const;
//-----------------------------------------------------------------------
/**
* \brief Parses the XML startup file for configuration.
*
* Reads and processes the msr2data XML startup file containing
* paths, templates, and other configuration settings.
*
* \return 0 on success, non-zero on parsing errors
*/
int ParseXmlStartupFile();
int ReadMsrFile(const std::string&) const;
//-----------------------------------------------------------------------
/**
* \brief Reads and parses an msr-file.
*
* \param msrFileName Path to the msr-file to read
* \return 0 on success, non-zero on read/parse errors
*/
int ReadMsrFile(const std::string& msrFileName) const;
//-----------------------------------------------------------------------
/**
* \brief Reads the run data file for the current run.
*
* \return 0 on success, non-zero on read errors
*/
int ReadRunDataFile();
bool PrepareNewInputFile(unsigned int, bool) const; // template
bool PrepareGlobalInputFile(unsigned int, const std::string&, unsigned int) const; // generate msr-input file for a global fit
//-----------------------------------------------------------------------
/**
* \brief Generates a new msr-file from a template.
*
* Creates an msr-file by substituting run number placeholders in the
* template with actual run numbers.
*
* \param templateNumber Template identifier number
* \param sorted Whether to generate sorted output
* \return true on success, false on failure
*/
bool PrepareNewInputFile(unsigned int templateNumber, bool sorted) const;
int WriteOutput(const std::string&, const std::vector<unsigned int>&, bool, unsigned int, bool global = false, unsigned int counter = 0) const;
//-----------------------------------------------------------------------
/**
* \brief Generates an msr-file for global (multi-run) fitting.
*
* Creates a combined msr-file for global fits across multiple runs.
*
* \param templateNumber Template identifier number
* \param globalOutputFile Path to output global msr-file
* \param runListSize Number of runs in the global fit
* \return true on success, false on failure
*/
bool PrepareGlobalInputFile(unsigned int templateNumber, const std::string& globalOutputFile, unsigned int runListSize) const;
//-----------------------------------------------------------------------
/**
* \brief Writes extracted parameters to output file.
*
* Outputs fit parameters in either DB format or ASCII table format.
*
* \param outputFileName Output file path
* \param parameters Vector of parameter indices to output
* \param dbFormat Whether to use DB format (true) or ASCII (false)
* \param precision Number of significant digits for output
* \param global Whether this is global fit output
* \param counter Counter for global fit indexing
* \return 0 on success, non-zero on write errors
*/
int WriteOutput(const std::string& outputFileName, const std::vector<unsigned int>& parameters, bool dbFormat, unsigned int precision, bool global = false, unsigned int counter = 0) const;
private:
bool PrepareNewSortedInputFile(unsigned int) const; // template
//-----------------------------------------------------------------------
/**
* \brief Generates a sorted msr-file from a template.
*
* Internal helper for creating sorted msr-files with proper histogram ordering.
*
* \param templateNumber Template identifier number
* \return true on success, false on failure
*/
bool PrepareNewSortedInputFile(unsigned int templateNumber) const;
//-----------------------------------------------------------------------
/**
* \brief Retrieves msr-file handler for a single run.
*
* \return Pointer to PMsrHandler for the current run
*/
PMsrHandler* GetSingleRunMsrFile() const;
//-----------------------------------------------------------------------
/**
* \brief Writes a single numeric value to output stream.
*
* \param outFile Output file stream
* \param value Value to write
* \param width Field width for formatting
*/
void WriteValue(std::fstream &outFile, const double &value, const unsigned int &width) const;
void WriteValue(std::fstream &outFile, const double &value, const double &errValue, const unsigned int &width, const bool &db) const;
int GetFirstSignificantDigit(const double &value) const;
bool InParameterList(const unsigned int &paramValue, const std::vector<unsigned int>&) const;
std::string fFileExtension;
std::vector<unsigned int> fRunVector;
mutable std::vector<unsigned int>::const_iterator fRunVectorIter;
bool fRunListFile;
std::vector<std::string> fIndVar;
std::unique_ptr<std::ifstream> fRunListFileStream;
std::unique_ptr<TSAXParser> fSaxParser;
std::unique_ptr<PStartupHandler> fStartupHandler;
mutable std::unique_ptr<PRunDataHandler> fDataHandler;
mutable std::unique_ptr<PMsrHandler> fMsrHandler;
mutable unsigned int fNumGlobalParam;
mutable unsigned int fNumSpecParam;
mutable unsigned int fNumTempRunBlocks;
mutable unsigned int fRunNumberDigits;
mutable bool fHeaderWritten;
//-----------------------------------------------------------------------
/**
* \brief Writes a value with its error to output stream.
*
* Formats output based on DB or ASCII mode.
*
* \param outFile Output file stream
* \param value Value to write
* \param errValue Error/uncertainty value
* \param width Field width for formatting
* \param db Whether to use DB format (true) or ASCII (false)
*/
void WriteValue(std::fstream &outFile, const double &value, const double &errValue, const unsigned int &width, const bool &db) const;
//-----------------------------------------------------------------------
/**
* \brief Determines the first significant digit position of a value.
*
* Used for intelligent formatting and precision control.
*
* \param value Value to analyze
* \return Position of first significant digit
*/
int GetFirstSignificantDigit(const double &value) const;
//-----------------------------------------------------------------------
/**
* \brief Checks if a parameter is in the output parameter list.
*
* \param paramValue Parameter index to check
* \param paramList List of parameters to output
* \return true if parameter should be output, false otherwise
*/
bool InParameterList(const unsigned int &paramValue, const std::vector<unsigned int>& paramList) const;
std::string fFileExtension; ///< File extension for data files (e.g., "bin", "root")
std::vector<unsigned int> fRunVector; ///< Vector of run numbers to process
mutable std::vector<unsigned int>::const_iterator fRunVectorIter; ///< Iterator for current position in run vector
bool fRunListFile; ///< Flag indicating if run list is from a file
std::vector<std::string> fIndVar; ///< Independent variables for output
std::unique_ptr<std::ifstream> fRunListFileStream; ///< Stream for reading run list file
std::unique_ptr<TSAXParser> fSaxParser; ///< XML SAX parser for startup file
std::unique_ptr<PStartupHandler> fStartupHandler; ///< Handler for XML startup file configuration
mutable std::unique_ptr<PRunDataHandler> fDataHandler; ///< Handler for run data files
mutable std::unique_ptr<PMsrHandler> fMsrHandler; ///< Handler for msr-file parsing and generation
mutable unsigned int fNumGlobalParam; ///< Number of global parameters in fit
mutable unsigned int fNumSpecParam; ///< Number of spectrum-specific parameters
mutable unsigned int fNumTempRunBlocks; ///< Number of temporary run blocks
mutable unsigned int fRunNumberDigits; ///< Number of digits for run number formatting
mutable bool fHeaderWritten; ///< Flag tracking if output header has been written
};