LArSoft  v09_90_00
Liquid Argon Software toolkit - https://larsoft.org/
proxy::Tracks (recob::Track proxy)

Proxy for a recob::Track collection. More...

Classes

struct  proxy::Tracks
 Proxy tag for a recob::Track collection proxy. More...
 
class  proxy::TrackPointWrapper< Data >
 Wrapper for a track data proxy. More...
 
struct  proxy::TrackPoint
 Type of track point information. More...
 
struct  proxy::TrackCollectionProxyElement< CollProxy >
 Class for track proxy elements. More...
 

Typedefs

using proxy::TrackPointData = std::tuple< recob::Track const *, art::Ptr< recob::Hit >, recob::TrackFitHitInfo const *, std::size_t >
 Container of track point information. More...
 
template<typename TrackCollProxy >
using proxy::Track = TrackCollectionProxyElement< TrackCollProxy >
 Proxy to an element of a proxy collection of recob::Track objects. More...
 

Auxiliary data

These functions may be used as arguments to proxy::getCollection<proxy::Tracks>() call to merge of some data associated to the tracks.

auto proxy::withOriginalTrajectory (art::InputTag const &inputTag)
 Adds recob::TrackTrajectory information to the proxy. More...
 
auto proxy::withOriginalTrajectory ()
 Adds recob::TrackTrajectory information to the proxy. More...
 
auto proxy::withFitHitInfo (art::InputTag const &inputTag)
 Adds recob::TrackFitHitInfo information to the proxy. More...
 
auto proxy::withFitHitInfo ()
 Adds recob::TrackFitHitInfo information to the proxy. More...
 

Detailed Description

Proxy for a recob::Track collection.

Track proxies is a way to facilitate the navigation of recob::Track data objects. The ensemble of fundamental data of a track collection includes:

Special customisations are provided for:

LArSoft prescribes conventions to be followed, which include:

For track data products respecting this convention, a track proxy provides an interface to navigate the track information.

Note
The interface is experimental, and it is likely not to include all the features you may need. If you find a missing feature, or find a use case violating an assumption, or you find the interface cumbersome to use, please contact the author for a discussion on how to improve this utility.

Obtaining a track proxy

Track proxies are created by specifying the tag of the tracks, and the event to read them from.

To create a track proxy:

auto tracks = proxy::getCollection<proxy::Tracks>(event, tracksTag);

Here we ask getCollection() to create a proxy of category proxy::Tracks. Each proxy is a different beast which needs to be explicitly supported: here support for the proxy to recob::Track is described.

The additional customizations for track proxy are described above. For example, if the module with label fitTag stored the fit information for the track, that information can be merged as:

auto tracks = proxy::getCollection<proxy::Tracks>
(event, tracksTag, withFitHitInfo(fitTag));

while in the more likely case where that information was produced together with the tracks,

auto tracks = proxy::getCollection<proxy::Tracks>
(event, tracksTag, withFitHitInfo());

will suffice. After this, the interface specific to recob::TrackFitHitInfo will be available. Otherwise, any attempt to use it will cause (complicate) compilation errors.

In addition, any type of data can be associated using the generic collection proxy interface (withAssociated(), withParallelData(), etc.).

The C++ type of tracks object should not matter to the user, and it depends on which additional data are merged in.

Types of proxies, and what to do with them

Currently there are three different type of proxy-like objects for tracks. Each one supports a specific concept:

For the details of the interface and the information that is exposed by each of these proxy classes, please refer to each class documentation. In particular, see proxy::Tracks documentation for more usage examples.

Note
The interface allows by deliberate design only read-only access to the underlying data.

Technical details

Track collection proxy

The track collection proxy object is derived from proxy::CollectionProxyBase, which points to the original (track) data product. In addition, it contains a proxy::details::AssociatedData object for the recob::Trackrecob::Hit association list.

The proxy::Tracks interface is currently quite limited: it only allows to access a track by index, or to iterate through all of them, in addition to know how many tracks are available (size()).

The object returned when accessing the single track information, proxy::Track, actually contains enough information so that it is independent of the track collection proxy. This is derived from the generic collection element proxy object (proxy::CollectionProxyElement).

The object describing the information of a single point has the interface of TrackPointWrapper. The underlying storage includes pointers to the track, the associated hit, and the index of the point in the track. This is track-specific and it is not part of the generic proxy infrastructure.

Track proxy as an example of proxy customization

The proxy utilities provide the basic functionality of the track proxy, including the track collection proxy, representing all the tracks in the event, and the track proxy, representing a single track. Access to a third tier, the single trajectory point, as proxy is not covered by the basic framework, and it has been implemented here from scratch.

The most relevant customization pertains proxy to the single track. The proxy is derived from proxy::details::CollectionProxyElement for basic functionality, which is enriched by a custom interface that does not in fact add functionality, except for the trajectory point proxy described below. The customizations are fairly trivial, overlaying user-friendly names on the existing functionality. A step beyond that is the access to data that might not be present, that is the fit information. The proxy takes the necessary steps to determine (statically) whether that information is present, and to provide a null pointer to the information if that is not the case. This is a functionality that can't be completely implemented by the basic proxy code, since that generic code has no clue about what type of null pointer to return when the tag Tracks::TrackFitHitInfoTag is unknown. This information is provided by the track proxy via the getIf() call. For convenience, proxy::Track is defined as alias of this single track proxy.

The collection proxy customization is way more straightforward. A proxy "tag" is defined, proxy::Tracks, with the only purpose of identifying the collection proxy for tracks. For convenience, it hosts a definition used internally to identify one of the optional auxiliary data, and the type of the main data product, but both definitions are contingent and their presence in there is only to centralize some customization in a single place. Traits (CollectionProxyMakerTraits<Tracks>) are specialized to inform that this proxy::Tracks proxy relies on std::vector<recob::Track> as main data product collection type (std::vector<recob::Track> is learned from proxy::Tracks, but again, this is a contingent detail). The only other customization we need is to have for our proxy our element class above: since we can use the standard collection base, just with the custom element, we define collection_proxy_impl_t in that way. Finally, the creation of the collection proxy is customised by specializing CollectionProxyMaker (CollectionProxyMaker<Tracks>). That class normally takes care of creating the whole proxy, and our purpose is to have it always add the associated hits as auxiliary data, so that the caller does not have to explicitly use withAssociated<recob::Hit>() in getCollection(). The simple customization does exactly that, under the hood. As candy, some customized functions may be provided for convenience, like withFitHitInfo() as alias of withAssociated<recob::TrackFitHitInfo>().

The trajectory point proxy has been implemented from scratch here, and it is much less refined than the generic proxy code. It is based on a data structure with a selected list of pointers to the actual data. This structure is implemented as a std::tuple. On top of it, a wrapper provides the interface (by interface substitution). This choice is non-essential and has been taken to stress the separation between data storage and interface. Point data structures are created by the proxy on demand, and they are designed so that they don't become invalid when the original proxies fall out of scope, at the price of added memory usage (the minimal information would be a pointer to the track proxy and a point index).

Summary of the customization procedure:

  1. define the tag to identify the proxy (proxy::Tracks)
  2. choose what type of object that will be (proxy::CollectionProxyBase should do for most)
  3. (optional) customize the element type; deriving it from proxy::CollectionProxyElement is recommended
  4. define the main data product type (std::vector<recob::Track>) and set the traits of the collection proxy, often deriving them from proxy::CollectionProxyMakerTraits with the main data product type as template argument is enough; in this example, we specified a collection proxy object with customized element though
  5. customize the creation of the proxy collection, if special logic or default components are specified for the proxy (here, withAssociated<recob::Hit>()); in this case, proxy::CollectionProxyMaker must be specialized (for proxy::Tracks), and a starting point may be to derive the specialization from proxy::CollectionProxyMakerBase and redefine its make() member

Overhead

See the notes on overhead in ProxyBase.h.

Typedef Documentation

template<typename TrackCollProxy >
using proxy::Track = typedef TrackCollectionProxyElement<TrackCollProxy>

Proxy to an element of a proxy collection of recob::Track objects.

Template Parameters
TrackCollProxytype of the track collection proxy

This class is the proxy equivalent of recob::Track, which exposes data associated with the track. An object of this type is returned when accessing a single track from a track collection proxy. While the data itself is not copied, this object owns some pointers to the actual data, and once created it is independent of the track collection proxy which created it.

The interface is currently defined by proxy::TrackCollectionProxyElement.

Definition at line 992 of file Track.h.

using proxy::TrackPointData = typedef std:: tuple<recob::Track const*, art::Ptr<recob::Hit>, recob::TrackFitHitInfo const*, std::size_t>

Container of track point information.

See also
proxy::Track, proxy::TrackPointWrapper

This class contains some information pertaining a single point of a recob::Track.

The information is not extensible via the usual proxy mechanisms. The data supported is stored in proxy::TrackPointData class, and it currently includes:

  • the recob::Track the point belongs to
  • the position, momentum and flags of the point
  • the hit associated to the point
  • the index of the point in its track
  • fit information

The access interface is determined by proxy::TrackPointWrapper.

An object of this type is returned when accessing a single track point from a track proxy. While the data itself is not copied, this object owns some pointers to the actual data, and once created it is independent of the track proxy which created it.

Definition at line 533 of file Track.h.

Function Documentation

auto proxy::withFitHitInfo ( art::InputTag const &  inputTag)
inline

Adds recob::TrackFitHitInfo information to the proxy.

Parameters
inputTagthe data product label to read the data from
Returns
an object driving getCollection() to use recob::TrackFitHitInfo
See also
proxy::Tracks, proxy::getCollection(), proxy::withFitHitInfo()

This function behaves like withFitHitInfo(), but allows to use inputTag as input tag, instead of the same label as for the track collection. See proxy::withFitHitInfo() for explanations and examples.

Definition at line 1085 of file Track.h.

1086  {
1087  return proxy::withParallelDataAs<std::vector<recob::TrackFitHitInfo>,
1088  Tracks::TrackFitHitInfoTag>(inputTag);
1089  }
auto proxy::withFitHitInfo ( )
inline

Adds recob::TrackFitHitInfo information to the proxy.

Returns
an object driving getCollection() to use recob::TrackFitHitInfo
See also
proxy::withFitHitInfo(art::InputTag const&), proxy::Tracks, proxy::getCollection()

A recob::TrackFitHitInfodata product is read from the event and merged into the proxy being created by proxy::getCollection(). The data product has the same input tag as the track data product; if a different one is needed, use proxy::withFitHitInfo(art::InputTag const&) instead.

Example of usage (more can be found in TrackProxyTest::testTracks()):

auto tracks = proxy::getCollection<proxy::Tracks>
(event, tracksTag, proxy::withFitHitInfo());
for (auto const& trackInfo: tracks) {
for (auto const& point: track.points()) {
auto const& pos = point.position();
auto const* hit = point.hit();
auto const* fitInfo = point.fitInfoPtr();
// ...
} // for point
} // for tracks

The proxy helps associating the right set of recob::TrackFitHitInfo for each track in the outer loop (not shown in the example: it might have looked like auto const& fitInfo = tracks.get<recob::TrackFitHitInfo>()). It also helps to pick the fit information of the current point in the inner loop of the example (fitInfo will never be nullptr here, since we did merge the fit information).

The collection of recob::TrackFitHitInfo is required to be a std::vector<std::vector<recob::TrackFitHitInfo>>, where the first index addresses which track the information is about, and the second index which point within that track.

The data is also available through the regular interface via tag recob::TrackFitHitInfo.

The data must satisfy the parallel data product requirement.

Definition at line 1142 of file Track.h.

1143  {
1144  return proxy::withParallelDataAs<std::vector<recob::TrackFitHitInfo>,
1145  Tracks::TrackFitHitInfoTag>();
1146  }
auto proxy::withOriginalTrajectory ( art::InputTag const &  inputTag)
inline

Adds recob::TrackTrajectory information to the proxy.

Parameters
inputTagthe data product label to read the data from
Returns
an object driving getCollection() to use recob::TrackTrajectory
See also
proxy::withOriginalTrajectory(), proxy::Tracks, proxy::getCollection()

The behaviour of this function is like withOriginalTrajectory(), but reading the original trajectories from the association with the specified label rather than the label of the tracks in the proxy.

Definition at line 1018 of file Track.h.

1019  {
1020  return proxy::withZeroOrOneAs<recob::TrackTrajectory, Tracks::TrackTrajectoryTag>(inputTag);
1021  }
auto proxy::withOriginalTrajectory ( )
inline

Adds recob::TrackTrajectory information to the proxy.

Returns
an object driving getCollection() to use recob::TrackTrajectory
See also
proxy::withOriginalTrajectory(art::InputTag const&), proxy::Tracks, proxy::TrackCollectionProxyElement::hasOriginalTrajectory(), proxy::TrackCollectionProxyElement::originalTrajectory(), proxy::TrackCollectionProxyElement::originalTrajectoryPtr()

The information from the associated trajectories is merged in the proxy. That association data product must have the same input tag as the track collection data product. To specify a different one, use withOriginalTrajectory(art::InputTag const&).

The data is available through the regular interface via tag recob::TrackTrajectory, or via custom interface, e.g.:

auto tracks = proxy::getCollection<proxy::Tracks>
for (auto const& trackProxy: tracks) {
if (!trackProxy.hasOriginalTrajectory()) continue;
const auto& track = *trackProxy;
recob::TrackTrajectory const& original = trackProxy.originalTrajectory();
recob::TrackTrajectory const& fitted = track.Trajectory();
// ...
} // for tracks

Note the subtle difference between the two inner lines: trackProxy is a track proxy, and the first line is accessing its interface. The second line is talking to the track object (recob::Track, actually) directly. The same effect is obtained using directly the proxy, but with the indirection operator (->) instead of the member operator (.): trackProxy->Trajectory().

The recob::TrackTrajectory information is required to be from a art association with recob::Track. The association must fulfil the one-to-(zero-or-one) sequential association requirements.

Definition at line 1068 of file Track.h.

1069  {
1070  return proxy::withZeroOrOneAs<recob::TrackTrajectory, Tracks::TrackTrajectoryTag>();
1071  }