icarus::trigger::SlidingWindowTrigger Class Reference

Combines trigger channels (V1730 LVDS gates) into sliding windows. More...

Inheritance diagram for icarus::trigger::SlidingWindowTrigger:

Classes
struct	Config

Public Types
using	Parameters = art::EDProducer::Table< Config >

Public Member Functions
	SlidingWindowTrigger (Parameters const &config)
	SlidingWindowTrigger (SlidingWindowTrigger const &)=delete
	SlidingWindowTrigger (SlidingWindowTrigger &&)=delete
SlidingWindowTrigger &	operator= (SlidingWindowTrigger const &)=delete
SlidingWindowTrigger &	operator= (SlidingWindowTrigger &&)=delete
virtual void	produce (art::Event &event) override
	Fills the plots. Also extracts the information to fill them with. More...

Private Types
using	WindowDefs_t = icarus::trigger::TriggerWindowDefs_t
	Definition of all windows. More...
using	TriggerGateData_t = icarus::trigger::OpticalTriggerGate::GateData_t
using	TrackedTriggerGate_t = icarus::trigger::TrackedOpticalTriggerGate< sbn::OpDetWaveformMeta >
	Reconstituted trigger gate type internally used. More...

Private Member Functions
unsigned int	nDisabledWindows () const noexcept
	Returns the number of disabled windows. More...
void	produceThreshold (art::Event &event, icarus::trigger::OpDetWaveformMetaDataProductMap_t &waveformMap, std::string const &threshold, art::InputTag const &dataTag) const
	Performs the combination for data with a specified threshold. More...
std::vector < icarus::trigger::TrackedOpticalTriggerGate < sbn::OpDetWaveformMeta > >	ReadTriggerGates (art::Event const &event, art::InputTag const &dataTag, icarus::trigger::OpDetWaveformMetaDataProductMap_t &waveformMap) const
	Reads a set of input gates from the event and updates waveformMap. More...
WindowDefs_t	defineWindows () const
	Defines the channels falling in each window. More...

Static Private Member Functions
static std::vector< std::size_t >	makeEnabledWindowIndices (std::size_t nWindows, fhicl::OptionalSequence< std::size_t > const &enabled, fhicl::OptionalSequence< std::size_t > const &disabled)
	Returns a list of enabled window indices. More...
static void	UpdateWaveformMap (icarus::trigger::OpDetWaveformMetaDataProductMap_t &map, art::Assns< TriggerGateData_t, sbn::OpDetWaveformMeta > const &assns)
	Adds the waveforms in the specified association to the waveform map. More...

Private Attributes
std::map< std::string, art::InputTag >	fADCthresholds
	ADC thresholds to read, and the input tag connected to their data. More...
unsigned int const	fWindowSize
	Sliding window size in number of channels. More...
unsigned int const	fWindowStride
	Sliding window base offset. More...
WindowDefs_t const	fWindowChannels
	Channel content of each window. More...
std::vector< std::size_t > const	fEnabledWindows
	List of windows to be included. More...
bool	fProduceWaveformAssns
	Whether to produce gate/waveform associations. More...
std::string const	fLogCategory
	Message facility stream category for output. More...
icarus::trigger::SlidingWindowCombinerAlg const	fCombiner
	Combining algorithm. More...

Detailed Description

Combines trigger channels (V1730 LVDS gates) into sliding windows.

This module combines the input discriminated waveforms into a set of new multi-level discriminated gates according to the geometric criterion of a sliding window.

The combination is a sum of all the discriminated waveforms within the window. Different optical detector planes are treated independently and separately. It is expected that the input is from V1730 LVDS gates (see icarus::trigger::LVDSgates module) which combine (usually) two optical detector channels each.

Sliding window configuration

The size of the window is specified in terms on number of optical detector channels per window and of stride. The windows are allowed to overlap, but they have all the same number of channels. If the parameters yield an invalid configuration, the module will throw an exception.

The definition of a valid window configuration is quite restrictive. Optical detector channels are grouped by the TPC width coordinate (z) into "towers". In ICARUS, a tower is made of either two or three channels, depending on the position in z. A window can't split a tower, but rather has to include whole towers. In addition, the input discriminated waveforms may include information from multiple channels (that is the common case if the input is LVDS gates). A window can't cover only part of the channels of any input, but rather must extend wide enough so that all the channels in the included gates are covered. Channels may be exempted by marking them as "missing". Finally, all the channels which are not "missing" must be covered by at least one window.

For the sliding window configuration to be valid, all the windows starting with an offset multiple of the stride must be valid.

For the standard pairing of LVDS gates in ICARUS, this translates into the only allowed window sizes are by 10 and 15 channels or their multiples, with a stride also in multiples of 10 or 15 respectively. For example, the following configurations are all valid:

• 10 channels per window, with stride of 10 channels (9 windows per plane);
• 20 channels per window, with stride of 10 channels (8 windows per plane);
• 30 channels per window, with stride of 10 channels (7 windows per plane);
• 15 channels per window, with stride of 15 channels (6 windows per plane);
• 30 channels per window, with stride of 30 channels (3 windows per plane);
• 30 channels per window, with stride of 15 channels (5 windows per plane);
• 45 channels per window, with stride of 45 channels (2 windows per plane).

Input data products

• 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 waveform metadata (sbn::OpDetWaveformMeta). One set per threshold.

Requirements

The algorithms require that in each set all optical channels are covered.

Output data products

• std::vector<icarus::trigger::OpticalTriggerGateData_t> (instance name: same as the input gates): sets of gates combined according to the window configuration; one set per input threshold.
• art::Assns<icarus::trigger::OpticalTriggerGateData_t, sbn::OpDetWaveformMeta> (instance name: same as the input gates): associations between each produced gate and the metadata of optical waveforms providing the original data.
• art::Assns<icarus::trigger::OpticalTriggerGateData_t, raw::OpDetWaveform> (instance name: same as the input gates): associations between each produced gate and the optical waveforms providing the original data. It is produced only if ProduceWaveformAssns configuration parameter is true, and it relies on the assumption that there is an association available between each sbn::OpDetWaveformMeta and its raw::OpDetWaveform, produced by the same module (i.e. with the same input tag) as the one of the original sbn::OpDetWaveformMeta data product itself.

If window selection is requested (with EnableOnlyWindows or DisableWindows configuration parameters), only the selected windows will have an output entry. While each trigger data object comes with all the channels it covers, there is no explicit information of the index of the surviving windows.

Note

At the moment, associations between input and output gates is not produced. art::Assns would not support it, requiring distinct types for the associated objects.

Configuration parameters

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

• TriggerGatesTag (string, mandatory): name of the module instance which produced the discriminated waveforms; it must not include any instance name, as the instance names will be automatically added from Thresholds parameter.
• Thresholds (list of strings, 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 entry in this list. While it is common for this entry to be the actual threshold value in ADC (e.g. "400"), this is not required.
• WindowSize (integral, mandatory): the number of optical detector channels that every window must include. Note that this is not equivalent to the number of input objects from the TriggerGatesTag data products: for example, in the standard ICARUS configuration, a window spanning 15 channels is generated out of only 8 LVDS input gates.
• Stride (integral, default: as WindowSize): the base offset, in number of optical detector channels, where to start a new window. Windows are started at all multiples of Stride. For example, windows of 30 channels with Stride 15 will start after 0, 15, 30, 45 and 60 channels on each optical detector plane.
• EnableOnlyWindows (list of integers, default: omitted): if specified, only the windows with index in this list will be processed and output; mutually exclusive with DisableWindows.
• DisableWindows (list of integers, default: omitted): if specified, the windows with index in this list will be excluded from processing and from output; mutually exclusive with EnableOnlyWindows.
• MissingChannels (list of integers, default: empty): the channels whose ID is included in this list are expected and required not to be present in the input (i.e. no input gate should include them).
• ProduceWaveformAssns (flag, default: true): produce also associations between each gate and the raw::OpDetWaveform which contributed to it.
• LogCategory (string): name of the output stream category for console messages (managed by MessageFacility library).

Note: when using EnableOnlyWindows or DisableWindows it may be useful to check the output of the module (at construction) to verify that the selected indices match the intended windows.

Definition at line 213 of file SlidingWindowTrigger_module.cc.

Member Typedef Documentation

using icarus::trigger::SlidingWindowTrigger::Parameters = art::EDProducer::Table<Config>

Definition at line 280 of file SlidingWindowTrigger_module.cc.

using icarus::trigger::SlidingWindowTrigger::TrackedTriggerGate_t = icarus::trigger::TrackedOpticalTriggerGate<sbn::OpDetWaveformMeta>

private

Reconstituted trigger gate type internally used.

Definition at line 313 of file SlidingWindowTrigger_module.cc.

using icarus::trigger::SlidingWindowTrigger::TriggerGateData_t = icarus::trigger::OpticalTriggerGate::GateData_t

private

Definition at line 309 of file SlidingWindowTrigger_module.cc.

using icarus::trigger::SlidingWindowTrigger::WindowDefs_t = icarus::trigger::TriggerWindowDefs_t

private

Definition of all windows.

Definition at line 307 of file SlidingWindowTrigger_module.cc.

Constructor & Destructor Documentation

icarus::trigger::SlidingWindowTrigger::SlidingWindowTrigger ( Parameters const &  config )

explicit

Definition at line 403 of file SlidingWindowTrigger_module.cc.

  : art::EDProducer(config)
  // configuration
  , fWindowSize(config().WindowSize())
  , fWindowStride
    (util::fhicl::getOptionalValue(config().Stride).value_or(fWindowSize))
  , fWindowChannels(defineWindows())
  , fEnabledWindows(makeEnabledWindowIndices(
     fWindowChannels.size(),
     config().EnableOnlyWindows, config().DisableWindows
     ))
  , fProduceWaveformAssns(config().ProduceWaveformAssns())
  , fLogCategory(config().LogCategory())
    // demand full PMT coverage only if no window was disabled:
  , fCombiner(
      filter(fWindowChannels, fEnabledWindows),
      config().MissingChannels(),
      nDisabledWindows() == 0U
    )
{
  //
  // more complex parameter parsing
  //
  std::string const discrModuleLabel = config().TriggerGatesTag();
  for (std::string const& threshold: config().Thresholds())
    fADCthresholds[threshold] = art::InputTag{ discrModuleLabel, threshold };

  //
  // configuration report (short)
  //
  {
    mf::LogInfo log(fLogCategory);
    log <<   "Trigger configuration: " << fWindowChannels.size() << " windows";
    if (fEnabledWindows.size() < fWindowChannels.size())
      log << " (only " << fEnabledWindows.size() << " enabled)";
    log << ":";
    for (auto const& [ iWindow, window ]: util::enumerate(fWindowChannels)) {
      log << "\n #" << iWindow << ": "
        << icarus::trigger::dumpTriggerWindowChannels(window);
      if (std::find(fEnabledWindows.begin(), fEnabledWindows.end(), iWindow)
        == fEnabledWindows.end())
      {
        log << " (disabled)";
      }
    } // for
    
    log << "\nConfigured " << fADCthresholds.size() << " thresholds (ADC):";
    for (auto const& [ threshold, dataTag ]: fADCthresholds)
      log << "\n * " << threshold << " (from '" << dataTag.encode() << "')";
  } // local block


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

  //
  // input data declaration
  //
  for (art::InputTag const& inputDataTag: util::const_values(fADCthresholds)) {
    consumes<std::vector<OpticalTriggerGateData_t>>(inputDataTag);
    consumes<art::Assns<OpticalTriggerGateData_t, sbn::OpDetWaveformMeta>>
      (inputDataTag);
  } // for


  //
  // output data declaration
  //
  for (art::InputTag const& inputDataTag: util::const_values(fADCthresholds)) {
    produces<std::vector<OpticalTriggerGateData_t>>(inputDataTag.instance());
    produces<art::Assns<OpticalTriggerGateData_t, sbn::OpDetWaveformMeta>>
      (inputDataTag.instance());
    if (fProduceWaveformAssns) {
      produces<art::Assns<OpticalTriggerGateData_t, raw::OpDetWaveform>>
        (inputDataTag.instance());
    }
  } // for

  
} // icarus::trigger::SlidingWindowTrigger::SlidingWindowTrigger()

icarus::trigger::SlidingWindowTrigger::SlidingWindowTrigger ( SlidingWindowTrigger const &  )

delete

icarus::trigger::SlidingWindowTrigger::SlidingWindowTrigger ( SlidingWindowTrigger &&  )

delete

Member Function Documentation

auto icarus::trigger::SlidingWindowTrigger::defineWindows ( ) const

private

Defines the channels falling in each window.

Definition at line 499 of file SlidingWindowTrigger_module.cc.

{
  // delegated to `SlidingWindowDefinitionAlg`
  
  icarus::trigger::SlidingWindowDefinitionAlg const algo {
    *(lar::providerFrom<geo::Geometry>()),
    "SlidingWindowTrigger/SlidingWindowDefinitionAlg"
    };
  
  return algo.makeWindows(fWindowSize, fWindowStride);
  
} // icarus::trigger::SlidingWindowTrigger::defineWindows()

auto icarus::trigger::SlidingWindowTrigger::makeEnabledWindowIndices ( std::size_t  nWindows, fhicl::OptionalSequence< std::size_t > const &  enabled, fhicl::OptionalSequence< std::size_t > const &  disabled  )

staticprivate

Returns a list of enabled window indices.

Definition at line 588 of file SlidingWindowTrigger_module.cc.

                          {
  
  std::vector<std::size_t> selection; // indices of the enabled windows
  
  // add all enabled windows (or all if no enabled list is specified)
  if (!enabled(selection)) {
    selection.resize(nWindows);
    std::iota(selection.begin(), selection.end(), 0U);
  }
  
  // remove all disabled windows (if any)
  std::vector<std::size_t> removeWindows;
  disabled(removeWindows);
  auto const find = [&selection](std::size_t index)
    { return std::find(selection.begin(), selection.end(), index); };
  for (std::size_t const index: removeWindows) {
    if (auto const it = find(index); it != selection.end()) selection.erase(it);
  } // for
  
  return selection;
} // icarus::trigger::SlidingWindowTrigger::makeEnabledWindowIndices()

unsigned int icarus::trigger::SlidingWindowTrigger::nDisabledWindows ( ) const

inlineprivatenoexcept

Returns the number of disabled windows.

Definition at line 342 of file SlidingWindowTrigger_module.cc.

    { return fWindowChannels.size() - fEnabledWindows.size(); }

SlidingWindowTrigger& icarus::trigger::SlidingWindowTrigger::operator= ( SlidingWindowTrigger const &  )

delete

SlidingWindowTrigger& icarus::trigger::SlidingWindowTrigger::operator= ( SlidingWindowTrigger &&  )

delete

void icarus::trigger::SlidingWindowTrigger::produce ( art::Event &  event )

overridevirtual

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

Definition at line 485 of file SlidingWindowTrigger_module.cc.

                                                               {
  
  icarus::trigger::OpDetWaveformMetaDataProductMap_t waveformMap;

  for (auto const& [ thresholdStr, dataTag ]: fADCthresholds) {

    produceThreshold(event, waveformMap, thresholdStr, dataTag);
    
  } // for all thresholds
  
} // icarus::trigger::SlidingWindowTrigger::produce()

void icarus::trigger::SlidingWindowTrigger::produceThreshold ( art::Event &  event, icarus::trigger::OpDetWaveformMetaDataProductMap_t &  waveformMap, std::string const &  threshold, art::InputTag const &  dataTag  ) const

private

Performs the combination for data with a specified threshold.

Definition at line 515 of file SlidingWindowTrigger_module.cc.

        {
  
  mf::LogDebug(fLogCategory)
    << "Processing threshold " << threshold
    << " from '" << dataTag.encode() << "'"
    ;

  using icarus::trigger::OpticalTriggerGateData_t; // for convenience
  using TrackedTriggerGate_t
    = icarus::trigger::TrackedOpticalTriggerGate<sbn::OpDetWaveformMeta>;
  
  std::vector<TrackedTriggerGate_t> const& gates
    = ReadTriggerGates(event, dataTag, waveformMap);
  
  std::vector<TrackedTriggerGate_t> combinedGates = fCombiner.combine(gates);

  // transform the data; after this line, `gates` is not usable any more
  art::PtrMaker<OpticalTriggerGateData_t> const makeGatePtr
    (event, dataTag.instance());
  auto [ outputGates, outputAssns ]
    = icarus::trigger::transformIntoOpticalTriggerGate
    (std::move(combinedGates), makeGatePtr, waveformMap);

  {
    mf::LogTrace log { fLogCategory };
    log
      << "Threshold " << threshold << " ('" << dataTag.encode() << "'): "
      << gates.size() << " input channels, "
      << outputGates.size() << " output channels (+"
      << outputAssns.size() << " associations to waveforms) into '"
      << moduleDescription().moduleLabel() << ":" << dataTag.instance() << "'"
      ;
    for (auto const& [ iGate, gate ]: util::enumerate(outputGates)) {
      log << "\n [#" << iGate << "] " << compactdump(gate);
    } // for
  } // local scope

  if (fProduceWaveformAssns) {
    
    // produce one gate-waveform association for each gate-metadata one;
    // do it now while the gate/metadata association is still locally available
    icarus::trigger::OpDetWaveformMetaMatcher waveformMetaMatcher{ event };
    art::Assns<OpticalTriggerGateData_t, raw::OpDetWaveform> outputWaveAssns;
    for (auto const [ gatePtr, metaPtr ]: outputAssns)
      outputWaveAssns.addSingle(gatePtr, waveformMetaMatcher(metaPtr));
    
    event.put(
      std::make_unique<art::Assns<OpticalTriggerGateData_t, raw::OpDetWaveform>>
        (std::move(outputWaveAssns)),
      dataTag.instance()
      );
  } // if fProduceWaveformAssns
  
  event.put(
    std::make_unique<std::vector<OpticalTriggerGateData_t>>
      (std::move(outputGates)),
    dataTag.instance()
    );
  event.put(
    std::make_unique<art::Assns<OpticalTriggerGateData_t, sbn::OpDetWaveformMeta>>
      (std::move(outputAssns)),
    dataTag.instance()
    );

} // icarus::trigger::SlidingWindowTrigger::produceThreshold()

auto icarus::trigger::SlidingWindowTrigger::ReadTriggerGates ( art::Event const &  event, art::InputTag const &  dataTag, icarus::trigger::OpDetWaveformMetaDataProductMap_t &  waveformMap  ) const

private

Reads a set of input gates from the event and updates waveformMap.

Definition at line 628 of file SlidingWindowTrigger_module.cc.

                                           {
  using icarus::trigger::OpticalTriggerGateData_t;
  
  auto const& assns =
    event.getProduct<art::Assns<OpticalTriggerGateData_t, sbn::OpDetWaveformMeta>>
    (dataTag);
  
  UpdateWaveformMap(waveformMap, assns);
  
  return icarus::trigger::FillTriggerGates
    (event.getProduct<std::vector<OpticalTriggerGateData_t>>(dataTag), assns);
  
} // icarus::trigger::SlidingWindowTrigger::ReadTriggerGates()

void icarus::trigger::SlidingWindowTrigger::UpdateWaveformMap ( icarus::trigger::OpDetWaveformMetaDataProductMap_t &  map, art::Assns< TriggerGateData_t, sbn::OpDetWaveformMeta > const &  assns  )

staticprivate

Adds the waveforms in the specified association to the waveform map.

Definition at line 616 of file SlidingWindowTrigger_module.cc.

  {
  
  for (art::Ptr<sbn::OpDetWaveformMeta> const& wave: util::get_elements<1U>(assns))
    map.emplace(wave.get(), wave);
  
} // icarus::trigger::SlidingWindowTrigger::UpdateWaveformMap()

Member Data Documentation

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

private

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

Definition at line 318 of file SlidingWindowTrigger_module.cc.

icarus::trigger::SlidingWindowCombinerAlg const icarus::trigger::SlidingWindowTrigger::fCombiner

private

Combining algorithm.

Definition at line 338 of file SlidingWindowTrigger_module.cc.

std::vector<std::size_t> const icarus::trigger::SlidingWindowTrigger::fEnabledWindows

private

List of windows to be included.

Definition at line 327 of file SlidingWindowTrigger_module.cc.

std::string const icarus::trigger::SlidingWindowTrigger::fLogCategory

private

Message facility stream category for output.

Definition at line 333 of file SlidingWindowTrigger_module.cc.

bool icarus::trigger::SlidingWindowTrigger::fProduceWaveformAssns

private

Whether to produce gate/waveform associations.

Definition at line 330 of file SlidingWindowTrigger_module.cc.

WindowDefs_t const icarus::trigger::SlidingWindowTrigger::fWindowChannels

private

Channel content of each window.

Definition at line 324 of file SlidingWindowTrigger_module.cc.

unsigned int const icarus::trigger::SlidingWindowTrigger::fWindowSize

private

Sliding window size in number of channels.

Definition at line 320 of file SlidingWindowTrigger_module.cc.

unsigned int const icarus::trigger::SlidingWindowTrigger::fWindowStride

private

Sliding window base offset.

Definition at line 321 of file SlidingWindowTrigger_module.cc.

---

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

• SlidingWindowTrigger_module.cc