Add MCTupleToolTOS to HltEfficiencyChecker control flow

FYI @rmatev @sstahl @mvesteri

Supersedes !26 (closed) and requires Analysis!604 (merged)

In Analysis!604 (merged) we have a new MCTupleTool which emulates TOS-like matching by checking that the trigger candidate shares sufficient LHCbIDs with the true MCParticle. The tool is described more thoroughly there.

Here we add the ability to work out TOS efficiencies in HltEfficiencyChecker, using the TOS variables written to the tuple by that tool. By default, if TOS lines are in the tree, hlt_line_efficiencies.py will find them and print the TOS efficiencies. If plots are asked for, you'll get TOS efficiencies too, but as one can imagine, the number of "lines" (DEC and TOS) have grown a lot, so best to use the --lines arg to specify exactly what you want on your plot. I've tried to write the default logic so the user gets more than they might have initially intended, then with the use of parsed args they can trim down the output.

New annotated decay descriptor behaviour

If you want TOS efficiencies, this might require you to ask for branches in the annotated decay descriptor that you didn't ask for before. E.g. in B_s \rightarrow J/\psi \phi you previously just needed to put in a name for the parent particle and the final state particles in order to define denominators. This used to look like:

decay = ("[${B_s0}B_s0 => "
         "( J/psi(1S) => ${muplus}mu+ ${muminus}mu- ) "
         "( phi(1020) => ${Kplus}K+ ${Kminus}K- )]CC")

which still works fine. However, if you wanted to get the Jpsi_Hlt1TwoTrackMVALineDecisionTOS efficiency (same for the phi), you'd need branches for these particles, e.g.

decay = ("[${B_s0}B_s0 => "
         "${Jpsi}( J/psi(1S) => ${muplus}mu+ ${muminus}mu- ) "
         "${phi}( phi(1020) => ${Kplus}K+ ${Kminus}K- )]CC")

Other improvements

• A new --json flag to save the integrated efficiencies and their errors to a json file. hlt_calculate_rates.py already had this.
• Added the new script makeRateVEfficiencyPlot.py that does what it says on the tin. If you get hlt_line_efficiencies.py and hlt_calculate_rates.py to output jsons, this new script only requires that you pass it the paths to these two jsons. I'll add some instructions in the docs on doing this in due course, or perhaps an example wrapper script.
• Refactored hlt_line_efficiencies.py a bit to reduce printouts and duplicated work.
• Added a --no-legend flag. In this case the (colour, marker) are printed to the console for busy plots.

Follow-ups

As noted/insinuated in the the TOS study submitted to vCHEP:

• this only currently works for the Moore HLT1. IIUC, Allen doesn't yet write out SelReports, which will be needed if we're to use it there. If HLT2 writes out SelReports yet (?) then it shouldn't require much work for HLT2 to be happy with this.
• Documentation needs to be written.
• The TOS algorithm will break down for 3- or 4-track candidates.

Plots from the TOS study are good examples of the results you can get here. In lieu of proper documentation, try:

MooreAnalysis/run gaudirun.py MooreAnalysis/HltEfficiencyChecker/options/hlt1_moore_lines_example.py  MooreAnalysis/HltEfficiencyChecker/options/hlt1_tos_eff_example_moore.py 
MooreAnalysis/run python MooreAnalysis/HltEfficiencyChecker/scripts/hlt_line_efficiencies.py eff_ntuple.root --level Hlt1 --reconstructible-children Kplus,Kminus,muplus,muminus 

TODO:

• Fix errors in MooreAnalysis tests e.g. here
• Add new test for this functionality.