Detailed Description

Module for computing PSD (Power Spectral Density) estimates and handling related structures.

Overview: create/destroy functions, modify functions, property functions, generation functions, file writing functions.

Data Structures
struct	MultiPSDVector
	A collection of PSD vectors – one for each IFO in a multi-IFO search. More...

struct	MultiNoiseWeights
	One noise-weight (number) per SFT (therefore indexed over IFOs and SFTs. More...

Typedefs
typedef REAL8FrequencySeriesVector	PSDVector
	Special type for holding a PSD vector (over several SFTs) More...

Enumerations
enum	MathOpType { MATH_OP_ARITHMETIC_SUM = 0 , MATH_OP_ARITHMETIC_MEAN , MATH_OP_ARITHMETIC_MEDIAN , MATH_OP_HARMONIC_SUM , MATH_OP_HARMONIC_MEAN , MATH_OP_POWERMINUS2_SUM , MATH_OP_POWERMINUS2_MEAN , MATH_OP_MINIMUM , MATH_OP_MAXIMUM , MATH_OP_LAST }
	common types of mathematical operations over an array More...

Variables
const UserChoices	MathOpTypeChoices

PSD type create/destroy functions

void	XLALDestroyPSDVector (PSDVector *vect)
	Destroy a PSD-vector. More...

void	XLALDestroyMultiPSDVector (MultiPSDVector *multvect)
	Destroy a multi PSD-vector. More...

MultiNoiseWeights *	XLALCreateMultiNoiseWeights (const UINT4 length)
	Create a `MultiNoiseWeights` of the given length. More...

MultiNoiseWeights *	XLALCopyMultiNoiseWeights (const MultiNoiseWeights *multiWeights)
	Create a full copy of a `MultiNoiseWeights` object. More...

void	XLALDestroyMultiNoiseWeights (MultiNoiseWeights *weights)
	Destroy a MultiNoiseWeights object. More...

PSD type modify functions

int	XLALCropMultiPSDandSFTVectors (MultiPSDVector multiPSDVect, MultiSFTVector multiSFTVect, UINT4 firstBin, UINT4 lastBin)
	Function that truncates the PSD in place to the requested frequency-bin interval [firstBin, lastBin] for the given multiPSDVector. More...

PSD type property functions

MultiNoiseWeights *	XLALComputeMultiNoiseWeights (const MultiPSDVector *rngmed, UINT4 blocksRngMed, UINT4 excludePercentile)
	Computes weight factors arising from MultiSFTs with different noise floors. More...

PSD generation functions

REAL8FrequencySeries *	XLALComputeSegmentDataQ (const MultiPSDVector *multiPSDVect, LALSeg segment)
	Compute the "data-quality factor" \( \mathcal{Q}(f) = \sum_X \frac{\epsilon_X}{\mathcal{S}_X(f)} \) over the given SFTs. More...

REAL8	XLALMathOpOverArray (const REAL8 *data, const size_t length, const MathOpType optype)
	Compute various types of "math operations" over the entries of an array. More...

REAL8	XLALGetMathOpNormalizationFactorFromTotalNumberOfSFTs (const UINT4 totalNumSFTs, const MathOpType optypeSFTs)
	Compute an additional normalization factor from the total number of SFTs to be applied after a loop of mathops over SFTs and IFOs. More...

int	XLALComputePSDandNormSFTPower (REAL8Vector finalPSD, MultiPSDVector multiPSDVector, REAL8Vector *normSFT, MultiSFTVector inputSFTs, const BOOLEAN returnMultiPSDVector, const BOOLEAN returnNormSFT, const UINT4 blocksRngMed, const MathOpType PSDmthopSFTs, const MathOpType PSDmthopIFOs, const MathOpType nSFTmthopSFTs, const MathOpType nSFTmthopIFOs, const BOOLEAN normalizeByTotalNumSFTs, const REAL8 FreqMin, const REAL8 FreqBand, const BOOLEAN normalizeSFTsInPlace)
	Compute the PSD (power spectral density) and the "normalized power" \( P_\mathrm{SFT} \) over a MultiSFTVector. More...

int	XLALComputePSDfromSFTs (REAL8Vector *finalPSD, MultiSFTVector inputSFTs, const UINT4 blocksRngMed, const MathOpType PSDmthopSFTs, const MathOpType PSDmthopIFOs, const BOOLEAN normalizeByTotalNumSFTs, const REAL8 FreqMin, const REAL8 FreqBand)
	Compute the PSD (power spectral density) over a MultiSFTVector. More...

PSD file writing functions

int	XLALDumpMultiPSDVector (const CHAR outbname, const MultiPSDVector multiPSDVect)
	Dump complete multi-PSDVector over IFOs, timestamps and frequency-bins into per-IFO ASCII output-files 'outbname-IFO'. More...

int	XLALWritePSDtoFilePointer (FILE fpOut, REAL8Vector PSDVect, REAL8Vector *normSFTVect, BOOLEAN outputNormSFT, BOOLEAN outFreqBinEnd, INT4 PSDmthopBins, INT4 nSFTmthopBins, INT4 binSize, INT4 binStep, REAL8 Freq0, REAL8 dFreq)
	Write a PSD vector as an ASCII table to an open output file pointer. More...

Function Documentation

◆ XLALDestroyPSDVector()

void XLALDestroyPSDVector ( PSDVector * vect )

Destroy a PSD-vector.

Parameters

vect	the PSD-vector to free

Definition at line 74 of file PSDutils.c.

◆ XLALDestroyMultiPSDVector()

void XLALDestroyMultiPSDVector ( MultiPSDVector * multvect )

Destroy a multi PSD-vector.

Parameters

multvect the SFT-vector to free

Definition at line 102 of file PSDutils.c.

◆ XLALCreateMultiNoiseWeights()

MultiNoiseWeights * XLALCreateMultiNoiseWeights ( const UINT4 length )

Create a MultiNoiseWeights of the given length.

NOTE: this does not allocate the individual data entries.

Parameters

[in] length Length of the MultiNoiseWeights.

Definition at line 125 of file PSDutils.c.

◆ XLALCopyMultiNoiseWeights()

MultiNoiseWeights * XLALCopyMultiNoiseWeights ( const MultiNoiseWeights * multiWeights )

Create a full copy of a MultiNoiseWeights object.

Parameters

[in] multiWeights Length of the MultiNoiseWeights.

Definition at line 143 of file PSDutils.c.

◆ XLALDestroyMultiNoiseWeights()

void XLALDestroyMultiNoiseWeights ( MultiNoiseWeights * weights )

Destroy a MultiNoiseWeights object.

Definition at line 172 of file PSDutils.c.

◆ XLALCropMultiPSDandSFTVectors()

int XLALCropMultiPSDandSFTVectors	(	MultiPSDVector *	multiPSDVect,
		MultiSFTVector *	multiSFTVect,
		UINT4	firstBin,
		UINT4	lastBin
	)

Function that truncates the PSD in place to the requested frequency-bin interval [firstBin, lastBin] for the given multiPSDVector.

Now also truncates the original SFT vector, as necessary for correct computation of normalized SFT power.

Definition at line 195 of file PSDutils.c.

◆ XLALComputeMultiNoiseWeights()

MultiNoiseWeights * XLALComputeMultiNoiseWeights	(	const MultiPSDVector *	rngmed,
		UINT4	blocksRngMed,
		UINT4	excludePercentile
	)

Computes weight factors arising from MultiSFTs with different noise floors.

Definition at line 285 of file PSDutils.c.

◆ XLALComputeSegmentDataQ()

REAL8FrequencySeries * XLALComputeSegmentDataQ	(	const MultiPSDVector *	multiPSDVect,
		LALSeg	segment
	)

Compute the "data-quality factor" \( \mathcal{Q}(f) = \sum_X \frac{\epsilon_X}{\mathcal{S}_X(f)} \) over the given SFTs.

The input multiPSD is a pre-computed PSD map \( \mathcal{S}_{X,i}(f) \) , over IFOs \( X \) , SFTs \( i \) and frequency \( f \) .

Returns: the output is a vector \( \mathcal{Q}(f) \) .

Parameters

multiPSDVect	input PSD map over IFOs, SFTs, and frequencies
segment	segment to compute Q for

Definition at line 375 of file PSDutils.c.

◆ XLALMathOpOverArray()

REAL8 XLALMathOpOverArray	(	const REAL8 *	data,
		const size_t	length,
		const MathOpType	optype
	)

Compute various types of "math operations" over the entries of an array.

The supported optypes (e.g. sums and averages) are defined in MathOpType.

This can be used e.g. for the different established conventions of combining SFTs for a PSD estimate.

Parameters

data	input data array
length	length of the input data array
optype	type of operation

Definition at line 491 of file PSDutils.c.

◆ XLALGetMathOpNormalizationFactorFromTotalNumberOfSFTs()

REAL8 XLALGetMathOpNormalizationFactorFromTotalNumberOfSFTs	(	const UINT4	totalNumSFTs,
		const MathOpType	optypeSFTs
	)

Compute an additional normalization factor from the total number of SFTs to be applied after a loop of mathops over SFTs and IFOs.

Currently only implemented for: MATH_OP_HARMONIC_SUM (to emulate MATH_OP_HARMONIC_MEAN over the combined array) MATH_OP_POWERMINUS2_SUM (to emulate MATH_OP_POWERMINUS2_MEAN over the combined array)

This function exists only as a simple workaround for when we want to compute some types of mathops, e.g. the harmonic or power2 mean, over all SFTs from all detectors together: then call XLALComputePSDandNormSFTPower with PSDmthopSFTs=PSDmthopIFOs=MATH_OP_[HARMONIC/POWERMINUS2]_SUM and then this factor is applied at the end, which gives equivalent results to if we had rewritten the loop order in XLALComputePSDandNormSFTPower to allow for calling MATH_OP_[HARMONIC/POWERMINUS2]_MEAN over the combined array.

Parameters

totalNumSFTs	total number of SFTs from all IFOs
optypeSFTs	type of operations that was done over SFTs

Definition at line 627 of file PSDutils.c.

◆ XLALComputePSDandNormSFTPower()

int XLALComputePSDandNormSFTPower	(	REAL8Vector **	finalPSD,
		MultiPSDVector **	multiPSDVector,
		REAL8Vector **	normSFT,
		MultiSFTVector *	inputSFTs,
		const BOOLEAN	returnMultiPSDVector,
		const BOOLEAN	returnNormSFT,
		const UINT4	blocksRngMed,
		const MathOpType	PSDmthopSFTs,
		const MathOpType	PSDmthopIFOs,
		const MathOpType	nSFTmthopSFTs,
		const MathOpType	nSFTmthopIFOs,
		const BOOLEAN	normalizeByTotalNumSFTs,
		const REAL8	FreqMin,
		const REAL8	FreqBand,
		const BOOLEAN	normalizeSFTsInPlace
	)

Compute the PSD (power spectral density) and the "normalized power" \( P_\mathrm{SFT} \) over a MultiSFTVector.

Returns: : a REAL8Vector of the final normalized and averaged/summed PSD; plus the full multiPSDVector array, and optionally a REAL8Vector of normalized SFT power (only if not passed as NULL)

If normalizeSFTsInPlace is TRUE, then the inputSFTs will be modified by XLALNormalizeMultiSFTVect(). If it is FALSE, an internal copy will be used and the inputSFTs will be returned unmodified.

Definition at line 677 of file PSDutils.c.

◆ XLALComputePSDfromSFTs()

int XLALComputePSDfromSFTs	(	REAL8Vector **	finalPSD,
		MultiSFTVector *	inputSFTs,
		const UINT4	blocksRngMed,
		const MathOpType	PSDmthopSFTs,
		const MathOpType	PSDmthopIFOs,
		const BOOLEAN	normalizeByTotalNumSFTs,
		const REAL8	FreqMin,
		const REAL8	FreqBand
	)

Compute the PSD (power spectral density) over a MultiSFTVector.

This is just a convenience wrapper around XLALComputePSDandNormSFTPower() without the extra options for normSFTpower computation.

Returns: a REAL8Vector of the final normalized and averaged/summed PSD.

NOTE: contrary to earlier versions of this function, it no longer modifies the inputSFTs in-place, so now it can safely be called multiple times.

Definition at line 894 of file PSDutils.c.

◆ XLALDumpMultiPSDVector()

int XLALDumpMultiPSDVector	(	const CHAR *	outbname,
		const MultiPSDVector *	multiPSDVect
	)

Dump complete multi-PSDVector over IFOs, timestamps and frequency-bins into per-IFO ASCII output-files 'outbname-IFO'.

Parameters

outbname	output basename 'outbname'
multiPSDVect	multi-psd vector to output

Definition at line 936 of file PSDutils.c.

◆ XLALWritePSDtoFilePointer()

int XLALWritePSDtoFilePointer	(	FILE *	fpOut,
		REAL8Vector *	PSDVect,
		REAL8Vector *	normSFTVect,
		BOOLEAN	outputNormSFT,
		BOOLEAN	outFreqBinEnd,
		INT4	PSDmthopBins,
		INT4	nSFTmthopBins,
		INT4	binSize,
		INT4	binStep,
		REAL8	Freq0,
		REAL8	dFreq
	)

Write a PSD vector as an ASCII table to an open output file pointer.

Adds a column header string, but version or commandline info needs to be printed by the caller.

Standard and (optional) columns: FreqBinStart (FreqBinEnd) PSD (normSFTpower)

Parameters

fpOut	output file pointer
PSDVect	required: PSD vector
normSFTVect	optional: normSFT vector (can be NULL if outputNormSFT==False)
outputNormSFT	output a column for normSFTVect?
outFreqBinEnd	output a column for the end frequency of each bin?
PSDmthopBins	math operation for binning of the PSD
nSFTmthopBins	math operation for binning of the normSFT
binSize	output bin size (in number of input bins, 1 to keep input binning)
binStep	output bin step (in number of input bins, 1 to keep input binning)
Freq0	starting frequency of inputs
dFreq	frequency step of inputs

Definition at line 1056 of file PSDutils.c.

Typedef Documentation

◆ PSDVector

typedef REAL8FrequencySeriesVector PSDVector

Special type for holding a PSD vector (over several SFTs)

Definition at line 59 of file PSDutils.h.

Enumeration Type Documentation

◆ MathOpType

enum MathOpType

common types of mathematical operations over an array

Enumerator
MATH_OP_ARITHMETIC_SUM	\( \sum_k x_k \)
MATH_OP_ARITHMETIC_MEAN	\( \sum_k x_k / N \)
MATH_OP_ARITHMETIC_MEDIAN	\( x_1 \leq \dots \leq x_{N/2} \leq \dots \leq x_n \)
MATH_OP_HARMONIC_SUM	\( 1 / \sum_k (1/x_k) \)
MATH_OP_HARMONIC_MEAN	\( N / \sum_k (1/x_k) \)
MATH_OP_POWERMINUS2_SUM	\( 1 / \sqrt{ \sum_k (1/x_k^2) } \)
MATH_OP_POWERMINUS2_MEAN	\( 1 / \sqrt{ \sum_k (1/x_k^2) / N } \)
MATH_OP_MINIMUM	\( \min_k(x_k) \)
MATH_OP_MAXIMUM	\( \max_k(x_k) \)
MATH_OP_LAST

Definition at line 82 of file PSDutils.h.

Variable Documentation

◆ MathOpTypeChoices

const UserChoices MathOpTypeChoices

extern

Definition at line 44 of file PSDutils.c.

Detailed Description

Data Structures

Typedefs

Enumerations

Variables

PSD type create/destroy functions

PSD type modify functions

PSD type property functions

PSD generation functions

PSD file writing functions

Function Documentation

◆ XLALDestroyPSDVector()

◆ XLALDestroyMultiPSDVector()

◆ XLALCreateMultiNoiseWeights()

◆ XLALCopyMultiNoiseWeights()

◆ XLALDestroyMultiNoiseWeights()

◆ XLALCropMultiPSDandSFTVectors()

◆ XLALComputeMultiNoiseWeights()

◆ XLALComputeSegmentDataQ()

◆ XLALMathOpOverArray()

◆ XLALGetMathOpNormalizationFactorFromTotalNumberOfSFTs()

◆ XLALComputePSDandNormSFTPower()

◆ XLALComputePSDfromSFTs()

◆ XLALDumpMultiPSDVector()

◆ XLALWritePSDtoFilePointer()

Typedef Documentation

◆ PSDVector

Enumeration Type Documentation

◆ MathOpType

Variable Documentation

◆ MathOpTypeChoices