Loading [MathJax]/extensions/TeX/AMSsymbols.js
LALPulsar 7.1.1.1-b246709
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
bin/Weave/Statistics.c
Go to the documentation of this file.
1//
2// Copyright (C) 2017 Reinhard Prix
3//
4// This program is free software; you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation; either version 2 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with with program; see the file COPYING. If not, write to the
16// Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17// MA 02110-1301 USA
18//
19
20///
21/// \file
22/// \ingroup lalpulsar_bin_Weave
23///
24
25#include "Statistics.h"
26#include "ComputeResults.h"
27
28#include <lal/LALString.h>
29
30///
31/// Struct defining the global 'statistics map' that contains all the defining properties
32/// of the supported statistics
33///
34typedef struct {
35 WeaveStatisticType val; ///< bitflag value for this statistic
36 const char *const name; ///< internal name of this statistics
37 WeaveStatisticType dependencies; ///< set of *direct* input dependencies of this statistic
38 const char *const help; ///< help string explaining this statistic
40
41///
42/// Sets of toplists, extra statistics and dependencies handled by this code
43///
44#define ENTRY_NONE WEAVE_STATISTIC_NONE, "none", " ", 0, \
45 "No statistic selected"
46
47#define ENTRY_COH2F WEAVE_STATISTIC_COH2F, "coh2F", " ", 0, \
48 "Per-segment multi-detector coherent 2F statistic"
49
50#define ENTRY_COH2F_DET WEAVE_STATISTIC_COH2F_DET, "coh2F_det", " ", 0, \
51 "Per-segment per-detector coherent 2F statistic"
52
53#define ENTRY_MAX2F WEAVE_STATISTIC_MAX2F, "max2F", " ", WEAVE_STATISTIC_COH2F, \
54 "Maximum over segments multi-detector coherent 2F statistic"
55
56#define ENTRY_MAX2F_DET WEAVE_STATISTIC_MAX2F_DET, "max2F_det", " ", WEAVE_STATISTIC_COH2F_DET, \
57 "Maximum over segments per-detector coherent 2F statistic"
58
59#define ENTRY_SUM2F WEAVE_STATISTIC_SUM2F, "sum2F", " ", WEAVE_STATISTIC_COH2F, \
60 "Sum over segments of multi-detector coherent 2F statistic"
61
62#define ENTRY_SUM2F_DET WEAVE_STATISTIC_SUM2F_DET, "sum2F_det", " ", WEAVE_STATISTIC_COH2F_DET, \
63 "Sum over segments of single-detector coherent 2F statistic"
64
65#define ENTRY_MEAN2F WEAVE_STATISTIC_MEAN2F, "mean2F", " ", WEAVE_STATISTIC_SUM2F, \
66 "Average over segments of multi-detector coherent 2F statistic"
67
68#define ENTRY_MEAN2F_DET WEAVE_STATISTIC_MEAN2F_DET, "mean2F_det", " ", WEAVE_STATISTIC_SUM2F_DET, \
69 "Average over segments of single-detector coherent 2F statistic"
70
71#define ENTRY_BSGL WEAVE_STATISTIC_BSGL, "log10BSGL", " ", WEAVE_STATISTIC_SUM2F|WEAVE_STATISTIC_SUM2F_DET, \
72 "Bayes factor 'Signal' vs 'Gaussian noise' or 'Line'"
73
74#define ENTRY_BSGLtL WEAVE_STATISTIC_BSGLtL, "log10BSGLtL", " ", WEAVE_STATISTIC_SUM2F|WEAVE_STATISTIC_SUM2F_DET|WEAVE_STATISTIC_MAX2F_DET, \
75 "Bayes factor 'Signal' vs 'Gaussian noise' or 'Line' or 'transient Line'."
76
77#define ENTRY_BtSGLtL WEAVE_STATISTIC_BtSGLtL, "log10BtSGLtL", " ", WEAVE_STATISTIC_MAX2F|WEAVE_STATISTIC_SUM2F_DET|WEAVE_STATISTIC_MAX2F_DET, \
78 "Bayes factor 'transient Signal' vs 'Gaussian noise' or 'Line' or 'transient Line'."
79
80#define ENTRY_NCOUNT WEAVE_STATISTIC_NCOUNT, "ncount", " ", WEAVE_STATISTIC_COH2F, \
81 "Multi-detector 'Hough' number count of 'threshold crossings' heavyside(2F - 2Fth) over segments"
82
83#define ENTRY_NCOUNT_DET WEAVE_STATISTIC_NCOUNT_DET, "ncount_det", " ", WEAVE_STATISTIC_COH2F_DET, \
84 "Per-detector 'Hough' number count of 'threshold crossings' heavyside(2F - 2Fth) over segments"
85
86#define ENTRY_2_NAME(X) ENTRY_2_NAME_X(X)
87#define ENTRY_2_NAME_X(v,n,s,d,h) [XLAL_BIT2IDX(v)] = n
88
89#define ENTRY_2_MAP(X) ENTRY_2_MAP_X(X)
90#define ENTRY_2_MAP_X(v,n,s,d,h) { .val = v, .name = n, .dependencies = d, .help = h }
91
92#define ENTRY_2_CHOICES(X) ENTRY_2_CHOICES_X(X)
93#define ENTRY_2_CHOICES_X(v,n,s,d,h) { .val = v, .name = n }
94
95#define ENTRY_2_HELPSTR(X) ENTRY_2_HELPSTR_X(X)
96#define ENTRY_2_HELPSTR_X(v,n,s,d,h) " - " n s ": " h ".\n"
97
112};
113
114///
115/// Array of descriptor structs for all statistics supported by Weave
116///
131};
132
133// Total set of current supported statistics
134#define SUPPORTED_STATISTICS ( \
135 0 \
136 | WEAVE_STATISTIC_COH2F \
137 | WEAVE_STATISTIC_COH2F_DET \
138 | WEAVE_STATISTIC_MAX2F \
139 | WEAVE_STATISTIC_MAX2F_DET \
140 | WEAVE_STATISTIC_SUM2F \
141 | WEAVE_STATISTIC_SUM2F_DET \
142 | WEAVE_STATISTIC_MEAN2F \
143 | WEAVE_STATISTIC_MEAN2F_DET \
144 | WEAVE_STATISTIC_BSGL \
145 | WEAVE_STATISTIC_BSGLtL \
146 | WEAVE_STATISTIC_BtSGLtL \
147 | WEAVE_STATISTIC_NCOUNT \
148 | WEAVE_STATISTIC_NCOUNT_DET \
149 )
165 { SUPPORTED_STATISTICS, "all" }
166};
167const char *const WeaveStatisticHelpString = \
168 ENTRY_2_HELPSTR( ENTRY_COH2F ) \
169 ENTRY_2_HELPSTR( ENTRY_COH2F_DET ) \
170 ENTRY_2_HELPSTR( ENTRY_MAX2F ) \
171 ENTRY_2_HELPSTR( ENTRY_MAX2F_DET ) \
172 ENTRY_2_HELPSTR( ENTRY_SUM2F ) \
173 ENTRY_2_HELPSTR( ENTRY_SUM2F_DET ) \
174 ENTRY_2_HELPSTR( ENTRY_MEAN2F ) \
175 ENTRY_2_HELPSTR( ENTRY_MEAN2F_DET ) \
176 ENTRY_2_HELPSTR( ENTRY_BSGL ) \
177 ENTRY_2_HELPSTR( ENTRY_BSGLtL ) \
178 ENTRY_2_HELPSTR( ENTRY_BtSGLtL ) \
179 ENTRY_2_HELPSTR( ENTRY_NCOUNT ) \
180 ENTRY_2_HELPSTR( ENTRY_NCOUNT_DET ) \
181 ;
182
183// Subset of statistics that are supported as toplist ranking statistics
184#define SUPPORTED_TOPLISTS ( \
185 0 \
186 | WEAVE_STATISTIC_MEAN2F \
187 | WEAVE_STATISTIC_SUM2F \
188 | WEAVE_STATISTIC_BSGL \
189 | WEAVE_STATISTIC_BSGLtL \
190 | WEAVE_STATISTIC_BtSGLtL \
191 )
198 {SUPPORTED_TOPLISTS, "all" }
199};
200const char *const WeaveToplistHelpString = \
201 ENTRY_2_HELPSTR( ENTRY_MEAN2F ) \
202 ENTRY_2_HELPSTR( ENTRY_SUM2F ) \
203 ENTRY_2_HELPSTR( ENTRY_BSGL ) \
204 ENTRY_2_HELPSTR( ENTRY_BSGLtL ) \
205 ENTRY_2_HELPSTR( ENTRY_BtSGLtL ) \
206 ;
207
208///
209/// Set all bits in 'deps' corresponding to *direct* dependencies of the set of input statistics 'stat'
210///
212 WeaveStatisticType *deps,
214)
215{
217
218 WeaveStatisticType tmp = 0;
219 for ( size_t i = 0; i < XLAL_NUM_ELEM( statistic_map ); ++i ) {
220 if ( stats & statistic_map[i].val ) {
222 }
223 }
224
225 ( *deps ) |= tmp;
226
227 return XLAL_SUCCESS;
228
229}
230
231
232///
233/// Fill StatisticsParams logic for given toplist and extra-output stats
234///
236 WeaveStatisticsParams *statistics_params, ///< [out] statstics dependency map
237 const WeaveStatisticType toplist_stats, ///< [in] requested toplist statistics
238 const WeaveStatisticType extra_output_stats, ///< [in] requested 'extra' (stage0) output statistics
239 const WeaveStatisticType recalc_stats ///< [in] requested 'recalc' (stage1) statistics
240)
241{
242 XLAL_CHECK( statistics_params != NULL, XLAL_EFAULT );
243 XLAL_CHECK( ( toplist_stats & ( ~SUPPORTED_TOPLISTS ) ) == 0, XLAL_EINVAL );
244 XLAL_CHECK( ( extra_output_stats & ( ~SUPPORTED_STATISTICS ) ) == 0, XLAL_EINVAL );
245 XLAL_CHECK( ( recalc_stats & ( ~SUPPORTED_STATISTICS ) ) == 0, XLAL_EINVAL );
246
247 WeaveStatisticType stage0_stats_to_output = ( toplist_stats | extra_output_stats );
248
249 // Work out the total set of all statistics we need to compute by
250 // expanding the statistics dependencies until converged [tree fully expanded]
251 WeaveStatisticType stats_to_compute = stage0_stats_to_output; // Start value
252 WeaveStatisticType mainloop_stats = toplist_stats; // Start value
253 WeaveStatisticType prev_stats_to_compute, prev_mainloop_stats;
254 do {
255 prev_stats_to_compute = stats_to_compute;
256 prev_mainloop_stats = mainloop_stats;
257
258 XLALWeaveStatisticsSetDirectDependencies( &stats_to_compute, stats_to_compute );
259 XLALWeaveStatisticsSetDirectDependencies( &mainloop_stats, mainloop_stats );
260
261 } while ( ( prev_stats_to_compute != stats_to_compute ) && ( prev_mainloop_stats != mainloop_stats ) );
262
263 // Special handling of stage0 'coh2F' and 'coh2F_det': these can *only* be computed as "main-loop" statistics!
264 // as they are defined to refer to the 'fine grid with (typically) interpolation', while
265 if ( stats_to_compute & WEAVE_STATISTIC_COH2F ) {
266 mainloop_stats |= WEAVE_STATISTIC_COH2F;
267 }
268 if ( stats_to_compute & WEAVE_STATISTIC_COH2F_DET ) {
269 mainloop_stats |= WEAVE_STATISTIC_COH2F_DET;
270 }
271
272 WeaveStatisticType completionloop_stats_stage0 = stats_to_compute & ( ~mainloop_stats );
273
274 // Figure out which mainloop statistics to keep outside of main loop: either
275 // 1) because they have been requested for output, or
276 // 2) they are a _direct_ (stage0) completionloop dependency,
277 // All other mainloop stats can be thrown away safely after the mainloop.
278 WeaveStatisticType mainloop_stats_to_keep = 0;
279
280 // 1) if requested for output:
281 mainloop_stats_to_keep |= ( mainloop_stats & stage0_stats_to_output );
282
283 // 2) if *direct* (stage0) completionloop dependencies:
284 WeaveStatisticType completionloop_stage0_deps = 0;
285 XLALWeaveStatisticsSetDirectDependencies( &completionloop_stage0_deps, completionloop_stats_stage0 );
286 mainloop_stats_to_keep |= ( mainloop_stats & completionloop_stage0_deps );
287
288 // 3) determine full recalc-stats dependencies
289 WeaveStatisticType recalc_stats_deps = recalc_stats;
290 WeaveStatisticType prev_recalc_stats_deps;
291 do {
292 prev_recalc_stats_deps = recalc_stats_deps;
293 XLALWeaveStatisticsSetDirectDependencies( &recalc_stats_deps, recalc_stats_deps );
294 } while ( prev_recalc_stats_deps != recalc_stats_deps );
295
296 stats_to_compute |= recalc_stats_deps;
297
298 // Store the resulting statistics logic in the 'statistics_params' struct
299 statistics_params->toplist_statistics = toplist_stats;
300 statistics_params->statistics_to_output[0] = stage0_stats_to_output;
301 statistics_params->statistics_to_output[1] = recalc_stats;
302
303 statistics_params->mainloop_statistics = mainloop_stats;
304 statistics_params->mainloop_statistics_to_keep = mainloop_stats_to_keep;
305 statistics_params->completionloop_statistics[0] = completionloop_stats_stage0;
306 statistics_params->completionloop_statistics[1] = recalc_stats_deps;
307
308 statistics_params->all_statistics_to_compute = stats_to_compute;
309
310 // Count number of toplists
311 statistics_params->ntoplists = 0;
312 for ( int idx = 0; idx < XLAL_BIT2IDX( WEAVE_STATISTIC_MAX ); ++idx ) {
313 if ( statistics_params->toplist_statistics & XLAL_IDX2BIT( idx ) ) {
314 ++statistics_params->ntoplists;
315 }
316 }
317
318 return XLAL_SUCCESS;
319
320}
321
322///
323/// Destroy a StatisticsParams struct
324///
326 WeaveStatisticsParams *statistics_params
327)
328{
329 if ( statistics_params == NULL ) {
330 return;
331 }
332
333 XLALDestroyStringVector( statistics_params->detectors );
334 XLALDestroyBSGLSetup( statistics_params->BSGL_setup );
335 if ( statistics_params->coh_input != NULL ) {
336 for ( size_t i = 0; i < statistics_params->nsegments; ++i ) {
337 XLALWeaveCohInputDestroy( statistics_params->coh_input[i] );
338 }
339 XLALFree( statistics_params->coh_input );
340 }
341 if ( statistics_params->coh_input_recalc != NULL ) {
342 for ( size_t i = 0; i < statistics_params->nsegments; ++i ) {
343 XLALWeaveCohInputDestroy( statistics_params->coh_input_recalc[i] );
344 }
345 XLALFree( statistics_params->coh_input_recalc );
346 }
347
348 XLALWeaveCohResultsDestroy( statistics_params->coh_res );
349
350 XLALFree( statistics_params );
351
352 return;
353
354}
355
356
357// Local Variables:
358// c-file-style: "linux"
359// c-basic-offset: 2
360// End:
void XLALWeaveCohResultsDestroy(WeaveCohResults *coh_res)
Destroy coherent results.
void XLALWeaveCohInputDestroy(WeaveCohInput *coh_input)
Destroy coherent input data.
Module which computes coherent and semicoherent results.
enum tagWeaveStatisticType WeaveStatisticType
Definition: Weave.h:61
const WeaveStatisticMap statistic_map[]
Array of descriptor structs for all statistics supported by Weave.
#define ENTRY_MEAN2F
#define SUPPORTED_TOPLISTS
#define ENTRY_2_CHOICES(X)
const char *const WeaveStatisticNamesByIndex[XLAL_BIT2IDX(WEAVE_STATISTIC_MAX)]
#define SUPPORTED_STATISTICS
#define ENTRY_COH2F
#define ENTRY_COH2F_DET
int XLALWeaveStatisticsParamsSetDependencyMap(WeaveStatisticsParams *statistics_params, const WeaveStatisticType toplist_stats, const WeaveStatisticType extra_output_stats, const WeaveStatisticType recalc_stats)
Fill StatisticsParams logic for given toplist and extra-output stats.
int XLALWeaveStatisticsSetDirectDependencies(WeaveStatisticType *deps, const WeaveStatisticType stats)
Set all bits in 'deps' corresponding to direct dependencies of the set of input statistics 'stat'.
#define ENTRY_BSGL
const char *const WeaveToplistHelpString
User input help string for toplist ranking statistics.
#define ENTRY_NONE
Sets of toplists, extra statistics and dependencies handled by this code.
#define ENTRY_BSGLtL
#define ENTRY_NCOUNT_DET
const UserChoices WeaveToplistChoices
User input choices for toplist ranking statistics.
#define ENTRY_2_NAME(X)
#define ENTRY_SUM2F
#define ENTRY_SUM2F_DET
#define ENTRY_MEAN2F_DET
#define ENTRY_2_MAP(X)
const char *const WeaveStatisticHelpString
User input help string for all supported statistics.
#define ENTRY_MAX2F
const UserChoices WeaveStatisticChoices
User input choices for all supported statistics.
#define ENTRY_BtSGLtL
#define ENTRY_MAX2F_DET
#define ENTRY_NCOUNT
void XLALWeaveStatisticsParamsDestroy(WeaveStatisticsParams *statistics_params)
Destroy a StatisticsParams struct.
@ WEAVE_STATISTIC_COH2F
Per segment multi-detector F-statistic.
@ WEAVE_STATISTIC_COH2F_DET
Per segment per-detector F-statistic.
@ WEAVE_STATISTIC_MAX
Marker +1 of maximal combined valid statistics value.
#define XLAL_NUM_ELEM(x)
void XLALFree(void *p)
void XLALDestroyBSGLSetup(BSGLSetup *setup)
void XLALDestroyStringVector(LALStringVector *vect)
#define XLAL_BIT2IDX(b)
#define XLAL_IDX2BIT(i)
#define XLAL_CHECK(assertion,...)
XLAL_SUCCESS
XLAL_EFAULT
XLAL_EINVAL
Struct defining the global 'statistics map' that contains all the defining properties of the supporte...
WeaveStatisticType val
bitflag value for this statistic
const char *const name
internal name of this statistics
WeaveStatisticType dependencies
set of direct input dependencies of this statistic
const char *const help
help string explaining this statistic