How to use this

This section deals with you as the end-user and what you have to do and look out for when trying to run CoincSuite. In short there are three major requirements to be fulfilled, so that CoincSuite can properly run: Frame structure, splitter and parameter correctness!

Requirements on Frames structure

CoincSuite is written to deal with multiple subevents in a QPP frame structure. The leading Q-frame should hold the uncleaned Pulses of that event and is the center-point of orientation of all regards. Important decisions concerning the event and any derived subevent are stored here. The following P-frames do represent different physical interpretations and aspects of this event, by holding different cleanings or reconstructions, different masked detector configuration (e.g. IceTop) or -what we are interested in- subevents which can be split from the host event.

It is the idiom that every one of the mentioned frames holds an object I3EventHeader, which does uniquely identify the frame, defines its rank in the order of frames and signals its purpose. This does also mean, that frames which are considered subevents do have the correct entries sub_event_stream and sub_event_ID, while all other entries, but explicitly runID and eventID, are the same with the host Q-frame.

It is also an idiom that Pulses are held in the Q-frame in their full representation as a object PulseSeries. Any applied cleaning or any other treatment of should be stored as a PulseSeriesMask of the original PulsesSeries. Also should subevent P-frames only hold PulseSeriesMasks even if their content is identical with the full original PulseSeries.

Because CoincSuite was developed explicitly for the application in IC86:2011 processing this hereout prescript structure is somewhat mandatory to enforce, because dealing in too many different frame and object configurations would make the code slow and hard to maintain.

Requirements on Splitter

CoincSuite is written to compensate the shortcomming of splitters erroneously fracturing up single events into a multitude of subevents. Therefore a splitter has to be applied to the data before treatment with CoincSuite can commence. CoincSuite does also require a bit of information from the Splitter in order that it can correctly identify its work task. Also does it require the splitter to run in such way that above described frame structure is maintained.

The choice of splitter is left to the user, however it must necessarily run on a PulseSeries(Mask) in the Q-frame and deliver subevents in the form of P-frames each holding a PulseSeriesMask. The subevent frames need to have the same sub_event_stream, which is preferably the name of the splitter itself, and a ascending sub_event_ID.

Most Splitters also offer to write out the number of splitframes they have issued per event (SplitCount) as an I3Int in the Q-Frame. This variable is needed for CoincSuite! If the splitter does not offer such option, this variable can be generated by the tool SplitCountMaker.

Requirements on parameter correctness

In order for CoincSuite to run correctly, its modules must be added to the tray in sequential order. This is because CoincSuite does not offer an integrated solution of a single module, but is an open solution, where also other foreign modules can interact with the current recombination process of any particular event. Thereby CoincSuite is more a collection of single modules, each given a specific task. If they are stacked correctly the wanted result is achieved.

This has two implications:

First, there is no communication behind the scenes by CoincSuite and information propagation must be realized solemnly by the processed frames themselves. Such communication objects in the frame are the hearth and bone of CoincSuite and should not be tempered with.

Second, single modules do not know about the configuration of previous modules, so it can be necessary that some parameter settings must be repeated for every module.

It is of utter importance that the configurable names in the Modules are set correctly, because failure in locating the requested name can under circumstances be desired behaviour for the program and no error is returned. So execution might continue while the desired task is not performed. So be aware!

Sequence of modules

There is a certain sequence in which order modules must be called, so that CoincSuite can work correctly. This is:

  • Preparation modules: augmenting the framestructure e.g. ReducedCountPlacer

  • Early Discard Modules: discarding nuisance frames like NoiseClusters or Afterpulse-Events e.g. AfterpulseDiscard, or foreign solutions like NoiseeEngine.

  • Hypoframe Creators: which provide a unsplit hypothesis by preparing the HypoFrames, e.g. HypoFrameCreator or HypoFrameFaker

  • Augmenting Modules: which do provide reconsructions and variable extractions for SplitFrames as well as HypoFrames; these are i.g. foreign modules like LineFit or CommonVariables. These Modules should if possible not be too expensive in computation.

  • Tester Modules: which test if the unsplit hypothesis in the HypoFrame is to be preferred above the split hypotheses represented by the two SplitFrames.

  • Final Decision Makers and Recombiners: which take into account all decisions from previous run Tester modules and make a final judgement. If the verdict is to recombined, this will be realized immediately by creating a new frame in the series of SplitFrames as the recombination of the two fracture SplitFrames identified. The latter are marked for removal.

  • Clean-Up modules: which do discard those frames which are marked for removal, and those which are not useful for anything other than within CoincSuite e.g. HypoFrames. It is also possible just to perform a purging process of frames and wipe them clean from any CoincSuite internal keys.

  • Re-augmentation Modules: which do rerun the augmentation modules from before, but just on these frames which are newly created and not have the augmentation present. This is not necessary, but is highly encouraged to have a consistent frame-structure and object content in all SplitFrames.

Where to start

For you as a new user to CoincSuite it is recommended to have a look at the scripts provided in /resources/examples.

It is highly recommended to give them a first pass by running on a well known event sample and checking the output. This is a good point to familiarize oneself with the frame-structure that has been written out and the frame-objects it contains.

Then in a second step it is advisable to comment out all modules and checking the output again. Then uncomment modules from top to bottom and check the output iteratively to grasp what each and every module does.

Where to continue

At some point you want to play around with the different Tester-Modules and settings to optimize your recombination success. Here are some general remarks which will help you to do so:

  • A cleaner event sample, means better controlled events, means stronger parameter settings possible, means more recombination success. Consider this when you proceed through your different cut-levels. You’ll observe events which have not not been recombined correctly more and more frequently as you are removing the easy and thus already recombined ones. This is normal and expected behaviour, so don’t panic!

    The problem can be remedied by application of event splitter and recombinations to the sample a second time, but now with more stringent settings adapted to you cleaner sample.

  • Choose wisely in which list of the DecisionMaker you put your Tester: written properly, almost all Testers are good to give Hints and could go to the Like-list, only few Testers can be trusted to not give false negatives and can go to the Veto-list, and even a few remaining ones are that robust in not giving false-positives, that they can go to the True-list. So observe and choose wisely.

  • If you need to use reconstructions as input to the testers, use simple ones, like (improved)Linefit. LLH-fits are too computation intensive and their plus in precision does not add to the excellency of the Testers.

  • Try to optimize your Testers once at a time.

  • If probing for optimized parameter settings, you need to know the truth of every SplitFrame, if it belongs to the same primary like another SplitFrame does; so to speak if the recombination is desired. This can either be achived by running on a pure sample of single-events where sequence with two SplitFrames is a wrong split and should be recombined. However, you can not quantify the false positives with this approach. Or you try to figure out the truth about individual SplitFrames in an uncontrolled event sample with the help of tools like MCHitSparator```or ``MCPulseSeparator.

  • Try to probe for as many recombination aspects as possible with your Testers to arrive at a conclusive decision. However, also do not try to unite too many aspects into a single Tester, because all of them can hardly be controlled at the same time: simpler is better!

  • Never interfere with the internal objects of CoincSuite (marked either by CS_ or the name of the subevent-stream in the name) while you have not concluded the processing with the DecisionMaker. This will lead to confusion and wrong decisions.

Last words

There is much room for improvement

There are a lot of options to CoincSuite and it can get kind of overwhelming to control them all. The default values of all modules are chosen with great consideration while CoincSuite is well modularized. So if you try to optimize and improve CoincSuite for your personal needs, it is best practice to improve on isolated parts e.g. single modules first, before introducing changes at too much at once. The TesterModules are an excellent testing-ground to do exactly that.

You can also always write your own TesterModule and learn from that: best practice is to pluck apart one of the existing TesterModules and rewrite that passages of the code that you like to alter to your needs (SpeedTester is a good starting point for that).

You’ll find some scripts in the project MCPulseSeparator that can actually help you to quantify your results for the possible improvements and which will help you to optimize your settings.

One final word

CoincSuite and the mechanisms it uses are nothing too sophisticated and actually quite crude. Also some parameters have not been optimized for a general use-case. This means there is a LOT of room for improvement: either by better ideas or simply better parameter settings.

The modularity for Testers allows to add further Testers to the project without interfering with the existing ones. So please consider to make your Tester-idea available to other people.

If you have ideas or actual implementations, which can improve CoincSuite, please do not hesitate to drop an email to me <mailto:marcel.fysik@fysik.su.se>.