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:

• the tracks themselves, in a std::vector<recob::Track> collection
• the associated hits, in a art::Assns<recob::Track, recob::Hit> data product

Special customisations are provided for:

• the associated hits (automatically pulled in): the information is provided with recob::Hit tag, with the dedicated accessor hits(), nHits() and hitAtPoint() of the track proxy and with hitPtr() and hit() when accessing a single point
• the track fit information: include it with withFitHitInfo(); the information is provided with recob::TrackFitHitInfo tag, with the dedicated accessor fitInfoAtPoint() of the track proxy and with fitInfoPtr() when accessing a single point

LArSoft prescribes conventions to be followed, which include:

• a track has at least two trajectory points
• for each track, there is one hit per trajectory point
• the association between tracks and hits is created with tracks as first ("left") element, and hits as second one ("right")
• hits in the association are in a well-defined order: first are the hits of the first track, sorted in the same way as their trajectory points; then the second track hits come, likewise; and all tracks follow in order; this is called the "one-to-many sequential association" requirement documented in ProxyBase.h.

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:

• proxy::Tracks represents the whole collection of tracks; it covers the tracks themselves, and their associated hits. It is obtained by calling getCollection() as described above.
• proxy::Track represents a single track; the list of hits and points, and of course the recob::Track object itself, can be accessed through it. Track proxies are obtained from a track collection proxy (proxy::Tracks).
• proxy::TrackPoint represents a single trajectory point in a track. It provide access to position and momentum of the track at that point, associated hit and point flags. Track point proxies are obtained from a track proxy (proxy::Track).

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::Track–recob::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

TrackCollProxy

type 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 1036 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 556 of file Track.h.

Function Documentation

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

inline

Adds recob::TrackFitHitInfo information to the proxy.

Parameters

inputTag

the 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 1133 of file Track.h.

    {
      return proxy::withParallelDataAs
        <std::vector<recob::TrackFitHitInfo>, Tracks::TrackFitHitInfoTag>
        (inputTag);
    }

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 1191 of file Track.h.

    {
      return proxy::withParallelDataAs
        <std::vector<recob::TrackFitHitInfo>, Tracks::TrackFitHitInfoTag>();
    }

auto proxy::withOriginalTrajectory ( art::InputTag const &  inputTag )

inline

Adds recob::TrackTrajectory information to the proxy.

Parameters

inputTag

the 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 1064 of file Track.h.

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

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>
  (event, tracksTag, proxy::withOriginalTrajectory());

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 1115 of file Track.h.

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