Header LineRobustStats.h

Detailed Description

Functions to compute line-robust CW statistics.

Author

David Keitel, Reinhard Prix

Prototypes
BSGLSetup *	XLALCreateBSGLSetup (const UINT4 numDetectors, const REAL4 Fstar0sc, const REAL4 oLGX[PULSAR_MAX_DETECTORS], const BOOLEAN useLogCorrection, const UINT4 numSegments)
void	XLALDestroyBSGLSetup (BSGLSetup *setup)
int	XLALVectorComputeBSGL (REAL4 *outBSGL, const REAL4 *twoF, const REAL4 *twoFPerDet[PULSAR_MAX_DETECTORS], const UINT4 len, const BSGLSetup *setup)
REAL4	XLALComputeBSGL (const REAL4 twoF, const REAL4 twoFX[PULSAR_MAX_DETECTORS], const BSGLSetup *setup)
	Single-bin wrapper of XLALVectorComputeBSGL(), provided for backwards compatibility. More...
int	XLALVectorComputeGLtLDenominator (REAL4 *outDenom, const REAL4 *twoFPerDet[PULSAR_MAX_DETECTORS], const REAL4 *maxTwoFSegPerDet[PULSAR_MAX_DETECTORS], const UINT4 len, const BSGLSetup *setup)
int	XLALVectorComputeBSGLtL (REAL4 *outBSGLtL, const REAL4 *twoF, const REAL4 *twoFPerDet[PULSAR_MAX_DETECTORS], const REAL4 *maxTwoFSegPerDet[PULSAR_MAX_DETECTORS], const UINT4 len, const BSGLSetup *setup)
REAL4	XLALComputeBSGLtL (const REAL4 twoF, const REAL4 twoFX[PULSAR_MAX_DETECTORS], const REAL4 maxtwoFlX[PULSAR_MAX_DETECTORS], const BSGLSetup *setup)
	Single-bin wrapper of XLALVectorComputeBSGLtL(), provided for backwards compatibility. More...
int	XLALVectorComputeBtSGLtL (REAL4 *outBtSGLtL, const REAL4 *maxTwoFSeg, const REAL4 *twoFPerDet[PULSAR_MAX_DETECTORS], const REAL4 *maxTwoFSegPerDet[PULSAR_MAX_DETECTORS], const UINT4 len, const BSGLSetup *setup)
REAL4	XLALComputeBtSGLtL (const REAL4 maxtwoFl, const REAL4 twoFX[PULSAR_MAX_DETECTORS], const REAL4 maxtwoFXl[PULSAR_MAX_DETECTORS], const BSGLSetup *setup)
	Single-bin wrapper of XLALVectorComputeBtSGLtL(), provided for backwards compatibility. More...
REAL4	XLALComputeBStSGLtL (const REAL4 twoF, const REAL4 maxtwoFl, const REAL4 twoFX[PULSAR_MAX_DETECTORS], const REAL4 maxtwoFXl[PULSAR_MAX_DETECTORS], const BSGLSetup *setup)
int	XLALParseLinePriors (REAL4 oLGX[PULSAR_MAX_DETECTORS], const LALStringVector *oLGX_string)
	Parse string-vectors (typically input by user) of N per-detector line-to-Gaussian prior ratios \( o_{LG}^X = \frac{P(H_L^X)}{P(H_G^X)} \) to a flat array of REAL4s. More...

Function Documentation

XLALCreateBSGLSetup()

BSGLSetup * XLALCreateBSGLSetup	(	const UINT4	numDetectors,
		const REAL4	Fstar0sc,
		const REAL4	oLGX[PULSAR_MAX_DETECTORS],
		const BOOLEAN	useLogCorrection,
		const UINT4	numSegments
	)

\[ \newcommand{\coh}[1]{\widetilde{#1}} \newcommand{\Ndet}{N_{\mathrm{det}}} \newcommand{\F}{\mathcal{F}} \newcommand{\scF}{\hat{\F}} \newcommand{\cohFtho}{\coh{\F}_*^{(0)}} \newcommand{\scFtho}{\scF_*^{(0)}} \newcommand{\oLGX}{o_{\mathrm{LG}}^X} \newcommand{\Nseg}{N_{\mathrm{seg}}} \]

Pre-compute the 'setup' for XLALComputeBSGL() for given prior parameters \( \scFtho \) and \( \{\oLGX\} \) .

Parameters

[in]	numDetectors	number of detectors \( \Ndet \)
[in]	Fstar0sc	(semi-coherent) prior transition-scale parameter \( \scFtho=\Nseg\cohFtho \)
[in]	oLGX	prior per-detector line odds \( \{\oLGX\} \) , if NULL: interpreted as \( \oLGX=\frac{1}{\Ndet} \forall X \)
[in]	useLogCorrection	include log-term correction [slower] or not [faster, less accurate]
[in]	numSegments	number of segments \( \Nseg \) in a semi-coherent search (=1 for coherent search)

Definition at line 74 of file LineRobustStats.c.

XLALDestroyBSGLSetup()

void XLALDestroyBSGLSetup

(

BSGLSetup *

setup

)

Definition at line 121 of file LineRobustStats.c.

XLALVectorComputeBSGL()

int XLALVectorComputeBSGL	(	REAL4 *	outBSGL,
		const REAL4 *	twoF,
		const REAL4 *	twoFPerDet[PULSAR_MAX_DETECTORS],
		const UINT4	len,
		const BSGLSetup *	setup
	)

\[ \newcommand{\F}{\mathcal{F}} \newcommand{\FpMax}{\F^{\#}_{\mathrm{max}}} \newcommand{\Ndet}{N_{\mathrm{det}}} \newcommand{\Signal}{\mathrm{S}} \newcommand{\Gauss}{\mathrm{G}} \newcommand{\Line}{\mathrm{L}} \newcommand{\SGL}{{\Signal/\Gauss\Line}} \newcommand{\oLG}{o_{\Line/\Gauss}} \newcommand{\oLGX}{\oLG^X} \newcommand{\OSGL}{O_\SGL} \newcommand{\oSGL}{o_\SGL} \newcommand{\data}{\mathrm{data}} \newcommand{\pL}{p_\Line} \newcommand{\logten}{\log_{10}} \newcommand{\BSGL}{B_{\SGL}} \]

Compute the 'line-robust statistic' \( \logten \BSGL \) from multi-detector \( 2\F \) and single-detector \( \{2\F^X\} \) 'F-stat values' (coherent or semi-coherent sum) and a pre-computed 'setup' from XLALCreateBSGLSetup().

\( \BSGL \) is the BayesFactor[Signal-vs-Gauss_OR_Line], i.e. \( \BSGL \equiv \frac{P(\data | \text{Signal})}{P(\data | \text{Gauss or Line})} \) , which is related to the odds ratio via \( \OSGL = \oSGL\,\BSGL \) in terms of the prior odds \( \oSGL \) .

Here we use the odds ratio derived in Eq.(36) (and Eq.(55)) of [13] , from which we can obtain

\begin{equation} \ln \BSGL = \F - \FpMax - \ln\left( e^{C - \FpMax} + \sum_X \pL^X \, e^{\F^X - \FpMax} \right) \,, \end{equation}

where setup->useLogCorrection controls whether or not to include the (usually small) log-correction of the last term, and we defined

\begin{equation} \FpMax \equiv \max\left[ C, \{ \F^X + \ln\pL^X \} \right] \end{equation}

and \( C,\{\ln\pL^X\} \) are the prior quantities pre-computed in XLALCreateBSGLSetup(), namely

\begin{align} C &\equiv \scFtho + \ln(1-\pL) = \scFtho - \ln(1+\oLG)\,,\\ \ln\pL^X &\equiv \ln \oLGX - \ln(1+\oLG)\,, \end{align}

and we used the following relations from [13] : \( \oLG = \sum_X \oLGX \; \) [Eq.(22)], and \( \pL = \frac{\oLG}{1 + \oLG} \; \) [Eq.(37)].

Here, \( \FpMax \) differs from \( \F''_{\mathrm{max}} \) from [Eq.(41)] by \( \ln\Ndet \) , due to summation instead of an average over detectors.

Returns

NOTE: return is \( \logten B_\SGL = \ln B_\SGL \, \logten e \)

Parameters

[out]	outBSGL	pre-allocated output vector for returning BSGL
[in]	twoF	input vector of multi-IFO 2F values
[in]	twoFPerDet	input vector of per-IFO 2F[X] values
[in]	len	length of input/output vectors
[in]	setup	pre-computed setup from XLALCreateBSGLSetup()

Definition at line 174 of file LineRobustStats.c.

XLALComputeBSGL()

REAL4 XLALComputeBSGL	(	const REAL4	twoF,
		const REAL4	twoFX[PULSAR_MAX_DETECTORS],
		const BSGLSetup *	setup
	)

Single-bin wrapper of XLALVectorComputeBSGL(), provided for backwards compatibility.

Parameters

[in]	twoF	multi-detector F-stat \( 2\F \) (coherent or semi-coherent sum(!))
[in]	twoFX	per-detector F-stats \( \{2\F^X\} \) (coherent or semi-coherent sum(!))
[in]	setup	pre-computed setup from XLALCreateBSGLSetup()

Definition at line 218 of file LineRobustStats.c.

XLALVectorComputeGLtLDenominator()

int XLALVectorComputeGLtLDenominator	(	REAL4 *	outDenom,
		const REAL4 *	twoFPerDet[PULSAR_MAX_DETECTORS],
		const REAL4 *	maxTwoFSegPerDet[PULSAR_MAX_DETECTORS],
		const UINT4	len,
		const BSGLSetup *	setup
	)

\[ \newcommand{\cohF}{\coh{\F}} \]

Helper function to compute the denominator for XLALVectorComputeBSGLtL() and XLALVectorComputeBtSGLtL() - see their documentation for details.

Parameters

[out]	outDenom	pre-allocated output array of denominator values
[in]	twoFPerDet	input vector of semi-coherent sums \( \{2\scF^X\} \) of per-detector F-stats
[in]	maxTwoFSegPerDet	input vector of maxima over segments of \( \{\max\limits_{\ell}2\{\cohF^{X\ell}\}\} \) of per-detector F-stats
[in]	len	length of input/output vectors
[in]	setup	pre-computed setup from XLALCreateBSGLSetup()

Definition at line 241 of file LineRobustStats.c.

XLALVectorComputeBSGLtL()

int XLALVectorComputeBSGLtL	(	REAL4 *	outBSGLtL,
		const REAL4 *	twoF,
		const REAL4 *	twoFPerDet[PULSAR_MAX_DETECTORS],
		const REAL4 *	maxTwoFSegPerDet[PULSAR_MAX_DETECTORS],
		const UINT4	len,
		const BSGLSetup *	setup
	)

\[ \newcommand{\sc}[1]{\widehat{#1}} \newcommand{\cohF}{\coh{\F}} \newcommand{\scF}{\sc{\F}} \newcommand{\denomterm}{\sc{D}} \newcommand{\denommax}{\denomterm_{\mathrm{max}}} \newcommand{\Transline}{{\mathrm{t\Line}}} \newcommand{\cppLX}{\sc{p}_{\Line}^X} \newcommand{\cppTLXk}{\coh{p}_{\Transline}^{X\ell}} \newcommand{\cppLTLsc}{\sc{p}_{\Line\Transline}} \newcommand{\denomtermset}{\mathcal{\denomterm}} \newcommand{\SGLtL}{{\Signal/\Gauss\Line\Transline}} \newcommand{\OSGLtL}{O_\SGLtL} \newcommand{\oSGLtL}{o_\SGLtL} \newcommand{\BSGLtL}{B_{\SGLtL}} \]

Compute the semi-coherent transient-line-robust CW detection statistic \( \logten \BSGLtL \) from [14] .

As defined in Eq.(22), \( \BSGLtL \) is the BayesFactor for CW signals vs. either Gaussian noise, a persistent line or a transient line, i.e. \( \BSGLtL \equiv \frac{P(\data | \text{Signal})}{P(\data | \text{Gauss or Line or transient Line})} \) .

This function returns an approximation of \( \logten \BSGLtL = \ln \BSGLtL \, \logten e \) , with the general expression for \( \ln \BSGLtL \) given in Eq.(23) of [14], while here we compute only the leading term

\begin{equation} \ln \BSGLtL \approx \F - \denommax\,. \end{equation}

NOTE: In the current implementation, only setup->useLogCorrection == FALSE is accepted! In this case, the output is simply the maximum of the set of denominator exponents,

\begin{equation} \denommax \equiv \max \left\{ \Nseg\cohFtho + \ln\left( 1-\cppLTLsc \right) ,\, \scF^X + \ln\cppLX ,\, \cohF^{X\ell} + (\Nseg-1)\cohFtho + \ln\cppTLXk \right\} \,, \end{equation}

with the simplifying assumption of equal prior odds for persistent and transient lines (with equal odds for all segments), ie. \( \cppTLXk = \cppLX / \Nseg \) , therefore \( \ln\cppTLXk = \ln\cppLX - \ln\Nseg \) .

Parameters

[out]	outBSGLtL	pre-allocated vector for returning BSLGtL values
[in]	twoF	vector of semi-coherent sum \( 2\scF \) of multi-detector F-stats
[in]	twoFPerDet	vector of semi-coherent sums \( \{2\scF^X\} \) of per-detector F-stats
[in]	maxTwoFSegPerDet	vector of maxima over segments of \( \{\max\limits_{\ell}2\{\cohF^{X\ell}\}\} \) of per-detector F-stats
[in]	len	length of input/output vectors
[in]	setup	pre-computed setup from XLALCreateBSGLSetup()

Definition at line 319 of file LineRobustStats.c.

XLALComputeBSGLtL()

REAL4 XLALComputeBSGLtL	(	const REAL4	twoF,
		const REAL4	twoFX[PULSAR_MAX_DETECTORS],
		const REAL4	maxtwoFlX[PULSAR_MAX_DETECTORS],
		const BSGLSetup *	setup
	)

Single-bin wrapper of XLALVectorComputeBSGLtL(), provided for backwards compatibility.

Parameters

[in]	twoF	semi-coherent sum \( 2\scF \) of multi-detector F-stats
[in]	twoFX	semi-coherent sums \( \{2\scF^X\} \) of per-detector F-stats
[in]	maxtwoFlX	maxima \( \{\max\limits_{\ell}2\{\cohF^{X\ell}\}\} \) of per-detector F-stats over segments
[in]	setup	pre-computed setup from XLALCreateBSGLSetup()

Definition at line 343 of file LineRobustStats.c.

XLALVectorComputeBtSGLtL()

int XLALVectorComputeBtSGLtL	(	REAL4 *	outBtSGLtL,
		const REAL4 *	maxTwoFSeg,
		const REAL4 *	twoFPerDet[PULSAR_MAX_DETECTORS],
		const REAL4 *	maxTwoFSegPerDet[PULSAR_MAX_DETECTORS],
		const UINT4	len,
		const BSGLSetup *	setup
	)

\[ \newcommand{\Transsig}{{\mathrm{t\Signal}}} \newcommand{\tSGLtL}{{\Transsig/\Gauss\Line\Transline}} \newcommand{\BtSGLtL}{B_{\tSGLtL}} \newcommand{\OtSGLtL}{O_\tSGLtL} \newcommand{\otSGLtL}{o_\tSGLtL} \newcommand{\oTSGk}{\coh{o}_{\Transsig/\Gauss}^{\ell}} \]

Compute a semi-coherent transient-line-robust tCW detection statistic \( \logten \BtSGLtL \) from [14] .

As defined in Eq.(40), \( \BtSGLtL \) is the BayesFactor for tCW signals vs. either Gaussian noise, a persistent line or a transient line, i.e. \( \BtSGLtL \equiv \frac{P(\data | \text{transient Signal})}{P(\data | \text{Gauss or Line or transient Line})} \) .

This function returns an approximation of \( \logten \BtSGLtL = \ln \BtSGLtL \, \logten e \) , computing only the leading term

\begin{equation} \ln \BtSGLtL \approx \max_{\ell}\cohF^{\ell} + (\Nseg - 1)\cohFtho - \ln \Nseg - \denommax\,, \end{equation}

using the maximum multi-detector, single-segment F-stat value \( \max\cohF^{\ell} \) in the numerator, and the maximum \( \denommax \) of the set of denominator exponents, see the documentation of XLALVectorComputeBSGLtL() for its definition.

NOTE: This implementation also assumes equal prior transient-signal odds for all segments.

Parameters

[out]	outBtSGLtL	pre-allocated vector for returning BtSGLtL values
[in]	maxTwoFSeg	vector of maximum \( \max\limits_{\ell}2\cohF^\ell \) of multi-detector F-stats over segments
[in]	twoFPerDet	vector of semi-coherent sums \( \{2\scF^X\} \) of per-detector F-stats
[in]	maxTwoFSegPerDet	vector of maxima \( \{\max\limits_{\ell}2\{\cohF^{X\ell}\}\} \) of per-detector F-stats over segments
[in]	len	length of input/output vectors
[in]	setup	pre-computed setup from XLALCreateBSGLSetup()

Definition at line 390 of file LineRobustStats.c.

XLALComputeBtSGLtL()

REAL4 XLALComputeBtSGLtL	(	const REAL4	maxtwoFl,
		const REAL4	twoFX[PULSAR_MAX_DETECTORS],
		const REAL4	maxtwoFXl[PULSAR_MAX_DETECTORS],
		const BSGLSetup *	setup
	)

Single-bin wrapper of XLALVectorComputeBtSGLtL(), provided for backwards compatibility.

Parameters

[in]	maxtwoFl	maximum \( \max\limits_{\ell}2\cohF^\ell \) of multi-detector F-stats over segments
[in]	twoFX	semi-coherent sums \( \{2\scF^X\} \) of per-detector F-stats
[in]	maxtwoFXl	maxima \( \{\max\limits_{\ell}2\{\cohF^{X\ell}\}\} \) of per-detector F-stats over segments
[in]	setup	pre-computed setup from XLALCreateBSGLSetup()

Definition at line 413 of file LineRobustStats.c.

XLALComputeBStSGLtL()

REAL4 XLALComputeBStSGLtL	(	const REAL4	twoF,
		const REAL4	maxtwoFl,
		const REAL4	twoFX[PULSAR_MAX_DETECTORS],
		const REAL4	maxtwoFXl[PULSAR_MAX_DETECTORS],
		const BSGLSetup *	setup
	)

\[ \newcommand{\StSGLtL}{{\Signal\Transsig\Gauss\Line\Transline}} \newcommand{\OStSGLtL}{O_\StSGLtL} \newcommand{\oStSGLtL}{o_\StSGLtL} \newcommand{\BStSGLtL}{B_{\StSGLtL}} \newcommand{\numerterm}{\sc{E}} \newcommand{\numertermset}{\mathcal{\numerterm}} \newcommand{\numermin}{\numerterm_{\mathrm{min}}} \newcommand{\numermax}{\numerterm_{\mathrm{max}}} \newcommand{\cppS}{\sc{p}_{\Signal}} \newcommand{\cppTS}{\coh{p}_{\Transsig}} \newcommand{\cppTSk}{\coh{p}_{\Transsig}^{\ell}} \]

Compute the semi-coherent transient-line-robust CW+tCW detection statistic \( \logten \BStSGLtL \) from [14] .

As defined in Eq.(35), \( \BStSGLtL \) is the BayesFactor for either persistent CW or transient tCW signals vs. either Gaussian noise, a persistent line or a transient line, i.e. \( \BStSGLtL \equiv \frac{P(\data | \text{Signal or transient Signal})}{P(\data | \text{Gauss or Line or transient Line})} \) .

This function returns an approximation of \( \logten \BStSGLtL = \ln \BStSGLtL \, \logten e \) , with the general expression for \( \ln \BStSGLtL \) given in Eq.(36) of [14] . Here we compute only the leading term

\begin{equation} \ln \BStSGLtL \approx \numermax + \ln \left( 1 + e^{\numermin-\numermax} \right) - \denommax \,, \end{equation}

with the \( \denommax \) terms defined in the documentation of XLALVectorComputeBSGLtL(), and

\( \numermax = \max \left\{ \scF, \max\limits_{\ell}\cohF^\ell + \cohFtho (\Nseg-1) - \ln \Nseg\right\} \) , where we have assumed prior equal odds between persistent and transient signals and equal odds for all segments.

Parameters

[in]	twoF	semi-coherent sum \( 2\scF \) of multi-detector F-stats
[in]	maxtwoFl	maximum \( \max\limits_{\ell}2\cohF^\ell \) of multi-detector F-stats over segments
[in]	twoFX	semi-coherent sums \( \{2\scF^X\} \) of per-detector F-stats
[in]	maxtwoFXl	maxima \( \{\max\limits_{\ell}2\{\cohF^{X\ell}\}\} \) of per-detector F-stats over segments
[in]	setup	pre-computed setup from XLALCreateBSGLSetup()

Definition at line 466 of file LineRobustStats.c.

XLALParseLinePriors()

int XLALParseLinePriors	(	REAL4	oLGX[PULSAR_MAX_DETECTORS],
		const LALStringVector *	oLGX_string
	)

Parse string-vectors (typically input by user) of N per-detector line-to-Gaussian prior ratios \( o_{LG}^X = \frac{P(H_L^X)}{P(H_G^X)} \) to a flat array of REAL4s.

Parameters

[out]	oLGX	array of parsed \( o_{LG}^X \) values
[in]	oLGX_string	string-list of \( o_{LG}^X \) values

Definition at line 501 of file LineRobustStats.c.