AssociationUtil.h

Go to the documentation of this file.

#ifndef ASSOCIATIONUTIL_H
#define ASSOCIATIONUTIL_H

// C/C++ standard libraries
#include <climits>
#include <memory>
#include <string>
#include <utility> // std::move(), std::pair<>
#include <vector>

// framework libraries
#include "art/Framework/Principal/Handle.h"
#include "art/Framework/Principal/fwd.h"
#include "art/Persistency/Common/PtrMaker.h"
#include "canvas/Persistency/Common/Assns.h"
#include "canvas/Persistency/Common/FindMany.h"
#include "canvas/Persistency/Common/FindManyP.h"
#include "canvas/Persistency/Common/FindOne.h"
#include "canvas/Persistency/Common/FindOneP.h"
#include "canvas/Persistency/Common/Ptr.h"
#include "canvas/Persistency/Common/PtrVector.h"
#include "messagefacility/MessageLogger/MessageLogger.h"

namespace util {

  // see https://cdcvs.fnal.gov/redmine/projects/art/wiki/Inter-Product_References
  // for information about using art::Assns

  // MARK CreateAssn_01
  template <class T, class U>
  bool CreateAssn(art::Event& evt,
                  std::vector<T> const& a,
                  art::Ptr<U> const& b,
                  art::Assns<U, T>& assn,
                  std::string a_instance,
                  size_t index = UINT_MAX);

  // MARK CreateAssn_02
  template <class T, class U>
  inline bool CreateAssn(art::Event& evt,
                         std::vector<T> const& a,
                         art::Ptr<U> const& b,
                         art::Assns<U, T>& assn,
                         size_t index = UINT_MAX)
  {
    return CreateAssn(evt, a, b, assn, std::string(), index);
  }

  // MARK CreateAssn_03
  template <class T, class U>
  bool CreateAssn(art::Event& evt,
                  art::Ptr<T> const& a,
                  art::Ptr<U> const& b,
                  art::Assns<U, T>& assn);

  // MARK CreateAssn_04
  template <class T, class U>
  bool CreateAssn(art::Event& evt,
                  std::vector<T> const& a,
                  art::PtrVector<U> const& b,
                  art::Assns<T, U>& assn,
                  size_t index = UINT_MAX);

  // method to create a 1 to many association, with the many being of type U
  // index is the location in the input std::vector<T> of the object you wish to
  // associate with the art::PtrVector<U>
  // MARK CreateAssn_05
  template <class T, class U>
  bool CreateAssn(art::Event& evt,
                  art::Ptr<T> const& a,
                  std::vector<art::Ptr<U>> const& b,
                  art::Assns<T, U>& assn);

  // MARK CreateAssn_06
  template <class T, class U>
  bool CreateAssn(art::Event& evt,
                  std::vector<T> const& a,
                  std::vector<art::Ptr<U>> const& b,
                  art::Assns<T, U>& assn,
                  size_t index = UINT_MAX);

  // MARK CreateAssn_07
  template <class T, class U>
  bool CreateAssn(art::Event& evt,
                  std::vector<T> const& a,
                  std::vector<U> const& b,
                  art::Assns<T, U>& assn,
                  size_t startU,
                  size_t endU,
                  size_t index = UINT_MAX);

  // MARK CreateAssn_07a
  template <class T, class U>
  bool CreateAssn(art::Event& evt,
                  std::vector<T> const& a,
                  std::vector<U> const& b,
                  art::Assns<T, U>& assn,
                  std::vector<size_t> const& indices,
                  size_t index = UINT_MAX);

  // MARK CreateAssn_08
  template <typename T, typename U, typename Iter>
  bool CreateAssn(art::Event& evt,
                  art::Assns<T, U>& assn,
                  size_t first_index,
                  Iter from_second_index,
                  Iter to_second_index);


  // MARK CreateAssnD_01
  // MARK CreateAssnD_01a
  template <typename T, typename U, typename D>
  bool CreateAssnD(art::Event& evt,
                   art::Assns<T, U, D>& assn,
                   size_t first_index,
                   size_t second_index,
                   typename art::Assns<T, U, D>::data_t&& data);
  // MARK CreateAssnD_01b
  template <typename T, typename U, typename D>
  bool CreateAssnD(art::Event& evt,
                   art::Assns<T, U, D>& assn,
                   size_t first_index,
                   size_t second_index,
                   typename art::Assns<T, U, D>::data_t const& data);

  // method to return all objects of type U that are not associated to
  // objects of type T. Label is the module label that would have produced
  // the associations and likely the objects of type T
  // this method assumes there is a one to many relationship between T and U
  // for example if you want to get all recob::Hits
  // that are not associated to recob::Clusters
  // std::vector<const recob::Hit*> hits = FindUNotAssociatedToU<recob::Cluster>(art::Handle<recob::Hit>, ...);
  template <class T, class U>
  std::vector<const U*> FindUNotAssociatedToT(art::Handle<U> b,
                                              art::Event const& evt,
                                              std::string const& label);

  // method to return all objects of type U that are not associated to
  // objects of type T. Label is the module label that would have produced
  // the associations and likely the objects of type T
  // this method assumes there is a one to many relationship between T and U
  // for example if you want to get all recob::Hits
  // that are not associated to recob::Clusters
  // std::vector< art::Ptr<recob::Hit> > hits = FindUNotAssociatedToTP<recob::Cluster>(art::Handle<recob::Hit>, ...);
  template <class T, class U>
  std::vector<art::Ptr<U>> FindUNotAssociatedToTP(art::Handle<U> b,
                                                  art::Event const& evt,
                                                  std::string const& label);

  // Methods make getting simple ART-independent association information.
  // --- GetAssociatedVectorOneI takes in a handle to an association, and a handle to a product on the event.
  //     The ouput is a vector of with the same number of entries as the handle to the product, containing an index
  //     to the location of one associated product in that product's collection.
  // --- GetAssociatedVectorOneP takes in a handle to an association, and a handle to a product on the event.
  //     The ouput is a vector of with the same number of entries as the handle to the product, containing a pointer
  //     to one associated product.
  // --- GetAssociatedVectorManyI takes in a handle to an association, and a handle to a product on the event.
  //     The ouput is a vector of with the same number of entries as the handle to the product, containing a vector
  //     of indices that give the locations of all associated products in those products' collection.
  // --- GetAssociatedVectorManyP takes in a handle to an association, and a handle to a product on the event.
  //     The ouput is a vector of with the same number of entries as the handle to the product, containing a vector
  //     of pointers to all associated products.

  template <class T, class U>
  std::vector<size_t> GetAssociatedVectorOneI(art::Handle<art::Assns<T, U>> h,
                                              art::Handle<std::vector<T>> index_p);
  template <class T, class U>
  std::vector<const U*> GetAssociatedVectorOneP(art::Handle<art::Assns<T, U>> h,
                                                art::Handle<std::vector<T>> index_p);

  template <class T, class U>
  std::vector<std::vector<size_t>> GetAssociatedVectorManyI(art::Handle<art::Assns<T, U>> h,
                                                            art::Handle<std::vector<T>> index_p);
  template <class T, class U>
  std::vector<std::vector<const U*>> GetAssociatedVectorManyP(art::Handle<art::Assns<T, U>> h,
                                                              art::Handle<std::vector<T>> index_p);

} // end namespace

//----------------------------------------------------------------------
// MARK CreateAssn_01
template <class T, class U>
bool util::CreateAssn(art::Event& evt,
                      std::vector<T> const& a,
                      art::Ptr<U> const& b,
                      art::Assns<U, T>& assn,
                      std::string a_instance,
                      size_t index /* = UINT_MAX */
)
{
  if (index == UINT_MAX) index = a.size() - 1;

  try {
    assn.addSingle(b, art::PtrMaker<T>{evt, a_instance}(index));
    return true;
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

} // util::CreateAssn() [01]

//----------------------------------------------------------------------
// MARK CreateAssn_03
template <class T, class U>
bool util::CreateAssn(art::Event&,
                      art::Ptr<T> const& a,
                      art::Ptr<U> const& b,
                      art::Assns<U, T>& assn)
{

  try {
    assn.addSingle(b, a);
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssn() [03]

//----------------------------------------------------------------------
// MARK CreateAssn_04
template <class T, class U>
bool util::CreateAssn(art::Event& evt,
                      std::vector<T> const& a,
                      art::PtrVector<U> const& b,
                      art::Assns<T, U>& assn,
                      size_t index /* = UINT_MAX */
)
{
  if (index == UINT_MAX) index = a.size() - 1;

  try {
    auto const aptr = art::PtrMaker<T>{evt}(index);
    for (art::Ptr<U> const& b_item : b)
      assn.addSingle(aptr, b_item);
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssn() [04]

//----------------------------------------------------------------------
// MARK CreateAssn_05
template <class T, class U>
bool util::CreateAssn(art::Event&,
                      art::Ptr<T> const& a,
                      std::vector<art::Ptr<U>> const& b,
                      art::Assns<T, U>& assn)
{

  try {
    for (art::Ptr<U> const& b_item : b)
      assn.addSingle(a, b_item);
  }
  catch (cet::exception const& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssn() [05]

//----------------------------------------------------------------------
// MARK CreateAssn_06
template <class T, class U>
bool util::CreateAssn(art::Event& evt,
                      std::vector<T> const& a,
                      std::vector<art::Ptr<U>> const& b,
                      art::Assns<T, U>& assn,
                      size_t index /* = UINT_MAX */
)
{

  if (index == UINT_MAX) index = a.size() - 1;

  try {
    auto const aptr = art::PtrMaker<T>{evt}(index);
    for (art::Ptr<U> const& b_item : b)
      assn.addSingle(aptr, b_item);
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssn() [06]

//----------------------------------------------------------------------
// MARK CreateAssn_07
template <class T, class U>
bool util::CreateAssn(art::Event& evt,
                      std::vector<T> const& a,
                      std::vector<U> const& /* b */,
                      art::Assns<T, U>& assn,
                      size_t startU,
                      size_t endU,
                      size_t index /* = UINT_MAX */
)
{

  if (index == UINT_MAX) index = a.size() - 1;

  try {
    auto const aptr = art::PtrMaker<T>{evt}(index);
    art::PtrMaker<U> const make_bptr{evt};
    for (size_t i = startU; i < endU; ++i) {
      assn.addSingle(aptr, make_bptr(i));
    }
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssn() [07]

//----------------------------------------------------------------------
// MARK CreateAssn_07a
template <class T, class U>
bool util::CreateAssn(art::Event& evt,
                      std::vector<T> const& a,
                      std::vector<U> const& /* b */,
                      art::Assns<T, U>& assn,
                      std::vector<size_t> const& indices,
                      size_t index /* = UINT_MAX */
)
{

  if (index == UINT_MAX) index = a.size() - 1;

  try {
    auto const aptr = art::PtrMaker<T>{evt}(index);
    art::PtrMaker<U> const make_bptr{evt};
    for (size_t index : indices) {
      assn.addSingle(aptr, make_bptr(index));
    }
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssn() [07a]

//----------------------------------------------------------------------
// MARK CreateAssn_08
template <typename T, typename U, typename Iter>
bool util::CreateAssn(art::Event& evt,
                      art::Assns<T, U>& assn,
                      size_t first_index,
                      Iter from_second_index,
                      Iter to_second_index)
{

  try {
    // we declare here that we want to associate the element first_index of the
    // (only) data product of type std::vector<T> with other objects.
    // This is the pointer to that element:
    auto const first_ptr = art::PtrMaker<T>{evt}(first_index);

    // we are going to associate that element in a with a number of elements
    // of the only data product of type std::vector<U>
    art::PtrMaker<U> const make_second_ptr{evt};
    for (; from_second_index != to_second_index; ++from_second_index) {
      assn.addSingle(first_ptr, make_second_ptr(*from_second_index));
    } // while
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssn() [08]

//----------------------------------------------------------------------
// MARK CreateAssnD_01a
template <typename T, typename U, typename D>
bool util::CreateAssnD(art::Event& evt,
                       art::Assns<T, U, D>& assn,
                       size_t first_index,
                       size_t second_index,
                       typename art::Assns<T, U, D>::data_t&& data)
{

  try {
    // we declare here that we want to associate the element first_index of the
    // (only) data product of type std::vector<T> with the other object
    auto const first_ptr = art::PtrMaker<T>{evt}(first_index);

    // the same to associate the element second_index of the (only)
    // data product of type std::vector<U> with the first object.
    auto const second_ptr = art::PtrMaker<U>{evt}(second_index);

    assn.addSingle(first_ptr, second_ptr, std::move(data));
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssnD() [01a]

template <typename T, typename U, typename D>
bool util::CreateAssnD(art::Event& evt,
                       art::Assns<T, U, D>& assn,
                       size_t first_index,
                       size_t second_index,
                       typename art::Assns<T, U, D>::data_t const& data)
{

  try {
    // we declare here that we want to associate the element first_index of the
    // (only) data product of type std::vector<T> with the other object
    auto const first_ptr = art::PtrMaker<T>{evt}(first_index);

    // the same to associate the element second_index of the (only)
    // data product of type std::vector<U> with the first object.
    auto const second_ptr = art::PtrMaker<U>{evt}(second_index);

    assn.addSingle(first_ptr, second_ptr, data);
  }
  catch (cet::exception& e) {
    mf::LogWarning("AssociationUtil")
      << "unable to create requested art:Assns, exception thrown: " << e;
    return false;
  }

  return true;
} // util::CreateAssnD() [01b]

//----------------------------------------------------------------------
template <class T, class U>
inline std::vector<const U*> util::FindUNotAssociatedToT(art::Handle<U> b,
                                                         art::Event const& evt,
                                                         std::string const& label)
{
  // Do a FindOne for type T for each object of type U
  // If the FindOne returns an invalid maybe ref, add the pointer
  // of object type U to the return vector

  std::vector<const U*> notAssociated;

  art::FindOne<T> const fa(b, evt, label);

  for (size_t u = 0; u < b->size(); ++u) {
    cet::maybe_ref<T const> t(fa.at(u));
    if (!t.isValid()) {
      art::Ptr<U> ptr(b, u);
      notAssociated.push_back(ptr.get());
    }
  }

  return notAssociated;
}

//----------------------------------------------------------------------
template <class T, class U>
inline std::vector<art::Ptr<U>> util::FindUNotAssociatedToTP(art::Handle<U> b,
                                                             art::Event const& evt,
                                                             std::string const& label)
{
  // Do a FindOneP for type T for each object of type U
  // If the FindOne returns an invalid maybe ref, add the pointer
  // of object type U to the return vector

  std::vector<art::Ptr<U>> notAssociated;

  art::FindOneP<T> const fa(b, evt, label);

  for (size_t u = 0; u < b->size(); ++u) {
    cet::maybe_ref<T const> t(fa.at(u));
    if (!t.isValid()) { notAssociated.emplace_back(b, u); }
  }

  return notAssociated;
}

template <class T, class U>
inline std::vector<size_t> util::GetAssociatedVectorOneI(art::Handle<art::Assns<T, U>> h,
                                                         art::Handle<std::vector<T>> index_p)
{
  std::vector<size_t> associated_index(index_p->size());
  for (auto const& pair : *h)
    associated_index.at(pair.first.key()) = pair.second.key();
  return associated_index;
}

template <class T, class U>
inline std::vector<const U*> util::GetAssociatedVectorOneP(art::Handle<art::Assns<T, U>> h,
                                                           art::Handle<std::vector<T>> index_p)
{
  std::vector<const U*> associated_pointer(index_p->size());
  for (auto const& pair : *h)
    associated_pointer.at(pair.first.key()) = &(*(pair.second));
  return associated_pointer;
}

template <class T, class U>
inline std::vector<std::vector<size_t>> util::GetAssociatedVectorManyI(
  art::Handle<art::Assns<T, U>> h,
  art::Handle<std::vector<T>> index_p)
{
  std::vector<std::vector<size_t>> associated_indices(index_p->size());
  for (auto const& pair : *h)
    associated_indices.at(pair.first.key()).push_back(pair.second.key());
  return associated_indices;
}

template <class T, class U>
inline std::vector<std::vector<const U*>> util::GetAssociatedVectorManyP(
  art::Handle<art::Assns<T, U>> h,
  art::Handle<std::vector<T>> index_p)
{
  std::vector<std::vector<const U*>> associated_pointers(index_p->size());
  for (auto const& pair : *h)
    associated_pointers.at(pair.first.key()).push_back(&(*(pair.second)));
  return associated_pointers;
}

//--------------------------------------------------------------------
// Functions to support unnecessary leading producer argument
//
//   These are legacy function signatures that accept a reference to a
//   producer module.  Although the signatures are still supported,
//   they should not be encouraged.  They, along with the other
//   CreateAssn(D) functions above, will be marked as [[deprecated]]
//   once art supports Assns::addMany (expected in art 3.04).
//--------------------------------------------------------------------

#include "art/Framework/Core/EDProducer.h"

namespace util {
  template <typename Producer, typename... Args>
  std::enable_if_t<std::is_base_of_v<art::EDProducer, Producer>, bool> CreateAssn(Producer const&,
                                                                                  Args&&... args)
  {
    return CreateAssn(std::forward<Args>(args)...);
  }

  template <typename Producer, typename... Args>
  std::enable_if_t<std::is_base_of_v<art::EDProducer, Producer>, bool> CreateAssnD(Producer const&,
                                                                                   Args&&... args)
  {
    return CreateAssnD(std::forward<Args>(args)...);
  }
}

#endif //ASSOCIATIONUTIL_H