Event mixer

[gondiaz]

This PR adds a Event Mixer implementation. This PR requires #807 to be merged since it uses newer pandas functionality.

The Event Mixer is the program that reads MC events from different detector volume and isotope (component) and selects the number of events for each component based on the activity-assumptions and desired exposure.
The isotopes can be background like (Bi214, Tl208, Co60, K40) or signal like (0nubb, 2nubb).

The Event Mixer reads high level isaura files, selects the events and writes them in same isaura-like files.

The Event Mixer configuration parameters are obtained in the mixer.conf file, and the program is called similarly as IC cities, such that: event_mixer /path/to/conf/mixer.conf. The user must name the input and output files as described in the config file.

The event_mixer script is divided in several parts, which allows unit testing:

1. read the config parameters
2. compute number of events per component (g4volume, isotope)
3. run event mixer

The most important part is carried out in point 3 by the Event_Mixer class. The class computes the number of output files based on the total number of events and number of events per file (being the latter a config parameter). Then it creates an event counter to keep track of the events that are saved. Each output file will contain events for each MC component based on proportionality.

Since each MC component (g4volume, isotope) are processed separately, event label might be repeated. Then the output files also save the MC component label as new columns in the dsts. Besides this information is required to do MC analysis (background fits). The file number is also saved inRun/events if lower level data consults are required.

[jahernando]

About the get_nevents_from_db function in mixer.py:

1. It needs documentation for the client

2. it should have a more clear interface and name: i.e: get_nevents_of_items_in_mix(exposure, isotopes, volumes, db_name)

   The volumes could be 'all' = [], an empty list, by default, but it could be of interest to make mixtures with a defined set of volumes.

   I guess isotopes could have also a default, 'all',

   Maybe for NEXT-100 we should have also a default db_name

3. The body of the function could reflect the different steps in a visible way:

   get number of events of every item in the mix (exposure, isotopes, volumes, db_name):

   check that the items (isotopes, volumes) are in the DB

   compute the number fo events for each item and the exposure

   return a table with (isotopes, volumen, nevents)

4. The functionality of the function is fine, the code also,

my recommendations:

1. comment the function,
2. rename the function, add the volumes in the interface and put a default as "all"
3. separate more clearly (or comment) the body to indicate/show clearly the functions tasks

[gondiaz]

As we talked offline, I renamed the function, added an explanatory comment and implemented keyword defaults. Also, as we decided, volumes argument is not included since it is impractical in the event-mixer: the number of volumes is larger than the number of isotopes and it would require a list of pairs (g4volume, isotope) to provide the correct functionality (not all the volumes are radioactive for all the possible background isotopes)

[jahernando]

The documentaion of Event_Mixer class is now clear and helps to follow the flow of the instance when running. Nevertheless, it is good to clarify i) what are the columns/labels of the DF that the get_mixer_events function returns, ii) the procedure of the _get_component_data method, indicating that the nevts decreases when the correspondent number of events per file is written in the output. That is that nevts is a dynamic variable that indicate sin every-moment the number of events still to write out. If I am correct.

[jahernando]

In Event_Mixer, the way the indices of the input data files (stores in maps) and how the are accessed in _get_component_data are obscure, please document how this works better.

[jahernando]

The test functions are file in mixer_text.py, but again, please comment what is testing each one!

[jahernando]

I think the PR is in good state, ready for my approval, but please add the comments indicated before!

There are still some issues, I guess, pending: i) shuffle the index of the output-files ii) to generate nevents of each sample via Poisson. I guess both can be added in this pull-request, otherwise, indicate why not.

[gondiaz]

I have resolved the comments (except the shuffling which we can maybe avoid as talked offline), plus some additions:

• Remove timestamp variable, since it is useless and confusing for the user (as talked offline)
• Add half-lifes: for 0nubb is provided in the configuration, for 2nubb is hardcoded (referenced therein)
• Compute reconstruction efficiency dataframe, containing nreco (number of reconstructed events) and nsim (number of simulated events). Take into account the reconstruction efficiency in the number of events to be mixed.
• Check that the number of reconstructed events in the input files is enough to run the mixer, if not, raise an exception.

[jahernando]

In Computing the 2nubb events, you are hardwaring 100 kg for the mass of 'NEXT-100', but the final kg should be a parameters of a value in the DB. Discuss it with @msorel!

[jahernando]

The verbosity configuration parameters is a must!

[jahernando]

I think the new commits improve the PR and solve the comments about better documenting the code. The issue of the 100 kg mass hardware, could led to confusions later, unless it is clear and documented, that the mass will be consider always for NEXT-100 as 100 kg!

When this issues is solved, I think the PR is ready for approval!

[msorel]

In Computing the 2nubb events, you are hardwaring 100 kg for the mass of 'NEXT-100', but the final kg should be a parameters of a value in the DB. Discuss it with @msorel!

Yes, even with fixed detector geometry, mass will depend on average pressure/temperature of the run, which we do not know now. Detector mass must be a configuration parameter.

Same for enrichment factor, I think now hard-coded to one. We will have at least two values, one for depleted and one for enriched xenon, so this is probably another configurable parameter (or a choice from a list of options; probably best a config parameter?).

Final comment on this issue of computing bb2nu events. You now assume K-Zen's latest central value. However, EXO-200 value still has smaller errors, so I would probably go with 2.165e21 yr instead, as we did for bb2nu sensitivity studies for NEXT-White paper. The other option is to do a weighted average between EXO and K-Zen, but probably not worth it. Reference for EXO-200 paper: Phys.Rev. C 89 (2014) 1, 015502.

Sorry for not commenting on the rest of this pull request. But from what @jahernando says, this is pretty much ready to go: great! Thanks a lot for the work.