Add statistic correction option

[spxiwh]

This patch adds a statistic_correction "statistic keyword" in stat.py. This option will add a constant factor to all returned statistic values.

The immediate problem this patch sets out to fix is this plot (from https://inspirehep.net/literature/2053424)

This shows the desired behaviour using the state of the art statistic as of a few years ago. In particular HL doubles lie above other things.

When adding the new KDE term we see this relative behaviour change and H/L singles lie above the doubles line, causing singles to be weighted more than HL doubles when combining. Using this option we can downrank singles relative to doubles (and add appropriate factors when considering 3-ifo behaviour).

However, the patch is broader than that, it could be used (for e.g.) to try to make 0 correspond to a 50/50 chance of being real ... Or any other thing you could dream up where we just want to scale the statistic.

I've tested that this produces the desired effect.

[tdent]

How does this deal with different event types? Is that already in the stat parsing machinery, and if so can you remind me where?

[tdent]

See suggested comment changes & the question about event types.

[spxiwh]

Different event types are handled in the config file. SO one specifies something like:

[sngls-h1&sngls-l1]
statistic-keywords = correction_factor:-3.7
minimum-stat = -4

[sngls-v1]
statistic-keywords = correction_factor:-7.4
minimum-stat = -7

[coinc-h1l1]
statistic-keywords = correction_factor:-1

[coinc-l1v1]
statistic-keywords = correction_factor:-3.7

[coinc-h1v1]
statistic-keywords = correction_factor:-3.7


[coinc-h1l1v1]
statistic-keywords = correction_factor:0

(old naming for this argument, but same idea).

[tdent]

Right, that is what I suspected & seems the easiest way of doing this (modulo the case where we would want a different number for the same event type in different coinc times, but that seems not to be needed quite yet).

[spxiwh]

So to me the only remaining concern is around benchmark_lograte and if this adds redundancy. Is there anything I should do about this, or are folks happy?

[GarethCabournDavies]

So to me the only remaining concern is around benchmark_lograte and if this adds redundancy. Is there anything I should do about this, or are folks happy?

I am happy with the redundancy - all the benchmark_lograte means is that the numbers are a bit more natural this way

[tdent]

If both the benchmark lograte and this term are used in exactly the same ranking statistics, we ought to be able to get rid of one of them by defining a constant, eg BENCHMARK_LOGRATE = -14.6 at the module level to replace the class attribute in ln_noise_rate -= self.benchmark_lograte.

This leaves the output identical but takes out one redundant option which could confuse any users who tried to understand all the optional kwargs.
How do people feel about adding that 'trivial' change here?

[tdent]

I guess alternatively, in the spirit of keeping the production branch changes as simple as possible, we could cherry pick this minimal change to the 2.3 branch and then clean up the benchmark redundancy on master with a separate PR.