Study and characterize coupling between 2 trigger data sets. More...

#include <UUPV.h>

Public Member Functions
void	ComputeVetoSegments (void)
	Computes the veto segments. More...

unsigned int	GetSourceN (void)
	Returns the number of source channels. More...

string	GetSourceName (const unsigned int aSourceIndex)
	Returns the stream name of a given source. More...

bool	GetStatus (void)
	Returns the class status. More...

string	GetTargetName (void)
	Returns the target stream name. More...

unsigned int	GetVetoN (void)
	Returns the current number of vetoes. More...

string	GetVetoName (const unsigned int aVetoIndex)
	Returns the name of a given veto. More...

string	GetVetoName (void)
	Returns the name of the most recent veto. More...

bool	GetVetoPerfFlag (void)
	Returns the VetoPerf flag. More...

bool	GetVetoPrintFlag (void)
	Returns the print-veto flag. More...

Segments *	GetVetoSegments (void)
	Returns a copy of the most recent veto segments. More...

unsigned int	GetVetoUsed (const unsigned int aVetoIndex)
	Returns the number of source clusters used to veto a target cluster. More...

unsigned int	GetVetoUsed (void)
	Returns the number of source clusters used to veto a target cluster. More...

bool	MakeReport (vector< unsigned int > aVetoIndex)
	Generates a html report. More...

bool	MakeVeto (const unsigned int aSourceIndex, Segments *aSelSegments=NULL)
	Loads a set of source triggers and creates a new veto. More...

void	PrintMonitors (const unsigned int aVetoIndex)
	Prints veto monitors as plots in PNG files. More...

void	PrintMonitors (void)
	Prints the most recent veto monitors as plots in PNG files. More...

void	PrintVetoThr (const unsigned int aVetoIndex)
	Prints the veto threshold in a ROOT file. More...

void	PrintVetoThr (void)
	Prints the most recent veto threshold in a ROOT file. More...

void	RemoveVeto (const bool aRemoveDirectory=true)
	Removes the most recent veto from the veto list. More...

void	RemoveVeto (const unsigned int aVetoIndex, const bool aRemoveDirectory=true)
	Removes a given veto from the veto list. More...

void	SetSubTitle (const string aSubTitle)
	Adds a subtitle in the html output. More...

vector< unsigned int >	SortVetoes (void)
	Sorts vetoes by decreasing efficiencies (for html report). More...

void	VetoAttachChannels (vector< unsigned int > aSourceIndexList)
	Attaches a list of source channels to the last veto. More...

Constructors and destructors
	UPV (const string aOptFile, Segments *aInSeg)
	Constructor of the UPV class. More...

virtual	~UPV (void)
	Destructor of the UPV class. More...

Private Member Functions
bool	GetParameters (void)
	Extract parameters from the option file. More...

void	InitVetoMonitors (void)
	Initializes the veto monitors. More...

Private Attributes
Coinc2 *	C2
	Coincs object. More...

Segments *	insegments
	Initial segments. More...

string	optionfile
	Parameter file. More...

string	outdir
	Main output directory. More...

bool	printveto
	Flag to print the veto segments in UPV report. More...

ReadTriggers *	source
	Current source triggers. More...

double	source_clusterdt
	Time clustering to cluster source triggers [s]. More...

unsigned int	source_index
	Current source index. More...

bool	status_OK
	Class status. More...

string	subtitle
	Subtitle. More...

TriggerPlot *	target
	Target triggers. More...

time_t	timer_start
	Timer start. More...

vector< Usource >	usource
	List of sources. More...

vector< Uveto >	uveto
	List of vetoes. More...

unsigned int	verbosity
	Verbosity level. More...

unsigned int	veto_umin
	Veto use min. More...

double	veto_upmin
	Veto use-percentage min. More...

VetoPerf *	vp
	Veto perf object. More...

bool	vp_printveto
	VetoPerf: flag to print the veto segments. More...

bool	vp_printvetoclusters
	VetoPerf: flag to print the veto clusters. More...

bool	vp_report
	VetoPerf: flag to produce a VetoPerf report. More...

vector< double >	vp_snrthr
	VetoPerf SNR thresolds. More...

Detailed Description

Study and characterize coupling between 2 trigger data sets.

The coupling is characterized using 'monitors' which are histograms measuring the trigger parameters as a function of the trigger frequency.

After the coupling is characterized, a veto is optimized for target triggers and using the source triggers.

Author: Florent Robinet - florent.robinet@ijclab.in2p3.fr

Constructor & Destructor Documentation

◆ UPV()

UPV::UPV	(	const string	aOptFile,
		Segments *	aInSeg
	)

Constructor of the UPV class.

The option file is parsed with GetParameters(). Target triggers are loaded and clustered. The coincidence algorithm is initialized.

Parameters

[in]	aOptFile	Path to option file.
[in]	aInSeg	Pointer to input segments.

◆ ~UPV()

UPV::~UPV ( void )

virtual

Destructor of the UPV class.

Member Function Documentation

◆ ComputeVetoSegments()

void UPV::ComputeVetoSegments ( void )

Computes the veto segments.

This function should be called for each generated veto, after MakeVeto() and before MakeReport(). It loops over active source clusters loaded with MakeVeto() and adds a veto segment for each clusters above the veto threshold.

◆ GetParameters()

bool UPV::GetParameters ( void )

private

Extract parameters from the option file.

Downloads the parameters from the option file.

The UPV parameters must be listed in a text file with a system of keywords.

Target triggers

TARGET TRIGGERS [path to trigger files]

This option provides the target trigger dataset. Triggers must be stored in ROOT files following the GWOLLUM convention. The list of trigger files must be separated by a space. Alternatively, a file pattern like /path/to/my/files/myfiles*.root can be used, or even a list of file patterns. With this option, one can also simply give one directory where ROOT files are saved.

TARGET OMICRON [channel name]

Omicron triggers can also be used as target triggers. Here, just specify the name of the channel to consider. Of course, this option only works if Omicron triggers are centrally managed.

TARGET CLUSTERDT [time window]

Target triggers are clustered before being processed. Here you can specify the time window [s] for the clustering. Default: 0.1 s

TARGET SNRMIN [SNR]

Target clusters can be selected. Here specify the minimum SNR. Default: 7.

TARGET FREQUENCYMIN [frequency]

Target clusters can be selected. Here specify the minimum Frequency [Hz]. Default: -1.0 Hz.

TARGET FREQUENCYMAX [frequency]

Target clusters can be selected. Here specify the maximum Frequency [Hz]. Default: 1e20 Hz.

Source triggers

SOURCE TRIGGERS [path to trigger files]

This option provides the source trigger dataset. Triggers must be stored in ROOT files following the GWOLLUM convention. The list of trigger files must be separated by a space. Alternatively, a file pattern like /path/to/my/files/myfiles*.root can be used, or even a list of file patterns. With this option, one can also simply give a list of directories where ROOT files are saved.

Note: This option can be given over several lines, repeating the keywords "SOURCE/TRIGGERS"

Warning: Each option entry is considered as a different source.

SOURCE OMICRON [channel names]

Omicron triggers can also be used as source triggers. Here, just specify the names of channels to consider. Of course this option only works if Omicron triggers are centrally managed.

Note: This option can be given over several lines, repeating the keywords "SOURCE/OMICRON"

Warning: Each option entry is considered as a different source.

SOURCE CLUSTERDT [time window]

Source triggers are clustered before being processed. Here you can specify the time window [s] for the clustering. Default: 0.1 s

Coincidence

COINC TIMEWIN [time window]

Coincidence time window [s]. Default: 1.0 s

See also: Coinc::MakeCoinc().

Vetoes

VETO UMIN [minimum statistic]

Vetoes optimized with UPV require a minimum number of source clusters participating to a coincidence with a target cluster in a frequency bin. Define this parameter here. Default: 10

VETO UPMIN [minimum use-percentage]

Vetoes optimized with UPV require a minimum use-percentage. Define this parameter here. Default: 0.5

VETO PRINT [flag to print veto segments]

Veto segments are printed in text file if the flag is set to a non-zero value. Default: 0

VETO PERF [list of SNR thresholds]

After being optimized, vetoes can be tested using the VetoPerf algorithm. Provide here the list of SNR thresholds (target) to evaluate the veto performance. Default: no VetoPerf analysis.

VETO PERFPRINT [flag to print veto segments] [flag to print vetoed clusters]

Set these flags to 1 (or 0) to print (or not) in the vetoperf report:

the list of veto segments (default: 1)
the list of vetoed target clusters (default: 0)

Output

OUTPUT DIRECTORY [output directory path]

Set the path to the output directory (must exist!) to save the result plots and the html report. Default: current directory.

OUTPUT VERBOSITY [verbosity level]

Set the verbosity level from 0 to 3. Default: 0

Example/template:

// path to output directory
OUTPUT  DIRECTORY ./report
 
// verbosity level
OUTPUT  VERBOSITY 1
 
 
// channel name (for centralized Omicron triggers only)
TARGET OMICRON    V1:Hrec_hoft_16384Hz
 
// ... or: path to the directory with trigger files for the target channel
// TARGET  TRIGGERS  ./triggers/V1:Pr_B1_ACp
 
// SNR threshold applied to target triggers
TARGET  SNRMIN    8
 
// clustering time window [s] for target triggers
TARGET  CLUSTERDT  0.1
 
 
// Maximum time window used for the coincidence [s]
COINC   TIMEWIN   1.0
 
 
// Veto definition: minimum use-percentage (per frequency bin)
VETO UPMIN        0.4
 
// Veto definition: minimum number of source clusters
// used to veto target clusters (per frequency bin)
VETO UMIN        10
 
 
// run VetoPerf at the end of the UPV processing 
// (linked from the UPV web report)
// here, set the list of SNR thresholds
VETO    PERF      5 8 10 20
 
// Set this option to:
// - to print the veto segments (first number set to 1)
// - to print the list of vetoed target clusters (second number set to 1)
VETO    PERFPRINT 1 1
 
 
// List of source channels
// This is the list of directories to find the trigger files
SOURCE TRIGGERS ./triggers/V1:Pr_B8_ACp ./triggers/V1:Pr_B8_ACq
SOURCE TRIGGERS ./triggers/V1:Pr_B8_DC
 
// ... or: use centralized Omicron triggers identified by the source channel names
//SOURCE OMICRON V1:Pr_B8_ACp V1:Pr_B8_ACq
//SOURCE OMICRON V1:Pr_B8_DC
 
// clustering time window [s] for source triggers
SOURCE  CLUSTERDT  0.1

◆ GetSourceN()

unsigned int UPV::GetSourceN ( void )

inline

Returns the number of source channels.

◆ GetSourceName()

string UPV::GetSourceName ( const unsigned int aSourceIndex )

inline

Returns the stream name of a given source.

Parameters

[in] aSourceIndex Source index.

Precondition: The source index must be valid.

◆ GetStatus()

bool UPV::GetStatus ( void )

inline

Returns the class status.

◆ GetTargetName()

string UPV::GetTargetName ( void )

inline

Returns the target stream name.

◆ GetVetoN()

unsigned int UPV::GetVetoN ( void )

inline

Returns the current number of vetoes.

◆ GetVetoName() [1/2]

string UPV::GetVetoName ( const unsigned int aVetoIndex )

inline

Returns the name of a given veto.

Parameters

[in] aVetoIndex Veto index.

Precondition: The veto index must be valid.

◆ GetVetoName() [2/2]

string UPV::GetVetoName ( void )

inline

Returns the name of the most recent veto.

◆ GetVetoPerfFlag()

bool UPV::GetVetoPerfFlag ( void )

inline

Returns the VetoPerf flag.

◆ GetVetoPrintFlag()

bool UPV::GetVetoPrintFlag ( void )

inline

Returns the print-veto flag.

◆ GetVetoSegments()

Segments* UPV::GetVetoSegments ( void )

inline

Returns a copy of the most recent veto segments.

◆ GetVetoUsed() [1/2]

unsigned int UPV::GetVetoUsed ( const unsigned int aVetoIndex )

inline

Returns the number of source clusters used to veto a target cluster.

Parameters

[in] aVetoIndex Veto index.

Precondition: The veto index must be valid.

◆ GetVetoUsed() [2/2]

unsigned int UPV::GetVetoUsed ( void )

inline

Returns the number of source clusters used to veto a target cluster.

Note: The most recent veto tuned with MakeVeto() is considered.

◆ InitVetoMonitors()

void UPV::InitVetoMonitors ( void )

private

Initializes the veto monitors.

◆ MakeReport()

bool UPV::MakeReport ( vector< unsigned int > aVetoIndex )

Generates a html report.

The VetoPerf report is also generated if requested in the UPV option file: see GetParameters().

Parameters

[in] aVetoIndex Sorted list of veto indices.

◆ MakeVeto()

bool UPV::MakeVeto	(	const unsigned int	aSourceIndex,
		Segments *	aSelSegments = `NULL`
	)

Loads a set of source triggers and creates a new veto.

The source triggers are loaded and clustered. The resulting clusters are set in coincidence with the target clusters.

A new veto is created and tuned using the coincidence results. All the tuning monitors are saved in memory as well as the veto threshold.

The veto threshold is a SNR threshold which is frequency dependent. It applies to the source triggers. The veto threshold is tuned to have a minimum source use-percentage and a minimum number of coincident clusters, as requested from the option file.

Note: This function can be called multiple times for the same source. A new veto is created every time.

Parameters

[in]	aSourceIndex	Source index.
[in]	aSelSegments	If not NULL, these segments are used to select the coincidence segments.

◆ PrintMonitors() [1/2]

void UPV::PrintMonitors ( const unsigned int aVetoIndex )

Prints veto monitors as plots in PNG files.

The PNG files are saved in the veto output directory.

Parameters

[in] aVetoIndex Veto index

Precondition: The veto index must be valid.

◆ PrintMonitors() [2/2]

void UPV::PrintMonitors ( void )

inline

Prints the most recent veto monitors as plots in PNG files.

The PNG files are saved in the veto output directory.

◆ PrintVetoThr() [1/2]

void UPV::PrintVetoThr ( const unsigned int aVetoIndex )

Prints the veto threshold in a ROOT file.

The ROOT file is saved in the veto output directory.

Parameters

[in] aVetoIndex Veto index

Precondition: The veto index must be valid.

◆ PrintVetoThr() [2/2]

void UPV::PrintVetoThr ( void )

inline

Prints the most recent veto threshold in a ROOT file.

The ROOT file is saved in the veto output directory.

◆ RemoveVeto() [1/2]

void UPV::RemoveVeto ( const bool aRemoveDirectory = true )

inline

Removes the most recent veto from the veto list.

Parameters

[in] aRemoveDirectory Set this flag to true to also remove the veto directory and its content.

◆ RemoveVeto() [2/2]

void UPV::RemoveVeto	(	const unsigned int	aVetoIndex,
		const bool	aRemoveDirectory = `true`
	)

Removes a given veto from the veto list.

Parameters

[in]	aVetoIndex	Veto index.
[in]	aRemoveDirectory	Set this flag to true to also remove the veto directory and its content.

◆ SetSubTitle()

void UPV::SetSubTitle ( const string aSubTitle )

inline

Adds a subtitle in the html output.

Parameters

[in] aSubTitle Subtitle string.

◆ SortVetoes()

vector< unsigned int > UPV::SortVetoes ( void )

Sorts vetoes by decreasing efficiencies (for html report).

Returns: The sorted list of veto indices. To be used with MakeReport().

◆ VetoAttachChannels()

void UPV::VetoAttachChannels ( vector< unsigned int > aSourceIndexList )

Attaches a list of source channels to the last veto.

A list of source channels can be attached to a veto. It is provided as a list of source indices. The list of channels is printed in a text file in the veto directory: "veto_attached.txt".

Parameters

[in] aSourceIndexList List of source indices.

Member Data Documentation

◆ C2

Coinc2* UPV::C2

private

Coincs object.

◆ insegments

Segments* UPV::insegments

private

Initial segments.

◆ optionfile

string UPV::optionfile

private

Parameter file.

◆ outdir

string UPV::outdir

private

Main output directory.

◆ printveto

bool UPV::printveto

private

Flag to print the veto segments in UPV report.

◆ source

ReadTriggers* UPV::source

private

Current source triggers.

◆ source_clusterdt

double UPV::source_clusterdt

private

Time clustering to cluster source triggers [s].

◆ source_index

unsigned int UPV::source_index

private

Current source index.

◆ status_OK

bool UPV::status_OK

private

Class status.

◆ subtitle

string UPV::subtitle

private

Subtitle.

◆ target

TriggerPlot* UPV::target

private

Target triggers.

◆ timer_start

time_t UPV::timer_start

private

Timer start.

◆ usource

vector<Usource> UPV::usource

private

List of sources.

◆ uveto

vector<Uveto> UPV::uveto

private

List of vetoes.

◆ verbosity

unsigned int UPV::verbosity

private

Verbosity level.

◆ veto_umin

unsigned int UPV::veto_umin

private

Veto use min.

◆ veto_upmin

double UPV::veto_upmin

private

Veto use-percentage min.

◆ vp

VetoPerf* UPV::vp

private

Veto perf object.

◆ vp_printveto

bool UPV::vp_printveto

private

VetoPerf: flag to print the veto segments.

◆ vp_printvetoclusters

bool UPV::vp_printvetoclusters

private

VetoPerf: flag to print the veto clusters.

◆ vp_report

bool UPV::vp_report

private

VetoPerf: flag to produce a VetoPerf report.

◆ vp_snrthr

vector<double> UPV::vp_snrthr

private

VetoPerf SNR thresolds.

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

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ UPV()

◆ ~UPV()

Member Function Documentation

◆ ComputeVetoSegments()

◆ GetParameters()

Target triggers

Source triggers

Coincidence

Vetoes

Output

◆ GetSourceN()

◆ GetSourceName()

◆ GetStatus()

◆ GetTargetName()

◆ GetVetoN()

◆ GetVetoName() [1/2]

◆ GetVetoName() [2/2]

◆ GetVetoPerfFlag()

◆ GetVetoPrintFlag()

◆ GetVetoSegments()

◆ GetVetoUsed() [1/2]

◆ GetVetoUsed() [2/2]

◆ InitVetoMonitors()

◆ MakeReport()

◆ MakeVeto()

◆ PrintMonitors() [1/2]

◆ PrintMonitors() [2/2]

◆ PrintVetoThr() [1/2]

◆ PrintVetoThr() [2/2]

◆ RemoveVeto() [1/2]

◆ RemoveVeto() [2/2]

◆ SetSubTitle()

◆ SortVetoes()

◆ VetoAttachChannels()

Member Data Documentation

◆ C2

◆ insegments

◆ optionfile

◆ outdir

◆ printveto

◆ source

◆ source_clusterdt

◆ source_index

◆ status_OK

◆ subtitle

◆ target

◆ timer_start

◆ usource

◆ uveto

◆ verbosity

◆ veto_umin

◆ veto_upmin

◆ vp

◆ vp_printveto

◆ vp_printvetoclusters

◆ vp_report

◆ vp_snrthr