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

improve doxygen documentation of PMusrCanvas.*

Browse Source
This commit is contained in:
suter_a
2025-11-14 09:36:18 +01:00
parent 7762f69c24
commit 368957b46f
2 changed files with 235 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
src/classes/PMusrCanvas.cpp
View File

@@ -50,7 +50,10 @@ ClassImp(PMusrCanvasPlotRange)
// Constructor // Constructor
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Constructor * \brief Constructor initializing plot range to undefined state.
*
* Sets both X and Y ranges as not present and initializes all range
* values to zero. Ranges must be explicitly set via SetXRange/SetYRange.
*/ */
PMusrCanvasPlotRange::PMusrCanvasPlotRange() PMusrCanvasPlotRange::PMusrCanvasPlotRange()
{ {
@@ -67,10 +70,13 @@ PMusrCanvasPlotRange::PMusrCanvasPlotRange()
// SetXRange (public) // SetXRange (public)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Sets the x-range values. * \brief Sets the X-axis range and marks it as present.
* *
* \param xmin minimum range value * Automatically swaps values if xmin > xmax to ensure proper ordering.
* \param xmax maximum range value * Outputs a warning to stderr when swapping occurs.
*
* \param xmin Minimum X value
* \param xmax Maximum X value
*/ */
void PMusrCanvasPlotRange::SetXRange(Double_t xmin, Double_t xmax) void PMusrCanvasPlotRange::SetXRange(Double_t xmin, Double_t xmax)
{ {
@@ -89,10 +95,13 @@ void PMusrCanvasPlotRange::SetXRange(Double_t xmin, Double_t xmax)
// SetYRange (public) // SetYRange (public)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Sets the y-range values. * \brief Sets the Y-axis range and marks it as present.
* *
* \param ymin minimum range value * Automatically swaps values if ymin > ymax to ensure proper ordering.
* \param ymax maximum range value * Outputs a warning to stderr when swapping occurs.
*
* \param ymin Minimum Y value
* \param ymax Maximum Y value
*/ */
void PMusrCanvasPlotRange::SetYRange(Double_t ymin, Double_t ymax) void PMusrCanvasPlotRange::SetYRange(Double_t ymin, Double_t ymax)
{ {
@@ -114,7 +123,19 @@ ClassImpQ(PMusrCanvas)
// Constructor // Constructor
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Constructor * \brief Default constructor initializing canvas to undefined state.
*
* Initializes all member variables to default values:
* - No timeout
* - N0 and background scaling enabled
* - Not valid (requires proper initialization via other constructors)
* - Data view mode
* - All pointers set to nullptr
* - Fourier and average structures initialized
* - No explicit ranges set
*
* This constructor creates an invalid canvas that cannot be used directly.
* Use one of the full constructors to create a functional canvas.
*/ */
PMusrCanvas::PMusrCanvas() PMusrCanvas::PMusrCanvas()
{ {
@@ -158,18 +179,30 @@ PMusrCanvas::PMusrCanvas()
// Constructor // Constructor
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Constructor. * \brief Basic constructor creating canvas with default Fourier settings.
* *
* \param number The plot number of the msr-file PLOT block * Creates a functional PMusrCanvas with standard Fourier transform settings
* \param title Title to be displayed * and default markers/colors. This is the simpler constructor for cases where
* \param wtopx top x coordinate (in pixels) to place the canvas. * custom Fourier parameters or plot styling are not needed.
* \param wtopy top y coordinate (in pixels) to place the canvas. *
* \param ww width (in pixels) of the canvas. * Initialization sequence:
* \param wh height (in pixels) of the canvas. * 1. Initializes member variables
* \param batch flag: if set true, the canvas will not be displayed. This is used when just dumping of a * 2. Sets up default Fourier parameters (via InitFourier)
* graphical output file is wished. * 3. Initializes average data structures (via InitAverage)
* \param fourier flag: if set true, the canvas will present the Fourier view. * 4. Creates ROOT graphics style (via CreateStyle)
* \param avg flag: if set true, the canvas will present the averages data/Fourier view. * 5. Creates canvas pads and menus (via InitMusrCanvas)
* 6. Sets histogram minimum to zero for proper bar chart display
*
* \param number Plot number from MSR file PLOT block
* \param title Canvas title to display
* \param wtopx Top-left X coordinate of canvas window (pixels)
* \param wtopy Top-left Y coordinate of canvas window (pixels)
* \param ww Canvas width (pixels)
* \param wh Canvas height (pixels)
* \param batch If true, run in batch mode without GUI display (for file export)
* \param fourier If true, start with Fourier view instead of time domain
* \param avg If true, start with averaged data view
* \param theoAsData If true, calculate theory only at data points (faster)
*/ */
PMusrCanvas::PMusrCanvas(const Int_t number, const Char_t* title, PMusrCanvas::PMusrCanvas(const Int_t number, const Char_t* title,
Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh,
@@ -205,21 +238,37 @@ PMusrCanvas::PMusrCanvas(const Int_t number, const Char_t* title,
// Constructor // Constructor
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Constructor. * \brief Full constructor with custom Fourier settings and plot styling.
* *
* \param number The plot number of the msr-file PLOT block * Creates a PMusrCanvas with user-specified Fourier transform parameters,
* \param title Title to be displayed * custom marker styles, and color schemes. This constructor provides maximum
* \param wtopx top x coordinate (in pixels) to place the canvas. * control over canvas appearance and behavior.
* \param wtopy top y coordinate (in pixels) to place the canvas. *
* \param ww width (in pixels) of the canvas. * The marker and color lists allow customization of how multiple datasets
* \param wh height (in pixels) of the canvas. * appear in plots. Each dataset uses the marker/color at the corresponding
* \param fourierDefault structure holding the pre-defined settings for a Fourier transform * index in the provided vectors.
* \param markerList pre-defined list of markers *
* \param colorList pre-defined list of colors * Initialization sequence:
* \param batch flag: if set true, the canvas will not be displayed. This is used when just dumping of a * 1. Initializes member variables with custom settings
* graphical output file is wished. * 2. Copies Fourier parameters, marker list, and color list
* \param fourier flag: if set true, the canvas will present the Fourier view. * 3. Initializes average data structures
* \param avg flag: if set true, the canvas will present the averages data/Fourier view. * 4. Creates ROOT graphics style
* 5. Creates canvas pads and menus
* 6. Sets histogram minimum to zero for proper bar chart display
*
* \param number Plot number from MSR file PLOT block
* \param title Canvas title to display
* \param wtopx Top-left X coordinate of canvas window (pixels)
* \param wtopy Top-left Y coordinate of canvas window (pixels)
* \param ww Canvas width (pixels)
* \param wh Canvas height (pixels)
* \param fourierDefault Fourier transform parameters (ranges, apodization, etc.)
* \param markerList Vector of ROOT marker style indices (e.g., 20=circle, 21=square)
* \param colorList Vector of ROOT color indices (e.g., 1=black, 2=red, 4=blue)
* \param batch If true, run in batch mode without GUI display
* \param fourier If true, start with Fourier view
* \param avg If true, start with averaged data view
* \param theoAsData If true, calculate theory only at data points
*/ */
PMusrCanvas::PMusrCanvas(const Int_t number, const Char_t* title, PMusrCanvas::PMusrCanvas(const Int_t number, const Char_t* title,
Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh,

187
src/include/PMusrCanvas.h
View File

@@ -50,65 +50,89 @@
#include "PRunListCollection.h" #include "PRunListCollection.h"
#endif // __MAKECLING__ #endif // __MAKECLING__
#define YINFO 0.1 //--------------------------------------------------------------------------
#define YTITLE 0.95 // Layout constants
#define XTHEO 0.75 //--------------------------------------------------------------------------
#define YINFO 0.1 ///< Y-position of info/legend pad
#define YTITLE 0.95 ///< Y-position of title pad
#define XTHEO 0.75 ///< X-position of theory pad
//--------------------------------------------------------------------------
// Current Plot Views // Current Plot Views
#define PV_DATA 1 //--------------------------------------------------------------------------
#define PV_FOURIER_REAL 2 #define PV_DATA 1 ///< Plot view: time-domain data
#define PV_FOURIER_IMAG 3 #define PV_FOURIER_REAL 2 ///< Plot view: real part of Fourier transform
#define PV_FOURIER_REAL_AND_IMAG 4 #define PV_FOURIER_IMAG 3 ///< Plot view: imaginary part of Fourier transform
#define PV_FOURIER_PWR 5 #define PV_FOURIER_REAL_AND_IMAG 4 ///< Plot view: real and imaginary parts simultaneously
#define PV_FOURIER_PHASE 6 #define PV_FOURIER_PWR 5 ///< Plot view: power spectrum
#define PV_FOURIER_PHASE_OPT_REAL 7 #define PV_FOURIER_PHASE 6 ///< Plot view: phase spectrum
#define PV_FOURIER_PHASE_OPT_REAL 7 ///< Plot view: phase-optimized real part
// Canvas menu id's //--------------------------------------------------------------------------
#define P_MENU_ID_DATA 10001 // Canvas menu IDs
#define P_MENU_ID_FOURIER 10002 //--------------------------------------------------------------------------
#define P_MENU_ID_DIFFERENCE 10003 #define P_MENU_ID_DATA 10001 ///< Menu ID for Data view
#define P_MENU_ID_AVERAGE 10004 #define P_MENU_ID_FOURIER 10002 ///< Menu ID for Fourier submenu
#define P_MENU_ID_EXPORT_DATA 10005 #define P_MENU_ID_DIFFERENCE 10003 ///< Menu ID for Difference view (data-theory)
#define P_MENU_ID_AVERAGE 10004 ///< Menu ID for Average view
#define P_MENU_ID_EXPORT_DATA 10005 ///< Menu ID for Export Data function
#define P_MENU_PLOT_OFFSET 1000 #define P_MENU_PLOT_OFFSET 1000 ///< Offset for plot-specific menu IDs
#define P_MENU_ID_FOURIER_REAL 100 //--------------------------------------------------------------------------
#define P_MENU_ID_FOURIER_IMAG 101 // Fourier submenu IDs
#define P_MENU_ID_FOURIER_REAL_AND_IMAG 102 //--------------------------------------------------------------------------
#define P_MENU_ID_FOURIER_PWR 103 #define P_MENU_ID_FOURIER_REAL 100 ///< Fourier menu: real part
#define P_MENU_ID_FOURIER_PHASE 104 #define P_MENU_ID_FOURIER_IMAG 101 ///< Fourier menu: imaginary part
#define P_MENU_ID_FOURIER_PHASE_OPT_REAL 105 #define P_MENU_ID_FOURIER_REAL_AND_IMAG 102 ///< Fourier menu: real and imaginary
#define P_MENU_ID_FOURIER_PHASE_PLUS 106 #define P_MENU_ID_FOURIER_PWR 103 ///< Fourier menu: power spectrum
#define P_MENU_ID_FOURIER_PHASE_MINUS 107 #define P_MENU_ID_FOURIER_PHASE 104 ///< Fourier menu: phase spectrum
#define P_MENU_ID_FOURIER_PHASE_OPT_REAL 105 ///< Fourier menu: phase-optimized real
#define P_MENU_ID_FOURIER_PHASE_PLUS 106 ///< Fourier menu: increment phase
#define P_MENU_ID_FOURIER_PHASE_MINUS 107 ///< Fourier menu: decrement phase
//------------------------------------------------------------------------ //------------------------------------------------------------------------
/** /**
* <p> * \brief Helper class for managing plot axis ranges.
*
* Stores and manages X and Y axis ranges for plots, allowing explicit
* range specification from MSR file PLOT blocks or automatic range
* determination based on data.
*/ */
class PMusrCanvasPlotRange : public TObject class PMusrCanvasPlotRange : public TObject
{ {
public: public:
/// Default constructor
PMusrCanvasPlotRange(); PMusrCanvasPlotRange();
/// Destructor
virtual ~PMusrCanvasPlotRange() {} virtual ~PMusrCanvasPlotRange() {}
/// Sets X-axis range and marks it as present
virtual void SetXRange(Double_t xmin, Double_t xmax); virtual void SetXRange(Double_t xmin, Double_t xmax);
/// Sets Y-axis range and marks it as present
virtual void SetYRange(Double_t ymin, Double_t ymax); virtual void SetYRange(Double_t ymin, Double_t ymax);
/// Returns true if X-axis range has been explicitly set
virtual Bool_t IsXRangePresent() { return fXRangePresent; } virtual Bool_t IsXRangePresent() { return fXRangePresent; }
/// Returns true if Y-axis range has been explicitly set
virtual Bool_t IsYRangePresent() { return fYRangePresent; } virtual Bool_t IsYRangePresent() { return fYRangePresent; }
/// Returns minimum X value
virtual Double_t GetXmin() { return fXmin; } virtual Double_t GetXmin() { return fXmin; }
/// Returns maximum X value
virtual Double_t GetXmax() { return fXmax; } virtual Double_t GetXmax() { return fXmax; }
/// Returns minimum Y value
virtual Double_t GetYmin() { return fYmin; } virtual Double_t GetYmin() { return fYmin; }
/// Returns maximum Y value
virtual Double_t GetYmax() { return fYmax; } virtual Double_t GetYmax() { return fYmax; }
private: private:
Bool_t fXRangePresent; Bool_t fXRangePresent; ///< Flag: true if X-range explicitly set
Bool_t fYRangePresent; Bool_t fYRangePresent; ///< Flag: true if Y-range explicitly set
Double_t fXmin; Double_t fXmin; ///< Minimum X value
Double_t fXmax; Double_t fXmax; ///< Maximum X value
Double_t fYmin; Double_t fYmin; ///< Minimum Y value
Double_t fYmax; Double_t fYmax; ///< Maximum Y value
ClassDef(PMusrCanvasPlotRange, 1) ClassDef(PMusrCanvasPlotRange, 1)
}; };
@@ -197,44 +221,139 @@ typedef std::vector<PMusrCanvasAsciiDump> PMusrCanvasAsciiDumpVector;
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>The preprocessor tag __MAKECLING__ is used to hide away from rootcling * \brief ROOT-based canvas for interactive visualization of muSR data and fits.
* the overly complex spirit header files. *
* PMusrCanvas provides comprehensive visualization capabilities for muSR data analysis:
*
* **Display Modes:**
* - Time-domain data with fitted theory curves
* - Difference plots (data - theory)
* - Fourier transforms (real, imaginary, power, phase)
* - Phase-optimized real Fourier spectra
* - Averaged data across multiple runs
*
* **Supported Fit Types:**
* - Single histogram fits
* - Asymmetry fits (forward-backward, alpha-beta-LR)
* - Beta-NMR asymmetry
* - Non-muSR data (generic X-Y plots with errors)
*
* **Interactive Features:**
* - Menu-driven view switching (Data/Fourier/Difference/Average)
* - Keyboard shortcuts for quick navigation
* - Phase adjustment for Fourier transforms
* - Data export to ASCII format
* - Graphics export (EPS, PDF, PNG, etc.)
* - Automatic timeout for batch processing
*
* **Canvas Layout:**
* The canvas is divided into several pads:
* - Title pad: Displays MSR file title
* - Data/Theory pad: Main plotting area for histograms/graphs
* - Parameter pad: Shows fitted parameter values
* - Theory pad: Lists theory functions used in fit
* - Info/Legend pad: Displays run information and legend
*
* **Integration:**
* - Reads MSR files via PMsrHandler
* - Accesses fit results via PRunListCollection
* - Uses ROOT's TCanvas and graphics primitives
* - Supports both interactive and batch modes
*
* \note The preprocessor tag __MAKECLING__ is used to hide complex
* Boost Spirit headers from rootcling during dictionary generation
*
* \see PMsrHandler for MSR file management
* \see PRunListCollection for fit results
* \see PMsrFourierStructure for Fourier transform parameters
*/ */
class PMusrCanvas : public TObject, public TQObject class PMusrCanvas : public TObject, public TQObject
{ {
public: public:
/// Default constructor
PMusrCanvas(); PMusrCanvas();
//----------------------------------------------------------------------
/**
* \brief Basic constructor for canvas without custom markers/colors.
*
* \param number Plot number from MSR file PLOT block
* \param title Canvas title
* \param wtopx X-position of canvas window (pixels)
* \param wtopy Y-position of canvas window (pixels)
* \param ww Canvas width (pixels)
* \param wh Canvas height (pixels)
* \param batch If true, run in batch mode (no GUI)
* \param fourier If true, start with Fourier view instead of time domain
* \param avg If true, start with averaged view
* \param theoAsData If true, calculate theory only at data points
*/
PMusrCanvas(const Int_t number, const Char_t* title, PMusrCanvas(const Int_t number, const Char_t* title,
Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, const Bool_t batch, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, const Bool_t batch,
const Bool_t fourier=false, const Bool_t avg=false, const Bool_t theoAsData=false, const Bool_t fourier=false, const Bool_t avg=false, const Bool_t theoAsData=false,
const Bool_t useDKS=false); const Bool_t useDKS=false);
//----------------------------------------------------------------------
/**
* \brief Full constructor with Fourier defaults and custom markers/colors.
*
* \param number Plot number from MSR file PLOT block
* \param title Canvas title
* \param wtopx X-position of canvas window (pixels)
* \param wtopy Y-position of canvas window (pixels)
* \param ww Canvas width (pixels)
* \param wh Canvas height (pixels)
* \param fourierDefault Default Fourier transform parameters
* \param markerList Vector of ROOT marker styles for plots
* \param colorList Vector of ROOT color indices for plots
* \param batch If true, run in batch mode (no GUI)
* \param fourier If true, start with Fourier view instead of time domain
* \param avg If true, start with averaged view
* \param theoAsData If true, calculate theory only at data points
*/
PMusrCanvas(const Int_t number, const Char_t* title, PMusrCanvas(const Int_t number, const Char_t* title,
Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh,
PMsrFourierStructure fourierDefault, PMsrFourierStructure fourierDefault,
const PIntVector markerList, const PIntVector colorList, const Bool_t batch, const PIntVector markerList, const PIntVector colorList, const Bool_t batch,
const Bool_t fourier=false, const Bool_t avg=false, const Bool_t theoAsData=false, const Bool_t fourier=false, const Bool_t avg=false, const Bool_t theoAsData=false,
const Bool_t useDKS=false); const Bool_t useDKS=false);
/// Destructor - cleans up all histograms, graphs, and ROOT objects
virtual ~PMusrCanvas(); virtual ~PMusrCanvas();
/// Returns true if canvas initialized successfully
virtual Bool_t IsValid() { return fValid; } virtual Bool_t IsValid() { return fValid; }
#ifndef __MAKECLING__ #ifndef __MAKECLING__
/// Sets the MSR file handler for accessing fit parameters and configuration
virtual void SetMsrHandler(PMsrHandler *msrHandler); virtual void SetMsrHandler(PMsrHandler *msrHandler);
/// Sets the run list collection for accessing fit data and results
virtual void SetRunListCollection(PRunListCollection *runList) { fRunList = runList; } virtual void SetRunListCollection(PRunListCollection *runList) { fRunList = runList; }
#endif // __MAKECLING__ #endif // __MAKECLING__
/// Sets timeout in seconds after which Done signal is emitted (0=no timeout)
virtual void SetTimeout(Int_t ival); virtual void SetTimeout(Int_t ival);
/// Updates parameter and theory display pads with current fit results
virtual void UpdateParamTheoryPad(); virtual void UpdateParamTheoryPad();
/// Updates main data/theory plotting pad
virtual void UpdateDataTheoryPad(); virtual void UpdateDataTheoryPad();
/// Updates info/legend pad with run information
virtual void UpdateInfoPad(); virtual void UpdateInfoPad();
/// ROOT signal emitted when canvas is closed or timeout occurs
virtual void Done(Int_t status=0); // *SIGNAL* virtual void Done(Int_t status=0); // *SIGNAL*
/// ROOT slot handling keyboard commands (e.g., 'f' for Fourier, 'd' for data)
virtual void HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected); // SLOT virtual void HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected); // SLOT
/// ROOT slot handling menu selections
virtual void HandleMenuPopup(Int_t id); // SLOT virtual void HandleMenuPopup(Int_t id); // SLOT
/// ROOT slot called when this is the last canvas being closed
virtual void LastCanvasClosed(); // SLOT virtual void LastCanvasClosed(); // SLOT
/// ROOT slot called when canvas window is closed
virtual void WindowClosed(); // SLOT virtual void WindowClosed(); // SLOT
/// Saves canvas to graphics file and emits Done signal
virtual void SaveGraphicsAndQuit(Char_t *fileName, Char_t *graphicsFormat); virtual void SaveGraphicsAndQuit(Char_t *fileName, Char_t *graphicsFormat);
/// Exports displayed data to ASCII file
virtual void ExportData(const Char_t *fileName); virtual void ExportData(const Char_t *fileName);
private: private: