adding add_statmap code

[GarethCabournDavies]

pycbc_multiifo_add_statmap code will use backgrounds of any coincidences where that detector combination is 'on'.

For example, if the foreground coincidence comes from H1L1, but V1 was also operating at the time, the background used for ifar/fap/ifar_exc/fap_exc calculation will combine backgrounds from H1L1, H1V1, L1V1 and H1L1V1

[GarethCabournDavies]

diff between this and the multiifo combine statmap may make the changes easier to see:
add_vs_combine_statmap_diff_output.txt

I will try to remember to upload again after changes, but the version on CIT will probably be updated more regularly: add_vs_combine_statmap_diff_output.txt

[tdent]

I think the appropriate test here is to print out or otherwise output the FAR values after clustering from the previous trials-factor (combine_statmap) method and from this one and check they are the same for double time and comparable (but not identical) for triple time

the gps times of the new clustered events may not be identical to the old ones but we should be able to compare one cluster with another around the same time in all or nearly all cases.

[GarethCabournDavies]

The changes to the effective trials factor are as follows:

This is as expected for this chunk of data. The background reverse-cumulative histogram for all coincidences divided by that for only those in each coincidence is as follows (zoomed to match plot area of above), This has been divided by 4 to get the changes to the effective trials factor:

We see that these agree well

[tdent]

(Note that these plots are from an O2 chunk 21 run with a weird background statistic distribution due to a separate issue with the [uncombined] statmap code which is being addressed in parallel.)

[GarethCabournDavies]

Updated diff of add_statmap and combine_statmap:

add_vs_combine_statmap_diff_output_20190702.txt

on CIT

[tdent]

Noting that we want to initially cluster coincs in triple time by stat (not ifar) since we believe the stat should be a better ranking between different types of coinc.
Also the assignment of the final FAR as the sum of the individual coinc type FARs at the stat value of the candidate event is appropriate for clustering on stat not ifar.

[GarethCabournDavies]

After latest updates, the ifar calculation is now equivalent to before (with a better comparison plot style now being used)

I believe this is ready for review now

[tdent]

@ahnitz note this is no longer WIP.

[tdent]

mostly changes to comments, ordering etc., one significant request to make the 'available combos' calc more readable.

[tdent]

& you will want to fetch/rebase after addressing comments.

[ahnitz]

@GarethDaviesGW I haven't tried running this myself, but I've scanned through the code. I don't have any major comments. It looks to have the pieces I'd have expected to be there for what I think it's supposed to do (i.e. rerank events with a combined background).

[ahnitz]

Barring implementing @tdent's changes.