Beam timing integration and optical calibration nutples update

[mvicenzi]

This PR is the initial step towards integrating the beam timing information into the official reconstruction workflow. It includes the low-lovel producer that extracts the beam times (EW,RWM) from the digitized waveforms as well as the infrastructure update to propagate RWM-relative times up to the calibration ntuples.

In particular, the main updates are:

• A new producer PMTBeamSignalsExtractor to extract the RWM/EW times from their digitized waveforms in the spare channels of the PMT digitizers and two new products std::vector<icarus::timing::PMTBeamSignal> storing the corrected RWM and EW times respectively.
• A new analyzer ICARUSBeamStructureAna as a quick shortcut for studies on the beam bunch structure, combining together PMT, beam and CRT information.
• Updates to ICARUSFlashAssAna (standard light analysis for the calibration ntuples), including the addition of new beam-related variables and other small changes (including the option to dump the full PMT waveforms!)
• Updates to icarus_stage0_defs to include PMTBeamSignalsExtractor in the chain of PMT producers with label beam, therefore injecting two new data products (beam:EW and beam:RWM).
• New fcl files to run ICARUSBeamStructureAna and ICARUSFlashAssAna on raw files.

More details are given below for the reviewers. I'm summoning for the task @PetrilloAtWork (as LArSoft grandmaster and OpReco/trigger convener), @rtriozzi , @aheggest and @francescopoppi (as CRT experts, timing enthusiasts and calibration ntuples enjoyers).

Details

PMTBeamSignalsExtractor

This module extracts the RWM and EW times from the waveforms recorded in the spare PMT channels and associates these times with all the channels in the same PMT readout crate. A few notes:

• The mapping of the special EW/RWM channels is read from CAEN_V1730_setup_icarus.fcl. The wrong labels due to fibers having been swapped in the middle of Run-2 (see SBN-doc-34631 for details) are corrected while packaging the data products.
• Offbeam events are skipped, and the resulting data products are empty vectors.
• The EW/RWM signals are expected to be sharp square waves in negative polarity. The time is based on the front side of that wave. The extracton algorithm is quite unsophisticated and follows what is done for the digitized trigger signal in PMTWaveformTimeCorrectionExtractor: get the absolute minimum, get the baseline 20 samples before, and take the start time from the sample that crosses 20% of the amplitude (baseline-minimum). It's important to note that a tunable threshold (default: 200 ADC) has been added to avoid picking up on electronic crosstalk (see SBN-doc-34928) which becomes particularly relevant when no real signal is present.
• The EW/RWM are re-aligned to all the other PMT waveforms using the digitized trigger correction.
• The module produces two std::vector<icarus::timing::PMTBeamSignal> with 360 elements each, representing the relevant RWM or EW time for the corresponding PMT channel (similar concept to std::vector<icarus::timing::PMTWaveformTimeCorrection>). The reason for saving different RWM times for each PMT crate is related to being currently unable to determine a unique one. If no signal was found in the waveform, the RWM/EW time defaults to zero and isValid() returns false for icarus::timing::PMTBeamSignal (which should always be checked before using the product).
• A debug mode is available to produce ROOT trees to easily inspect the EW/RWM times. Another configuration option also allows to dump the full EW/RWM waveforms in the debug trees. Note that the Run-2 fiber swap is not corrected for in the ROOT trees.
• This producer has been added to the icarus_stage0_defs.fcl as beam: the two data products are labelled as beam:EW and beam:RWM respectively.

ICARUSBeamStructureAna

This analyzer is meant to simplify the work for people looking directly at the beam bunch structure by putting together two ROOT trees with relevant trigger, PMT, beam and CRT variables. This is an updated version of what has been used for the light-only reconstruction of the BNB/NuMI bunch structure.

• Offbeam events are skipped.
• Two ROOT trees are produced, one per cryostat. In each tree, one row rapresents a PMT OpFlash and stores general trigger/flash information. In addition, it stores vectors with the first OpHit start/peak/rise times from each PMT in the flash and vectors with the CRT hits that matched with the flash (if any).
• For each OpHit, start/peak/rise times are provided relative to both the trigger time and and the RWM time (_rwm in the variable name). If the RWM time is not available for a particular channel, the RWM-relative times are defaulted to zero. This could happen both if the RWM digitized signal was missing completely for the event or if it was missing for only one or few crates.
• For each OpFlash, the flash time relative to the RWM time is provided by considering the mean between the first OpHit rise time on the left wall and the first OpHit rise time on the right wall (see SBN-docdb-34793). If no RWM times are available, this variable defaults to zero. Similarly, if one the PMT channels involved in the flash had no RWM time available, the variable is zero again. The rationale is that it might no be possible to use the correct "first" OpHit if some are being excluded because of no RWM reference. If the flash involves PMTs from only one wall (rare? impossibile?), the first OpHit time on that wall is picked.
• The time-of-flight correction is not computed, but the OpFlash z barycenter is available in the ROOT trees.
• run_beamstructure_ana.fcl is provided to run this analyzer directly on raw data. The final output contains both its output trees and the debug trees from PMTBeamSignalsExtractor so that it provides all the info needed for reconstructing and studying the beam bunch structure on data.

ICARUSFlashAssAna (calibration ntuples)

This analyzer produces the optical trees that are part of the calibration nutples. It has been updated to propagate the new beam timing variables to a common widely-used output. At the same time, additional updates were implemented to either clean-up the code or add functionalities. Changing variable names or conventions was avoided to maintain compatibility with user codes that might be based off these trees.

• In the OpHit trees, the start/peak times are now provided both w.r.t to the trigger time and the RWM time (_rwm in the variable name). If the RWM time is not available for a particular channel, the RWM-relative times are defaulted to zero. Please note that the RWM-relative rise time is not provided in this format as the rise time is defined by convention as being relative to the start time, so it can be easily computed from the other variable.
• The OpFlash trees contain vectors with information on the first OpHit from each PMT in the flash. An additional vector has been added to store the OpHit start times w.r.t RWM reference. The format of these vectors is inefficient. They always store 360 values with the vector index being the channel id. However, flashes never include all PMTs so the empty elements are filled with zeros. Should we change this behavior and save only the relevant channels? This might affected everyone who uses the calibration ntuples.
• The flash time relative to the RWM time is provided by considering the mean between the first OpHit rise time on the left wall and the first OpHit rise time on the right wall. If no RWM times are available, this variable defaults to zero. Similarly, if one the PMT channels involved in the flash had no RWM time available, the variable is zero again. The computation is made annoying by the fact that vectors have always 360 elements, several of which defaulted to zero because not included in the flash. Times that are exactly zero are excluded from the search of the first OpHit times because of this reason. If the flash involves PMTs from only one wall (rare? impossibile?), the first OpHit time on that wall is picked.
• The event trees now stores the adders LVDS bits in addition to the usual majority LVDS bits.
• A parameter (UseSharedBaseline) has been added (defaulted to true) for the the baseline computation in the waveform info tree using the SharedBaseline module instead of a single median over the waveform. If the option is disabled or the number of baselines does not match the number of waveforms (which can happen if you mix data products, e.g. daqPMTonbeam with pmtbaselines), the simple median is used. Please note that even if the option is disabled, the module still requires the SharedBaseline data product to be available... this shouldn't be too much of a problem given that it's in the standard stage0 flow.
• A parameter (SaveRawWaveforms, defaulted to false) has also been added to dump the full waveforms in the waveform info tree. This was requested some time ago and might be useful for specific productions. It should generally be disabled since the it makes the output tree quite heavy.
• run_flashana.fcl is provided to run this analyzer directly on raw data.

[mmrosenberg]

trigger build

[FNALbuild]

✔️ CI build for LArSoft Succeeded on slf7 for c14:prof -- details available through the CI dashboard

[FNALbuild]

❌ CI build for ICARUS Failed at phase build ICARUS on slf7 for c14:prof -- details available through the CI dashboard

🚨 For more details about the failed phase, check the build ICARUS phase logs

parent CI build details are available through the CI dashboard

[FNALbuild]

✔️ CI build for LArSoft Succeeded on slf7 for e26:prof -- details available through the CI dashboard

[FNALbuild]

❌ CI build for ICARUS Failed at phase ci_tests ICARUS on slf7 for e26:prof - ignored warnings for build -- details available through the CI dashboard

🚨 For more details about the failed phase, check the ci_tests ICARUS phase logs

parent CI build details are available through the CI dashboard

[mvicenzi]

Second part, reviewing the producer module. I think there is a minor bug with the debug tree in case of swapped cables, which I pointed out. For the rest, beside my usual pedantry, I don't find major problems. And I am assuming that I won't be able to convince you to move from fhicl::ParameterSet to a specific configuration object so that the usual lar --print-description works (possibly excluding the BoardSetup configuration, which maybe can be turned into a fhicl::Sequence<fhicl::DelegatedParameters>).

But I ask anyway.

I reviewed, implemented and resolved all the comments!
Many thanks for the detailed reviewed, I learned a lot of witchcraft today.
Regarding the debug trees, I would dare saying that it's not a bug but rather a feature... either way it's something I intented to keep this way. My reasoning is that these debug trees would be looked at by "expert" people who can do the swap themselves, while the data products injected downstream are rectified to allow a more straighfoward and simple use.

And yes, as an avid non-user of lar --print-description, I'm happy to stick with fhicl::ParameterSet.

[mmrosenberg]

trigger build LArSoft/lar*@LARSOFT_SUITE_v09_91_02

[FNALbuild]

✔️ CI build for LArSoft Succeeded on slf7 for c14:prof -- details available through the CI dashboard

[FNALbuild]

✔️ CI build for LArSoft Succeeded on slf7 for e26:prof -- details available through the CI dashboard

[FNALbuild]

❌ CI build for ICARUS Failed at phase build ICARUS on slf7 for c14:prof -- details available through the CI dashboard

🚨 For more details about the failed phase, check the build ICARUS phase logs

parent CI build details are available through the CI dashboard

[FNALbuild]

⚠️ CI build for ICARUS Warning at phase ci_tests ICARUS on slf7 for e26:prof -- details available through the CI dashboard

🚨 For more details about the warning phase, check the ci_tests ICARUS phase logs

parent CI build details are available through the CI dashboard