Construct a time-frequency-Q tiling structure. More...

#include <Otile.h>

Inheritance diagram for Otile:

Collaboration diagram for Otile:

[legend]

Public Member Functions
void	DrawMapTiling (const unsigned int aQindex)
	Displays a canonical representation of a given Q-plane. More...

void	FillFullMap (const unsigned int aWindowIndex, const double aTimeOffset=0.0)
	Fills the full map. More...

void	FillMaps (void)
	Fills the Q-plane maps. 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 bands 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 band of a given Q-plane. More...

double	GetChirpMass (void)
	Returns the chirp mass [solar masses]. More...

double	GetFrequencyMax (void)
	Returns the highest frequency of this tiling [Hz]. More...

double	GetFrequencyMin (void)
	Returns the minimum frequency of this tiling [Hz]. More...

TH2D *	GetFullMap (const unsigned int aWindowIndex)
	Returns a copy of the full map. More...

string	GetMapFill (void)
	Returns the current map fill type. More...

double	GetMismatchMax (void)
	Returns the maximum mismatch between tiles. More...

vector< unsigned int >	GetPlotTimeWindows (void)
	Returns the list of time windows for plots. More...

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

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

double	GetRangezMin (void)
	Returns the map Z-axis range minimum. More...

double	GetSnrMapThr (void)
	Returns the current SNR threshold for maps. More...

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

double	GetSnrTriggerThr (void)
	Returns the current SNR threshold for triggers. 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...

long unsigned int	GetTileN (const double aPadding=0.0)
	Returns the total 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...

unsigned int	GetTimeRange (void)
	Returns the time range [s]. More...

long unsigned int	ProjectData (fft *aDataFft)
	Projects a whitened data vector onto the Q planes. More...

double	SaveMaps (const string aOutdir, const string aName, const string aFormat, const double aTimeOffset=0.0, const bool aThumb=false)
	Saves the maps for each Q-planes in output files. More...

bool	SaveTriggers (TriggerBuffer *aTriggers)
	Saves tiles in a trigger structure. More...

void	SetChirp (const double aMchirp=-1.0, const double aMergerTime=-1.0)
	Sets the chirp mass [solar mass]. More...

void	SetMapFill (const string aMapContentType="snr")
	Defines how to fill the maps. More...

void	SetPlotTimeWindows (vector< unsigned int > aWindows)
	Sets the list of time windows for plots. More...

void	SetPower (Spectrum aSpec1, Spectrum aSpec2)
	Computes the noise power associated to the tiling structure. More...

void	SetRangez (const double aZmin=-1.0, const double aZmax=-1.0)
	Sets the map Z-axis range. More...

void	SetSnrThr (const double aSnrThr_map=0.0, const double aSnrThr_trigger=2.0)
	Sets a SNR threshold when saving maps and triggers. More...

Constructors and destructors
	Otile (const unsigned int aTimeRange, const unsigned int aTimeOverlap, const double aQMin, const double aQMax, const double aFrequencyMin, const double aFrequencyMax, const unsigned int aSampleFrequency, const double aMaximumMismatch, const unsigned int aFullMapNt=1, const string aPlotStyle="GWOLLUM", const unsigned int aVerbosity=0)
	Constructor of the Otile class. More...

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

Public Member Functions inherited from Osequence
Segments *	GetChunkOut (void)
	Returns the active segments in the current chunk. More...

unsigned int	GetChunkTimeCenter (void)
	Returns the central GPS time of current chunk [s]. More...

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

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

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

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

unsigned int	GetTimeRange (void)
	Returns the sequence time range [s]. More...

bool	NewChunk (bool &aNewSegFlag)
	Loads a new `Sequence` chunk. More...

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

unsigned int	SetSegments (Segments aInSeg, Segments aOutSeg=NULL)
	Sets new input/output segments. More...

	Osequence (const unsigned int aTimeRange, const unsigned int aTimeOverlap, const unsigned int aVerbosity=0)
	Constructor of the Osequence class. More...

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

Private Attributes
TF1 *	chirp
	Chirp track. More...

double	chirpm
	Chirp mass [solar mass]. More...

double	chirpt
	Chirp merger time [s]. More...

unsigned int **	f_snrmax
	Loudest frequency tile (SNR). More...

TH2D **	fullmap
	Full maps. More...

unsigned int	FullMapNt
	Number of time bins in the full map (0 for full resolution). More...

unsigned int	fVerbosity
	Verbosity level. More...

string	mapfill
	Map fill type. More...

double	MaximumMismatch
	Maximum mismatch. More...

unsigned int	nq
	number of q planes. More...

vector< unsigned int >	pwin
	Plot time windows. More...

Oqplane **	qplanes
	Q planes. More...

double	SnrThr_map
	Map SNR threshold. More...

unsigned int **	t_snrmax
	Loudest time tile (SNR). More...

double	vrange [2]
	Map Z-axis range. More...

Detailed Description

Construct a time-frequency-Q tiling structure.

This class is designed to tile the 3-dimensional space in time, frequency and Q. The tiling consists of logarithmically spaced Q-planes. Each of these planes is divided in logarithmically spaced frequency bands. Each of these bands are then linearly divided in time bins. Once constructed, the planes can be used to apply a Q-transform.

See also: Oqplane.

This class also initializes an analysis sequence with the Osequence class from which it inherits.

This class offers a graphical interface (GwollumPlot inheritance) and plotting functions to display the tiles and the data.

Constructor & Destructor Documentation

◆ Otile()

Otile::Otile	(	const unsigned int	aTimeRange,
		const unsigned int	aTimeOverlap,
		const double	aQMin,
		const double	aQMax,
		const double	aFrequencyMin,
		const double	aFrequencyMax,
		const unsigned int	aSampleFrequency,
		const double	aMaximumMismatch,
		const unsigned int	aFullMapNt = `1`,
		const string	aPlotStyle = `"GWOLLUM"`,
		const unsigned int	aVerbosity = `0`
	)

Constructor of the Otile class.

The 3-dimensional tiling structure is constructed given the user parameters. The parameter space is defined by a time range, a frequency range and a Q range. The user must specify a maximum mismatch value to guarantee a maximal fractional energy loss from one tile to the next.

The analysis sequence is initialized:

See also: Osequence::Osequence().

Parameters

[in]	aTimeRange	Time range [s].
[in]	aTimeOverlap	Time overlap [s].
[in]	aQMin	Minimal Q value.
[in]	aQMax	Maximal Q value.
[in]	aFrequencyMin	Minimal frequency [Hz].
[in]	aFrequencyMax	Maximal frequency [Hz].
[in]	aSampleFrequency	Sampling frequency [Hz].
[in]	aMaximumMismatch	Maximum mismatch between tiles.
[in]	aFullMapNt	Full map time resolution (number of bins). 0 = full resolution. Use = 1 for a minimum resolution. This resolution cannot be changed anymore.
[in]	aPlotStyle	Plotting style.
[in]	aVerbosity	Verbosity level.

◆ ~Otile()

Otile::~Otile ( void )

virtual

Destructor of the Otile class.

Member Function Documentation

◆ DrawMapTiling()

void Otile::DrawMapTiling ( const unsigned int aQindex )

Displays a canonical representation of a given Q-plane.

Parameters

[in] aQindex Q-plane index: must be valid.

◆ FillFullMap()

void Otile::FillFullMap	(	const unsigned int	aWindowIndex,
		const double	aTimeOffset = `0.0`
	)

Fills the full map.

The full map combines all the Q-planes. For a given full map bin, the highest SNR ovelapping Q-plane tile is considered.

Parameters

[in]	aWindowIndex	Window index, as defined with SetPlotTimeWindows().
[in]	aTimeOffset	Time offset [s].

Precondition: aWindowIndex must be a valid index.

◆ FillMaps()

void Otile::FillMaps ( void )

inline

Fills the Q-plane maps.

◆ GetBandFrequency()

double Otile::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 Otile::GetBandN ( const unsigned int aQindex )

inline

Returns the number of frequency bands 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 * Otile::GetBands ( const unsigned int aQindex )

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 Otile::GetBandTileN	(	const unsigned int	aQindex,
		const unsigned int	aBandIndex
	)

inline

Returns the number of tiles in a band 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 (irrelevant for the full map).

Precondition: The band index must be valid for a Q plane.

◆ GetChirpMass()

double Otile::GetChirpMass ( void )

inline

Returns the chirp mass [solar masses].

◆ GetFrequencyMax()

double Otile::GetFrequencyMax ( void )

inline

Returns the highest frequency of this tiling [Hz].

The maximum frequency of the highest Q plane is returned.

◆ GetFrequencyMin()

double Otile::GetFrequencyMin ( void )

inline

Returns the minimum frequency of this tiling [Hz].

The minimum frequency of the lowest-Q plane is returned.

◆ GetFullMap()

TH2D* Otile::GetFullMap ( const unsigned int aWindowIndex )

inline

Returns a copy of the full map.

Warning: Make sure the full map was built with FillFullMap().

Parameters

[in] aWindowIndex Window index, as defined with SetPlotTimeWindows().

Precondition: aWindowIndex must be a valid index.

◆ GetMapFill()

string Otile::GetMapFill ( void )

inline

Returns the current map fill type.

See also: SetMapFill().

◆ GetMismatchMax()

double Otile::GetMismatchMax ( void )

inline

Returns the maximum mismatch between tiles.

◆ GetPlotTimeWindows()

vector<unsigned int> Otile::GetPlotTimeWindows ( void )

inline

Returns the list of time windows for plots.

◆ GetQ()

double Otile::GetQ ( const unsigned int aQindex )

inline

Returns the Q value of a given Q-plane.

Parameters

[in] aQindex Q-plane index. If the index is out of range, 0 is returned.

◆ GetQN()

unsigned int Otile::GetQN ( void )

inline

Returns the number of Q-planes.

◆ GetRangezMin()

double Otile::GetRangezMin ( void )

inline

Returns the map Z-axis range minimum.

◆ GetSnrMapThr()

double Otile::GetSnrMapThr ( void )

inline

Returns the current SNR threshold for maps.

See also: SetSnrThr().

◆ GetSnrSqMax()

double Otile::GetSnrSqMax ( const unsigned int aQindex )

inline

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

Parameters

[in] aQindex Q-plane index.

◆ GetSnrTriggerThr()

double Otile::GetSnrTriggerThr ( void )

inline

Returns the current SNR threshold for triggers.

See also: SetSnrThr().

◆ GetTileAmplitude()

double Otile::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 Otile::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.

◆ GetTileN()

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

Returns the total 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 * Otile::GetTileSegments	(	TH1D *	aSnrThreshold,
		const double	aPadding
	)

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.

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

See also: Oqplane::AddTileSegments()

◆ GetTileSnrSq()

double Otile::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.

◆ GetTimeRange()

unsigned int Otile::GetTimeRange ( void )

inline

Returns the time range [s].

◆ ProjectData()

long unsigned int Otile::ProjectData ( fft * aDataFft )

Projects a whitened data vector onto the Q planes.

The complex data vector is projected onto each Q-plane. The data is provided through a fft object. The fft::Forward() must be applied before calling this function.

Returns: The number of tiles (excluding half the overlap on both sides) above the SNR threshold.

See also: Oqplane::ProjectData().

Parameters

[in] aDataFft fft structure containing the data to project.

◆ SaveMaps()

double Otile::SaveMaps	(	const string	aOutdir,
		const string	aName,
		const string	aFormat,
		const double	aTimeOffset = `0.0`,
		const bool	aThumb = `false`
	)

Saves the maps for each Q-planes in output files.

The maps are saved in output files. An additionnal map called "full map" is also saved. It combines all tiles projected in the time-frequency plane.

Warning: Maps are not saved if the maximum SNR within the first window is below the SNR map threshold: see SetSnrThr().

Returns: The maximum SNR value within the first window time range (-1.0 if this function fails)

Parameters

[in]	aOutdir	Output directory path to save the plots. It must exist.
[in]	aName	Name identifier used for titles.
[in]	aFormat	Output format string: usual graphical formats are supported.
[in]	aTimeOffset	Time offset applied to the window center [s].
[in]	aThumb	Produce thumbnails if set to true.

◆ SaveTriggers()

bool Otile::SaveTriggers ( TriggerBuffer * aTriggers )

Saves tiles in a trigger structure.

Tiles with a SNR value above the SNR threshold are saved in the input trigger structure.

See also: Oqplane::SaveTriggers().

The corresponding triggers Segments are also saved following the GWOLLUM convention for triggers. If the Sequence algorithm is in use, the current timing is applied to the tiling.

See also: SetSnrThr() and Osequence::SetSegments().

Parameters

[in] aTriggers TriggerBuffer object.

Returns: true if the function was successful, false otherwise.

◆ SetChirp()

void Otile::SetChirp	(	const double	aMchirp = `-1.0`,
		const double	aMergerTime = `-1.0`
	)

inline

Sets the chirp mass [solar mass].

Use a negative mass value to not draw the chirp track. If the merger time is negative, the merger time is taken at the center of the timing window.

Parameters

[in]	aMchirp	Chirp mass in solar masses.
[in]	aMergerTime	Merger GPS time [s].

◆ SetMapFill()

void Otile::SetMapFill ( const string aMapContentType = "snr" )

inline

Defines how to fill the maps.

Use a keyword to define the content of maps:

"snr": fill with SNR values
"amplitude": fill with amplitude values
"phase": fill with phase values

Parameters

[in] aMapContentType Map content keyword.

◆ SetPlotTimeWindows()

void Otile::SetPlotTimeWindows ( vector< unsigned int > aWindows )

Sets the list of time windows for plots.

The full map containers are created.

Note: If a time window in the list is 0 or is larger than the tiling time range, it is forced to take the tiling time range value.

Parameters

[in] aWindows List of time windows [s].

◆ SetPower()

void Otile::SetPower	(	Spectrum *	aSpec1,
		Spectrum *	aSpec2
	)

inline

Computes the noise power associated to the tiling structure.

See also: Oqplane::SetPower().

Parameters

[in]	aSpec1	First noise power spectrum used to whiten the data.
[in]	aSpec2	Second noise power spectrum used to whiten the data.

◆ SetRangez()

void Otile::SetRangez	(	const double	aZmin = `-1.0`,
		const double	aZmax = `-1.0`
	)

inline

Sets the map Z-axis range.

If aZmin>=aZmax, the Z-axis is automatically ranged.

Parameters

[in]	aZmin	Minimum Z value.
[in]	aZmax	Maximum Z value.

◆ SetSnrThr()

void Otile::SetSnrThr	(	const double	aSnrThr_map = `0.0`,
		const double	aSnrThr_trigger = `2.0`
	)

inline

Sets a SNR threshold when saving maps and triggers.

The thresholds are applied when calling the SaveMaps() or SaveTriggers() functions.

Parameters

[in]	aSnrThr_map	When calling SaveMaps(), a map is not saved if the loudest tile is below that threshold.
[in]	aSnrThr_trigger	Tiles with a SNR value below that threshold are not saved when calling SaveTriggers().

Member Data Documentation

◆ chirp

TF1* Otile::chirp

private

Chirp track.

◆ chirpm

double Otile::chirpm

private

Chirp mass [solar mass].

◆ chirpt

double Otile::chirpt

private

Chirp merger time [s].

◆ f_snrmax

unsigned int** Otile::f_snrmax

private

Loudest frequency tile (SNR).

◆ fullmap

TH2D** Otile::fullmap

private

Full maps.

◆ FullMapNt

unsigned int Otile::FullMapNt

private

Number of time bins in the full map (0 for full resolution).

◆ fVerbosity

unsigned int Otile::fVerbosity

private

Verbosity level.

◆ mapfill

string Otile::mapfill

private

Map fill type.

◆ MaximumMismatch

double Otile::MaximumMismatch

private

Maximum mismatch.

◆ nq

unsigned int Otile::nq

private

number of q planes.

◆ pwin

vector<unsigned int> Otile::pwin

private

Plot time windows.

◆ qplanes

Oqplane** Otile::qplanes

private

Q planes.

◆ SnrThr_map

double Otile::SnrThr_map

private

Map SNR threshold.

◆ t_snrmax

unsigned int** Otile::t_snrmax

private

Loudest time tile (SNR).

◆ vrange

double Otile::vrange[2]

private

Map Z-axis range.

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

src/Otile.h
src/Otile.cc

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Otile()

◆ ~Otile()

Member Function Documentation

◆ DrawMapTiling()

◆ FillFullMap()

◆ FillMaps()

◆ GetBandFrequency()

◆ GetBandN()

◆ GetBands()

◆ GetBandTileN()

◆ GetChirpMass()

◆ GetFrequencyMax()

◆ GetFrequencyMin()

◆ GetFullMap()

◆ GetMapFill()

◆ GetMismatchMax()

◆ GetPlotTimeWindows()

◆ GetQ()

◆ GetQN()

◆ GetRangezMin()

◆ GetSnrMapThr()

◆ GetSnrSqMax()

◆ GetSnrTriggerThr()

◆ GetTileAmplitude()

◆ GetTileAmplitudeSq()

◆ GetTileN()

◆ GetTileSegments()

◆ GetTileSnrSq()

◆ GetTimeRange()

◆ ProjectData()

◆ SaveMaps()

◆ SaveTriggers()

◆ SetChirp()

◆ SetMapFill()

◆ SetPlotTimeWindows()

◆ SetPower()

◆ SetRangez()

◆ SetSnrThr()

Member Data Documentation

◆ chirp

◆ chirpm

◆ chirpt

◆ f_snrmax

◆ fullmap

◆ FullMapNt

◆ fVerbosity

◆ mapfill

◆ MaximumMismatch

◆ nq

◆ pwin

◆ qplanes

◆ SnrThr_map

◆ t_snrmax

◆ vrange