Construct and apply a time-frequency-Q analysis. More...
#include <Otile.h>
Public Member Functions | |
| bool | DrawMapTiling (const int aQindex) |
| Displays a canonical representation of a given Q-plane. | |
| int | GetChunkTimeCenter (void) |
| Returns the GPS center time of current chunk. | |
| int | GetChunkTimeEnd (void) |
| Returns the GPS ending time of current chunk. | |
| int | GetChunkTimeStart (void) |
| Returns the GPS starting time of current chunk. | |
| int | GetCurrentOverlapDuration (void) |
| Returns the current overlap duration. | |
| double | GetFrequencyMax (void) |
| Returns the highest frequency of this tiling. | |
| double | GetFrequencyMin (void) |
| Returns the lowest frequency of this tiling. | |
| string | GetMapFill (void) |
| Returns the current map fill type. | |
| double | GetMismatchMax (void) |
| Returns the maximum mismatch between tiles. | |
| int | GetNQ (void) |
| Returns the number of Q planes. | |
| int | GetOverlapDuration (void) |
| Returns the nominal overlap duration. | |
| double | GetQ (const int aQindex) |
| Returns the Q value of a given plane. | |
| double | GetSNRMapThr (void) |
| Returns the current SNR threshold for maps. | |
| double | GetSNRTriggerThr (void) |
| Returns the current SNR threshold for triggers. | |
| int | GetTimeRange (void) |
| Returns the time range. | |
| bool | NewChunk (bool &aNewSegFlag) |
| Loads a new sequence chunk. | |
| int | ProjectData (fft *aDataFft) |
| Projects a data vector onto the Q planes. | |
| double | SaveMaps (const string aOutdir, const string aName, const string aFormat, vector< int > aWindows, const bool aThumb=false) |
| Saves the maps for each Q-planes in output files. | |
| bool | SaveTriggers (TriggerBuffer *aTriggers) |
| Saves tiles in a MakeTriggers structure. | |
| void | SetMapFill (const string aMapFill="snr") |
| Defines how to fill the maps. | |
| void | SetOverlapDuration (const int aOverlapDuration) |
| Sets a new sequence overlap duration. | |
| bool | SetPower (Spectrum *aSpec1, Spectrum *aSpec2) |
| Sets the data power spectrum. | |
| void | SetRangez (const double aZmin=-1.0, const double aZmax=-1.0) |
| Sets the map vertical range. | |
| bool | SetSegments (Segments *aInSeg, Segments *aOutSeg=NULL) |
| Sets new input/output segments. | |
| void | SetSNRThr (const double aSNRThr_map=0.0, const double aSNRThr_trigger=2.0) |
| Sets a SNR threshold when saving maps and triggers. | |
Constructors and destructors | |
| Otile (const int aTimeRange, const double aQMin, const double aQMax, const double aFrequencyMin, const double aFrequencyMax, const int aSampleFrequency, const double aMaximumMismatch, const string aPlotStyle="GWOLLUM", const int aVerbosity=0) | |
| Constructor of the Otile class. | |
| virtual | ~Otile (void) |
| Destructor of the Otile class. | |
Static Public Member Functions | |
| static vector< double > | ComputeQs (const double aQMin, const double aQMax, const double aMaximumMismatch) |
| Computes a set of Q values. | |
Construct and apply a time-frequency-Q analysis.
This class was 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 data segments.
This class offers an algorithm, called Sequence, to read an input segment list sequentially. The Segments object is divided into overlapping time chunks matching the tiling duration. The chunks are loaded sequentially any time the NewChunk() function is called. The chunk sequence can be represented in the following way:
------------------------------------------------------------ current segment
|------------------| chunk i-1
|------------------| chunk i
|------------------| chunk i+1
|---| overlap
In general, the Segments object contain multiple time segments. The sequence described above does not necessarily match the size of the input segments. The sequence algorithm is designed to deal with such edge effects. Firstly, segments shorter than the tiling duration are skipped. When calling NewChunk() for the last chunk of a segment, the overlap duration is adjusted to fit the leftover:
-----------------------------------------| <--- input segment under processing
|--------------------------| <--- penultimate chunk
###### call NextChunk() to cover the left-over
|--------------------------| <--- last chunk
|---------------| <--- adjusted overlap
* Obviously, the user must be careful about this special case as the overlap duration is modified (the chunk duration is never changed). Some functions are available to monitor the overlap size.
When moving to a new segment, the overlap duration is set back to nominal values.
This class offers a graphical interface (GwollumPlot inheritance) and plotting functions to display the tiles and the data.
| Otile::Otile | ( | const int | aTimeRange, | |
| const double | aQMin, | |||
| const double | aQMax, | |||
| const double | aFrequencyMin, | |||
| const double | aFrequencyMax, | |||
| const int | aSampleFrequency, | |||
| const double | aMaximumMismatch, | |||
| const string | aPlotStyle = "GWOLLUM", |
|||
| const int | aVerbosity = 0 | |||
| ) |
Constructor of the Otile class.
The tiling 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 corresponding to a maximal fractional energy loss from one tile to the next.
Some conditions are to be met to use this class:
The tiling parameters (time, Q and frequency range and the mismatch max) can be internally modified to match these conditions.
| aTimeRange | time range [s] | |
| aQMin | minimal Q value | |
| aQMax | maximal Q value | |
| aFrequencyMin | minimal frequency [Hz] | |
| aFrequencyMax | maximal frequency [Hz] | |
| aSampleFrequency | sampling frequency [Hz] | |
| aMaximumMismatch | maximum mismatch between tiles | |
| aPlotStyle | plotting style | |
| aVerbosity | verbosity level |
| Otile::~Otile | ( | void | ) | [virtual] |
Destructor of the Otile class.
| vector< double > Otile::ComputeQs | ( | const double | aQMin, | |
| const double | aQMax, | |||
| const double | aMaximumMismatch | |||
| ) | [static] |
Computes a set of Q values.
This function returns a vector of Q values corresponding to a set of parameters:
| aQMin | minimal Q value | |
| aQMax | maximal Q value | |
| aMaximumMismatch | maximum mismatch between Q planes |
| bool Otile::DrawMapTiling | ( | const int | aQindex | ) |
Displays a canonical representation of a given Q-plane.
| aQindex | Q-plane index |
| int Otile::GetChunkTimeCenter | ( | void | ) | [inline] |
Returns the GPS center time of current chunk.
| int Otile::GetChunkTimeEnd | ( | void | ) | [inline] |
Returns the GPS ending time of current chunk.
| int Otile::GetChunkTimeStart | ( | void | ) | [inline] |
Returns the GPS starting time of current chunk.
| int Otile::GetCurrentOverlapDuration | ( | void | ) | [inline] |
Returns the current overlap duration.
In most cases the overlap duration is nominal unless the special case of the end of an input segment is hit.
| double Otile::GetFrequencyMax | ( | void | ) | [inline] |
Returns the highest frequency of this tiling.
The maximum frequency of the highest Q plane is returned.
| double Otile::GetFrequencyMin | ( | void | ) | [inline] |
Returns the lowest frequency of this tiling.
The minimum frequency of the lowest Q plane is returned.
| string Otile::GetMapFill | ( | void | ) | [inline] |
Returns the current map fill type.
See SetMapFill().
| double Otile::GetMismatchMax | ( | void | ) | [inline] |
Returns the maximum mismatch between tiles.
| int Otile::GetNQ | ( | void | ) | [inline] |
Returns the number of Q planes.
| int Otile::GetOverlapDuration | ( | void | ) | [inline] |
Returns the nominal overlap duration.
| double Otile::GetQ | ( | const int | aQindex | ) | [inline] |
Returns the Q value of a given plane.
-1.0 is returned if this function fails.
| aQindex | Q-plane index |
| double Otile::GetSNRMapThr | ( | void | ) | [inline] |
Returns the current SNR threshold for maps.
See SetSNRThr().
| double Otile::GetSNRTriggerThr | ( | void | ) | [inline] |
Returns the current SNR threshold for triggers.
See SetSNRThr().
| int Otile::GetTimeRange | ( | void | ) | [inline] |
Returns the time range.
| bool Otile::NewChunk | ( | bool & | aNewSegFlag | ) |
Loads a new sequence chunk.
The chunks are loaded following the definition presented in the description of this class. This function should be called iteratively to cover the full data set defined with SetSegments(). The returned value indicates the status of this operation:
| aNewSegFlag | set to true if a new segment is started |
| int Otile::ProjectData | ( | fft * | aDataFft | ) |
Projects a data vector onto the Q planes.
The complex data vector is projected onto all the Q-planes. The data are provided through a fft object. The fft:Forward() must be done before calling this function. The number of tiles (excluding overlaps/2) above the SNR threshold is returned.
IMPORTANT: the input data vector must the right size, i.e. SampleFrequency/2 as defined in the constructor. No check will be performed!
| aFft | fft structure containing the data to project |
| double Otile::SaveMaps | ( | const string | aOutdir, | |
| const string | aName, | |||
| const string | aFormat, | |||
| vector< int > | aWindows, | |||
| 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 'fullmap' is also saved. It represents active tiles projected in the time-frequency plane. IMPORTANT NOTE: Maps are not saved if the maximum SNR within the first window time range is below the SNR threshold, see SetSNRThr(). The returned value is the maximum SNR value within the first window time range. -1.0 is returned if this function fails.
See also SetSNRThr().
| aOutdir | output directory path | |
| aName | name identifier | |
| aFormat | output format string | |
| aWindows | list of time windows | |
| aThumb | also produce thumbnails if set to true |
| bool Otile::SaveTriggers | ( | TriggerBuffer * | aTriggers | ) |
Saves tiles in a MakeTriggers structure.
Tiles with a SNR value above the SNR threshold are saved in the input trigger structure. 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.
A time selection is performed if specific output segments were previously set with SetSegments(): triggers the time of which is outside the output segment list are not saved.
See also SetSNRThr() and SetSegments().
| aTriggers | MakeTriggers object |
| void Otile::SetMapFill | ( | const string | aMapFill = "snr" |
) | [inline] |
Defines how to fill the maps.
| aMapFill | fill type |
| void Otile::SetOverlapDuration | ( | const int | aOverlapDuration | ) | [inline] |
Sets a new sequence overlap duration.
The input parameter can be modified to be an even number.
| aOverlapDuration | new overlap duration [s] |
Sets the data power spectrum.
This function must be called to compute the amplitude in a given tile: amplitude = SNR * (band noise amplitude). The noise power of a tile is given by the input noise power spectrum averaged across the bisquare window. If this function is never called, the power is set to 0. Two spectra must be given as a double whitening is into play.
The PSDs must be given as valid Spectrum structures, i.e, the PSDs were previously computed.
| void Otile::SetRangez | ( | const double | aZmin = -1.0, |
|
| const double | aZmax = -1.0 | |||
| ) | [inline] |
Sets the map vertical range.
If aZmin>=aZmax, the map is automatically ranged.
| aZmin | minimum Z value | |
| aZmax | maximum Z value |
Sets new input/output segments.
The input list of segments will be read sequencially using Sequence. The input segment times must be integer numbers. They will be considered as such!
Optionally, an ouput segment list can be provided to select triggers when calling SaveTriggers(). If pointing to NULL, no time selection is performed.
| aInSeg | input segment list | |
| aOutSeg | output segment list |
| 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.
| aSNRThr_map | when calling SaveMaps(), a map is not saved if the loudest tile is below that threshold | |
| aSNRThr_trigger | tiles with a SNR value below that threshold are not saved when calling SaveTriggers() |
1.6.1