Detailed Description

A helper class to draw the evolution or correlation of metadata information from a set of REST files.

TRestMetadataPlot will allow to take a set or range of files and create TGraph objects with any two metadata members defined in any metadata class inside the REST-ROOT processed files. The class TRestMetadataPlot works in a similar way to TRestAnalysisPlot. While TRestAnalysisPlot serves to draw and combine data from different event observables found at the TRestAnalysisTree, TRestMetadataPlot is used to draw and correlate the metadata information that is found at different metadata classes inside TRestRun.

1. Adding REST files for plotting

This class can be initialized through a RML configuration file where we define the different plots and graphs to be produced. The files that will be used for plot generation can be added to the class using the restManager command as follows:

restManager --c mdPlots.rml --f "/full/or/relative/path/to/data/R012*Hits*.root"

The previous execution will search for the files matching the given pattern, at the path given. I.e. it will collect all the files with run number starting by 012 and containing Hits inside its name.

Each of the files on the filelist produced will be used to generate one point at the graphs defined inside the mdPlots.rml file.

The metadata variables can be specified at the graphs or plots by using the following format TRestMetadataClass::fMetadataMember or TRestMetadataClass->fMetadataMember. Where TRestMetadataClass is the name of the class/object or the name ROOT name associated to the class, and that it is usually retrieved using the method GetName().

2. writing the RML metadata section

The RML section allows to define the main properties of the canvas to be generated, basic or common properties of each plot, and the definition of the plots description and graph properties together with the specification of the metadata to be used in the graph. A working example with minimum modifications can be found at examples/metadataPlot.rml.

This metadata class receives only an optional parameter, previewPlot, that is true by default if it has not been defined. If this parameter is true it will show the produced canvas on screen, and the user will be allowed to interact with it. If not, plots will be just written to disk as defined by the parameter save defined in the main canvas, or in separate plots.

Canvas definition

The canvas will be divided in different pads where the plots defined inside this class will be placed. The canvas section allows us to define the size of the canvas in pixels, how it will be divided, and optionally the file where it will be saved. It is important to notice that the number of pad divisions must be enough to host the total number of plots given.

Legend properties

If we use a legend in our plots, we can define its properties and position using the legend key.

An example, of definition of the legend key. The ROOT drawing option lp is used to draw the line and the point. Please, check the documentation of TLegend for other available options.

Warning: For the moment this entry is common to all the plots, althought it would be desirable that in the future we are allowed to define the legend properties for each single plot independently. The positions are defined with coordinates relative to the pad using the ROOT object TLegend.

Plot properties

Inside a TRestMetadataPlot RML section we are allowed to define any number of plots, and inside a graph we are allowed to define any number of graphs.

The only mandatory field inside the plot description is the xVariable to be used on the x-axis of the resulting plot.

The parameters that can be defined (see also TRestMetadataPlot::Plot_Info_Set) inside each <plot section are:

name: The default name that will be used for the TGraph object if no name is explicitly given.
title: An optional title that will be shown on the top of the plot.
xVariable: A mandatory field specifying the variable, extracted from a metadata member to be used for the x-axis. The keyword "timestamp" can be used instead of the data member so that the run middle time is considered.
logscale (or logY): It defines a logarithmic scale on the y-axis.
logX: It defines a logarithmic scale on the x-axis.
xlabel: The label or title to be given to the x-axis.
ylabel: The label or title to be given to the y-axis.
legend: If it is "true" or "on" the legend of the plot will be displayed.
timeDisplay: If it is "true" or "on" the x-axis will be translated to a date/time format. The value given at xVariable should be a valid UNIX timestamp.
save: A filename specifying the output where the current plot will be saved. Any image/document format supported by ROOT will be accepted.
xRange: It allows to define manually the x-range to be used in the plot. If not given, ROOT will automatically define the range.
yRange: We can provide optionally the range to be used in the plot. If not, it will be automatically calculated as 80%-120% of the minimum-maximum values.

Note: As previously mentioned, the xVariable must be a valid metadata member. However, there is one exception where we are allowed to use the timestamp keyword so that the middle time of each run is used on the x-axis.

Graph properties

Inside each plot we can define any number of graphs to be plotted together. Each graph must define a unique name and the corresponding yVariable to be used on the graph data. Those fields are mandatory.

The parameters that can be defined inside each <graph section are:

name: The default name that will be used for the TGraph object if no name is explicitely given.
title: An optional title that will be shown on the top of the plot.
yVariable: A mandatory field specifying the variable, extracted from a metadata member to be used for the y-axis.
option: It defines the ROOT option to be used at the TGraph Draw method. The available options are defined by the ROOT class TGraphPainter, please, check the official ROOT documentation of TGraphPainter to see all the available options.

Including metadata rules, or conditions

When we provide a set of files we may filter the input files passed to the class to create a selection that will follow a certain condition or metadata rule. Only the files fulfilling the given conditions will contribute to the TGraph.

In order to use this feature we need to define the metadataRule parameter specifying the condition to be satisfied. Any numerical operator is allowed, as well as direct string comparison.

The following line inside the <graph definition would force the corresponding graph to include points extracted only from files where the fRunTag metadata member is equal to `Calibration_BIPO`.

<parameter name="metadataRule" value="TRestRun->fRunTag==Calibration_BIPO" />

Warning: for the moment the conditions can be applied to a single metadata member. Or in other words, we cannot create a metadata rule based on the combination of different conditions on different metadata parameters.

Adding panels

Additionally, we can add a pad to the canvas containing basic information. As it is implemented, this panel will only be able to gather the run information from the first file given in the filelist. Therefore it might be useful to show only information common to all the files.

The panel is built defining labels where metadata members given between << >> are replaced by the corresponding run values.

<panel font_size="0.06">
    <label value="Run number : <<TRestRun::fRunNumber>>" x="0.25" y="0.9" />
    ...

The panel it is given at the same level as the <plot, as it will fill a given pad region inside the canvas. Additional keywords are available, and calculated inside the class with all the files passed. Those keywords are also enclosed between << >>, and are the following ones:

startTime: The earliest (or lowest) start time found between all the files given.
endTime: The latest (or highest) end time found between all the files given.
entries: The integrated number of entries using all the filelist given to the class.
runLength: The integrated run length in hours using all the filelist given to the class.
meanRate: The rate calculated as the result of the total number of entries and the run length, the resulting rate is expressed in Hz.

Note: All panels will be always placed at the first pads of the canvas, independently of the order given inside the RML file.

RESTsoft - Software for Rare Event Searches with TPCs

History of developments:

2020-June: First concept and implementation

Author: Javier Galan

Definition at line 32 of file TRestMetadataPlot.h.

#include <TRestMetadataPlot.h>

Inheritance diagram for TRestMetadataPlot:

Data Structures
struct	Graph_Info_Set
	This structure is used to register the values from a <graph definition inside the RML. More...

struct	Panel_Info
	This structure is used to register the values from a <panel definition inside the RML. More...

struct	Plot_Info_Set
	This structure is used to register the values from a <plot definition inside the RML. More...

Public Member Functions
	ClassDefOverride (TRestMetadataPlot, 3)

void	GenerateCanvas ()
	The main method of this class, collecting the input files, producing the TGraphs and generating the plots inside the main canvas.

TVector2	GetCanvasDivisions () const
	It will return the number of divisions inside the canvas.

TVector2	GetCanvasSize () const
	It will return the canvas size in pixel units.

Int_t	GetPlotIndex (TString plotName)
	It returns the index of the array correspoding to the plot with the given plotName.

void	Initialize () override
	Initialization of TRestMetadataPlot data members.

void	PrintMetadata () override
	Implemented it in the derived metadata class to print out specific metadata information. More...

void	SaveCanvasToPDF (TString fileName)
	A method to execute the generation of an output file with the contents of the TCanvas as it is. The name of the output file is given through the argument.

void	SaveGraphToPDF (TString fileName, Int_t nPlot=0, Int_t nGraph=0)
	A method to execute the generation of a particular graph from a plot inside the canvas using the index of the plot, and the index of the graph. The name of the output file is given through the argument.

void	SavePlotToPDF (TString fileName, Int_t n=0)
	A method to execute the generation of a plot inside the canvas using the index of the plot. The name of the output file is given through the argument.

void	SetOutputPlotsFilename (TString fname)
	It will set the filename of the plots output file to be generated when GenerateCanvas is called.

	TRestMetadataPlot ()
	Default constructor.

	TRestMetadataPlot (const char configFilename, const char name="")
	Constructor loading data from a config file. More...

virtual	~TRestMetadataPlot ()
	Default destructor.

Public Member Functions inherited from TRestMetadata
void	AddLog (std::string log="", bool print=true)
	Add logs to messageBuffer.

void	DoNotStore ()
	If this method is called the metadata information will not be stored in disk.

TVector2	Get2DVectorParameterWithUnits (std::string parName, TVector2 defaultValue=TVector2(-1, -1))

TVector3	Get3DVectorParameterWithUnits (std::string parName, TVector3 defaultValue=TVector3(-1, -1, -1))

TString	GetCommit ()
	Returns the REST commit value stored in fCommit.

std::string	GetConfigBuffer ()
	Returns the config section of this class.

std::string	GetDataMemberValue (std::string memberName)
	Get the value of data member as string. More...

std::vector< std::string >	GetDataMemberValues (std::string memberName, Int_t precision=0)
	Get the value of datamember as a vector of strings. More...

TString	GetDataPath ()
	Returns a std::string with the path used for data storage.

Double_t	GetDblParameterWithUnits (std::string parName, Double_t defaultValue=PARAMETER_NOT_FOUND_DBL)
	Gets the value of the parameter name parName, after applying unit conversion. More...

Bool_t	GetError () const
	It returns true if an error was identified by a derived metadata class.

TString	GetErrorMessage ()
	Returns a std::string containing the error message.

TString	GetLibraryVersion ()
	Returns the REST libraty version stored in fLibraryVersion.

TString	GetMainDataPath ()
	Gets a std::string with the path used for data storage.

Int_t	GetNumberOfErrors () const

Int_t	GetNumberOfWarnings () const

std::string	GetParameter (std::string parName, TString defaultValue=PARAMETER_NOT_FOUND_STR)
	Returns corresponding REST Metadata parameter from multiple sources. More...

std::string	GetSectionName ()
	Returns the section name of this class, defined at the beginning of fSectionName.

TRestStringOutput::REST_Verbose_Level	GetVerboseLevel ()
	returns the verboselevel in type of REST_Verbose_Level enumerator

TString	GetVerboseLevelString ()
	returns the verbose level in type of TString More...

TString	GetVersion ()
	Returns the REST version stored in fVersion.

Int_t	GetVersionCode ()

UInt_t	GetVersionMajor () const

UInt_t	GetVersionMinor () const

UInt_t	GetVersionPatch () const

Bool_t	GetWarning () const
	It returns true if an error was identified by a derived metadata class.

TString	GetWarningMessage ()
	Returns a std::string containing the warning message.

TRestMetadata *	InstantiateChildMetadata (int index, std::string pattern="")
	This method will retrieve a new TRestMetadata instance of a child element of the present TRestMetadata instance based on the `index` given by argument, which defines the element order to be retrieved, 0 for first element found, 1 for the second element found, etc. More...

TRestMetadata *	InstantiateChildMetadata (std::string pattern="", std::string name="")
	This method will retrieve a new TRestMetadata instance of a child element of the present TRestMetadata instance based on the `name` given by argument. More...

Bool_t	isCleanState () const

Bool_t	isOfficialRelease () const

Int_t	LoadConfigFromBuffer ()
	Initialize data from a string element buffer. More...

Int_t	LoadConfigFromElement (TiXmlElement eSectional, TiXmlElement eGlobal, std::map< std::string, std::string > envs={})
	Main starter method. More...

Int_t	LoadConfigFromFile (const std::string &configFilename, const std::string &sectionName="")
	Give the file name, find out the corresponding section. Then call the main starter.

virtual void	Merge (const TRestMetadata &)

TRestMetadata &	operator= (const TRestMetadata &)

void	Print ()
	Implementing TObject::Print() method.

void	PrintConfigBuffer ()
	Print the config xml section stored in the class. More...

void	PrintMessageBuffer ()
	Print the buffered message.

void	PrintTimeStamp (Double_t timeStamp)
	Print the current time on local machine. More...

void	SetConfigFile (std::string configFilename)
	set config file path from external

void	SetError (std::string message="", bool print=true, int maxPrint=5)
	A metadata class may use this method to signal that something went wrong.

void	SetHostmgr (TRestManager *m)
	Set the host manager for this class.

void	SetSectionName (std::string sName)
	set the section name, clear the section content

void	SetVerboseLevel (TRestStringOutput::REST_Verbose_Level v)
	sets the verbose level

void	SetWarning (std::string message="", bool print=true, int maxPrint=5)
	A metadata class may use this method to signal that something went wrong.

void	Store ()
	If this method is called the metadata information will be stored in disk.

	TRestMetadata (const TRestMetadata &)

virtual void	UpdateMetadataMembers ()
	Method to allow implementation of specific metadata members updates at inherited classes.

virtual Int_t	Write (const char *name=nullptr, Int_t option=0, Int_t bufsize=0)
	overwriting the write() method with fStore considered

void	WriteConfigBuffer (std::string fName)
	Writes the config buffer to a file in append mode.

	~TRestMetadata ()
	TRestMetadata default destructor.

Private Member Functions
void	AddFile (TString fileName)
	It creates a new TRestRun object extracted from the fileName, and it adds it to the list of input files beloning to this class.

void	AddFileFromEnv ()
	We can add input file from parameter "inputFile".

void	AddFileFromExternalRun ()
	We can add input file from process's output file.

void	InitFromConfigFile () override
	Initialization of TRestMetadataPlot members through a RML file.

Graph_Info_Set	SetupGraphFromConfigFile (TiXmlElement *ele, Plot_Info_Set info)
	It fills the components of a Graph_Info_set object using the definition inside a <graph element.

Private Attributes
TVector2	fCanvasDivisions
	The number of canvas divisions on X and Y.

TString	fCanvasSave
	A std::string to define the output filename where to store the canvas.

TVector2	fCanvasSize
	The size of the canvas window in pixels.

TCanvas *	fCombinedCanvas
	Output canvas.

Int_t	fLabelFont
	The font label size.

Double_t	fLabelOffsetX = 1.1
	A label offset to be applied in the x-label (not tested)

Double_t	fLabelOffsetY = 1.3
	A label offset to be applied in the y-label (not tested)

Double_t	fLabelScaleX = 1.2
	A label title scale to be applied in the x-label (not tested)

Double_t	fLabelScaleY = 1.3
	A label title scale to be applied in the y-label (not tested)

TString	fLegendOption = "lp"
	The legend drawing option.

Double_t	fLegendX1 = 0.7
	The X1 legend position.

Double_t	fLegendX2 = 0.88
	The X2 legend position.

Double_t	fLegendY1 = 0.75
	The Y1 legend position.

Double_t	fLegendY2 = 0.88
	The Y2 legend position.

Int_t	fNFiles
	The total number of files for plotting added to this class.

std::vector< Panel_Info >	fPanels
	A std::vector with the defined panels.

std::vector< std::string >	fPlotNamesCheck
	A std::vector to double check that there are no repeated graph names.

std::vector< Plot_Info_Set >	fPlots
	A std::vector with the defined plots.

TRestRun *	fRun
	TRestRun to handle output file.

std::vector< std::string >	fRunInputFileName
	To keep a list of files used.

Double_t	fTicksScaleX = 1.5
	A label ticks scale to be applied in the x-label (not tested)

Double_t	fTicksScaleY = 1.5
	A label ticks scale to be applied in the y-label (not tested)

Additional Inherited Members
Protected Member Functions inherited from TRestMetadata
std::string	ElementToString (TiXmlElement *ele)
	Convert an TiXmlElement object to string. More...

TVector2	Get2DVectorParameterWithUnits (std::string parName, TiXmlElement *e, TVector2 defaultValue=TVector2(-1, -1))

TVector3	Get3DVectorParameterWithUnits (std::string parName, TiXmlElement *e, TVector3 defaultValue=TVector3(-1, -1, -1))

Double_t	GetDblParameterWithUnits (std::string parName, TiXmlElement *e, Double_t defaultVal=PARAMETER_NOT_FOUND_DBL)

TiXmlElement *	GetElement (std::string eleDeclare, TiXmlElement *e=nullptr)
	Get an xml element from a given parent element, according to its declaration.

TiXmlElement *	GetElementFromFile (std::string configFilename, std::string NameOrDecalre="")
	Open an xml encoded file and find its element. More...

TiXmlElement *	GetElementWithName (std::string eleDeclare, std::string eleName)
	Get an xml element from the default location, according to its declaration and its field "name".

TiXmlElement *	GetElementWithName (std::string eleDeclare, std::string eleName, TiXmlElement *e)
	Get an xml element from a given parent element, according to its declaration and its field "name".

std::string	GetFieldValue (std::string fieldName, std::string definition, size_t fromPosition=0)
	Gets field value in an xml element string by parsing it as TiXmlElement.

std::string	GetFieldValue (std::string parName, TiXmlElement *e)
	Returns the field value of an xml element which has the specified name. More...

std::string	GetKEYDefinition (std::string keyName)
	Gets the first key definition for keyName found inside buffer starting at fromPosition. More...

std::string	GetKEYDefinition (std::string keyName, size_t &Position)

std::string	GetKEYDefinition (std::string keyName, size_t &Position, std::string buffer)

std::string	GetKEYDefinition (std::string keyName, std::string buffer)

std::string	GetKEYStructure (std::string keyName)
	Gets the first key structure for keyName found inside buffer after fromPosition. More...

std::string	GetKEYStructure (std::string keyName, size_t &Position)

std::string	GetKEYStructure (std::string keyName, size_t &Position, std::string buffer)

std::string	GetKEYStructure (std::string keyName, size_t &Position, TiXmlElement *ele)

std::string	GetKEYStructure (std::string keyName, std::string buffer)

TiXmlElement *	GetNextElement (TiXmlElement *e)
	Get the next sibling xml element of this element, with same eleDeclare.

std::string	GetParameter (std::string parName, size_t &pos, std::string inputString)
	Returns the value for the parameter name parName found in inputString. More...

std::string	GetParameter (std::string parName, TiXmlElement *e, TString defaultValue=PARAMETER_NOT_FOUND_STR)
	Returns the value for the parameter named parName in the given section. More...

std::pair< std::string, std::string >	GetParameterAndUnits (std::string parname, TiXmlElement *e=nullptr)
	Returns the unit string of the given parameter of the given xml section. More...

std::map< std::string, std::string >	GetParametersList ()
	It retrieves a map of all parameter:value found in the metadata class.

TString	GetSearchPath ()

virtual void	InitFromRootFile ()
	Method called after the object is retrieved from root file.

virtual Int_t	LoadSectionMetadata ()
	This method does some preparation of xml section. More...

void	ReadAllParameters ()
	Reflection methods, Set value of a datamember in class according to TRestMetadata::fElement. More...

void	ReadParametersList (std::map< std::string, std::string > &list)
	It reads a parameter list and associates it to its corresponding metadata member. par0 --> fPar0.

std::string	ReplaceConstants (const std::string buffer)
	Identifies "constants" in the input buffer, and replace them with corresponding value. More...

std::string	ReplaceVariables (const std::string buffer)
	Identifies environmental variable replacing marks in the input buffer, and replace them with corresponding value. More...

void	ReSetVersion ()
	Resets the version of TRestRun to REST_RELEASE. Only TRestRun is allowed to update version.

std::string	SearchFile (std::string filename)
	Search files in current directory and directories specified in "searchPath" section. More...

void	SetLibraryVersion (TString version)
	Set the library version of this metadata class.

TiXmlElement *	StringToElement (std::string definition)
	Parsing a string into TiXmlElement object. More...

	TRestMetadata ()
	TRestMetadata default constructor.

	TRestMetadata (const char *configFilename)
	constructor

void	UnSetVersion ()
	Resets the version of TRestRun to -1, in case the file is old REST file. Only TRestRun is allowed to update version.

Protected Attributes inherited from TRestMetadata
std::string	configBuffer
	The buffer where the corresponding metadata section is stored. Filled only during Write()

std::string	fConfigFileName
	Full name of the rml file. More...

std::map< std::string, std::string >	fConstants
	Saving a list of rml constants. name-value std::pair. Constants are temporary for this class only.

TiXmlElement *	fElement
	Saving the sectional element together with global element.

TiXmlElement *	fElementGlobal
	Saving the global element, to be passed to the resident class, if necessary.

Bool_t	fError = false
	It can be used as a way to identify that something went wrong using SetError method.

TString	fErrorMessage = ""
	A std::string to store an optional error message through method SetError.

TRestManager *	fHostmgr
	All metadata classes can be initialized and managed by TRestManager.

Int_t	fNErrors = 0
	It counts the number of errors notified.

Int_t	fNWarnings = 0
	It counts the number of warnings notified.

std::string	fSectionName
	Section name given in the constructor of the derived metadata class.

Bool_t	fStore
	This variable is used to determine if the metadata structure should be stored in the ROOT file.

std::map< std::string, std::string >	fVariables
	Saving a list of rml variables. name-value std::pair.

TRestStringOutput::REST_Verbose_Level	fVerboseLevel
	Verbose level used to print debug info.

Bool_t	fWarning = false
	It can be used as a way to identify that something went wrong using SetWarning method.

TString	fWarningMessage = ""
	It can be used as a way to identify that something went wrong using SetWarning method.

std::string	messageBuffer
	The buffer to store the output message through TRestStringOutput in this class.

endl_t	RESTendl
	Termination flag object for TRestStringOutput.

Constructor & Destructor Documentation

◆ TRestMetadataPlot()

TRestMetadataPlot::TRestMetadataPlot	(	const char *	configFilename,
		const char *	name = `""`
	)

Constructor loading data from a config file.

If no configuration path is defined using TRestMetadata::SetConfigFilePath the path to the config file must be specified using full path, absolute or relative.

The default behaviour is that the config file must be specified with full path, absolute or relative.

Parameters

configFilename	A const char* giving the path to an RML file.
name	The name of the specific metadata. It will be used to find the corresponding TRestGeant4Metadata section inside the RML.

Definition at line 268 of file TRestMetadataPlot.cxx.

Member Function Documentation

◆ PrintMetadata()

void TRestMetadataPlot::PrintMetadata ( )

inlineoverridevirtual

Implemented it in the derived metadata class to print out specific metadata information.

Prints metadata content on screen. Usually overloaded by the derived metadata class.

Reimplemented from TRestMetadata.

Definition at line 178 of file TRestMetadataPlot.h.

The documentation for this class was generated from the following files: