icarus::trigger::TriggerEfficiencyPlotsBase Class Reference

Helper class to produce plots about trigger simulation and trigger efficiency. More...

#include <TriggerEfficiencyPlotsBase.h>

Inheritance diagram for icarus::trigger::TriggerEfficiencyPlotsBase:

Classes
struct	Config
struct	GatePack_t
	A collection of useful beam gates. Make one with makeGatePack(). More...
class	HistGetter
class	PlotCategory
struct	SettingsInfo_t
	Generic description of trigger settings. More...

Protected Types
using	microseconds = util::quantities::intervals::microseconds
using	nanoseconds = util::quantities::intervals::nanoseconds
using	EventInfo_t = details::EventInfo_t
using	PMTInfo_t = details::PMTInfo_t
using	TriggerInfo_t = details::TriggerInfo_t
using	PlotSandbox = icarus::trigger::PlotSandbox
	Import type. More...
using	PlotSandboxRefs_t = std::vector< std::reference_wrapper< PlotSandbox const >>
	List of references to plot sandboxes. More...
using	PlotCategories_t = std::vector< PlotCategory >
using	InputTriggerGate_t = icarus::trigger::TrackedOpticalTriggerGate< sbn::OpDetWaveformMeta >
	Type of trigger gate extracted from the input event. More...
using	TriggerGates_t = std::vector< InputTriggerGate_t >
	A list of trigger gates from input. More...
using	TriggerGatesPerCryostat_t = std::vector< TriggerGates_t >
	Type of lists of gates, one list per cryostat (outer index: cryostat no). More...
using	ChannelID_t = InputTriggerGate_t::TriggerGate_t::ChannelID_t
	Type representing the unique identifier of a optical detector channel. More...

Protected Member Functions
	TriggerEfficiencyPlotsBase (Config const &config, art::ConsumesCollector &consumer)
	Constructor; requires a configuration and module's consumesCollector(). More...
void	process (art::Event const &event)
	Fills the plots. Also extracts the information to fill them with. More...
void	printSummary () const
	Prints end-of-job summaries. More...
std::string const &	logCategory () const
	Returns the name of the log category. More...
TTree *	eventTree ()
	Returns a pointer to the tree where event information is written. More...
bool	useGen () const
	Returns whether we are using and filling generator information. More...
bool	useEDep () const
	Returns whether we are using and filling energy deposition information. More...
std::size_t	nADCthresholds () const
	Returns the number of configured PMT thresholds. More...
auto	ADCthresholds () const
	Returns a iterable sequence of all configured PMT thresholds. More...
std::string const &	ADCthresholdTag (std::size_t iThr) const
geo::GeometryCore const &	geometry () const
	Returns the detector geometry service provider. More...
nanoseconds	triggerTimeResolution () const
	Returns the resolution of trigger timing clock [ns]. More...
virtual void	initializePlots (PlotCategories_t categories, std::vector< SettingsInfo_t > const &settings)
	Initializes all the plot sets, one per PMT threshold. More...
void	initializePlots (std::vector< SettingsInfo_t > const &settings)
	Initializes sets of default plots, one per PMT threshold. More...
virtual void	initializePlotSet (PlotSandbox &plots, std::vector< SettingsInfo_t > const &settings) const
	Initializes full set of plots for (ADC threshold + category) into plots. More...
virtual void	initializeEfficiencyPerTriggerPlots (PlotSandbox &plots) const
	Initializes set of plots per complete trigger definition into plots. More...
virtual void	initializeEventPlots (PlotSandbox &plots) const
	Initializes a single, trigger-independent plot set into plots. More...
virtual void	initializePMTplots (PlotSandbox &plots) const
virtual bool	shouldPlotEvent (EventInfo_t const &eventInfo) const
virtual void	simulateAndPlot (std::size_t const thresholdIndex, TriggerGatesPerCryostat_t const &gates, EventInfo_t const &eventInfo, detinfo::DetectorClocksData const &clockData, PlotSandboxRefs_t const &selectedPlots)=0
	Simulates all triggers for a trigger setting and plots the results. More...
virtual void	fillEventPlots (EventInfo_t const &eventInfo, PlotSandbox const &plots) const
	Fills the plots (initializeEventPlots()) with info from eventInfo. More...
virtual void	fillPMTplots (PMTInfo_t const &PMTinfo, PlotSandbox const &plots) const
	Fill the plots (initializePMTplots()) with info from PMTinfo. More...
virtual void	fillEfficiencyPlots (EventInfo_t const &eventInfo, TriggerInfo_t const &triggerInfo, PlotSandbox const &plots) const
virtual void	fillAllEfficiencyPlots (EventInfo_t const &eventInfo, PMTInfo_t const &PMTinfo, TriggerInfo_t const &triggerInfo, PlotSandbox const &plots) const
void	deleteEmptyPlots ()
	Deletes plots with no entries, and directories which became empty. More...
std::size_t	createCountersForPattern (std::string const &patternName)
	Creates counters for all the thresholds of the specified trigger. More...
GatePack_t	makeGatePack (art::Event const *event=nullptr) const
	Creates a GatePack_t from the specified event. More...
void	registerTriggerResult (std::size_t threshold, std::size_t pattern, bool fired)
	Registers the outcome of the specified trigger. More...
void	registerTriggerResult (std::size_t threshold, std::size_t pattern, TriggerInfo_t const &triggerInfo)
icarus::trigger::ApplyBeamGateClass	makeMyBeamGate (detinfo::DetectorClocksData const &clockData) const
	Shortcut to create an ApplyBeamGate with the current configuration. More...
icarus::trigger::ApplyBeamGateClass	makeMyBeamGate (art::Event const *event=nullptr) const
icarus::trigger::ApplyBeamGateClass	makeMyBeamGate (art::Event const &event) const

Static Protected Member Functions
static std::vector< ChannelID_t >	extractActiveChannels (TriggerGatesPerCryostat_t const &cryoGates)
	Returns all channels contributing to the trigger gates. More...

Static Protected Attributes
static PlotCategories_t const	DefaultPlotCategories
	List of event categories. More...

Private Member Functions
std::vector< std::string >	selectPlotCategories (EventInfo_t const &info, PlotCategories_t const &categories) const
	Returns the names of the plot categories event qualifies for. More...
geo::TPCGeo const *	pointInTPC (geo::Point_t const &point) const
	Returns the TPC point is within, nullptr if none. More...
geo::TPCGeo const *	pointInActiveTPC (geo::Point_t const &point) const
TriggerGates_t	readTriggerGates (art::Event const &event, art::InputTag const &dataTag) const
TriggerGatesPerCryostat_t	splitByCryostat (TriggerGates_t &&gates) const
	Moves the data in gates in a collection of gates by cryostat. More...
bool	deleteEmptyPlots (PlotSandbox &plots) const

Static Private Member Functions
static std::vector < geo::CryostatID >	makeChannelCryostatMap (geo::GeometryCore const &geom)
	Fills and returns a map of cryostat ID for each optical detector channel. More...
static std::string	thrAndCatName (std::string const &boxName, std::string const &category)
static std::string	thrAndCatName (PlotSandbox const &box, std::string const &category)
static icarus::trigger::details::EventInfoExtractor::EDepTags_t	makeEdepTag (fhicl::Sequence< art::InputTag > const &EnergyDepositTags, fhicl::OptionalAtom< art::InputTag > const &EnergyDepositSummaryTag)
	Creates a EDepTags_t out of the module configuration. More...

Private Attributes
art::InputTag	fDetectorParticleTag
	Input simulated particles. More...
std::map< std::string, art::InputTag >	fADCthresholds
	ADC threshold tags to read, and the input tag connected to their data. More...
microseconds	fBeamGateDuration
	Duration of the gate during with global optical triggers are accepted. More...
microseconds	fBeamGateStart
	Start of the beam gate with respect to BeamGate(). More...
microseconds	fPreSpillWindow
	Duration of the pre-spill gate. More...
microseconds	fPreSpillStart
	Start of the pre-spill gate. More...
nanoseconds	fTriggerTimeResolution
	Trigger resolution in time. More...
bool	fPlotOnlyActiveVolume
	Plot only events in active volume. More...
std::vector< std::string >	fOnlyPlotCategories
std::string const	fLogCategory
	Message facility stream category for output. More...
std::string	fLogEventDetails
	Steam where to print event info. More...
PlotCategories_t	fPlotCategories
	Plot categories (via initializePlots()). More...
geo::GeometryCore const &	fGeom
art::TFileDirectory	fOutputDir
	ROOT directory where all the plots are written. More...
details::EventInfoExtractorMaker const	fEventInfoExtractorMaker
	Helper to extract information from the event. More...
std::vector< geo::CryostatID > const	fChannelCryostat
	ID of cryostat where each optical detector channel (vector index) is. More...
std::vector< PlotSandbox >	fThresholdPlots
	All plots, one set per ADC threshold. More...
std::unique_ptr < details::EventIDTree >	fIDTree
	Handler of ROOT tree output. More...
std::unique_ptr < details::PlotInfoTree >	fPlotTree
	Handler of ROOT tree output. More...
std::unique_ptr < details::EventInfoTree >	fEventTree
	Handler of ROOT tree output. More...
std::atomic< unsigned int >	nEvents { 0U }
	Count of seen events. More...
std::atomic< unsigned int >	nPlottedEvents { 0U }
	Count of plotted events. More...
icarus::ns::util::ThreadSafeChangeMonitor < icarus::trigger::BeamGateStruct >	fBeamGateChangeCheck
	Functor returning whether a gate has changed. More...
details::TriggerPassCounters	fPassCounters
	Counters for all triggers. More...

Detailed Description

Helper class to produce plots about trigger simulation and trigger efficiency.

See Also

icarus::trigger::MajorityTriggerEfficiencyPlots

This helper class provides the foundation for writing a module producing sets of plots based on trigger primitives given in input.

The following documentation mainly deals with the most standard configuration and operations in ICARUS. Modules made with this helper and the modules upstream of them in data processing have quite some knobs that can be manipulated to test unorthodox configurations.

An example of module implemented with this class is icarus::trigger::MajorityTriggerEfficiencyPlots.

Overview of trigger simulation steps

This simulation only trigger primitives derived from the optical detector via hardware (V1730B boards). The trigger simulation branches from the standard simulation of optical detector waveforms (icarus::SimPMTIcarus module). From there, multiple steps are needed.

1. Produce single-PMT-channel discriminated waveforms: the discrimination threshold can be chosen ("ADC threshold" or just "threshold" in the following), and the result is one binary discriminated waveform that has value 0 when the waveform is under threshold and 1 when it's above threshold, with the same time discretization as the PMT waveform. Each discriminated waveform spans the whole event readout time and therefore it may merge information from multiple readout waveforms (raw::OpDetWaveform), but all from the same optical detector channel. This step can be performed with the module icarus::trigger::DiscriminatePMTwaveforms.
2. Combine the discriminated waveforms in pairs, in the same fashion as the V1730B readout board does to produce LVDS output. The output of this step is roughly half as many discriminated outputs as there were from the previous step (some channels are not paired). This output will be called trigger primitives because it is what the trigger logics is based on. We say that a trigger primitive is "on" when its level is 1. This step can be performed with the module icarus::trigger::LVDSgates.
3. Simulate the trigger logic based on the trigger primitives _(see below)_. This usually includes the requirement of coincidence with the beam gate.

Trigger logic may be complex, being implemented in a FPGA. Many options are available, including:

• coincidence of a minimum number of trigger primitives: the event is trigger if at least N trigger primitives are on at the same time;
• sliding window: primitives are grouped depending on their location, and there is a requirement on the minimum number of primitives in "on" level within one or more of these groups. For example, any sliding window of 30 channels (corresponding to 16 trigger primitives in standard ICARUS PMT readout installation) has to contain at least 10 trigger primitives "on" at the same time; or there must be two sliding windows with that condition; etc. Sliding windows can be obtained from further processing of the LVDS trigger primitives, for example with the module icarus::trigger::SlidingWindowTrigger.

This class is expected to support modules implementing different trigger logics.

Data objects for discriminated waveforms

A discriminated waveform is the information whether the level of a waveform is beyond threshold, as function of time. A discriminated waveform may be binary, i.e. with only levels 0 and 1 based on a single threshold, or with multiple levels. Also the numerical addition of two binary discriminated waveforms yields a multi-level waveform (in fact, three levels – 0, 1 and 2).

We represent this data in the forms of "events": an event is a change of level happening at a certain time. The class holding this information, icarus::trigger::TriggerGateData, covers the whole time, starting with a ground level 0. The next event will be a "opening" that increases the level, usually to 1. Other changing events may follow, and typically the last one will bring the level back to 0.

This information is joined by a list of channel numbers in order to represent a discriminated waveform e.g. from the optical detector. There may be one or more channels associated to a discriminated waveform, but for us there should always be at least one. The discriminated waveforms from PMT readout (raw::OpDetWaveform) are associated to a single channel, while LVDS trigger primitives are most often associated to two channels (some channels are not paired and will have only one channel). A sliding window will have as many channels as the PMT it covers. The global trigger should have all channels, while in ICARUS each of the two discriminated wabeforms from a cryostat should have half the channels. This information is represented in the class icarus::trigger::ReadoutTriggerGate, which inherits from icarus::trigger::TriggerGateData. This class is generic and can hold any representation for the time of the level changing events, for the levels, and for the identifiers of the channels. ICARUS specifies a data type for each of these quantities, and the resulting icarus::trigger::ReadoutTriggerGate class instance is called icarus::trigger::OpticalTriggerGateData_t.

Note

The class icarus::trigger::OpticalTriggerGateData_t is the one that gets written to disk in the art ROOT files. That is not a class by itself, but rather an alias of icarus::trigger::ReadoutTriggerGate, and many coding tools will call it in the latter way.

It is often convenient to track for each trigger gate object which input contributed to it, both in terms of channels and of single waveforms. The list of channels is embedded in icarus::trigger::ReadoutTriggerGate, while the list of source waveforms is not. An additional wrapper object, icarus::trigger::TrackedOpticalTriggerGate, contains a trigger gate proper (icarus::trigger::ReadoutTriggerGate) and a list of pointers to the source waveforms. In most of the code the source is represented by metadata (sbn::OpDetWaveformMeta) rather than the full waveforms (raw::OpDetWaveform) so that the bulk of the data is not necessary for the vast majority of the uses, and it can be dropped.

Utilities are available to manage the serialization of icarus::trigger::TrackedOpticalTriggerGate objects (icaruscode/PMT/Trigger/Utilities/TriggerDataUtils.h), which is implemented as a trigger gate collection and a association object

There are utilities available in icaruscode/PMT/Trigger/Utilities/TriggerDataUtils.h that can convert them into a collection of icarus::trigger::OpticalTriggerGateData_t objects plus a collection of art associations (for writing), and the other way around (for reading). Additional utilities allow to bridge between the waveform metadata and their original waveforms (icaruscode/PMT/Trigger/Utilities/OpDetWaveformMetaMatcher.h), which is needed when a producer utilising the metadata and combining trigger gates wants to save associations not only of the gates with the metadata, but also with the original waveforms. The module icarus::trigger::LVDSgates uses all of them and can be used as an illustration of the functionality.

A module is provided, called icarus::trigger::DumpTriggerGateData, which dumps on screen or on text file the information from a collection of discriminated waveforms in a (sort-of) human readable format. An example configuration for this module is provided in icaruscode, called dump_triggergatedata_icarus.fcl.

The main functions to manipulate the trigger gates are defined in the very base class, icarus::trigger::TriggerGateData: these allow e.g. to find events and query the level at a given time. Another important set of features is also present in icarus::trigger::TriggerGateData and replicated in the higher levels: the combination of trigger gates by sum (OR), multiplication (AND), minimum and maximum value.

Note

Combining a multi-level gate via Min() with a binary gate results into a binary gate which is logic AND of the two gates.

On the terminology

In this documentation, the "discriminated waveforms" are sometimes called "trigger gates" and sometimes "trigger primitives". Although these concepts are, strictly, different, usually the difference does not affect the meaning and they end up being exchanged carelessly.

Trigger logic algorithm

The trigger logic algorithm is completely absent from this helper, and it is entirely delegated to the derived classes (simulateAndPlot()). There are nevertheless a lot of functions that may help to process the input trigger primitives and fill some standard plots. Many of them are listed in the documentation of simulateAndPlot().

Event categories

Each event is assigned to a set of categories, and its information contributes to the plots of all those categories. The categories are passed to the helper in the initializePlots() call to create all the plots to be filled later. A default list of categories is provided as DefaultPlotCategories.

Module usage

The following aspects are common to all modules based on this helper.

Input data products

This module uses the following data products as input:

• trigger primitives:
  • std::vector<icarus::trigger::OpticalTriggerGateData_t> (labels out of TriggerGatesTag and Thresholds): full sets of discriminated waveforms, each waveform possibly covering multiple optical channels, and their associations to optical waveforms. One set per threshold; note that these are converted into InputTriggerGate_t data type for internal use;
  • associations with raw::OpDetWaveform (currently superfluous);
• event characterization:
  • std::vector<simb::MCTruth>: generator information (from GeneratorTags; multiple generators are allowed at the same time); it is used mostly to categorize the type of event (background, weak charged current, electron neutrino, etc.);
  • std::vector<simb::MCParticle>: particles propagating in the detector (from PropagatedParticles); currently not used;
  • std::vector<sim::SimEnergyDeposit>: energy deposited in the active liquid argon volume (from EnergyDepositTags); it is used to quantify the energy available to be detected in the event.

Output plots

The module produces a standard set of plots for each configured ADC threshold and for each event category. The plots are saved via art service TFileService in a ROOT file and they are organized in nested ROOT directories under the module label directory which is assigned by art:

• Thr### (outer level) describes the ADC threshold on the discriminated waveforms: the threshold is ### from the baseline;
• \<Category\> (inner level) describes the category of events included in the plots (e.g. All, NuCC; see PlotCategories).

Each of the inner ROOT directories contains a full set of plots, whose name is the standard plot name followed by its event category and threshold (e.g. Eff_NuCC_Thr15 for the trigger efficiency plot on neutrino charged current events with 15 ADC counts as PMT threshold).

Each set of plots, defined in icarus::trigger::TriggerEfficiencyPlots::initializePlotSet() (and, within, initializeEventPlots() and initializeEfficiencyPerTriggerPlots()), is contributed only by the events in the set category.

There are different "types" of plots. Some do not depend on triggering at all, like the deposited energy distribution. Others cross different trigger definitions, like the trigger efficiency as function of trigger requirement. Others still assume a single trigger definition: this is the case of trigger efficiency plots versus energy. Finally, there are plots that depend on a specific trigger definition and outcome: this is the case of all the plots including only triggering or non-triggering events.

A list of plots follows for each plot type. All the plots are always relative to a specific optical detector channel threshold (ADC) and a broad event category.

Plots independent of the triggers (including selection plots)

These plots are stored directly in a threshold/category folder:

• EnergyInSpill: total energy deposited in the detector during the time the beam gate is open. It is proportional to the amount of scintillation light in the event;
• EnergyInSpillActive: energy deposited in the active volume of the detector during the time the beam gate is open; the active volume is defined as the union of all TPC drift voulmes;
• plots specific to neutrino interactions (if the event is not a neutrino interaction, it will not contribute to them); if not otherwise specified, only the first neutrino interaction in the event is considered:
  • InteractionType: code of the interaction type, as in sim::TruthInteractionTypeName;
  • NeutrinoEnergy: generated energy of the interacting neutrino;
  • LeptonEnergy: generated energy of the lepton out of the first neutrino interaction;
  • InteractionVertexYZ: coordinates of the location of all interactions in the event, in world coordinates, projected on the anode plane.
• ActivePMT: the channels contributing to the trigger; a channel is added to this plot if it belongs to a gate (LVDS output) which during the beam gate it is beyond threshold at least once (note that in case of LVDS OR combination, a channel will appear in this plot even if it is not beyond threshold if the one paired with it is beyond threshold); this plot depends on the discrimination threshold.

Note

In fact, these plots usually do not even depend on the ADC threshold of the optical detector channels. Nevertheless, they are stored in the folders under specific thresholds, and they are duplicate.

Plots including different trigger requirements

These plots collect information from scenarios with different trigger requirements, but still with the same underlying optical detector channel ADC threshold. No plots are provided in this category by TriggerEfficiencyPlotsBase at the moment. Implementing modules can add plots by overriding the method initializePlotSet():

void MyTriggerEfficiencyPlots::initializePlotSet
  (PlotSandbox& plots, std::vector<SettingsInfo_t> const& settings) const
{
  // (inherited)
  helper().TriggerEfficiencyPlotsBase::initializePlotSet(plots, settings);

  // ... add more plot definitions, e.g.
  plots.make<TEfficiency>(
    "Eff",
    "Efficiency of triggering;requested primitives;trigger efficiency",
    settings.size(), 0, settings.size()
    );

} // MyTriggerEfficiencyPlots::initializePlotSet()

Plots depending on a specific trigger definition

The following plots depend on the full definition of the trigger, including PMT thresholds and other requirements. They are hosted each in a subfolder of the threshold/category folder, with a name encoding the requirement: ReqXX for trigger with minimum required primitives XX.

• EffVsEnergyInSpill: trigger efficiency as function of the total energy deposited during the beam gate.
• EffVsEnergyInSpillActive: trigger efficiency as function of the energy deposited in the TPC active volumes during the beam gate.
• EffVsNeutrinoEnergy, EffVsLeptonEnergy: trigger efficiency as function of the true energy of the first interacting neutrino, and of the outgoing lepton in the final state of the interaction, respectively.
• TriggerTick: time of the earliest trigger, in ticks. Only triggering events contribute.
• TriggerTime: the time (relative to the nominal beam gate opening) of the "main" trigger (the earliest in the triggering window). Only triggering events contribute.
• OpeningTimes: the time (relative to the nominal beam gate opening) of all the times the trigger requirements were satisfied (limited to the time interval where the trigger emulation is performed). Only triggering events contribute.

The parameters are defined in the same way as in the selection plots, unless stated otherwise.

Plots depending on a specific trigger definition and response

These plots depend on the trigger definition, as the ones in the previous type, and on the actual trigger response. They are hosted each in a subfolder of the threshold/category/requirement folder, with a name encoding the response: triggering for triggering events, nontriggering for the others.

Their event pool is filtered to include only the events in the current category which also pass, or do not pass, the trigger requirement.

The plots are:

• EnergyInSpill, EnergyInSpillActive, InteractionType, NeutrinoEnergy,LeptonEnergy, InteractionVertexYZ: these are defined in the same way as the selection plots

Configuration parameters

A terse description of the parameters is printed by running lar --print-description TriggerEfficiencyPlots.

• TriggerGatesTag (string, mandatory): name of the module instance which produced the trigger primitives to be used as input; it must not include any instance name, as the instance names will be automatically added from Thresholds parameter. The typical trigger primitives used as input may be LVDS discriminated output (e.g. from icarus::trigger::LVDSgates module) or combinations of them (e.g. from icarus::trigger::SlidingWindowTrigger module).
• Thresholds (list of tags, mandatory): list of the discrimination thresholds to consider. A data product containing a digital signal is read for each one of the thresholds, and the tag of the data product is expected to be the module label TriggerGatesTag with as instance name the value of the threshold (e.g. for a threshold of "60" ADC counts the data product tag might be LVDSgates:60).
• GeneratorTags (list of input tags, default: [ generator ]): a list of data products containing the particles generated by event generators; if empty, plots or categories requiring truth information will be omitted;
• DetectorParticleTag (input tag, default: largeant): data product containing the list of particles going through the argon in the detector;
• EnergyDepositTags (list of input tags, default: [ "largeant:TPCActive" ]): a list of data products with energy depositions; if empty, plots or categories requiring energy deposition information will be omitted; in alternative, EnergyDepositSummaryTag can be specified with the same purpose;
• EnergyDepositSummaryTag (input tags, optional): if specified, overrides EnergyDepositTags and uses for the energy deposition the information from the summary in the specified data product; such summary may be created for example by ExtractEnergyDepositionSummary module;
• BeamGateDuration (time, mandatory): the duration of the beam gate; the time requires the unit to be explicitly specified: use "1.6 us" for BNB, 9.5 us for NuMI (also available as BNB_settings.spill_duration and NuMI_settings.spill_duration in trigger_icarus.fcl);
• BeamGateStart (time, default: 0_us): how long after the
• nominal beam gate opening time the actual beam gate opens at;
• PreSpillWindow (time, default: 10_us): a pre-spill window is defined to observe the activity before the beam gate that might leak into the latter; this parameter regulates how long that window last; its position can be tweaked with the PreSpillWindowGap parameter;
• PreSpillWindowGap (time, default: 0_us): the delay from the end of the pre-spill window and the start of the beam gate (BeamGateStart); by default, the pre-spill window immediately precedes the beam gate; negative values of the gap allow the pre-spill window to overlap (or to be after) the beam gate; the duration of the pre-spill window is set via PreSpillWindow parameter;
• TriggerTimeResolution (time, default: 8 ns): time resolution for the trigger primitives;
• EventTreeName (optional string): if specified, a simple ROOT tree is created with the information from each event (see EventInfoTree for its structure);
• EventDetailsLogCategory (optional string): if specified, information for each single event is output into the specified stream category; if the string is specified empty, the default module stream is used, as determined by LogCategory parameter;
• PlotOnlyActiveVolume (flag, default: true): if set, only events within TPC active volume are plot; the check is performed on the generated location of the neutrino interactions (if any); events with no neutrino interactions are always plotted;
• LogCategory (string, default TriggerEfficiencyPlots): name of category used to stream messages from this module into message facility.

An example job configuration is provided as maketriggerplots_icarus.fcl.

Technical description of the module

The modules based on this helper read trigger gate data products from different ADC thresholds, and for each threshold they combine the data into a trigger response depending on a ADC threshold. Then they apply different trigger settings and for each one they fill plots.

All the input sets (each with its own ADC treshold) are treated independently from each other.

Each event is assigned to event categories. These categories do not depend on trigger definition nor primitives. For example, a electron neutrino neutral current interaction event would be assigned to the neutral current neutrino interaction category, to the electron neutrino category, and so on. A set of plot is produced at once for each of the event categories.

This module is designed as follows:

• each art event is treated independently from the others (this is the norm; method: process(), to be called in module's analyze());
• information for the plots which do not depend on the trigger primitives are extracted once per event (method: extractEventInfo());
• the event is assigned its categories (method: selectedPlotCategories(), with the categories defined at the time of initializePlots() call);
• for each input primitive set (i.e. for each ADC threshold):
  • trigger logic is applied, the beam gate is imposed, a trigger result is extracted and plots are filled; all is done in the method simulateAndPlot() provided by the derived module.

Note that the plots depending on the response may require multiple fillings. For example, a trigger efficiency plot as function of the trigger settings is a single plot in the plot set which requires a filling for every trigger setting. In a similar fashion, the plot of trigger time requires one filling for each requirement level that is met.

Organization of the plots

Plots are written on disk via the standard art service TFileService, which puts them in a ROOT subdirectory named as the instance of this module being run.

As described above, there are two "dimensions" for the plot sets: there is one plot set for each ADC threshold and for each event category, the total number of plot sets being the product of the options in the two dimensions.

The code is structured to work by threshold by threshold, because the trigger response depends on the threshold but not by the event category: the response is computed once per threshold, then all the plots related to that response (including all the event categories) are filled.

The structure in the file reflects this logic, and there are two levels of ROOT directories inside the one assigned by art to this module:

• the outer level pins down the ADC threshold of the plots inside it; the name of the directory follows the pattern Thr### (### being the ADC threshold), which is the "threshold tag";
• the inner level is the category of events included in the plots, and the name of the directories reflect the name of the category as defined in the corresponding PlotCategory object (PlotCategory::name()); this defines the "category tag".

In each inner directory, a complete set of plots is contained. The name of each plot is a base name for that plot (e.g. Eff for the efficiency plot) with the event category tag and the threshold tag appended (separated by an underscore character, "_"). The title of the plot is also modified to include the description of the plot category (as defined in PlotCategory::description()) and the ADC threshold. Therefore, within the same module directory, all plot names are different.

Adding a plot

When adding a plot, two actions are necessary:

1. initialize the new plot
2. fill the new plot

The initialization happens in icarus::trigger::TriggerEfficiencyPlots::initializePlotSet() method. A request must be issued to the plot sandbox to "make" the plot. In general it can be expected that all the arguments args in a call plots.make<PlotType>(args) are forwarded to the constructor of PlotType, so that to make a new PlotType object one has to consult only the constructor of that class. Be aware though that the library expects the first argument to be the ROOT name of the new object and the second to be its ROOT title. It is possible to work around this requirement with additional coding.

The method performing the plotting is simulateAndPlot(). The plots should be filled inside loops going through all plot sets. The existing code already does that in two loops, one for the plots depending on the trigger response requirement, and the other for the plots not depending on it.

About plot sandboxes

For the sake of this module, a plot sandbox is an object similar to a ROOT TDirectory, which can mangle the objects it contains to change ("process") their name and title, and that interacts properly with art::TFileDirectory so make TFileService happy. The processing of the name and title is used to add the category and threshold tags to the plot ROOT name and the corresponding annotations to the plot title, as described above.

Adding an event category

Event categories are specified to initializePlots() call: each category is described by a simple object PlotCategory which contains a name (used in ROOT directories, plot name tags and to univocally identify the category), a description (used in plot titles) and a condition for the event to fulfill in order to qualify for the category. The condition is a function object that accepts an EventInfo_t object with the relevant event information, and returns its decision (true if the event belongs to this category).

To add a category, it is enough to add an entry in the collection of plot categories passed to initializePlots(). The DefaultPlotCategories list can be used as a starting point.

The condition function adjudicates based on the information in EventInfo_t. It is likely though that if a new category is needed, the information currently available in EventInfo_t is not enough to decide the response. In that case, EventInfo_t must be extended to hold the newly required information. In addition, the method extractEventInfo() must be modified to set the new information. The documentation of that method expands on this topic.

Usage of the helper

An example of how to turn this helper class in a full blown art module is icarus::trigger::MajorityTriggerEfficiencyPlots.

Changing the trigger logic

The trigger logic is required to be coded in simulateAndPlot() of the derived class. Some details on implementing it can be found in the documentation of the method itself.

To implement a trigger logic, several components need to be coordinated:

1. combination of trigger primitives;
2. the data structure the combination is stored in;
3. interpretation of that data structure in terms of trigger firing (which we call here "trigger settings");
4. configuration of the trigger logic from user parameters.

A module may simulate a trigger which counts the number of primitives that are "on" and imposing a required minimum on that number for the trigger to fire. This is a possible implementation including those elements:

1. combination of trigger primitives: primitives are summed into a single multilevel gate (with beam gate on top);
2. the data structure the combination is stored in: a trigger gate object;
3. interpretation of that data structure in terms of trigger firing: the logic requires a minimum number of primitives being on at the same time; the interpretation uses the level of the combined trigger gate as the number of primitives on at every time, and decides that the first time this number meets the requirement, the trigger fires;
4. configuration of the trigger logic from user parameters: it's a parameter of the module itself (MinimumPrimitives).

An example of how a different trigger logic could be implemented following a similar model: let's assume we want a trigger based on two sliding windows. A window is a group of LVDS signals from neighboring channels. We can split the whole optical detector channels into many windows, and we can make the windows overlap: for example, a window includes the first 30 channels behind one anode plane, the second window includes 30 channels starting from the fifteenth, the third window includes 30 channels starting from the thirtieth, and so on. In ICARUS, 30 channels are served in 16 LVDS discriminated waveforms, i.e. 16 trigger primitives. We may require as a loose trigger that any window contains at least 10 primitives on at the same time (that is about 20 PMT channels beyond ADC threshold), and as a tighter trigger that there is a window with at least 8 trigger primitives on, and the corresponding window in the opposite TPC has at least 6 primitives on at the same time. Note that a splitting 7/7 won't do: one of the two windows must have 8 or more primitives on. The input primitives from the point of view of the module now become the "sliding window" combination of the LVDS trigger primitives, as produced e.g. by icarus::trigger::SlidingWindowTrigger module. How this can be implemented following the pattern of this module:

1. combination of trigger primitives: we prepare two primitives: one describes the maximum level among all the windows, and the other describes the level of the window opposite to the maximum (the way to achieve this is quite complicate);
2. the data structure the combination is stored in: two trigger gate objects;
3. interpretation of that data structure in terms of trigger firing: for the loose trigger, we look for the first time the maximum window level reaches the designated threshold; for the tighter trigger, some additional logic is required, discriminating the maximum window level primitive to the higher threshold, the opposite window level on the lower threshold, and setting them in coincidence; then the time the resulting gate opens, if any, is the trigger time;
4. configuration of trigger logic parameters: the two requirements (single window, double window with their minimum number of LVDS primitives) are read from the module FHiCL configuration; for computing efficiency, either in the constructor or in a beginJob() method we may also prepare the associations (pairing) between opposite windows or just channels;

Todo:

add ability to discriminate a trigger gate object? discrimination on level N (>=N -> 1, <N -> 0) can be obtained with adding a _-N_ uniform level, flooring on level 0 and (if needed) maxing on level 1.

Code style: quantities with units

To avoid issues with missing or wrong conversions, this code often uses LArSoft quantities library. A variable with a Quantity type is represented with a specific unit (e.g. microseconds) and can undergo only limited manipulation. The allowed manipulation should guarantee that the unit of the quantity is correctly preserved. For example, it is not possible to add to a microseconds interval a pure number (e.g. 9.0), but rather it is only possible to add time quantities (e.g. another microseconds variable, or a nanoseconds variable, or a literal value with unit, like 9.0_ns), and those quantities are properly converted, with the caveat that rounding errors may happen that a more careful explicit handling could avoid. Also, there are two types of variables that can feature the same unit, intervals and points. A point can't be scaled (e.g. you can't "double" the time the beam gate opens, while you can double the beam gate duration) and it can't be added to another point (the difference between two points is an interval).

To avoid mistakes in the conversion between different time scales, the LArSoft utility library detinfo::DetectorTimings is used, which is a wrapper of DetectorClocks service provider that makes the interface to convert times easier and uniform. Here we use it to convert time points from the simulation (which are expressed in nanoseconds and are starting at trigger time) into optical detector readout ticks, and vice versa. The values returned by this library have encoded in them which time scale they belong to, and in which unit they are measured.

Definition at line 974 of file TriggerEfficiencyPlotsBase.h.

Member Typedef Documentation

using icarus::trigger::TriggerEfficiencyPlotsBase::ChannelID_t = InputTriggerGate_t::TriggerGate_t::ChannelID_t

protected

Type representing the unique identifier of a optical detector channel.

Definition at line 1238 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::EventInfo_t = details::EventInfo_t

protected

Definition at line 1086 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::InputTriggerGate_t = icarus::trigger::TrackedOpticalTriggerGate<sbn::OpDetWaveformMeta>

protected

Type of trigger gate extracted from the input event.

Definition at line 1229 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::microseconds = util::quantities::intervals::microseconds

protected

Definition at line 980 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::nanoseconds = util::quantities::intervals::nanoseconds

protected

Definition at line 981 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::PlotCategories_t = std::vector<PlotCategory>

protected

Definition at line 1192 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::PlotSandbox = icarus::trigger::PlotSandbox

protected

Import type.

Definition at line 1149 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::PlotSandboxRefs_t = std::vector<std::reference_wrapper<PlotSandbox const>>

protected

List of references to plot sandboxes.

Definition at line 1153 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::PMTInfo_t = details::PMTInfo_t

protected

Definition at line 1087 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::TriggerGates_t = std::vector<InputTriggerGate_t>

protected

A list of trigger gates from input.

Definition at line 1232 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::TriggerGatesPerCryostat_t = std::vector<TriggerGates_t>

protected

Type of lists of gates, one list per cryostat (outer index: cryostat no).

Definition at line 1235 of file TriggerEfficiencyPlotsBase.h.

using icarus::trigger::TriggerEfficiencyPlotsBase::TriggerInfo_t = details::TriggerInfo_t

protected

Definition at line 1088 of file TriggerEfficiencyPlotsBase.h.

Constructor & Destructor Documentation

icarus::trigger::TriggerEfficiencyPlotsBase::TriggerEfficiencyPlotsBase ( Config const &  config, art::ConsumesCollector &  consumer  )

explicitprotected

Constructor; requires a configuration and module's consumesCollector().

Definition at line 494 of file TriggerEfficiencyPlotsBase.cxx.

  : fDetectorParticleTag  (config.DetectorParticleTag())
  , fBeamGateDuration     (config.BeamGateDuration())
  , fBeamGateStart        (config.BeamGateStart())
  , fPreSpillWindow       (config.PreSpillWindow())
  , fPreSpillStart
      (fBeamGateStart - config.PreSpillWindowGap() - fPreSpillWindow)
  , fTriggerTimeResolution(config.TriggerTimeResolution())
  , fPlotOnlyActiveVolume (config.PlotOnlyActiveVolume())
  , fOnlyPlotCategories   (sortCollection(config.OnlyPlotCategories()))
  , fLogCategory          (config.LogCategory())
  // services
  , fGeom      (*lar::providerFrom<geo::Geometry>())
  , fOutputDir (*art::ServiceHandle<art::TFileService>())
  // cached
  , fEventInfoExtractorMaker(
      config.GeneratorTags(),              // truthTags
      makeEdepTag(config.EnergyDepositTags, config.EnergyDepositSummaryTag),
                                           // edepTags
      fGeom,                               // geom
      nullptr,                             // detProps
      nullptr,                             // detTimings
      fLogCategory,                        // logCategory
      consumer                             // consumesCollector
    )
  , fChannelCryostat(makeChannelCryostatMap(fGeom))
{
  //
  // more complex parameter parsing
  //
  if (config.EventDetailsLogCategory(fLogEventDetails)) {
    // the parameter is somehow set, so fLogEventDetails won't be empty;
    // but if the parameter value is specified empty, we set it to fLogCategory
    if (fLogEventDetails.empty()) fLogEventDetails = fLogCategory;
  } // if EventDetailsLogCategory is specified

  std::string const discrModuleLabel = config.TriggerGatesTag();
  for (std::string const& threshold: config.Thresholds())
    fADCthresholds[threshold] = art::InputTag{ discrModuleLabel, threshold };
  

  if (config.EventTreeName.hasValue()) {
    
    std::string treeName;
    config.EventTreeName(treeName);

    fIDTree = std::make_unique<details::EventIDTree>
      (*(fOutputDir.make<TTree>(treeName.c_str(), "Event information")));
    fEventTree = std::make_unique<details::EventInfoTree>
      (fIDTree->tree(), useGen(), useEDep());
    fPlotTree = std::make_unique<details::PlotInfoTree>(fIDTree->tree());

  } // if make tree

  //
  // input data declaration
  //
  using icarus::trigger::OpticalTriggerGateData_t; // for convenience
  
  // trigger primitives
  for (art::InputTag const& inputDataTag: util::const_values(fADCthresholds)) {
    consumer.consumes<std::vector<OpticalTriggerGateData_t>>(inputDataTag);
    consumer.consumes<art::Assns<OpticalTriggerGateData_t, raw::OpDetWaveform>>
      (inputDataTag);
  } // for

  {
    mf::LogInfo log(fLogCategory);
    log << "\nConfigured " << fADCthresholds.size() << " thresholds (ADC):";
    for (auto const& [ thresholdTag, dataTag ]: fADCthresholds)
      log << "\n * " << thresholdTag << " (from '" << dataTag.encode() << "')";
    
  } // local block
  
  
  if (!useGen()) {
    mf::LogVerbatim(fLogCategory)
      << "Generation information will not be produced.";
  }
  if (!useEDep()) {
    mf::LogVerbatim(fLogCategory)
      << "Energy deposition information will not be produced.";
  }
  
} // icarus::trigger::TriggerEfficiencyPlots::TriggerEfficiencyPlots()

Member Function Documentation

auto icarus::trigger::TriggerEfficiencyPlotsBase::ADCthresholds ( ) const

inlineprotected

Returns a iterable sequence of all configured PMT thresholds.

Definition at line 1132 of file TriggerEfficiencyPlotsBase.h.

{ return util::get_elements<0U>(fADCthresholds); }

std::string const& icarus::trigger::TriggerEfficiencyPlotsBase::ADCthresholdTag ( std::size_t  iThr ) const

inlineprotected

Returns the ADC threshold tag value for PMT threshold index iThr.

Exceptions

std::out_of_range

if iThr is not a valid threshold index

See Also

nADCthresholds()

Definition at line 1137 of file TriggerEfficiencyPlotsBase.h.

    { return next(fADCthresholds.begin(), iThr)->first; }

auto icarus::trigger::TriggerEfficiencyPlotsBase::createCountersForPattern ( std::string const &  patternName )

protected

Creates counters for all the thresholds of the specified trigger.

Parameters

patternName

an identified for the pattern

Returns

the index of the pattern in the counter list

Definition at line 1245 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  std::size_t patternIndex = fPassCounters.NoIndex;
  std::size_t iThr [[maybe_unused]] = 0U;
  for (std::string const& thresholdTag: util::get_elements<0U>(fADCthresholds))
  {
    
    auto const indices = fPassCounters.create(thresholdTag, patternName);
    if (patternIndex == fPassCounters.NoIndex) patternIndex = indices.second;
    else assert(indices.second == patternIndex);
    
  } // for thresholds
  
  return patternIndex;
} // icarus::trigger::TriggerEfficiencyPlotsBase::createCountersForPattern()

void icarus::trigger::TriggerEfficiencyPlotsBase::deleteEmptyPlots ( )

protected

Deletes plots with no entries, and directories which became empty.

Definition at line 1235 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  for (auto& thrPlots: fThresholdPlots) deleteEmptyPlots(thrPlots);
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::deleteEmptyPlots()

bool icarus::trigger::TriggerEfficiencyPlotsBase::deleteEmptyPlots ( PlotSandbox &  plots ) const

private

Deletes from plots sandbox all plots and subboxes with no entries.

Returns

whether plots is now empty

Definition at line 1381 of file TriggerEfficiencyPlotsBase.cxx.

{
  TDirectory* baseDir = plots.getDirectory();
  if (!baseDir) return true; // no content, nothing to do
  
  // our plots first
  unsigned int nEntries = 0U, nDirectories = 0U, nDeleted = 0U;
  for (TObject* obj: *(baseDir->GetList())) {
    
    // we do not deal with directories (except for subboxes below)
    if (dynamic_cast<TDirectory*>(obj)) {
      ++nDirectories;
      continue;
    }
    
    ++nEntries;
    
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    if (auto hist = dynamic_cast<TH1 const*>(obj)) {
      if (hist->GetEntries() > 0) continue;
    }
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    else if (auto graph = dynamic_cast<TGraph const*>(obj)) {
      if (graph->GetN() > 0) continue;
    }
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    else if (auto* eff = dynamic_cast<TEfficiency const*>(obj)) {
      auto const* hist = eff->GetTotalHistogram();
      if (hist && hist->GetEntries() > 0) continue;
    }
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    else if (auto* tree = dynamic_cast<TTree const*>(obj)) {
      if (tree->GetEntries() > 0) continue;
    }
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // add here more supported object types
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    else continue; // we don't delete unknown objects
    
    mf::LogTrace(fLogCategory)
      << "Deleting empty " << obj->IsA()->GetName() << "['" << obj->GetName()
      << "'] from " << plots.name();
    delete obj;
    ++nDeleted;
    
  } // for objects in directory
  
  // if we have found no more directories than the ones expected
  // from the subboxes and all the other entries have been deleted,
  // this box might be empty
  
  bool empty
    = (nDeleted == nEntries) && (nDirectories <= plots.nSubSandboxes());
  
  // we can't delete the sandboxes while iterating on them...
  std::vector<std::string> toBeDeleted;
  for (PlotSandbox& subbox: plots.subSandboxes()) {
    if (!deleteEmptyPlots(subbox)) continue;
    toBeDeleted.push_back(subbox.name());
    mf::LogTrace(fLogCategory)
      << "Scheduling empty " << plots.name() << "/" << toBeDeleted.back() << " for deletion";
  } // for subboxes
  if (toBeDeleted.size() != plots.nSubSandboxes()) empty = false;
  for (std::string const& subName: toBeDeleted) {
    if (!plots.deleteSubSandbox(subName)) continue;
    mf::LogTrace(fLogCategory)
      << "Deleted box " << plots.name() << "/" << subName;
  } // for
  
  return empty;
} // icarus::trigger::TriggerEfficiencyPlotsBase::deleteEmptyPlots()

TTree* icarus::trigger::TriggerEfficiencyPlotsBase::eventTree ( )

inlineprotected

Returns a pointer to the tree where event information is written.

Definition at line 1120 of file TriggerEfficiencyPlotsBase.h.

{ return fIDTree? &(fIDTree->tree()): nullptr; }

auto icarus::trigger::TriggerEfficiencyPlotsBase::extractActiveChannels ( TriggerGatesPerCryostat_t const &  cryoGates )

staticprotected

Returns all channels contributing to the trigger gates.

Parameters

cryoGates

all trigger gates

Returns

a list of ID of "active" channels

A channels is considered "active" when it is contributing to a trigger gate which is open at least one. Conversely, all channels belonging to gates which have no opening are excluded.

Definition at line 1351 of file TriggerEfficiencyPlotsBase.cxx.

{

  //
  // get channels contributing to gates in a fired event
  //

  std::vector<ChannelID_t> channelList;
  for (auto const& gates: cryoGates) {
    for (auto const& gate: icarus::trigger::gatesIn(gates)) {

      if (gate.alwaysClosed()) continue;
      for (auto const channel: gate.channels()) {
        channelList.push_back(channel);
      }
    } // for gates
  } // for

  // remove duplicates
  std::sort(channelList.begin(), channelList.end());
  auto const firstDuplicate
    = std::unique(channelList.begin(), channelList.end());
  channelList.erase(firstDuplicate, channelList.end());
  return channelList;
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::extractActiveChannels()

void icarus::trigger::TriggerEfficiencyPlotsBase::fillAllEfficiencyPlots ( EventInfo_t const &  eventInfo, PMTInfo_t const &  PMTinfo, TriggerInfo_t const &  triggerInfo, PlotSandbox const &  plots  ) const

protectedvirtual

Fills the plots as fillEfficiencyPlots() and also as fillEventPlots() for the proper category: triggered or not triggered.

Definition at line 1211 of file TriggerEfficiencyPlotsBase.cxx.

        {
  
  fillEfficiencyPlots(eventInfo, triggerInfo, plots);
  
  // plotting split for triggering/not triggering events
  fillEventPlots(
    eventInfo,
    plots.demandSandbox(triggerInfo.fired()? "triggering": "nontriggering")
    );
  
  fillPMTplots(
    PMTinfo,
    plots.demandSandbox(triggerInfo.fired()? "triggering": "nontriggering")
    );
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::fillAllEfficiencyPlots()

void icarus::trigger::TriggerEfficiencyPlotsBase::fillEfficiencyPlots ( EventInfo_t const &  eventInfo, TriggerInfo_t const &  triggerInfo, PlotSandbox const &  plots  ) const

protectedvirtual

Fills the plots (initializeEfficiencyPerTriggerPlots()) with info from eventInfo and triggerInfo.

Definition at line 1150 of file TriggerEfficiencyPlotsBase.cxx.

        {
  
  using namespace std::string_literals;
  using OpeningInfo_t = icarus::trigger::details::TriggerInfo_t::OpeningInfo_t;

  auto const detTimings = icarus::ns::util::makeDetTimings();

  HistGetter const getTrigEff { plots };
  
  bool const fired = triggerInfo.fired();

  // efficiency plots
  if (useEDep()) {
    getTrigEff.Eff("EffVsEnergyInSpill"s).Fill
      (fired, double(eventInfo.DepositedEnergyInSpill()));
    getTrigEff.Eff("EffVsEnergyInPreSpill"s).Fill
      (fired, double(eventInfo.DepositedEnergyInPreSpill()));
    getTrigEff.Eff("EffVsEnergyInSpillActive"s).Fill
      (fired, double(eventInfo.DepositedEnergyInSpillInActiveVolume()));
    getTrigEff.Eff("EffVsEnergyInPreSpillActive"s).Fill
      (fired, double(eventInfo.DepositedEnergyInPreSpillInActiveVolume()));
  } // if use energy deposits
  if (useGen()) {
    if (eventInfo.isNeutrino()) {
      getTrigEff.Eff("EffVsNeutrinoEnergy"s).Fill
        (fired, double(eventInfo.NeutrinoEnergy()));
      getTrigEff.Eff("EffVsLeptonEnergy"s).Fill
        (fired, double(eventInfo.LeptonEnergy()));
    }
  } // if use generated information
  
  if (fired) {
    detinfo::timescales::electronics_time const beamGateTime
      = detTimings.BeamGateTime();
    
    getTrigEff.Hist("TriggerTick"s).Fill(triggerInfo.atTick().value());
    
    // converts the tick in the argument into electronics time:
    auto openingTime = [&detTimings](OpeningInfo_t const& info)
      { return detTimings.toElectronicsTime(info.tick); };

    getTrigEff.Hist("TriggerTime"s).Fill
      ((openingTime(triggerInfo.main()) - beamGateTime).value());

    std::vector<OpeningInfo_t> const& allTriggerOpenings = triggerInfo.all();

    for (OpeningInfo_t const& opening : allTriggerOpenings) {
      getTrigEff.Hist("OpeningTimes"s).Fill
        ((openingTime(opening) - beamGateTime).value());
    } // for all trigger openings
    
  } // if fired
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::fillEfficiencyPlots()

void icarus::trigger::TriggerEfficiencyPlotsBase::fillEventPlots ( EventInfo_t const &  eventInfo, PlotSandbox const &  plots  ) const

protectedvirtual

Fills the plots (initializeEventPlots()) with info from eventInfo.

Definition at line 1097 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  using namespace std::string_literals;
  
  HistGetter const getTrig { plots };
  
  if (useEDep()) {
    assert(eventInfo.hasDepEnergy());
    getTrig.Hist("EnergyInSpill"s).Fill(double(eventInfo.DepositedEnergyInSpill()));
    getTrig.Hist("EnergyInSpillActive"s).Fill(double(eventInfo.DepositedEnergyInSpillInActiveVolume()));
    getTrig.Hist("EnergyInPreSpill"s)
      .Fill(double(eventInfo.DepositedEnergyInPreSpill()));
    getTrig.Hist("EnergyInPreSpillActive"s)
      .Fill(double(eventInfo.DepositedEnergyInPreSpillInActiveVolume()));
    getTrig.Hist2D("EnergyInPreSpillVsSpillActive"s).Fill(
      double(eventInfo.DepositedEnergyInSpillInActiveVolume()),
      double(eventInfo.DepositedEnergyInPreSpillInActiveVolume())
      );
  }
  if (useGen()) {
    if (eventInfo.isNeutrino()) {
      assert(eventInfo.hasGenerated());
      getTrig.Hist("NeutrinoEnergy"s).Fill(double(eventInfo.NeutrinoEnergy()));
      getTrig.Hist("InteractionType"s).Fill(eventInfo.InteractionType());
      getTrig.Hist("LeptonEnergy"s).Fill(double(eventInfo.LeptonEnergy()));
      getTrig.Hist("InteractionTypeNeutrinoEnergy"s).Fill(double(eventInfo.InteractionType()), double(eventInfo.NeutrinoEnergy()));
    } // if neutrino event
    TH2& vertexHist = getTrig.Hist2D("InteractionVertexYZ"s);
    for (auto const& point: eventInfo.Vertices())
      vertexHist.Fill(point.Z(), point.Y());
  } // if use generated information
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::fillEventPlots()

void icarus::trigger::TriggerEfficiencyPlotsBase::fillPMTplots ( PMTInfo_t const &  PMTinfo, PlotSandbox const &  plots  ) const

protectedvirtual

Fill the plots (initializePMTplots()) with info from PMTinfo.

Definition at line 1135 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  using namespace std::string_literals;
  
  HistGetter const getTrig { plots };
  
  auto& activePMThist = getTrig.Hist("ActivePMT"s);
  for (raw::Channel_t const channel: PMTinfo.activeChannels())
    activePMThist.Fill(channel);
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::fillPMTplots()

geo::GeometryCore const& icarus::trigger::TriggerEfficiencyPlotsBase::geometry ( ) const

inlineprotected

Returns the detector geometry service provider.

Definition at line 1141 of file TriggerEfficiencyPlotsBase.h.

{ return fGeom; }

void icarus::trigger::TriggerEfficiencyPlotsBase::initializeEfficiencyPerTriggerPlots ( PlotSandbox &  plots ) const

protectedvirtual

Initializes set of plots per complete trigger definition into plots.

Definition at line 826 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  auto const [ detTimings, beamGate, preSpillWindow ] = makeGatePack();

  detinfo::timescales::optical_time_ticks const triggerResolutionTicks
    { detTimings.toOpticalTicks(fTriggerTimeResolution) };
  
  auto const PreSpillDuration = preSpillWindow.asSimulationRange().duration();
  
  //
  // Triggering efficiency vs. something else
  //
  if (useEDep()) {
    plots.make<TEfficiency>(
      "EffVsEnergyInSpill",
      "Efficiency of triggering vs. energy deposited in spill"
        ";energy deposited in spill  [ GeV ]"
        ";trigger efficiency  [ / 50 MeV ]",
      120, 0.0, 6.0 // 6 GeV should be enough for a MIP crossing 20 m of detector
      );
    
    plots.make<TEfficiency>(
      "EffVsEnergyInSpillActive",
      "Efficiency of triggering vs. energy deposited in active volume"
        ";energy deposited in active volume in spill  [ GeV ]"
        ";trigger efficiency  [ / 50 MeV ]",
      120, 0.0, 6.0 // 6 GeV should be enough for a MIP crossing 20 m of detector
      );
    
    plots.make<TEfficiency>(
      "EffVsEnergyInPreSpill",
      (
        "Efficiency of triggering vs. energy deposited in pre-spill ("
        + to_string(PreSpillDuration) + ")"
        ";energy deposited in pre-spill  [ GeV ]"
        ";trigger efficiency  [ / 100 MeV ]"
      ).c_str(),
      120, 0.0, 12.0
      );
    
    plots.make<TEfficiency>(
      "EffVsEnergyInPreSpillActive",
      (
        "Efficiency of triggering vs. energy deposited in active volume"
          " (pre-spill: " + to_string(PreSpillDuration) + ")"
          ";energy deposited in active volume in pre-spill  [ GeV ]"
          ";trigger efficiency  [ / 100 MeV ]"
      ).c_str(),
      120, 0.0, 12.0 // 6 GeV should be enough for a MIP crossing 20 m of detector
      );
  } // if plots with deposited energy
  
  if (useGen()) {
    plots.make<TEfficiency>(
      "EffVsNeutrinoEnergy",
      "Efficiency of triggering vs. neutrino energy"
        ";neutrino true energy  [ GeV ]"
        ";trigger efficiency  [ / 50 MeV ]",
      120, 0.0, 6.0 // 6 GeV is not that much for NuMI, but we should be ok
      );
    
    plots.make<TEfficiency>(
      "EffVsLeptonEnergy",
      "Efficiency of triggering vs. outgoing lepton energy"
        ";final state lepton true energy  [ GeV ]"
        ";trigger efficiency  [ / 50 MeV ]",
      120, 0.0, 6.0
      );
  } // if plots with generated info
  
  auto const& beamGateOpt = beamGate.asOptTickRange();
  plots.make<TH1F>(
    "TriggerTick",
    "Trigger time tick"
      ";optical time tick [ /" + util::to_string(triggerResolutionTicks) + " ]",
    beamGateOpt.duration() / triggerResolutionTicks,
    beamGateOpt.start().value(), beamGateOpt.end().value()
    );

  // plots will be relative to the beam gate:
  constexpr util::quantities::intervals::microseconds beamPlotPadding { 4_us };
  icarus::ns::util::BinningSpecs const beamGateBinning = alignBinningTo(
    icarus::ns::util::BinningSpecs{
      (
        std::min(
          preSpillWindow.asElectronicsTimeRange().start(),
          beamGate.asElectronicsTimeRange().start()
        )
        - beamGate.asElectronicsTimeRange().start()
        - beamPlotPadding
      ).value(),
      (std::max(
        preSpillWindow.asElectronicsTimeRange().end()
          - beamGate.asElectronicsTimeRange().start(),
        beamGate.duration()
        ) + beamPlotPadding).value(),
      fTriggerTimeResolution.value()
      },
      0.0
    );
  
  plots.make<TH1F>(
    "OpeningTimes",
    "Times at which trigger logic was satisfied"
      ";trigger time (relative to beam gate opening)  [ us ]"
      ";opened trigger gates",
    beamGateBinning.nBins(), beamGateBinning.lower(), beamGateBinning.upper()
    );
  
  plots.make<TH1F>(
    "TriggerTime",
    "Time of the trigger"
      ";trigger time (relative to beam gate opening)  [ us ]"
      ";opened trigger gates",
    beamGateBinning.nBins(), beamGateBinning.lower(), beamGateBinning.upper()
    );

  //
  // plots independent of the trigger primitive requirements
  //

} // icarus::trigger::TriggerEfficiencyPlotsBase::initializeEfficiencyPerTriggerPlots()

void icarus::trigger::TriggerEfficiencyPlotsBase::initializeEventPlots ( PlotSandbox &  plots ) const

protectedvirtual

Initializes a single, trigger-independent plot set into plots.

Definition at line 953 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  auto const [ detTimings, beamGate, preSpillWindow ] = makeGatePack();
  
  auto const BeamGateDuration = beamGate.asSimulationRange().duration();
  auto const PreSpillDuration = preSpillWindow.asSimulationRange().duration();
  
  //
  // Selection-related plots
  //
  if (useGen()) {
    plots.make<TH1F>(
      "NeutrinoEnergy",
      "True Neutrino Energy"
        ";neutrino energy [GeV]"
        ";events",
      120, 0.0, 6.0 // GeV
    );
  }
  
  if (useEDep()) {
    plots.make<TH1F>(
      "EnergyInSpill",
      "Energy deposited during the beam gate opening"
        ";energy deposited in spill [ GeV ]"
        ";events  [ / 50 MeV ]",
      120, 0.0, 6.0 // 6 GeV should be enough for a MIP crossing 20 m of detector
      );
    plots.make<TH1F>(
      "EnergyInPreSpill",
      (
        "Energy deposited during the pre-spill window ("
          + to_string(PreSpillDuration) + ")"
        ";energy deposited in pre-spill [ GeV ]"
        ";events  [ / 100 MeV ]"
      ).c_str(),
      120, 0.0, 12.0
      );
    plots.make<TH1F>(
      "EnergyInSpillActive",
      "Energy deposited during the beam gate opening in active volume"
        ";energy deposited in active volume in spill [ GeV ]"
        ";events  [ / 50 MeV ]",
      120, 0.0, 6.0 // 6 GeV should be enough for a MIP crossing 20 m of detector
      );
    plots.make<TH1F>(
      "EnergyInPreSpillActive",
      (
        "Energy deposited in active volume during the pre-spill window ("
          + to_string(PreSpillDuration) + ")"
        ";energy deposited in active volume in pre-spill [ GeV ]"
        ";events  [ / 100 MeV ]"
      ).c_str(),
      120, 0.0, 12.0
      );
    plots.make<TH2F>(
      "EnergyInPreSpillVsSpillActive",
      (
        "Energy deposited in active volume" 
        ";energy in spill window (" + to_string(BeamGateDuration) + ")  [ GeV ]"
        ";energy in pre-spill window (" + to_string(PreSpillDuration)
          + ")  [ GeV ]"
      ).c_str(),
      120, 0.0, 6.0, 120, 0.0, 12.0
      );
  } // if use energy deposition
  
  if (useGen()) {
    plots.make<TH1I>(
      "InteractionType",
      "Interaction type"
        ";Interaction Type"
        ";events",
      200, 999.5, 1199.5
      );
    plots.make<TH1F>(
      "LeptonEnergy",
      "Energy of outgoing lepton"
        ";deposited energy  [ GeV ]"
        ";events  [ / 50 MeV ]",
      120, 0.0, 6.0
      );
    plots.make<TH2F>(
      "InteractionVertexYZ",
      "Vertex of triggered interaction"
        ";beam direction (z)  [ / 20 cm ]"
        ";vertical direction (y)  [ / 5 cm ]",
      120, -1200., +1200.,
      100,  -250.,  +250.
      );

    plots.make<TH2F>(
      "InteractionTypeNeutrinoEnergy",
      "Interaction Type vs Neutrino Energy"
      ";InteractionType"
      ";Neutrino Energy",
      200,999.5,1199.5,
      120, 0.0, 6.0
      );

  } // if generated information
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::initializeEventPlots()

void icarus::trigger::TriggerEfficiencyPlotsBase::initializePlots ( PlotCategories_t  categories, std::vector< SettingsInfo_t > const &  settings  )

protectedvirtual

Initializes all the plot sets, one per PMT threshold.

Definition at line 703 of file TriggerEfficiencyPlotsBase.cxx.

{
  using namespace std::string_literals;
  
  auto const beamGate = icarus::trigger::makeBeamGateStruct
    (icarus::ns::util::makeDetTimings(), fBeamGateDuration, fBeamGateStart);

  fBeamGateChangeCheck(beamGate);
  
  if (fOnlyPlotCategories.empty()) fPlotCategories = std::move(categories);
  else {
    auto const plotThisCategory = [this](std::string const& name)
      {
        return std::binary_search
          (fOnlyPlotCategories.begin(), fOnlyPlotCategories.end(), name);
      };
    
    fPlotCategories.clear();
    for (auto&& plotCategory: categories) {
      if (!plotThisCategory(plotCategory.name())) continue;
      fPlotCategories.push_back(std::move(plotCategory));
    } // for
  }
  
  
  {
    mf::LogTrace(fLogCategory)
      << "Beam gate:"
      << "\n - electronics time: " << beamGate.asGate()
      << "\n - simulation time: " << beamGate.asSimulationRange()
      << "\n - optical ticks: " << beamGate.asOptTickRange()
      ;
    
    mf::LogInfo log(fLogCategory);
    log << "\nConfigured " << fADCthresholds.size() << " thresholds (ADC):";
    for (auto const& [ thresholdTag, dataTag ]: fADCthresholds)
      log << "\n * " << thresholdTag << " (from '" << dataTag.encode() << "')";
    log << "\nBeam gate for plots is " << beamGate.asSimulationRange();
    
    log << "\nConfigured " << fPlotCategories.size() << " plot categories"
      << (fPlotCategories.empty()? '.': ':');
    for (auto const& plotCategory: fPlotCategories) {
      log << "\n ['" << plotCategory.name() << "'] "
        << plotCategory.description();
    } // for
    
  } // local block
  
  
  for (std::string const& thresholdTag: util::get_elements<0U>(fADCthresholds))
  {
    // create a plot sandbox inside `fOutputDir` with a name/prefix `Thr###`
    icarus::trigger::PlotSandbox thrPlots
      { fOutputDir, "Thr"s + thresholdTag, "(thr: "s + thresholdTag + ")"s };
    
    // create a subbox for each plot category
    for (PlotCategory const& category: fPlotCategories) {
      PlotSandbox& plots = thrPlots.addSubSandbox(
        category.name(),
        category.description()
        );
      
      initializePlotSet(plots, settings);
    } // for plot category
    fThresholdPlots.push_back(std::move(thrPlots));
  } // for thresholds
  
  mf::LogTrace log(fLogCategory);
  log << "Created " << fThresholdPlots.size() << " plot boxes:\n";
  for (auto const& box: fThresholdPlots) {
    box.dump(log, "  ");
  } // for
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::initializePlots()

void icarus::trigger::TriggerEfficiencyPlotsBase::initializePlots ( std::vector< SettingsInfo_t > const &  settings )

inlineprotected

Initializes sets of default plots, one per PMT threshold.

Definition at line 1255 of file TriggerEfficiencyPlotsBase.h.

    { initializePlots(DefaultPlotCategories, settings); }

void icarus::trigger::TriggerEfficiencyPlotsBase::initializePlotSet ( PlotSandbox &  plots, std::vector< SettingsInfo_t > const &  settings  ) const

protectedvirtual

Initializes full set of plots for (ADC threshold + category) into plots.

Reimplemented in icarus::trigger::SlidingWindowTriggerEfficiencyPlots, and icarus::trigger::MajorityTriggerEfficiencyPlots.

Definition at line 781 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  //
  // Selection-related plots
  //
  initializeEventPlots(plots);
  
  initializePMTplots(plots);
  
  //
  // Plots per trigger setting, split in triggering and not triggering events;
  // the plot set is the same as the "global" one.
  //
  using SS_t = std::pair<std::string, std::string>;
  std::array<SS_t, 2U> const classes {
    SS_t{ "triggering", "triggering events" },
    SS_t{ "nontriggering", "non-triggering events" }
    };
  for (auto const& settingsDesc: settings) {
    
    // this defines a specific trigger, with its thresholds and settings
    PlotSandbox& reqBox
      = plots.addSubSandbox(settingsDesc.tag, settingsDesc.description);
    
    initializeEfficiencyPerTriggerPlots(reqBox);
    
    for (auto const& [ name, desc ]: classes) {
      
      PlotSandbox& box = reqBox.addSubSandbox(name, desc);
      
      initializeEventPlots(box);
      
      initializePMTplots(box);
      
    } // for triggering requirement
  } // for triggering classes
  
 
} // icarus::trigger::TriggerEfficiencyPlotsBase::initializePlotSet()

void icarus::trigger::TriggerEfficiencyPlotsBase::initializePMTplots ( PlotSandbox &  plots ) const

protectedvirtual

Initializes a single, trigger-independent, threshold-dependent plot set into plots.

Definition at line 1061 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  unsigned int const nOpChannels = fGeom.NOpChannels();
  
  //
  // plots independent of the trigger primitive requirements
  //
  plots.make<TH1I>(
    "ActivePMT",
    "PMT channels contributing to the trigger"
    ";channel with opened trigger gate"
    ";events",
    nOpChannels, // large number, zoom in presentations!
    0.0, static_cast<double>(nOpChannels)
    );
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::initializePMTplots()

std::string const& icarus::trigger::TriggerEfficiencyPlotsBase::logCategory ( ) const

inlineprotected

Returns the name of the log category.

Definition at line 1117 of file TriggerEfficiencyPlotsBase.h.

{ return fLogCategory; }

auto icarus::trigger::TriggerEfficiencyPlotsBase::makeChannelCryostatMap ( geo::GeometryCore const &  geom )

staticprivate

Fills and returns a map of cryostat ID for each optical detector channel.

Definition at line 1456 of file TriggerEfficiencyPlotsBase.cxx.

{
  
  auto const nOpChannels = geom.NOpChannels();
  
  std::vector<geo::CryostatID> channelCryostatMap(nOpChannels);
  
  for (auto const opChannel: util::counter(nOpChannels)) {
    if (!geom.IsValidOpChannel(opChannel)) continue;
    channelCryostatMap.at(opChannel)
      = geom.OpDetGeoFromOpChannel(opChannel).ID();
  } // for all channels
  
  return channelCryostatMap;
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::makeChannelCryostatMap()

icarus::trigger::details::EventInfoExtractor::EDepTags_t icarus::trigger::TriggerEfficiencyPlotsBase::makeEdepTag ( fhicl::Sequence< art::InputTag > const &  EnergyDepositTags, fhicl::OptionalAtom< art::InputTag > const &  EnergyDepositSummaryTag  )

staticprivate

Creates a EDepTags_t out of the module configuration.

Definition at line 1476 of file TriggerEfficiencyPlotsBase.cxx.

  {
  
  if (auto summaryTag = util::fhicl::getOptionalValue(EnergyDepositSummaryTag))
  {
    return {
      icarus::trigger::details::EventInfoExtractor::SimEnergyDepositSummaryInputTag
        { *summaryTag }
      };
  }
  else {
    
    return { EnergyDepositTags() };
    
  }
  
} // icarus::trigger::MakeTriggerSimulationTree::makeEdepTag()

auto icarus::trigger::TriggerEfficiencyPlotsBase::makeGatePack ( art::Event const *  event = nullptr ) const

protected

Creates a GatePack_t from the specified event.

Parameters

event

the event to extract beam for (if nullptr, uses job info)

Returns

a set of relevant gates

Use it C++17-fancy!

auto const [ detTimings, beamGate, preSpillWindow ] = makeGatePack(&event);

(the arguments are mapped to the GatePack_t members by position).

Definition at line 1277 of file TriggerEfficiencyPlotsBase.cxx.

{
  auto const detTimings = icarus::ns::util::makeDetTimings(event);
  return GatePack_t{
    detTimings,
    icarus::trigger::makeBeamGateStruct
      (detTimings, fBeamGateDuration, fBeamGateStart),
    icarus::trigger::makeBeamGateStruct
      (detTimings, fPreSpillStart, fPreSpillStart + fPreSpillWindow)
    };
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::makeGatePack()

icarus::trigger::ApplyBeamGateClass icarus::trigger::TriggerEfficiencyPlotsBase::makeMyBeamGate ( detinfo::DetectorClocksData const &  clockData ) const

inlineprotected

Shortcut to create an ApplyBeamGate with the current configuration.

Definition at line 1415 of file TriggerEfficiencyPlotsBase.h.

    {
      return makeApplyBeamGate
        (fBeamGateDuration, fBeamGateStart, clockData, fLogCategory); 
    }

icarus::trigger::ApplyBeamGateClass icarus::trigger::TriggerEfficiencyPlotsBase::makeMyBeamGate ( art::Event const *  event = nullptr ) const

inlineprotected

Definition at line 1421 of file TriggerEfficiencyPlotsBase.h.

    { return makeMyBeamGate(icarus::ns::util::makeDetClockData(event)); }

icarus::trigger::ApplyBeamGateClass icarus::trigger::TriggerEfficiencyPlotsBase::makeMyBeamGate ( art::Event const &  event ) const

inlineprotected

Definition at line 1424 of file TriggerEfficiencyPlotsBase.h.

{ return makeMyBeamGate(&event); }

std::size_t icarus::trigger::TriggerEfficiencyPlotsBase::nADCthresholds ( ) const

inlineprotected

Returns the number of configured PMT thresholds.

Definition at line 1129 of file TriggerEfficiencyPlotsBase.h.

{ return fADCthresholds.size(); }

geo::TPCGeo const* icarus::trigger::TriggerEfficiencyPlotsBase::pointInActiveTPC ( geo::Point_t const &  point ) const

private

Returns in which TPC point is within the active volume of; nullptr if none.

geo::TPCGeo const* icarus::trigger::TriggerEfficiencyPlotsBase::pointInTPC ( geo::Point_t const &  point ) const

private

Returns the TPC point is within, nullptr if none.

void icarus::trigger::TriggerEfficiencyPlotsBase::printSummary ( ) const

protected

Prints end-of-job summaries.

Definition at line 691 of file TriggerEfficiencyPlotsBase.cxx.

                                                                 {
  
  mf::LogInfo log(fLogCategory);
  log << nPlottedEvents << "/" << nEvents << " events plotted.";
  
  log << "\n" << fPassCounters;
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::printSummary()

void icarus::trigger::TriggerEfficiencyPlotsBase::process ( art::Event const &  event )

protected

Fills the plots. Also extracts the information to fill them with.

Definition at line 584 of file TriggerEfficiencyPlotsBase.cxx.

{

  /*
   * 1. find out the features of the event and the categories it belongs to
   * 2. for each threshold:
   *   1. read the trigger primitives
   *   2. pick the plots to be filled
   *   3. combine the trigger primitives, apply the beam gate,
   *      generate the trigger response, add the response to all the plots
   *      (delegated)
   *
   */
  
  ++nEvents;
  
  //
  // 1. find out the features of the event and the categories it belongs to
  //
  
  auto const [ detTimings, beamGate, preSpillWindow ] = makeGatePack(&event);
  
  if (auto oldGate = fBeamGateChangeCheck(beamGate); oldGate) {
    mf::LogDebug(fLogCategory)
      << "Beam gate has changed from " << oldGate->asOptTickRange()
      << " to " << beamGate.asOptTickRange() << " (optical tick)!";
  }
  
  EventInfo_t const eventInfo = fEventInfoExtractorMaker
    (beamGate.asSimulationRange(), preSpillWindow.asSimulationRange())(event);

  
  bool const bPlot = shouldPlotEvent(eventInfo);
  if (bPlot) ++nPlottedEvents;
  
  if (fIDTree) fIDTree->assignID(event.id());
  if (fPlotTree) fPlotTree->assign(bPlot);
  if (fEventTree) fEventTree->assignEvent(eventInfo);
  
  std::vector<std::string> selectedPlotCategories
    = selectPlotCategories(eventInfo, fPlotCategories);
  {
    mf::LogTrace log(fLogCategory);
    log
      << "Event " << event.id() << " falls in " << selectedPlotCategories.size()
      << " categories:"
      ;
    for (std::string const& name: selectedPlotCategories)
      log << " \"" << name << "\"";
    // print the information on the event
  } // local block
  if (!fLogEventDetails.empty()) {
    mf::LogTrace(fLogEventDetails)
      << "Event " << event.id() << ": " << eventInfo;
  }

  //
  // 2. for each PMT threshold:
  //
  auto const clockData
   = art::ServiceHandle<detinfo::DetectorClocksService const>()->DataFor(event);
  for (auto&& [ iThr, thrPair, thrPlots ]
    : util::enumerate(fADCthresholds, fThresholdPlots)
  ) {

    auto const& [ thresholdTag, dataTag ] = thrPair;

    //
    // 2.1. read the trigger primitives
    //
    
    TriggerGatesPerCryostat_t const& cryoGates
      = splitByCryostat(readTriggerGates(event, dataTag));
    
    //
    // 2.2. pick the plots to be filled
    //
    PlotSandboxRefs_t selectedPlots;
    
    if (bPlot) {
      for (std::string const& name: selectedPlotCategories)
        selectedPlots.emplace_back(*(thrPlots.findSandbox(name)));
    }
    
    //
    // 2.3. combine the trigger primitives, apply the beam gate,
    //      generate the trigger response, add the response to all the plots
    //
    simulateAndPlot(
      iThr, // settings index
      cryoGates,
      eventInfo,
      clockData,
      selectedPlots
      );

  } // for thresholds

  //
  // store information in output tree if any
  //
  if (fIDTree) fIDTree->tree().Fill();

} // icarus::trigger::TriggerEfficiencyPlotsBase::process()

auto icarus::trigger::TriggerEfficiencyPlotsBase::readTriggerGates ( art::Event const &  event, art::InputTag const &  dataTag  ) const

private

Reads a set of input gates from the event

Returns

trigger gates, converted into InputTriggerGate_t

Definition at line 1308 of file TriggerEfficiencyPlotsBase.cxx.

{

  using icarus::trigger::OpticalTriggerGateData_t; // for convenience

  // currently the associations are a waste of time memory...
  auto const& gates
    = event.getProduct<std::vector<OpticalTriggerGateData_t>>(dataTag);
  auto const& gateToWaveforms = event.getProduct
      <art::Assns<OpticalTriggerGateData_t, sbn::OpDetWaveformMeta>>(dataTag);
  
  try {
    return icarus::trigger::FillTriggerGates(gates, gateToWaveforms);
  }
  catch (cet::exception const& e) {
    throw cet::exception("TriggerEfficiencyPlots", "", e)
      << "Error encountered while reading data products from '"
      << dataTag.encode() << "'\n";
  }

} // icarus::trigger::TriggerEfficiencyPlotsBase::readTriggerGates()

void icarus::trigger::TriggerEfficiencyPlotsBase::registerTriggerResult ( std::size_t  threshold, std::size_t  pattern, bool  fired  )

protected

Registers the outcome of the specified trigger.

Definition at line 1265 of file TriggerEfficiencyPlotsBase.cxx.

  { fPassCounters(threshold, pattern).add(fired); }

void icarus::trigger::TriggerEfficiencyPlotsBase::registerTriggerResult ( std::size_t  threshold, std::size_t  pattern, TriggerInfo_t const &  triggerInfo  )

protected

Definition at line 1271 of file TriggerEfficiencyPlotsBase.cxx.

  { registerTriggerResult(threshold, pattern, triggerInfo.fired()); }

std::vector< std::string > icarus::trigger::TriggerEfficiencyPlotsBase::selectPlotCategories ( EventInfo_t const &  info, PlotCategories_t const &  categories  ) const

private

Returns the names of the plot categories event qualifies for.

Definition at line 1294 of file TriggerEfficiencyPlotsBase.cxx.

{
  std::vector<std::string> selected;
  
  for (auto const& category: categories)
    if (category(info)) selected.push_back(category);
  
  return selected;
  
} // icarus::trigger::TriggerEfficiencyPlotsBase::selectPlotCategories()

bool icarus::trigger::TriggerEfficiencyPlotsBase::shouldPlotEvent ( EventInfo_t const &  eventInfo ) const

protectedvirtual

Returns whether an event with the specified information should be included in the plots at all (it's a filter).

Definition at line 1083 of file TriggerEfficiencyPlotsBase.cxx.

{
  if (fPlotOnlyActiveVolume
    && eventInfo.hasVertex() && !eventInfo.isInActiveVolume())
  {
    return false;
  }
  
  return true;
} // icarus::trigger::TriggerEfficiencyPlotsBase::shouldPlotEvent()

virtual void icarus::trigger::TriggerEfficiencyPlotsBase::simulateAndPlot ( std::size_t const  thresholdIndex, TriggerGatesPerCryostat_t const &  gates, EventInfo_t const &  eventInfo, detinfo::DetectorClocksData const &  clockData, PlotSandboxRefs_t const &  selectedPlots  )

protectedpure virtual

Simulates all triggers for a trigger setting and plots the results.

Parameters

thresholdIndex	the index of the PMT threshold of input primitives
gates	the trigger primitives used to simulate the trigger response
eventInfo	general information about the event being simulated
selectedPlots	list of boxes containing plots to be filled

This pure virtual function is the core of the customization of this class. The simulateAndPlot() method is expected to:

1. combine the trigger primitives
2. apply the beam gate
3. generate the trigger response
4. fill all plots

for each trigger setting. Note that this helper class has no knowledge of those settings: how many they are, what they mean, which are their parameters. It is simulateAndPlot() task to properly process all of them at once, i.e. within a single call.

Big deal! The second and fourth step (application of beam gate and plots filling) have some helpers in this same class:

• ApplyBeamGateClass::applyToAll() can easily apply the beam gate at the right time (the right time is chosen by the implementation of simulateAndPlot()); an ApplyBeamGateClass object is obtained with makeMyBeamGate();
• filling of standard plots is performed with fillAllEfficiencyPlots(), fillEfficiencyPlots() and fillEventPlots(), which can be used as such or be customized for more plots.

Combination of primitive can be helped with icarus::trigger::TriggerGateData

All plots must have already been initialized via initializePlots() and its helpers.

The method is required to perform the simulation of the trigger primitives specified in input. These primitives are provided in gates as many collections, one per cryostat. While this interface splits the primitives by cryostat, the trigger simulation gets to choose how to handle that information, e.g. performing an independent simulation per cryostat and then combining them all, or just merging back the two collections and treating the two cryostats as a single entity.

The input trigger primitives are extracted from PMT waveforms with a certain PMT threshold, which is documented by its index thresholdIndex; the threshold value can be obtained from ADCthreshold(thresholdIndex), and in the future more information may become available as well.

Plots will need information from the event being simulated: that information is precooked, extracted from the event and stored in eventInfo. If more information is needed, EventInfo_t needs to be updated in this helper, as no way is provided to perform that customization in the derived class.

It is expected that all PMT thresholds settings identified by the specified index. This helper class does not know the definition of any trigger, and it is expected that settings are tracked by the derived classes and each is associated to an index.

Implemented in icarus::trigger::SlidingWindowTriggerEfficiencyPlots, and icarus::trigger::MajorityTriggerEfficiencyPlots.

auto icarus::trigger::TriggerEfficiencyPlotsBase::splitByCryostat ( TriggerGates_t &&  gates ) const

private

Moves the data in gates in a collection of gates by cryostat.

Definition at line 1334 of file TriggerEfficiencyPlotsBase.cxx.

{

  TriggerGatesPerCryostat_t gatesPerCryostat{ fGeom.Ncryostats() };
  
  for (auto& gate: gates) {
    gatesPerCryostat[fChannelCryostat.at(gate.channels().front()).Cryostat]
      .push_back(std::move(gate));
  } // for gates
  
  return gatesPerCryostat;

} // icarus::trigger::TriggerEfficiencyPlotsBase::splitByCryostat()

static std::string icarus::trigger::TriggerEfficiencyPlotsBase::thrAndCatName ( std::string const &  boxName, std::string const &  category  )

inlinestaticprivate

Definition at line 1553 of file TriggerEfficiencyPlotsBase.h.

    { return boxName + "_" + category; }

static std::string icarus::trigger::TriggerEfficiencyPlotsBase::thrAndCatName ( PlotSandbox const &  box, std::string const &  category  )

inlinestaticprivate

Definition at line 1556 of file TriggerEfficiencyPlotsBase.h.

    { return thrAndCatName(box.name(), category); }

nanoseconds icarus::trigger::TriggerEfficiencyPlotsBase::triggerTimeResolution ( ) const

inlineprotected

Returns the resolution of trigger timing clock [ns].

Definition at line 1144 of file TriggerEfficiencyPlotsBase.h.

{ return fTriggerTimeResolution; }

bool icarus::trigger::TriggerEfficiencyPlotsBase::useEDep ( ) const

inlineprotected

Returns whether we are using and filling energy deposition information.

Definition at line 1126 of file TriggerEfficiencyPlotsBase.h.

{ return fEventInfoExtractorMaker.hasEDep(); }

bool icarus::trigger::TriggerEfficiencyPlotsBase::useGen ( ) const

inlineprotected

Returns whether we are using and filling generator information.

Definition at line 1123 of file TriggerEfficiencyPlotsBase.h.

{ return fEventInfoExtractorMaker.hasGenerated(); }

Member Data Documentation

icarus::trigger::TriggerEfficiencyPlotsBase::PlotCategories_t const icarus::trigger::TriggerEfficiencyPlotsBase::DefaultPlotCategories

staticprotected

List of event categories.

category name	condition
All	any event

—Nu_mu | —Nu_e | NuCC | at least one generated charged current neutrino interaction —Nu_mu | —Nu_e | NuNC | at least one generated neutral current neutrino interaction —Nu_mu | —Nu_e |

Definition at line 1429 of file TriggerEfficiencyPlotsBase.h.

std::map<std::string, art::InputTag> icarus::trigger::TriggerEfficiencyPlotsBase::fADCthresholds

private

ADC threshold tags to read, and the input tag connected to their data.

Definition at line 1455 of file TriggerEfficiencyPlotsBase.h.

icarus::ns::util::ThreadSafeChangeMonitor<icarus::trigger::BeamGateStruct> icarus::trigger::TriggerEfficiencyPlotsBase::fBeamGateChangeCheck

private

Functor returning whether a gate has changed.

Definition at line 1517 of file TriggerEfficiencyPlotsBase.h.

microseconds icarus::trigger::TriggerEfficiencyPlotsBase::fBeamGateDuration

private

Duration of the gate during with global optical triggers are accepted.

Definition at line 1458 of file TriggerEfficiencyPlotsBase.h.

microseconds icarus::trigger::TriggerEfficiencyPlotsBase::fBeamGateStart

private

Start of the beam gate with respect to BeamGate().

Definition at line 1461 of file TriggerEfficiencyPlotsBase.h.

std::vector<geo::CryostatID> const icarus::trigger::TriggerEfficiencyPlotsBase::fChannelCryostat

private

ID of cryostat where each optical detector channel (vector index) is.

Definition at line 1501 of file TriggerEfficiencyPlotsBase.h.

art::InputTag icarus::trigger::TriggerEfficiencyPlotsBase::fDetectorParticleTag

private

Input simulated particles.

Definition at line 1452 of file TriggerEfficiencyPlotsBase.h.

details::EventInfoExtractorMaker const icarus::trigger::TriggerEfficiencyPlotsBase::fEventInfoExtractorMaker

private

Helper to extract information from the event.

Definition at line 1498 of file TriggerEfficiencyPlotsBase.h.

std::unique_ptr<details::EventInfoTree> icarus::trigger::TriggerEfficiencyPlotsBase::fEventTree

private

Handler of ROOT tree output.

Definition at line 1509 of file TriggerEfficiencyPlotsBase.h.

geo::GeometryCore const& icarus::trigger::TriggerEfficiencyPlotsBase::fGeom

private

Definition at line 1487 of file TriggerEfficiencyPlotsBase.h.

std::unique_ptr<details::EventIDTree> icarus::trigger::TriggerEfficiencyPlotsBase::fIDTree

private

Handler of ROOT tree output.

Definition at line 1507 of file TriggerEfficiencyPlotsBase.h.

std::string const icarus::trigger::TriggerEfficiencyPlotsBase::fLogCategory

private

Message facility stream category for output.

Definition at line 1475 of file TriggerEfficiencyPlotsBase.h.

std::string icarus::trigger::TriggerEfficiencyPlotsBase::fLogEventDetails

private

Steam where to print event info.

Definition at line 1477 of file TriggerEfficiencyPlotsBase.h.

std::vector<std::string> icarus::trigger::TriggerEfficiencyPlotsBase::fOnlyPlotCategories

private

Definition at line 1472 of file TriggerEfficiencyPlotsBase.h.

art::TFileDirectory icarus::trigger::TriggerEfficiencyPlotsBase::fOutputDir

private

ROOT directory where all the plots are written.

Definition at line 1490 of file TriggerEfficiencyPlotsBase.h.

details::TriggerPassCounters icarus::trigger::TriggerEfficiencyPlotsBase::fPassCounters

private

Counters for all triggers.

Definition at line 1519 of file TriggerEfficiencyPlotsBase.h.

PlotCategories_t icarus::trigger::TriggerEfficiencyPlotsBase::fPlotCategories

private

Plot categories (via initializePlots()).

Definition at line 1480 of file TriggerEfficiencyPlotsBase.h.

bool icarus::trigger::TriggerEfficiencyPlotsBase::fPlotOnlyActiveVolume

private

Plot only events in active volume.

Only apply these categories (empty applies all).

Definition at line 1469 of file TriggerEfficiencyPlotsBase.h.

std::unique_ptr<details::PlotInfoTree> icarus::trigger::TriggerEfficiencyPlotsBase::fPlotTree

private

Handler of ROOT tree output.

Definition at line 1508 of file TriggerEfficiencyPlotsBase.h.

microseconds icarus::trigger::TriggerEfficiencyPlotsBase::fPreSpillStart

private

Start of the pre-spill gate.

Definition at line 1465 of file TriggerEfficiencyPlotsBase.h.

microseconds icarus::trigger::TriggerEfficiencyPlotsBase::fPreSpillWindow

private

Duration of the pre-spill gate.

Definition at line 1463 of file TriggerEfficiencyPlotsBase.h.

std::vector<PlotSandbox> icarus::trigger::TriggerEfficiencyPlotsBase::fThresholdPlots

private

All plots, one set per ADC threshold.

Definition at line 1504 of file TriggerEfficiencyPlotsBase.h.

nanoseconds icarus::trigger::TriggerEfficiencyPlotsBase::fTriggerTimeResolution

private

Trigger resolution in time.

Definition at line 1467 of file TriggerEfficiencyPlotsBase.h.

std::atomic<unsigned int> icarus::trigger::TriggerEfficiencyPlotsBase::nEvents { 0U }

private

Count of seen events.

Definition at line 1512 of file TriggerEfficiencyPlotsBase.h.

std::atomic<unsigned int> icarus::trigger::TriggerEfficiencyPlotsBase::nPlottedEvents { 0U }

private

Count of plotted events.

Definition at line 1513 of file TriggerEfficiencyPlotsBase.h.

---

The documentation for this class was generated from the following files:

• TriggerEfficiencyPlotsBase.h
• TriggerEfficiencyPlotsBase.cxx