Ox analysis results. More...

#include <OxResults.h>

Inheritance diagram for OxResults:

[legend]

Collaboration diagram for OxResults:

[legend]

Public Member Functions
bool	CreateOutputFile (void)
	Creates an ouput Ox file to save results.

OxResultType	GetEventResultType (void)
	Returns the result type of the current event.

unsigned int	GetProcessedEventsN (OxResultType aResultType)
	Returns the number of processed events.

double	GetRankDetectionThreshold (void)
	Returns the detection threshold on the event rank.

bool	MakeHtml (void)
	Generates an html report in the output directory.

bool	Process (void)
	Processes the list of Ox events.

double	RankToRate (OxResultType aResultType, const double aRank, const int aType=0)
	Returns the event rate at a given rank [Hz].

double	RateToRank (OxResultType aResultType, const double aRate)
	Returns the event rank at a given rate.

bool	SavePlots (const string aFormat="png")
	Saves all the result plots in the output directory.

Constructors and destructors
	OxResults (const string aOptionFile, const unsigned int aGpsRef)
	Constructor of the OxResults class.

virtual	~OxResults (void)
	Destructor of the OxResults class.

Public Member Functions inherited from OxEvent
bool	CreateOutputFile (string &aOutFileName, const unsigned int aTime)
	Creates an ouput file.

Long64_t	GetEntries (void)
	Returns the number of events in the input Ox files.

int	GetEntry (const Long64_t aEntry)
	Loads an entry in the event TTree (read-only).

UChar_t	GetEventAnalysisIndex (void)
	Returns the analysis index for the current event.

double	GetEventFrequency (void)
	Returns the frequency for the current event [Hz].

unsigned int	GetEventFrequencyRowRejectedN (const unsigned int aQindex)
	Returns the number of rejected frequency rows for the the current event.

double	GetEventIntegratedXi (const unsigned int aQindex)
	Returns the integrated cross-correlation \(\Xi\) for the the current event.

double	GetEventRank (void)
	Returns the rank for the current event.

unsigned int	GetEventSliceIndex (void)
	Returns the slice index for the current event.

double	GetEventTimeDelay (void)
	Returns the time delay for the the current event [s].

double	GetEventTimeVariance (const unsigned int aQindex)
	Returns the time variance along frequency rows for the the current event [s^2].

double	GetSliceHalfDuration (void)
	Returns the half duration of one slice [s].

unsigned int	GetSliceIndexCenter (void)
	Returns the index of the slice at the center of the cross-correlation map.

unsigned int	GetSliceN (void)
	Returns the number of slices in one cross-correlation map.

double	GetSliceTimeDelay (const unsigned int aSliceIndex)
	Returns the time delay at the center of a slice [s].

unsigned int	GetSliceTimeDelayBinsN (void)
	Returns the number of time-delay bins in one slice.

unsigned int	GetSliceUnusedTimeDelayBinsN (void)
	Returns the number of unsed time-delay bins after slicing.

bool	MakeEvent (const unsigned int aSliceIndex, const UChar_t aAnalysisIndex=0)
	Constructs an Ox event.

bool	MakeHtml (void)
	Generates an html report for the current event.

bool	SaveEvents (const UChar_t aAnalysisIndex=0)
	Save events in the TTree.

	OxEvent (const string aOptionFile, const unsigned int aGpsRef)
	Constructor of the OxEvent class.

virtual	~OxEvent (void)
	Destructor of the OxEvent class.

Public Member Functions inherited from OxCorr
double	GetTimeDelay (const unsigned int aTimeDelayBinIndex)
	Returns the time delay of a bin \(n\) in the cross-correlation map [s].

unsigned int	GetTimeDelayBinIndex (const double aTimeDelay)
	Returns the time-delay bin index \(n\) for a given time delay.

unsigned int	GetTimeDelayBinsN (void)
	Returns the number of time-delay bins \(N\).

double	GetTimeDelayResolution (void)
	Returns the time-delay resolution [s].

double	GetXi (const unsigned int aQindex, const unsigned int aFrequencyIndex, const unsigned int aTimeDelayIndex)
	Returns the cross-correlation coefficient \(\xi(Q,f,dt)=\xi[\lambda][q][l][n]\).

bool	Process (void)
	Runs the cross-correlation analysis.

bool	Transform (const unsigned int aDetectorIndex)
	Transforms the Omicron spectrogram in the Fourier domain.

bool	WriteMaps (const double aTimeDelay=1.0e20)
	Writes maps in the output directory as png files.

	OxCorr (const string aOptionFile, const unsigned int aGpsRef)
	Constructor of the OxCorr class.

virtual	~OxCorr (void)
	Destructor of the OxCorr class.

Public Member Functions inherited from OxOmicron
bool	CreateOutputFile (string &aOutFileName, const unsigned int aTime)
	Creates an ouput file.

void	DumpOmicronOptions (const unsigned int aDetectorIndex, const string aOutFile)
	Dumps Omicron options in a text file.

unsigned int	GetAnalysisDuration (void)
	Returns the Ox analysis duration [s].

Long64_t	GetEntries (const unsigned int aDetectorIndex)
	Returns the number of Omicron analysis results in the input Ox files.

int	GetEntry (const unsigned int aDetectorIndex, Long64_t aEntry)
	Loads an entry in the Omicron results in the input Ox files.

double	GetLightTravelTime (void)
	Returns the maximum light travel time between the two detectors.

unsigned int	GetOmicronChunkDuration (void)
	Returns the Omicron chunk duration [s].

unsigned int	GetOmicronEndTime (const unsigned int aDetectorIndex)
	Returns the current spectrogram end time.

unsigned int	GetOmicronOverlapDuration (void)
	Returns the Omicron overlap duration [s].

double	GetOmicronSnrSqMax (const unsigned int aDetectorIndex)
	Returns the maximum SNR squared in the current spectrogram.

unsigned int	GetOmicronStartTime (const unsigned int aDetectorIndex)
	Returns the current spectrogram start time.

bool	Process (const unsigned int aDetectorIndex, const unsigned int aTimeStart, const bool aResetPsd)
	Runs the Omicron analysis.

bool	WriteMaps (const unsigned int aDetectorIndex)
	Writes Omicron spectrograms as png files in the output directory.

	OxOmicron (const string aOptionFile, const unsigned int aGpsRef)
	Constructor of the OxOmicron class.

virtual	~OxOmicron (void)
	Destructor of the OxOmicron class.

Public Member Functions inherited from OxInit
void	AttachTree (TTree *aTree)
	Attach a TTree to the output Ox file.

void	CloseOutputFile (void)
	Closes the current ouput Ox file (if any).

bool	CreateOutputFile (string &aOutFileName, const unsigned int aTime)
	Creates a new ouput Ox file.

string	GetName (void)
	Returns the object name.

string	GetOutputDirectory (void)
	Returns the path to the output directory.

unsigned int	GetOxFileN (void)
	Returns the number of input Ox files.

bool	GetStatus (void)
	Returns the class status.

	OxInit (const string aOptionFile)
	Constructor of the OxInit class.

virtual	~OxInit (void)
	Destructor of the OxInit class.

Private Member Functions
void	CreateArrays (void)
	Creates the result arrays.

void	CreateHistograms (void)
	Creates the result histograms.

void	DrawFakeground (void)
	Draws a random slice to represent the fakeground.

bool	ExtractResults (void)
	Extracts Ox results from input Ox files.

void	FillHistograms (const OxResultType aResultType)
	Fills the result histograms.

void	MakeHtmlLoudest (ofstream &aReport, const OxResultType aResultType)
	Prints the list of loudest events in the html report.

void	SaveLoudest (const OxResultType aResultType, const Long64_t aEntry, const double aRank)
	Saves the loudest events.

void	SaveLoudestTree (const OxResultType aResultType)
	Saves the list of loudest events in output tree.

Private Attributes
TArrayL *	ev_loudest_entry [oxresult_n]
	List of event entries for loudest events: loudest first.

TArrayD *	ev_loudest_rank [oxresult_n]
	List of ranks for loudest events: loudest first.

int	fake_lag
	Fakeground definition: time lag [s].

unsigned int	fake_slice_index
	Fakeground definition: slice index.

TH1D *	h1_ev_freq [oxresult_n]
	Event frequency distribution.

TH1D *	h1_ev_rank [oxresult_n]
	Event rank distribution.

TH2D *	h2_ev_rank_freq [oxresult_n]
	Event rank/frequency distribution.

unsigned int	livetime [oxresult_n]
	Analysis livetime [s].

string	outfilename
	Output file name.

OxInj *	ox_inj
	List of injections.

TH1D *	oxr_ev_freq
	Result tree: event frequency distribution.

TArrayL *	oxr_ev_loudest_entry
	Result tree: list of event entries for loudest events: loudest first.

TArrayD *	oxr_ev_loudest_rank
	Result tree: list of ranks for loudest events: loudest first.

TH1D *	oxr_ev_rank
	Result tree: event rank distribution.

TH2D *	oxr_ev_rank_freq
	Result tree: event rank/frequency distribution.

unsigned int	oxr_livetime
	Result tree: cumulative livetime [s].

TTree *	oxr_tree
	Ox result tree.

bool *	results_found
	Flags input files when OXR results are found.

Segments *	segments [2][oxresult_n]
	Analysis segments for the two detectors.

Additional Inherited Members
Protected Member Functions inherited from OxEvent
int	FillTree (void)
	Fills the output tree with the current event.

Long64_t	GetEntriesOut (void)
	Returns the number of entries in the output tree.

unsigned int	GetTreeNumber (void)
	Returns the current tree number (or file number) in the list of input Ox files.

void	MakeHtmlConfigTable (ofstream &aReport, const string aOutDir)
	Generates an html table listing the Ox configuration.

void	MakeHtmlEventTable (ofstream &aReport)
	Generates an html table listing the current event parameters.

Protected Member Functions inherited from OxCorr
void	MakeHtmlMapTable (ofstream &aReport, const unsigned int aMapTime_0, const unsigned int aMapTime_1)
	Generates an html table displaying the cross-correlation maps.

Protected Member Functions inherited from OxOmicron
int	FillTree (const unsigned int aDetectorIndex)
	Fills the output tree with the current Omicron results.

void	MakeHtmlMapTable (ofstream &aReport, const unsigned int aDetectorIndex, const unsigned int aMapTime)
	Generates an html table displaying the Omicron spectrograms.

Protected Member Functions inherited from OxInit
void	AddOptions (void)
	Adds options from the text Ox option file.

void	CloseHtml (ofstream &aReport)
	Closes an html report.

ofstream	CreateHtml (const string aIndexFileName="index.html", const string aTitle="Omicron-X report")
	Creates an html report.

void	DefineOption (const string aTag, const string aKey, const double aDefaultValue, const unsigned int aSize)
	Defines an option (double).

void	DefineOption (const string aTag, const string aKey, const int aDefaultValue, const unsigned int aSize)
	Defines an option (integer).

void	DefineOption (const string aTag, const string aKey, const string aDefaultValue, const unsigned int aSize)
	Defines an option (string).

void	DefineOption (const string aTag, const string aKey, const unsigned int aDefaultValue, const unsigned int aSize)
	Defines an option (unsigned integer).

string	GetOxFileName (const unsigned int aFileIndex)
	Returns the path to the Ox file.

void	OverloadOption (const string aTag, const string aKey)
	Overloads an option using the text file as a reference.

Protected Attributes inherited from OxOmicron
Streams *	detector [2]
	Detector streams.

Omicron *	omicron [2]
	Omicron objects (detector 0 and 1).

TTree *	oxo_tree [2]
	TTree: Omicron results. Do not delete as it is owned by the output file.

TChain *	oxo_tree_read [2]
	TChain: Omicron results (read-only).

vector< unsigned int >	proc_maps [2]
	List of produced maps (map time).

Protected Attributes inherited from OxInit
GwollumOptions *	ox_opt
	List of options.

bool	status
	Class status.

Detailed Description

Ox analysis results.

This class is designed to collect Ox events and present results of an Ox analysis. Ox events are provided with a list of Ox files pointed by the OXI/OXFILELIST option (see OxInit::OxInit()).

This class can also be initialized with a list of Ox files already containing results (also pointed by OXI/OXFILELIST). These Ox result files were previously produced with this class. When Ox result files are provided, all the options are defined by the content of the files and can no longer be changed.

The results consist of a set of histograms and arrays of numbers to characterize a set of Ox events. This class provides many functions to generate plots and html pages to display the results.

The results are separated into 3 categories:

Foreground events: see oxresult_foreground
Background events: see oxresult_background
Fakeground events: see oxresult_fakeground

Constructor & Destructor Documentation

◆ OxResults()

OxResults::OxResults	(	const string	aOptionFile,
		const unsigned int	aGpsRef
	)

Constructor of the OxResults class.

OxResults options are:

OXR FAKEGROUND: Select a slice to represent fakeground events. Two integer number are expected. The first one is the slice index. The second one is the time difference between the second and first detector. Use a negative slice index to randomly choose the fakeground slice.
OXR DETECTIONTHRESHOLD: Detection thresholds. Two parameters are expected: a threshold on the event rank and a threshold on the false-alarm rate (Hz). If the threshold on the event rank is negative, it is ignored and the threshold on the false-alarm rate is considered. By default, both thresholds are set to 0.5.
OXR NLOUDEST: Number of loudest events to save in each category: foreground, background, fakeground. Default = 5 for each category.
OXR NLOUDESTMAP: Number of loudest events for which to print maps in each category: foreground, background, fakeground. Default = 0 for each category. Note that this number cannot exceed the number of loudest events provided with the OXR/NLOUDEST option. This option only applies when generating a web report with MakeHtml().
OXR NEVENTBINS: Number of bins to histogram the event parameters. Default = 100.
OXR NINJBINS: Number of bins to histogram the injection parameters. Default = 20. See also OxInj.

Warning: If Ox results are found in the list of input Ox files (OXI/OXFILELIST), all OXR options found in the option file are ignored. Instead, all OXR options are derived from the Ox files. Moreover, the class is initialized with the results found in the input Ox files: see ReadInputFiles().

Injection files (if any) in the Omicron configuration are loaded, using the OxInj class.

Parameters

[in]	aOptionFile	Path to the option file.
[in]	aGpsRef	Reference GPS time to intiate Omicron objects.

◆ ~OxResults()

OxResults::~OxResults ( void )

virtual

Destructor of the OxResults class.

Member Function Documentation

◆ CreateArrays()

void OxResults::CreateArrays ( void )

private

Creates the result arrays.

◆ CreateHistograms()

void OxResults::CreateHistograms ( void )

private

Creates the result histograms.

◆ CreateOutputFile()

bool OxResults::CreateOutputFile ( void )

Creates an ouput Ox file to save results.

A new ROOT file is opened in the output directory to save the Ox analysis results (OxInit::CreateOutputFile()). All the result plots are initialized in the ouput file.

See also: OxInit::CreateOutputFile() for the file management.

◆ DrawFakeground()

void OxResults::DrawFakeground ( void )

private

Draws a random slice to represent the fakeground.

◆ ExtractResults()

bool OxResults::ExtractResults ( void )

private

Extracts Ox results from input Ox files.

Input Ox files are scanned. Ox results are extracted from "oxr" trees. Result files are tagged, not to be processed with Process(). The Ox results are cumulated from all the input files.

Returns: true if at least one "oxr" tree is found in the input files and if the tree is formatted as expected.

Note: If results are found in the input files, this function creates local histograms with CreateHistograms() and local arrays with CreateArrays().

◆ FillHistograms()

void OxResults::FillHistograms ( const OxResultType aResultType )

private

Fills the result histograms.

Parameters

[in] aResultType Result type for this event.

◆ GetEventResultType()

OxResultType OxResults::GetEventResultType ( void )

Returns the result type of the current event.

A foreground event (oxresult_foreground) is identified if the event slice is at the center of the cross-correlation map (OxEvent::GetSliceIndexCenter()) and the two detector Omicron spectrogram times match. A fakeground event (oxresult_fakeground) is identified if the event slice matches the fakeground definition. Otherwise, the result type is oxresult_background.

◆ GetProcessedEventsN()

unsigned int OxResults::GetProcessedEventsN ( OxResultType aResultType )

inline

Returns the number of processed events.

Parameters

[in] aResultType Result type.

◆ GetRankDetectionThreshold()

double OxResults::GetRankDetectionThreshold ( void )

inline

Returns the detection threshold on the event rank.

The rank threshold is defined with the first parameter of the OXR/DETECTIONTHRESHOLD option. If the threshold on the event rank (first parameter) is negative, it is ignored and the threshold on the false-alarm rate is considered. It is converted in to a threshold on the event rank using the current oxresult_background distribution.

Warning: The background distribution must be computed first.

◆ MakeHtml()

bool OxResults::MakeHtml ( void )

Generates an html report in the output directory.

◆ MakeHtmlLoudest()

void OxResults::MakeHtmlLoudest	(	ofstream &	aReport,
		const OxResultType	aResultType
	)

private

Prints the list of loudest events in the html report.

Parameters

[in]	aReport	Output stream for the html report.
[in]	aResultType	Result type.

◆ Process()

bool OxResults::Process ( void )

Processes the list of Ox events.

The list of events is processed. For each event, the result type (OxResultType) is identified. Processed segments are saved. Result plots are filled with FillHistograms(). The list of loudest events is updated with SaveLoudest(). For foreground events, injections are matched with OxInj::Match().

The injections are detected above the rank threshold (GetRankDetectionThreshold) and the associated parameter histograms are filled.

Warning: Ox events from input Ox files with results are not processed!

Note: This function can only be called after an output file is opened with CreateOutputFile().

◆ RankToRate()

double OxResults::RankToRate	(	OxResultType	aResultType,
		const double	aRank,
		const int	aType = `0`
	)

Returns the event rate at a given rank [Hz].

The rank histogram is used to derive the event rate at a given rank. Three types of event rates can be returned:

if aType=0, the event rate is calculated over the rank bin.
if atype>0, the event rate is calculated above that rank value.
if atype<0, the event rate is calculated below that rank value.

Warning: The calculated event rate can be wrong for rank values outside the histogram range.

Parameters

[in]	aResultType	Result type.
[in]	aRank	Rank value.
[in]	aType	Calculation type.

◆ RateToRank()

double OxResults::RateToRank	(	OxResultType	aResultType,
		const double	aRate
	)

Returns the event rank at a given rate.

The rank cummulative event distribution is used to derive a rank value from a rate value. The rate value is defined as the rate of events above that rank value. The cumultive distribution histogram is interpolated.

If there is no events, the highest possible rank value is returned. If the provided rate value is smaller than the lowest rate achieved by the histogram, the highest achievable rank value is returned.

Parameters

[in]	aResultType	Result type.
[in]	aRate	Event rate [Hz].

◆ SaveLoudest()

void OxResults::SaveLoudest	(	const OxResultType	aResultType,
		const Long64_t	aEntry,
		const double	aRank
	)

private

Saves the loudest events.

The list of loudest events is sorted by decreasing rank values. The input event is saved if it is louder than the last event in the list. It is inserted to maintain the event order.

Parameters

[in]	aResultType	Result type for this event.
[in]	aEntry	Event entry number.
[in]	aRank	Event rank.

◆ SaveLoudestTree()

void OxResults::SaveLoudestTree ( const OxResultType aResultType )

private

Saves the list of loudest events in output tree.

The list of loudest events is scanned. Events are loaded and are saved in the output event tree.

Parameters

[in] aResultType Result type for this event.

◆ SavePlots()

bool OxResults::SavePlots ( const string aFormat = "png" )

Saves all the result plots in the output directory.

Parameters

[in] aFormat ROOT-supported formats.

Member Data Documentation

◆ ev_loudest_entry

TArrayL* OxResults::ev_loudest_entry[oxresult_n]

private

List of event entries for loudest events: loudest first.

◆ ev_loudest_rank

TArrayD* OxResults::ev_loudest_rank[oxresult_n]

private

List of ranks for loudest events: loudest first.

◆ fake_lag

int OxResults::fake_lag

private

Fakeground definition: time lag [s].

◆ fake_slice_index

unsigned int OxResults::fake_slice_index

private

Fakeground definition: slice index.

◆ h1_ev_freq

TH1D* OxResults::h1_ev_freq[oxresult_n]

private

Event frequency distribution.

◆ h1_ev_rank

TH1D* OxResults::h1_ev_rank[oxresult_n]

private

Event rank distribution.

◆ h2_ev_rank_freq

TH2D* OxResults::h2_ev_rank_freq[oxresult_n]

private

Event rank/frequency distribution.

◆ livetime

unsigned int OxResults::livetime[oxresult_n]

private

Analysis livetime [s].

◆ outfilename

string OxResults::outfilename

private

Output file name.

◆ ox_inj

OxInj* OxResults::ox_inj

private

List of injections.

◆ oxr_ev_freq

TH1D* OxResults::oxr_ev_freq

private

Result tree: event frequency distribution.

◆ oxr_ev_loudest_entry

TArrayL* OxResults::oxr_ev_loudest_entry

private

Result tree: list of event entries for loudest events: loudest first.

◆ oxr_ev_loudest_rank

TArrayD* OxResults::oxr_ev_loudest_rank

private

Result tree: list of ranks for loudest events: loudest first.

◆ oxr_ev_rank

TH1D* OxResults::oxr_ev_rank

private

Result tree: event rank distribution.

◆ oxr_ev_rank_freq

TH2D* OxResults::oxr_ev_rank_freq

private

Result tree: event rank/frequency distribution.

◆ oxr_livetime

unsigned int OxResults::oxr_livetime

private

Result tree: cumulative livetime [s].

◆ oxr_tree

TTree* OxResults::oxr_tree

private

Ox result tree.

◆ results_found

bool* OxResults::results_found

private

Flags input files when OXR results are found.

◆ segments

Segments* OxResults::segments[2][oxresult_n]

private

Analysis segments for the two detectors.

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

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ OxResults()

◆ ~OxResults()

Member Function Documentation

◆ CreateArrays()

◆ CreateHistograms()

◆ CreateOutputFile()

◆ DrawFakeground()

◆ ExtractResults()

◆ FillHistograms()

◆ GetEventResultType()

◆ GetProcessedEventsN()

◆ GetRankDetectionThreshold()

◆ MakeHtml()

◆ MakeHtmlLoudest()

◆ Process()

◆ RankToRate()

◆ RateToRank()

◆ SaveLoudest()

◆ SaveLoudestTree()

◆ SavePlots()

Member Data Documentation

◆ ev_loudest_entry

◆ ev_loudest_rank

◆ fake_lag

◆ fake_slice_index

◆ h1_ev_freq

◆ h1_ev_rank

◆ h2_ev_rank_freq

◆ livetime

◆ outfilename

◆ ox_inj

◆ oxr_ev_freq

◆ oxr_ev_loudest_entry

◆ oxr_ev_loudest_rank

◆ oxr_ev_rank

◆ oxr_ev_rank_freq

◆ oxr_livetime

◆ oxr_tree

◆ results_found

◆ segments