Process data with the Omicron algorithm. More...

#include <Oomicron.h>

Inheritance diagram for Omicron:

Collaboration diagram for Omicron:

[legend]

Public Member Functions
int	Condition (const unsigned int aInVectSize, double *aInVect, bool &aIsFlat)
	Conditions a data vector. More...

bool	DefineNewChunk (const unsigned int aTimeStart, const unsigned int aTimeEnd, const bool aResetPsdBuffer=false)
	Defines a new time chunk. More...

bool	ExtractTriggers (double &aTriggerRate)
	Extracts and saves triggers above threshold. More...

Long64_t	FlushTriggers (void)
	Flushes triggers. More...

double	GetBandFrequency (const unsigned int aQindex, const unsigned int aBandIndex)
	Returns the band central frequency [Hz] of a given Q-plane. More...

unsigned int	GetBandN (const unsigned int aQindex)
	Returns the number of frequency rows of a given Q-plane. More...

double *	GetBands (const unsigned int aQindex)
	Returns the list of frequency bands. More...

unsigned int	GetBandTileN (const unsigned int aQindex, const unsigned int aBandIndex)
	Returns the number of tiles in a frequency row of given Q-plane. More...

string	GetChannelName (const unsigned int aChannelIndex)
	Returns the name of a given channel. More...

string	GetChannelName (void)
	Returns the name of the current channel. More...

unsigned int	GetChannelNativeFrequency (void)
	Returns the native sampling frequency of the current channel. More...

string	GetChannelPrefix (const unsigned int aChannelIndex)
	Returns the name prefix of a given channel. More...

vector< string >	GetChannels (void)
	Returns the list of channels. More...

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

unsigned int	GetChunkDuration (void)
	Returns the chunk duration [s]. More...

unsigned int	GetChunkTimeEnd (void)
	Returns the current chunk end time [s]. More...

unsigned int	GetChunkTimeStart (void)
	Returns the current chunk start time [s]. More...

unsigned int	GetInjectionChannelN (void)
	Returns the number of injection channels. More...

unsigned int	GetInjGenN (void)
	Returns the total number of InjGen injections. More...

unsigned int	GetOverlapDuration (void)
	Returns the overlap duration [s]. More...

double	GetQ (const unsigned int aQindex)
	Returns the Q value of a given q planes. More...

unsigned int	GetQN (void)
	Returns the number of q planes. More...

unsigned int	GetSampleFrequency (void)
	Returns the working sampling frequency [Hz]. More...

bool	GetSgInjectionFlag (void)
	Returns the SG injection flag. More...

double	GetSnrSqMax (const unsigned int aQindex)
	Returns the maximum SNR squared estimated in a given Q plane. More...

double	GetSnrThreshold (void)
	Returns the SNR threshold used to save triggers. More...

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

double	GetTileAmplitude (const unsigned int aQindex, const unsigned int aBandIndex, const unsigned int aTimeTileIndex)
	Returns the amplitude of a given tile. More...

double	GetTileAmplitudeSq (const unsigned int aQindex, const unsigned int aBandIndex, const unsigned int aTimeTileIndex)
	Returns the amplitude squared of a given tile. More...

double	GetTileFrequencyMax (void)
	Returns the tiling maximum frequency [Hz]. More...

double	GetTileFrequencyMin (void)
	Returns the tiling minimum frequency [Hz]. More...

long unsigned int	GetTileN (const double aPadding=0.0)
	Returns the number of tiles. More...

Segments *	GetTileSegments (TH1D *aSnrThreshold, const double aPadding)
	Returns tile segments. More...

double	GetTileSnrSq (const unsigned int aQindex, const unsigned int aBandIndex, const unsigned int aTimeTileIndex)
	Returns the SNR squared of a given tile. More...

Long64_t	GetTriggerN (void)
	Returns the current number of triggers in memory for the current channel. More...

unsigned int	GetTriggerSegmentsN (void)
	Returns the number of processed segments. More...

bool	InitSegments (Segments aInSeg, Segments aOutSeg=NULL)
	Initializes the segments. More...

bool	LoadData (double **aDataVector, unsigned int &aSize)
	Loads a data vector. More...

bool	MakeDirectories (const double aId=0.0)
	Creates a specific directory tree for the output. More...

bool	NewChannel (void)
	Calls a new channel. More...

bool	NewChunk (void)
	Calls a new time chunk. More...

void	PrintMessage (const string aMessage)
	Prints a formatted message with a timer. More...

void	PrintStatusInfo (void)
	Prints a progress report. More...

long unsigned int	Project (void)
	Projects whitened data onto the tiles and fills output structures. More...

void	ResetPsdBuffer (void)
	Resets the PSD buffer of current channel. More...

void	ResetSequence (void)
	Resets the time sequence of chunks. More...

void	ResetTriggerBuffer (void)
	Resets the trigger buffer of current channel. More...

void	SetPlotTimeOffset (const double aTimeOffset)
	When time plots are requested in output, a time offset [s] can be added. More...

bool	WriteOutput (void)
	Writes output products to disk. More...

string	WriteTriggers (const bool aUseLVDir=false)
	Writes triggers to disk. More...

Constructors and destructors
	Omicron (const string aOptionFile, const bool aOneChannel, const unsigned int aGpsRef=0, const bool aStrict=false)
	Constructor of the Omicron class. More...

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

Private Member Functions
string	GetColorCode (const double aSnrRatio)
	Returns a html color code based on a SNR ratio value. More...

bool	IsFlat (const unsigned int aInVectSize, double *aInVect)
	Tests whether a data vector is flat. More...

void	MakeFfl (const unsigned int aGpsRef=0)
	Makes the FFL to access the data. More...

void	MakeHtml (void)
	Generates a HTML report in the main output directory. More...

void	MakeHtmlInit (void)
	Generates a preliminary HTML report in the main output directory. More...

void	MakeInjections (const unsigned int aGpsRef=0)
	Makes the injection engines. More...

void	MakeOptions (void)
	Saves a selection of options. More...

void	MakeSpectrum (const bool aOneChannel)
	Makes the Spectrum objects. More...

void	MakeTiling (void)
	Makes the tiling structure. More...

void	MakeTriggers (void)
	Makes the trigger objects. More...

void	ReadOptions (const string aOptFile, const bool aStrict=false)
	Reads the option file. More...

void	SaveAPSD (const string aType)
	Prints the ASD/PSD to a file. More...

void	SaveOptions (void)
	Prints the options in a ROOT file. More...

void	SaveSG (void)
	Prints the SineGaus injection parameters in a txt file. More...

void	SaveSummary (void)
	Prints the summary text file. More...

void	SaveTS (const bool aWhite=false)
	Prints the timeseries to a file. More...

void	SaveWPSD (void)
	Prints the PSD after whitening to a file. More...

void	Whiten (Spectrum *aSpec, const double aNorm=1.0)
	Whiten the chunk data vector. More...

Private Attributes
unsigned int *	chan_cond_ctr
	Number of Condition() calls /channel. More...

unsigned int *	chan_data_ctr
	Number of LoadData() calls /channel. More...

double *	chan_mapsnrmax
	Channel SNR max in maps (only for html) More...

unsigned int *	chan_proj_ctr
	Number of Project() calls /channel. More...

unsigned int *	chan_write_ctr
	Number of WriteOutput() calls /channel. More...

int	chanindex
	Current channel index (-1 = no channel). More...

unsigned int	chunk_ctr
	Number of called chunks. More...

vector< unsigned int >	chunkcenter
	Chunk centers (only for html). More...

vector< string >	chunktfile
	save chunk file (only for html) More...

double *	ChunkVect
	Chunk raw data (time domain). More...

ffl *	FFL
	ffl object (NULL if none). More...

ffl *	FFL_inject
	FFL for injections. More...

vector< string >	GO_InjChan
	List of injection channels. More...

vector< double >	GO_InjFact
	List of injection factors. More...

bool	GO_InjSg
	Flag to perform sine-Gaussian injections. More...

string	GO_MainDir
	Output main directory (original). More...

string	GO_OutFormat
	Output format string. More...

string	GO_OutProducts
	Output product string. More...

double	GO_RateMax
	Maximum trigger rate. More...

bool	GO_thumb
	Flag to produce thumbnails. More...

unsigned int	GO_Verbosity
	Verbosity level. More...

InjEct **	inject
	Software injections / channel. More...

Segments *	inSegments
	Requested segments. More...

string	MainDir
	Output main directory. More...

fft *	offt
	FFT plan to FFT the input chunk. More...

Oinject *	oinj
	Software Oinject injections. More...

ofstream	oinjfile
	Output file with omicron injection parameters. More...

unsigned int	one_channel
	Optimization flag to process one channel at a time. More...

ofstream	osummaryfile
	Output summary file. More...

vector< string >	outdir
	Output directories / channel. More...

Segments **	outSegments
	Processed segments /channel. More...

struct tm *	ptm
	GMT time. More...

Spectrum **	spectrum1
	1st spectrum structure / channel. More...

Spectrum **	spectrum2
	2nd spectrum structure / channel. More...

Spectrum *	spectrumw
	Spectrum structure to test whitening. More...

bool	status_OK
	General status. More...

Otile *	tile
	Tiling structure. More...

time_t	timer
	Timer. More...

time_t	timer_start
	Timer start. More...

double	toffset
	Time offset for plots [s]. More...

unsigned int *	trig_ctr
	Number of tiles above snr thr /channel. More...

vector< TriggerBuffer * >	triggers
	Output triggers / channel. More...

double *	TukeyWindow
	Tukey window. More...

Detailed Description

Process data with the Omicron algorithm.

This class is designed to offer various methods to conduct an Omicron analysis. The Omicron object must be initialized with an option file: see ReadOptions().

After construction, the Omicron methods should be called sequentially to perform the analysis. Here is a typical sequence:

InitSegments() defines the data segments to process.
MakeDirectories() creates a specific directory structure for the output (optional).
NewChannel() loads a new channel (loop #1).
NewChunk() loads a new chunk of data (loop #2).
LoadData() loads a data vector for this chunk and this channel from a FFL file (in loop #1/2)
Condition() conditions the data vector (in loop #1/2)
Project() projects data onto the tiling structure (in loop #1/2)
WriteOutput() writes output data products to disk (in loop #1/2)
ResetSequence() to go back to the first chunk (in loop #1)

Author: Florent Robinet

Constructor & Destructor Documentation

◆ Omicron()

Omicron::Omicron	(	const string	aOptionFile,
		const bool	aOneChannel,
		const unsigned int	aGpsRef = `0`,
		const bool	aStrict = `false`
	)

Constructor of the Omicron class.

This constructor initializes all the components to run Omicron: data structures, data streams, spectra, tiling, maps, triggers, injections, monitoring, etc.

An option file is required to define all the parameters to run Omicron. For more details about the Omicron configuration, see ReadOptions().

When the one-channel optimization flag is active, channels must be processed completely one by one with NewChannel(). Indeed, only one channel spectrum container is created and is used for one channel after the other. With this mode, it is impossible to process all channels one chunk at a time.

See also: NewChannel().

Parameters

[in]	aOptionFile	Path to the option file.
[in]	aOneChannel	One-channel optimization flag.
[in]	aGpsRef	Reference time to initiate structures.
[in]	aStrict	Strict mode: when set to true, the status of the Omicron object is set to false if options are incorrectly provided.

◆ ~Omicron()

Omicron::~Omicron ( void )

virtual

Destructor of the Omicron class.

Member Function Documentation

◆ Condition()

int Omicron::Condition	(	const unsigned int	aInVectSize,
		double *	aInVect,
		bool &	aIsFlat
	)

Conditions a data vector.

Before projecting the data onto the tiles, the data is conditioned and whitened with this function. The following operations are performed:

Check if the Omicron object is sane (returns -1 otherwise)
Check if the input data vector is sane (returns 1 otherwise)
Check if the input vector is flat (prints a warning and set the output flag to true).
Calculate the native sampling frequency based on the vector size. If the native sampling frequency has changed, it is updated (returns 2 if this update fails).
If requested in the option file, a SineGaus injection is added.
The DC component is removed (returns 3 if it fails).
If requested in the option file, the data is high-pass-filtered (returns 3 if it fails).
The data vector is resampled to the working frequency (returns 3 if it fails).
The data vector is applied a Tukey window.
The data is used to update the PSD (the first one).
The data is Fourier-transformed (returns 4 if it fails).
The data is whitened in the Fourier domain using the first PSD (see Whiten()).
The data Fourier-transformed back in the time domain.
The data is used to update the PSD (the second one).
The data is Fourier-transformed.
The data is whitened in the Fourier domain using the second PSD (see Whiten()).
- The power in the tiling structure is computed (Otile::SetPower()).

Warning: The input vector size MUST MATCH the chunk size loaded with NewChunk(). NO check is performed against that!

Returns: 0 if the data was correctly conditioned.

Parameters

[in]	aInVectSize	Input vector size.
[in]	aInVect	Input data vector (time domain).
[out]	aIsFlat	Flag set to true if the input data vector is detected to be flat.

◆ DefineNewChunk()

bool Omicron::DefineNewChunk	(	const unsigned int	aTimeStart,
		const unsigned int	aTimeEnd,
		const bool	aResetPsdBuffer = `false`
	)

Defines a new time chunk.

Instead of defining a list of input segments (see InitSegments()) and processing sequentially the data (see NewChunk()), it is possible to define any new time chunk.

Optionally, it is possible to reset the PSD buffer (for all channels).

Note: The chunk duration must match the one defined in the option file.

Parameters

[in]	aTimeStart	GPS start time of the chunk.
[in]	aTimeEnd	GPS end time of the chunk.
[in]	aResetPsdBuffer	Flag to reset the PSD buffers.

Returns

The returned value indicates the status of this operation:

true: the time chunk is successfully called
false: otherwise

◆ ExtractTriggers()

bool Omicron::ExtractTriggers ( double & aTriggerRate )

Extracts and saves triggers above threshold.

Triggers are saved using Otile::SaveTriggers(). The trigger structure for each channel is filled with tiles with a SNR above threshold.

Warning: If the number of triggers is greater than the maximum trigger rate specified in the option file, the current chunk is ignored and this function returns false.

Parameters

[out] aTriggerRate Trigger rate [Hz] measured over the chunk excluding half the overlap on both sides.

◆ FlushTriggers()

Long64_t Omicron::FlushTriggers ( void )

Flushes triggers.

All triggers collected until now with ExtractTriggers() are flushed in the final MakeTriggers structure.

Note: If requested, triggers are clustered.

Returns: This function returns the number of triggers (or clusters if requested) in the final MakeTriggers structure. It returns -1 if this function fails.

◆ GetBandFrequency()

double Omicron::GetBandFrequency	(	const unsigned int	aQindex,
		const unsigned int	aBandIndex
	)

inline

Returns the band central frequency [Hz] of a given Q-plane.

Parameters

[in]	aQindex	Q-plane index. If the index is out of range, the full map is considered.
[in]	aBandIndex	Band index.

◆ GetBandN()

unsigned int Omicron::GetBandN ( const unsigned int aQindex )

inline

Returns the number of frequency rows of a given Q-plane.

Parameters

[in] aQindex Q-plane index. If the index is out of range, the full map is considered.

◆ GetBands()

double* Omicron::GetBands ( const unsigned int aQindex )

inline

Returns the list of frequency bands.

The returned array is of size GetBandN()+1 and contains the bin limits.

Warning: The returned array must be deleted by the user.

Parameters

[in] aQindex Q-plane index. If the index is out of range, the full map is considered.

◆ GetBandTileN()

unsigned int Omicron::GetBandTileN	(	const unsigned int	aQindex,
		const unsigned int	aBandIndex
	)

inline

Returns the number of tiles in a frequency row of given Q-plane.

Parameters

[in]	aQindex	Q-plane index. If the index is out of range, the full map is considered.
[in]	aBandIndex	Band index.

Precondition: The band index must be valid.

◆ GetChannelName() [1/2]

string Omicron::GetChannelName ( const unsigned int aChannelIndex )

inline

Returns the name of a given channel.

Returns "" if no channel is defined.

Parameters

[in] aChannelIndex Channel index.

◆ GetChannelName() [2/2]

string Omicron::GetChannelName ( void )

inline

Returns the name of the current channel.

Returns "" if no channel is defined.

◆ GetChannelNativeFrequency()

unsigned int Omicron::GetChannelNativeFrequency ( void )

inline

Returns the native sampling frequency of the current channel.

Returns 0 if no channel is defined.

◆ GetChannelPrefix()

string Omicron::GetChannelPrefix ( const unsigned int aChannelIndex )

inline

Returns the name prefix of a given channel.

Returns "" if no channel is defined.

Parameters

[in] aChannelIndex Channel index.

◆ GetChannels()

vector< string > Omicron::GetChannels ( void )

Returns the list of channels.

◆ GetChannelsN()

unsigned int Omicron::GetChannelsN ( void )

inline

Returns the number of channels.

◆ GetChunkDuration()

unsigned int Omicron::GetChunkDuration ( void )

inline

Returns the chunk duration [s].

◆ GetChunkTimeEnd()

unsigned int Omicron::GetChunkTimeEnd ( void )

inline

Returns the current chunk end time [s].

◆ GetChunkTimeStart()

unsigned int Omicron::GetChunkTimeStart ( void )

inline

Returns the current chunk start time [s].

◆ GetColorCode()

string Omicron::GetColorCode ( const double aSnrRatio )

private

Returns a html color code based on a SNR ratio value.

Parameters

[in] aSnrRatio SNR ratio value.

◆ GetInjectionChannelN()

unsigned int Omicron::GetInjectionChannelN ( void )

inline

Returns the number of injection channels.

◆ GetInjGenN()

unsigned int Omicron::GetInjGenN ( void )

inline

Returns the total number of InjGen injections.

◆ GetOverlapDuration()

unsigned int Omicron::GetOverlapDuration ( void )

inline

Returns the overlap duration [s].

◆ GetQ()

double Omicron::GetQ ( const unsigned int aQindex )

inline

Returns the Q value of a given q planes.

Parameters

[in] aQindex Q-plane index.

Precondition: The Q-plane index must be valid.

◆ GetQN()

unsigned int Omicron::GetQN ( void )

inline

Returns the number of q planes.

◆ GetSampleFrequency()

unsigned int Omicron::GetSampleFrequency ( void )

inline

Returns the working sampling frequency [Hz].

◆ GetSgInjectionFlag()

bool Omicron::GetSgInjectionFlag ( void )

inline

Returns the SG injection flag.

◆ GetSnrSqMax()

double Omicron::GetSnrSqMax ( const unsigned int aQindex )

inline

Returns the maximum SNR squared estimated in a given Q plane.

Parameters

[in] aQindex Q-plane index.

Precondition: The Q-plane index must be valid.

◆ GetSnrThreshold()

double Omicron::GetSnrThreshold ( void )

inline

Returns the SNR threshold used to save triggers.

◆ GetStatus()

bool Omicron::GetStatus ( void )

inline

Returns class status.

◆ GetTileAmplitude()

double Omicron::GetTileAmplitude	(	const unsigned int	aQindex,
		const unsigned int	aBandIndex,
		const unsigned int	aTimeTileIndex
	)

inline

Returns the amplitude of a given tile.

Parameters

[in]	aQindex	Q-plane index.
[in]	aBandIndex	Band index.
[in]	aTimeTileIndex	Tile index in the band.

Precondition: The Q-plane index, the band index and the tile index must be valid.

◆ GetTileAmplitudeSq()

double Omicron::GetTileAmplitudeSq	(	const unsigned int	aQindex,
		const unsigned int	aBandIndex,
		const unsigned int	aTimeTileIndex
	)

inline

Returns the amplitude squared of a given tile.

Parameters

[in]	aQindex	Q-plane index.
[in]	aBandIndex	Band index.
[in]	aTimeTileIndex	Tile index in the band.

Precondition: The Q-plane index, the band index and the tile index must be valid.

◆ GetTileFrequencyMax()

double Omicron::GetTileFrequencyMax ( void )

inline

Returns the tiling maximum frequency [Hz].

◆ GetTileFrequencyMin()

double Omicron::GetTileFrequencyMin ( void )

inline

Returns the tiling minimum frequency [Hz].

◆ GetTileN()

long unsigned int Omicron::GetTileN ( const double aPadding = 0.0 )

inline

Returns the number of tiles.

Parameters

[in] aPadding Number of seconds excluded on both sides of the time range.

Precondition: The padding value is not checked! Make sure it is compatible with the time range.

◆ GetTileSegments()

Segments* Omicron::GetTileSegments	(	TH1D *	aSnrThreshold,
		const double	aPadding
	)

inline

Returns tile segments.

A tile segment is the tile start/stop. Here, tiles are selected if the SNR is larger than a given threshold. The threshold is given as a TH1D histogram binned in the tile frequency [Hz]. The bin content is the SNR threshold. A negative bin content is considered as an infinite threshold. Out-of-range frequencies are associated to an infinite threshold.

Parameters

[in]	aSnrThreshold	SNR threshold as a function of frequency.
[in]	aPadding	Number of seconds excluded on both sides of the tiling structure when selecting tiles above the SNR threshold.

See also: Otile::GetTileSegments()

Note: The user is in charge of deleting the returned Segments object.

◆ GetTileSnrSq()

double Omicron::GetTileSnrSq	(	const unsigned int	aQindex,
		const unsigned int	aBandIndex,
		const unsigned int	aTimeTileIndex
	)

inline

Returns the SNR squared of a given tile.

Parameters

[in]	aQindex	Q-plane index.
[in]	aBandIndex	Band index.
[in]	aTimeTileIndex	Tile index in the band.

Precondition: The Q-plane index, the band index and the tile index must be valid.

◆ GetTriggerN()

Long64_t Omicron::GetTriggerN ( void )

inline

Returns the current number of triggers in memory for the current channel.

◆ GetTriggerSegmentsN()

unsigned int Omicron::GetTriggerSegmentsN ( void )

inline

Returns the number of processed segments.

◆ InitSegments()

bool Omicron::InitSegments	(	Segments *	aInSeg,
		Segments *	aOutSeg = `NULL`
	)

Initializes the segments.

This function should always be called before processing data. The input segment structure is used:

to initialize the analysis sequence (see Otile::SetSegments())
to update the channel list in the FFL.

Optionally, output segments (for triggers only!) can be specified. If so, triggers outside the output segments are not be saved. Use a pointer to NULL to not use this option.

Parameters

[in]	aInSeg	Pointer to the input Segments structure.
[in]	aOutSeg	Pointer to the output Segments structure.

◆ IsFlat()

bool Omicron::IsFlat	(	const unsigned int	aInVectSize,
		double *	aInVect
	)

private

Tests whether a data vector is flat.

Returns: true if it is.

Parameters

[in]	aInVectSize	Vector size: must be strictly positive.
[in]	aInVect	Pointer to data vector.

◆ LoadData()

bool Omicron::LoadData	(	double **	aDataVector,
		unsigned int &	aSize
	)

Loads a data vector.

A data vector is returned, as well as its size.

The data vector of the current channel and the current chunk is loaded.
If requested in the option file, software injections (InjEct) are added to the data.
If requested in the option file, the injection data stream is loaded and added to the data.

Warning: The FFL option is mandatory to use this function.

Note: It is the user's responsibility to delete the returned data vector.

Returns: If this function fails, false is returned and the data vector points to NULL.

Parameters

[out]	aDataVector	Pointer to the data vector.
[out]	aSize	Size of the data vector.

◆ MakeDirectories()

bool Omicron::MakeDirectories ( const double aId = 0.0 )

Creates a specific directory tree for the output.

Two directory structures are possible:

[path_to_outdir]/aId/[channel_name] if aId is not 0
[path_to_outdir]/[channel_name] if aId is 0

where [path_to_outdir] is the output directory specified by the user in the option file and [channel_name] is the channel name being processed.

The aId value is rounded to the third digit.

If this function is never called, all the output is dumped in the output directory specified by the user in the option file.

Parameters

[in] aId Directory id.

◆ MakeFfl()

void Omicron::MakeFfl ( const unsigned int aGpsRef = 0 )

private

Makes the FFL to access the data.

The FFL object is created if provided in the options (DATA/FFL or DATA/LCF).

Parameters

[in] aGpsRef Provide a GPS time to load the channel list in the FFL. If not provided, the first frame is used.

◆ MakeHtml()

void Omicron::MakeHtml ( void )

private

Generates a HTML report in the main output directory.

◆ MakeHtmlInit()

void Omicron::MakeHtmlInit ( void )

private

Generates a preliminary HTML report in the main output directory.

This report can be produced before running the Omicron analysis.

◆ MakeInjections()

void Omicron::MakeInjections ( const unsigned int aGpsRef = 0 )

private

Makes the injection engines.

Parameters

[in] aGpsRef Provide a GPS time to load the injection channel list in the FFL. If not provided, the first frame is used.

◆ MakeOptions()

void Omicron::MakeOptions ( void )

private

Saves a selection of options.

This is mostly for optimization purposes. GwollumOptions::GetOptionValues() can be expensive when called multiple times.

◆ MakeSpectrum()

void Omicron::MakeSpectrum ( const bool aOneChannel )

private

Makes the Spectrum objects.

Parameters

[in] aOneChannel Set this flag to true to only create a single Spectrum object. Otherwise, one Spectrum object is created per channel.

◆ MakeTiling()

void Omicron::MakeTiling ( void )

private

Makes the tiling structure.

◆ MakeTriggers()

void Omicron::MakeTriggers ( void )

private

Makes the trigger objects.

The list of channels is extracted (blacklisted channels are removed). If a FFL file was provided, it is used to test the existence of a channel.

◆ NewChannel()

bool Omicron::NewChannel ( void )

Calls a new channel.

The channels defined in the option file are called sequentially. If this function is called after the last channel, false is returned and the channel sequence is reset: at the next call, the first channel will be loaded again.

Note: If the one-channel optimization is active, the PSD buffer is reset.

◆ NewChunk()

bool Omicron::NewChunk ( void )

Calls a new time chunk.

The time chunks are called following the time sequence defined by the Otile class.

Note: If a new segment is started, the PSD buffer is reset for all channels.; If the sine-Gauss injections are activated, waveforms are generated.

Returns

The returned value indicates the status of this operation:

true: a new time chunk has been successfully called
false: no more chunk to load

◆ PrintMessage()

void Omicron::PrintMessage ( const string aMessage )

Prints a formatted message with a timer.

Parameters

[in] aMessage Message to print.

◆ PrintStatusInfo()

void Omicron::PrintStatusInfo ( void )

Prints a progress report.

◆ Project()

long unsigned int Omicron::Project ( void )

Projects whitened data onto the tiles and fills output structures.

Otile::ProjectData() is called to fill the tiling structure.

Returns: The number of tiles above the threshold is returned.

◆ ReadOptions()

void Omicron::ReadOptions	(	const string	aOptFile,
		const bool	aStrict = `false`
	)

private

Reads the option file.

Parameters

[in]	aOptFile	Path to the option file. This can be either a txt file or a root file.
[in]	aStrict	Set this flag to true to operate a stricter check of parameters.

Omicron parameters must be provided with an option file. If the option file is a text file, each parameter is identified with a tag and a keyword:

TAG  KEYWORD  [PARAMETERS]

The combination of tag/keyword/parameters is called an option.

Note: For some options, multiple parameters can be used. They are separated by white spaces or tabs.

//*************************************************************************************
//************************   Omicron configuration file   *****************************
//*************************************************************************************
 
 
//*************************************************************************************
//************************           DATA CLASS           *****************************
//*************************************************************************************
 
//** path to a frame file list file (FFL or lalcache format)
DATA    FFL     /virgoData/ffl/raw.ffl
 
//** list of channels you want to process (here you have 3).
//   They can be listed on one single line or several lines
DATA    CHANNELS    V1:Hrec_hoft_16384Hz
DATA    CHANNELS    V1:LSC_DARM  V1:LSC_DARM_ERR
 
//** working sampling frequency (one value for all channels)
DATA    SAMPLEFREQUENCY 2048
 
//************************************************************************************
//************************         PARAMETER CLASS       *****************************
//************************************************************************************
 
//** analysis window duration and overlap in seconds
PARAMETER   TIMING      64  4
 
//** search frequency range [Hz]
PARAMETER   FREQUENCYRANGE  12  1024
 
//** search Q range
PARAMETER   QRANGE      4   100
 
//** maximal mismatch between tiles
PARAMETER   MISMATCHMAX 0.3
 
//** tile SNR threshold
PARAMETER   SNRTHRESHOLD    6
 
//** data length for optimal PSD estimation in seconds
PARAMETER       PSDLENGTH   300
 
//*************************************************************************************
//************************           OUTPUT CLASS         *****************************
//*************************************************************************************
 
//** path to output directory
OUTPUT     DIRECTORY       /path/to/output/directory
 
//** list of data products
OUTPUT     PRODUCTS    triggers html
 
//** output file format
OUTPUT     FORMAT      root
 
//** verbosity level (0-1-2-3)
OUTPUT     VERBOSITY       1

The list of options can also be provided in a ROOT file (extension: .root). In that case, the options are listed in a TTree named gwloptions which must be generated with the GwollumOptions class.

Note: It is possible to access the gwloptions TTree in a ROOT sub-directory. The sub-directory must be given after the path to the ROOT file using | as a separator. For example: /path/to/my/root/file.root|subdir1/subdir2

Here we list all the options for Omicron.

OUTPUT

Output directory

OUTPUT  DIRECTORY  [PARAMETER]

[PARAMETER] is the directory path (relative or absolute). The output directory must be provided and it must exist.

Output products

OUTPUT  PRODUCTS  [PARAMETERS]

[PARAMETERS] is the list of products computed by Omicron. Possible parameters are:

triggers: Omicron tiles above a SNR threshold are saved in a file.
asd: The amplitude spectral density function is saved in a file.
psd: The power spectral density function is saved in a file.
html: A html report is produced in the output directory specified with the directory option.
timeseries: The condition time series is saved in a file.
white: The time series after whitening is saved in a file.
whitepsd: The power spectral density after whitening is saved in a file.
mapsnr: The snr spectrograms are saved in a file.
mapamplitude: The amplitude spectrograms are saved in a file.
mapphase: The phase spectrograms are saved in a file.
summary: A channel summary is written in a text file.
options: The list of options is saved in a ROOT file.

By default, only triggers are produced. The ouput file format is specified with the format option.

File format

OUTPUT  FORMAT  [PARAMETERS]

[PARAMETERS] is the list of file formats to save output products. Supported formats: root (native), hdf5 (for triggers only), and all the usual graphical formats (svg, gif, pdf, png, eps and so on). By default = root.

Note: Use wav to produce sound files for time series.

Verbosity level

OUTPUT  VERBOSITY  [PARAMETER]

[PARAMETER] is the verbosity level: 0, 1, 2, or 3. By default = 0.

Output style

OUTPUT  STYLE  [PARAMETER]

[PARAMETER] defines the css style for the web report (if requested with the output products option). It also defines the graphical color palette for the plots. Several styles are supported:

GWOLLUM (default): black background, blue style.
FIRE: black background, color palette from red to yellow
STANDARD: light background, rainbow color palette
PINK: black background, pink style.

No logo flag

OUTPUT  NOLOGO  [PARAMETER]

If [PARAMETER] is set to a non-zero value, the omicron background logo does not appear on the web reports (if requested with the output products option). By default, the logo is present ([PARAMETER] = 0).

Plot dimensions

OUTPUT  PLOTDIMENSIONS  [PARAMETERS]

This option sets the graphical plot dimensions (if requested with the OUTPUT/FORMAT option). Two integer numbers should be provided with [PARAMETERS]: the width and the height measured in a number of pixels.

HTML main page name

OUTPUT  HTMLMAINPAGE  [PARAMETER]

This option specifies the file name of the html main page (if required with the OUTPUT/PRODUCTS option). By default = index.html.

DATA

Frame file list

DATA  FFL  [PARAMETERS]

or

DATA  LCF  [PARAMETERS]

This option specifies the list of frame files to be processed by omicron. In the first option, it is provided as a frame file list (FFL). In the second option, it is provided as a LAL cache file (LCF). [PARAMETERS] must provide the path to the FFL or LCF file (absolute or relative). It can be complemented by 2 optional parameters which are used to load the FFL file multiple times in a row (for online applications):

Number of retries to load the FFL,
Time in [s] between two retries.

By default, no FFL file is used.

Working sampling frequency

DATA  SAMPLEFREQUENCY  [PARAMETER]

This option specifies the working sampling frequency of omicron in [Hz]. All channel time series are sampled to a common frequency before being processed. Only downsampling is supported. The working sampling frequency must be a power of 2 and must be at least 16 Hz.

List of channels

DATA  CHANNELS  [PARAMETERS]

This option specifies the list of channels to process, e.g. V1:Hrec_hoft_16384Hz V1:LSC_DARM. Multiple channel names can be provided using wildcards. This option can also be used on multiple lines. This option is mandatory.

List of black-listed channels

DATA  BLACKLISTEDCHANNELS  [PARAMETERS]

This option specifies the list of channels to exclude from the processing, e.g. V1:Hrec_hoft_16384Hz V1:LSC_DARM. Multiple channel names can be provided using wildcards. This option can also be used on multiple lines.

PARAMETER

Analysis timing

PARAMETER  TIMING  [PARAMETERS]

This option specifies the timing parameters to perform the analysis. It includes 2 parameters:

The analysis window size in [s]. It must be an even number of seconds.
Overlap duration [s]. Two consecutive analysis windows overlap by this amount. This option is mandatory.

Frequency range

PARAMETER  FREQUENCYRANGE  [PARAMETERS]

This option specifies the search frequency range with a lower bound and a higher bound, both in [Hz]. The higher bound must be compatible with the sampling frequency option. This option is mandatory.

Q range

PARAMETER  QRANGE  [PARAMETERS]

This option specifies the search Q range with a lower bound and a higher bound. The lower bound must be at least \(\sqrt{11}\). This option is mandatory.

Maximum mismatch between tiles

PARAMETER  MISMATCHMAX  [PARAMETER]

This option specifies the maximum energy mismatch between time-frequency tiles. This value should be a number between 0 and 1. By default, max mismatch = 0.25.

Full map time resolution

PARAMETER  FULLMAPNT  [PARAMETER]

This option specifies the time resolution of the full time-frequency map, where all Q planes are combined. The given parameter is the number of bins used to cover the chunk time range. If this parameter is set to 0, the maximal resolution is used, which can be expensive in memory usage. By default, number of time bins = 301.

SNR thresholds

PARAMETER  SNRTHRESHOLD  [PARAMETERS]

This option specifies the signal-to-noise ratio. There are 2 SNR thresholds:

The first SNR threshold applies to the individual time-frequency tiles to define a trigger.
The second SNR threshold determines if spectogram plots must be generated. The plots are produced if at least one tile in the first plot time window is above this threshold.

By default, both thresholds are set to 7.

Power spectrum density length

PARAMETER  PSDLENGTH  [PARAMETER]

This option specifies the duration [s] over which the power spectrum density is estimated. By default, use the analysis window duration minus the overlap.

High-pass filter

PARAMETER  HIGHPASS  [PARAMETER]

This option specifies the frequency cutoff [Hz] at which to high-pass the data before processing. By default, do not high-pass the data.

Clustering algorithm

PARAMETER  CLUSTERING  [PARAMETER]

This option selects the clustering method. Only one clustering method is currently supported: "TIME". By default, no clustering.

Note: This option is useless for triggers saved in a ROOT format. Clusters are nevered saved in ROOT files.

Clustering time window

PARAMETER  CLUSTERDT  [PARAMETER]

This option specifies the time window duration to cluster triggers in [s]. By default, = 0.1 s

Time windows for plots

PARAMETER  WINDOWS  [PARAMETERS]

This option specifies the list of time windows for plots. There is no limit on the number of parameters. By default, the chunk duration is used.

Log scale for SNR scales in plots

PARAMETER  MAPLOGSCALE  [PARAMETER]

This option, when different from 0, activates the log scale for the color scale of spectrograms. By default, a log scale is used.

Vertical range for spectrograms

PARAMETER  MAPVRANGE  [PARAMETERS]

This option specifies the vertical range for spectrogram plots. Use an impossible range (e.g. 1 0) for an automatic scaling.

Use thumbnails for web pages

PARAMETER  THUMB  [PARAMETER]

When producing a web report (html in the OUTPUT/PRODUCTS), spectrogram thumbnails can be produced. This improves the resolutions of images in the web page. It also speed-up the loading of the page. Producing thumbnails has a cost on the processing speed. If thumbnails are not produced, a simple browser rescaling of the image is used. Use a non zero value to activate the thumbnail production. By default, thumbnails are produced.

FFT plan

PARAMETER  FFTPLAN  [PARAMETER]

This option specifies the plan to perform Fourier transforms with FFTW. By default = "FFTW_MEASURE".

Maximum trigger rate

PARAMETER  TRIGGERRATEMAX [PARAMETER]

This option specifies maximum trigger rate limit [Hz] when saving triggers to files. If the trigger rate is above this value (over the analysis window), the file is not saved. By default = 5000 Hz.

Trigger buffer size

PARAMETER  TRIGGERBUFFERSIZE  [PARAMETER]

This option is used for online applications. Triggers produced by omicron can be buffered. This parameter defines the size of the buffer. By default, there is no buffer (size=0).

Newtonian chirp

PARAMETER  CHIRP [PARAMETERS]

With this option, it is possible to draw a Newtonian chirp on top of omicron spectrograms. There can be one or two parameters:

A chirp mass in solar masses: the chirp is drawn with an end time positioned at the center of the analysis window.
A chirp mass in solar masses + a GPS time [s]: the chirp is drawn with an end time positioned at the requested GPS time.

By default: no chirp.

INJECTION

Injection channel list

INJECTION  CHANNELS [PARAMETERS]

This option specifies the list of channels to be used as injection signals. There should be as many channels as listed in the main channel list.

Injection scaling factors

INJECTION  FACTORS [PARAMETERS]

This option specifies the list of amplitude scaling factors used to inject signals. There should be as many factors as the number of injection channels.

Frame file list

INJECTION  FFL [PARAMETERS]

or

INJECTION  LCF [PARAMETERS]

If the injection channel(s) are not included in the main ffl file, this option specifies an additional ffl file. [PARAMETER] is the relative or absolute path to the ffl/lcf file. This parameter can be complemented by 2 optional parameters which are used to load the FFL file multiple times in a row (for online applications):

Number of retries to load the FFL,
Time in [s] between two retries.

InjGen injections

INJECTION  INJGEN [PARAMETERS]

Injections can also be performed with injection files listing the source/waveform parameters. The injection files must be ROOT files generated with the GWOLLUM/InjGen class. This option provides a list of file patterns to the injection files.

Tukey window

INJECTION  TUKEYFRAC [PARAMETER]

When the InjGen injections option is active, the injected waveform is Tukey-windowed before being added to the data. With this option, you can set the fraction of the time used to transition from 0 to 1 and then from 1 to 0. By default, this parameter is set to 0.1. It means that it takes 5% of the waveform to transition from 0 to 1 and 5% of the waveform to transition from 1 to 0.

Sine-Gauss injections

INJECTION  SG [PARAMETER]

Sine-gauss injections can be performed by setting [PARAMETER] to a value different from 0. One waveform is injected in every analysis window.

Sine-Gauss injection time

INJECTION  SGTIME [PARAMETERS]

By default, sine-Gaussian waveforms are always injected at the center of the analysis window. With this option, the time of the injection can be taken as a random value in a given time range. The time range is defined with 2 values: a negative and a positive range from the center (in seconds).

Sine-Gauss injection frequency

INJECTION  SGFREQUENCY [PARAMETERS]

With this option, the frequency of the injection is taken as a random value in a given frequency range, following a logarithmic distribution. If only one value is provided, the injection frequency is fixed at that value.

Sine-Gauss injection Q

INJECTION  SGQ [PARAMETERS]

With this option, the quality factor of the injection is taken as a random value in a given range, following a logarithmic distribution. If only one value is provided, the injection Q is fixed at that value.

Sine-Gauss amplitude

INJECTION  SGAMPLITUDE [PARAMETERS]

With this option, the amplitude of the injection is taken as a random value in a given range, following a logarithmic distribution. If only one value is provided, the injection amplitude is fixed at that value.

◆ ResetPsdBuffer()

void Omicron::ResetPsdBuffer ( void )

inline

Resets the PSD buffer of current channel.

◆ ResetSequence()

void Omicron::ResetSequence ( void )

inline

Resets the time sequence of chunks.

The sequence is initialized to the start at the first chunk. Note that the segments set with InitSegments() remain the same.

See also: Otile::ResetSequence().

◆ ResetTriggerBuffer()

void Omicron::ResetTriggerBuffer ( void )

inline

Resets the trigger buffer of current channel.

◆ SaveAPSD()

void Omicron::SaveAPSD ( const string aType )

private

Prints the ASD/PSD to a file.

Parameters

[in] aType "ASD" or "PSD".

◆ SaveOptions()

void Omicron::SaveOptions ( void )

private

Prints the options in a ROOT file.

◆ SaveSG()

void Omicron::SaveSG ( void )

private

Prints the SineGaus injection parameters in a txt file.

◆ SaveSummary()

void Omicron::SaveSummary ( void )

private

Prints the summary text file.

◆ SaveTS()

void Omicron::SaveTS ( const bool aWhite = false )

private

Prints the timeseries to a file.

Parameters

[in] aWhite Set to true to save the whitened timeseries.

◆ SaveWPSD()

void Omicron::SaveWPSD ( void )

private

Prints the PSD after whitening to a file.

◆ SetPlotTimeOffset()

void Omicron::SetPlotTimeOffset ( const double aTimeOffset )

inline

When time plots are requested in output, a time offset [s] can be added.

Parameters

[in] aTimeOffset Time offset [s].

◆ Whiten()

void Omicron::Whiten	(	Spectrum *	aSpec,
		const double	aNorm = `1.0`
	)

private

Whiten the chunk data vector.

The data vector (in the frequency domain) is whitened:

The DC frequency is set to 0.
The Fourier coefficients below the highpass frequency are set to 0.
The Fourier coefficients are divided by the amplitude spectral density. Afactor \(\sqrt{2}\) is included to account for the double whitening.
Optionally the data is multiplied by a normalization factor.
Parameters

[in] aSpec Spectrum object to whiten the data.

[in] aNorm Normalization factor.

◆ WriteOutput()

bool Omicron::WriteOutput ( void )

Writes output products to disk.

The output data products selected by the user in the option file and for the current chunk/channel are written to disk.

◆ WriteTriggers()

string Omicron::WriteTriggers ( const bool aUseLVDir = false )

Writes triggers to disk.

All triggers collected until now with FlushTriggers() are saved to disk.

Returns: This function returns the trigger file path. "" is returned if this function fails.

Optionnally, it is possible to use the LIGO/Virgo convention to save trigger files:

[OUTPUT DIRECTORY]/[IFO]/[CHANNEL]_OMICRON/[GPS (5 first digits)]/file

Parameters

[in] aUseLVDir Set to true to use the LIGO/Virgo convention for trigger files.

Member Data Documentation

◆ chan_cond_ctr

unsigned int* Omicron::chan_cond_ctr

private

Number of Condition() calls /channel.

◆ chan_data_ctr

unsigned int* Omicron::chan_data_ctr

private

Number of LoadData() calls /channel.

◆ chan_mapsnrmax

double* Omicron::chan_mapsnrmax

private

Channel SNR max in maps (only for html)

◆ chan_proj_ctr

unsigned int* Omicron::chan_proj_ctr

private

Number of Project() calls /channel.

◆ chan_write_ctr

unsigned int* Omicron::chan_write_ctr

private

Number of WriteOutput() calls /channel.

◆ chanindex

int Omicron::chanindex

private

Current channel index (-1 = no channel).

◆ chunk_ctr

unsigned int Omicron::chunk_ctr

private

Number of called chunks.

◆ chunkcenter

vector<unsigned int> Omicron::chunkcenter

private

Chunk centers (only for html).

◆ chunktfile

vector<string> Omicron::chunktfile

private

save chunk file (only for html)

◆ ChunkVect

double* Omicron::ChunkVect

private

Chunk raw data (time domain).

◆ FFL

ffl* Omicron::FFL

private

ffl object (NULL if none).

◆ FFL_inject

ffl* Omicron::FFL_inject

private

FFL for injections.

◆ GO_InjChan

vector<string> Omicron::GO_InjChan

private

List of injection channels.

◆ GO_InjFact

vector<double> Omicron::GO_InjFact

private

List of injection factors.

◆ GO_InjSg

bool Omicron::GO_InjSg

private

Flag to perform sine-Gaussian injections.

◆ GO_MainDir

string Omicron::GO_MainDir

private

Output main directory (original).

◆ GO_OutFormat

string Omicron::GO_OutFormat

private

Output format string.

◆ GO_OutProducts

string Omicron::GO_OutProducts

private

Output product string.

◆ GO_RateMax

double Omicron::GO_RateMax

private

Maximum trigger rate.

◆ GO_thumb

bool Omicron::GO_thumb

private

Flag to produce thumbnails.

◆ GO_Verbosity

unsigned int Omicron::GO_Verbosity

private

Verbosity level.

◆ inject

InjEct** Omicron::inject

private

Software injections / channel.

◆ inSegments

Segments* Omicron::inSegments

private

Requested segments.

◆ MainDir

string Omicron::MainDir

private

Output main directory.

◆ offt

fft* Omicron::offt

private

FFT plan to FFT the input chunk.

◆ oinj

Oinject* Omicron::oinj

private

Software Oinject injections.

◆ oinjfile

ofstream Omicron::oinjfile

private

Output file with omicron injection parameters.

◆ one_channel

unsigned int Omicron::one_channel

private

Optimization flag to process one channel at a time.

◆ osummaryfile

ofstream Omicron::osummaryfile

private

Output summary file.

◆ outdir

vector<string> Omicron::outdir

private

Output directories / channel.

◆ outSegments

Segments** Omicron::outSegments

private

Processed segments /channel.

◆ ptm

struct tm* Omicron::ptm

private

GMT time.

◆ spectrum1

Spectrum** Omicron::spectrum1

private

1st spectrum structure / channel.

◆ spectrum2

Spectrum** Omicron::spectrum2

private

2nd spectrum structure / channel.

◆ spectrumw

Spectrum* Omicron::spectrumw

private

Spectrum structure to test whitening.

◆ status_OK

bool Omicron::status_OK

private

General status.

◆ tile

Otile* Omicron::tile

private

Tiling structure.

◆ timer

time_t Omicron::timer

private

Timer.

◆ timer_start

time_t Omicron::timer_start

private

Timer start.

◆ toffset

double Omicron::toffset

private

Time offset for plots [s].

◆ trig_ctr

unsigned int* Omicron::trig_ctr

private

Number of tiles above snr thr /channel.

◆ triggers

vector<TriggerBuffer*> Omicron::triggers

private

Output triggers / channel.

◆ TukeyWindow

double* Omicron::TukeyWindow

private

Tukey window.

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

[in]	aSpec	Spectrum object to whiten the data.
[in]	aNorm	Normalization factor.

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Omicron()

◆ ~Omicron()

Member Function Documentation

◆ Condition()

◆ DefineNewChunk()

◆ ExtractTriggers()

◆ FlushTriggers()

◆ GetBandFrequency()

◆ GetBandN()

◆ GetBands()

◆ GetBandTileN()

◆ GetChannelName() [1/2]

◆ GetChannelName() [2/2]

◆ GetChannelNativeFrequency()

◆ GetChannelPrefix()

◆ GetChannels()

◆ GetChannelsN()

◆ GetChunkDuration()

◆ GetChunkTimeEnd()

◆ GetChunkTimeStart()

◆ GetColorCode()

◆ GetInjectionChannelN()

◆ GetInjGenN()

◆ GetOverlapDuration()

◆ GetQ()

◆ GetQN()

◆ GetSampleFrequency()

◆ GetSgInjectionFlag()

◆ GetSnrSqMax()

◆ GetSnrThreshold()

◆ GetStatus()

◆ GetTileAmplitude()

◆ GetTileAmplitudeSq()

◆ GetTileFrequencyMax()

◆ GetTileFrequencyMin()

◆ GetTileN()

◆ GetTileSegments()

◆ GetTileSnrSq()

◆ GetTriggerN()

◆ GetTriggerSegmentsN()

◆ InitSegments()

◆ IsFlat()

◆ LoadData()

◆ MakeDirectories()

◆ MakeFfl()

◆ MakeHtml()

◆ MakeHtmlInit()

◆ MakeInjections()

◆ MakeOptions()

◆ MakeSpectrum()

◆ MakeTiling()

◆ MakeTriggers()

◆ NewChannel()

◆ NewChunk()

◆ PrintMessage()

◆ PrintStatusInfo()

◆ Project()

◆ ReadOptions()

OUTPUT

Output directory

Output products

File format

Verbosity level

Output style

No logo flag

Plot dimensions

HTML main page name

DATA

Frame file list

Working sampling frequency

List of channels

List of black-listed channels

PARAMETER

Analysis timing

Frequency range