Namespace for the trajectory point flags. More...

#include "TrajectoryPointFlags.h"

Public Types
using	Flags_t = util::flags::FlagSet< MaxFlags >
	Type of mask of bits. More...

using	Mask_t = Flags_t::Mask_t
	Type of mask of bits. More...

using	Flag_t = Flags_t::Flag_t
	Type of single flag. More...

using	FlagIndex_t = Flags_t::FlagIndex_t
	Type of index of a single flag. More...

Static Public Member Functions
static constexpr FlagIndex_t	maxFlags ()
	Number of flags allocated (may be unused and unassigned). More...

static constexpr bool	isFlag (Flag_t flag)
	Returns whether the specified index represents a valid flag. More...

Static Public Attributes
static constexpr unsigned int	MaxFlags = 32
	Number of flags allocated (may be unused and unassigned). More...

Trajectory flags.
The definition of the flags will result somehow ambiguous, because it requires a judgement that is in the end arbitrary enough that it may be inconsistent between different algorithms. The design idea is that typically at most one flag is set. For example, if a hit is known to be associated to another trajectory, the point will be marked as `Shared` but not `Merged`, and if it is `Merged` or `Shared` it will not be flagged as `Suspicious`. Exceptions may apply. For example, a hit known to be shared with a δ ray which is reconstructed as a distinct trajectory may have both the `Shared` and the `DeltaRay` flags. Also note that there may be better ways than these flags to discover information. For example, the `DetectorIssue` flag might have been left unset because no check was done on the actual data quality, or because the failure of the channel was not yet known at the time the trajectory was reconstructed. Implementation note The single flags are of type `Flag_t`, which is effectively represented as a bit mask with a single bit set. The boundary flag indices instead are actual indices (type `FlagIndex_t`) which allows them to be beyond the range of the mask (think especially to `EndExperimentReservedFlags`, whose value of $2^{32}$ is just beyond the range of a 32-bit integer). Each flag can yield its index by the `index()` method, and this can be used to compare them to flag indices.
static constexpr FlagIndex_t	BeginTrajectoryFlags = 0
	First trajectory flag index. More...

static constexpr Flag_t	HitIgnored { 0 }
	Hit was not included for the computation of the trajectory. More...

static constexpr Flag_t	NoPoint { 1 }
	The trajectory point is not defined. More...

static constexpr Flag_t	Suspicious { 2 }
	The point reconstruction is somehow questionable. More...

static constexpr Flag_t	Merged { 3 }
	The hit might have contribution from particles other than this. More...

static constexpr Flag_t	DeltaRay { 4 }
	The hit might have contribution from a δ ray. More...

static constexpr Flag_t	DetectorIssue { 5 }
	The hit is associated to a problematic channel. More...

static constexpr Flag_t	Shared { 6 }
	The hit is known to be associated also to another trajectory. More...

static constexpr Flag_t	TrajReserved1 { 7 }
	Reserved for a future trajectory flag. More...

static constexpr FlagIndex_t	EndTrajectoryFlags = 8
	After-the-last trajectory flag index. More...

Track flags.
As for the trajectory flags, the ones pertaining the track fitting are designed to be set in the most exclusive way possible. For example, a hit that is `Rejected` is not flagged as `ExcludedFromFit` (although it is indeed not included in the fit).
static constexpr FlagIndex_t	BeginTrackFlags = EndTrajectoryFlags
	First track flag index. More...

static constexpr Flag_t	ExcludedFromFit { 8 }

static constexpr Flag_t	Rejected { 9 }
	The hit is extraneous to this track. More...

static constexpr Flag_t	Reinterpreted { 10 }
	The hit content has been elaborated before being used in the fit. More...

static constexpr Flag_t	TrackReserved5 { 11 }
	Reserved for a future track flag. More...

static constexpr Flag_t	TrackReserved4 { 12 }
	Reserved for a future track flag. More...

static constexpr Flag_t	TrackReserved3 { 13 }
	Reserved for a future track flag. More...

static constexpr Flag_t	TrackReserved2 { 14 }
	Reserved for a future track flag. More...

static constexpr Flag_t	TrackReserved1 { 15 }
	Reserved for a future track flag. More...

static constexpr FlagIndex_t	EndTrackFlags = 16
	After-the-last track flag index. More...

Flag reserved for the experiments (not to be used in LArSoft).
static constexpr FlagIndex_t	BeginExperimentReservedFlags = EndTrackFlags
	First flag reserved to experiment. More...

static constexpr FlagIndex_t	EndExperimentReservedFlags = 24
	After-the-last flag reserved to experiment. More...

Flag reserved for the users (algorithm-specific).
static constexpr FlagIndex_t	BeginUserReservedFlags = EndExperimentReservedFlags
	First flag reserved to users. More...

static constexpr FlagIndex_t	EndUserReservedFlags = 32
	After-the-last flag reserved to users. More...

Static Private Member Functions
static std::string	decorateFlagName (std::string baseName, Flag_t flag)
	Combines a base name and an index into a flag name. More...

static std::string	invalidFlagName (Flag_t flag)
	Returns the name of an invalid flag with the specified index. More...

static void	initDefaultFlagRangeNames (NameMap_t &flagNames, FlagIndex_t BeginFlags, FlagIndex_t EndFlags, std::string baseName)
	Initializes a range of flag names with default (decorated) names. More...

static void	initDefaultFlagsNames (NameMap_t &flagNames)
	Initialises all flag names with a default name. More...

static void	setFlagNames (NameMap_t &flagNames)
	Sets the names of the flags after default initialization. More...

Static Private Attributes
static const NameMap_t	names = recob::TrajectoryPointFlagTraits::initNames()
	Names of the flags. More...

Flag names
using	NameMap_t = std::array< std::string, MaxFlags >
	Type storing flag names. More...

static std::string	name (Flag_t flag)
	Returns a string with the name of the specified flag. More...

static NameMap_t	initNames ()
	Returns a map of flag names. More...

Detailed Description

Namespace for the trajectory point flags.

This class is a glorified namespace for the definition of named flags.

Each flag must have an identifier that is of integral type FlagIndex_t. There are four types of flags: pertaining a trajectory (and pattern recognition output), pertaining a track (and track fit output), experiment specific and user specific.

The trajectory flags have a meaning in the bare context of reconstructed trajectory in space and patter recognition (see recob::Trajectory and see recob::TrackTrajectory), and they should preserve the same meaning after fitting into a track.

The track flags have a meaning only in the context of a track (see recob::Track).

The experiment-specific flags are placeholders that are expected to get a meaning that is consistent within a single experiment, and unrelated between experiments.

The user-specific flags are placeholders that are expected to get a meaning that is specific to an algorithm. Objects from different algorithms will give these flags unrelated meaning.

Code shared in LArSoft using the flags should rely only on the flags of the first two categories. Code that requires access to experiment-specific flags should be also experiment-specific.

Definition at line 61 of file TrajectoryPointFlags.h.

Member Typedef Documentation

using recob::TrajectoryPointFlagTraits::Flag_t = Flags_t::Flag_t

Type of single flag.

Definition at line 73 of file TrajectoryPointFlags.h.

using recob::TrajectoryPointFlagTraits::FlagIndex_t = Flags_t::FlagIndex_t

Type of index of a single flag.

Definition at line 76 of file TrajectoryPointFlags.h.

using recob::TrajectoryPointFlagTraits::Flags_t = util::flags::FlagSet<MaxFlags>

Type of mask of bits.

Definition at line 67 of file TrajectoryPointFlags.h.

using recob::TrajectoryPointFlagTraits::Mask_t = Flags_t::Mask_t

Type of mask of bits.

Definition at line 70 of file TrajectoryPointFlags.h.

using recob::TrajectoryPointFlagTraits::NameMap_t = std::array<std::string, MaxFlags>

Type storing flag names.

Definition at line 254 of file TrajectoryPointFlags.h.

Member Function Documentation

std::string recob::TrajectoryPointFlagTraits::decorateFlagName	(	std::string	baseName,
		Flag_t	flag
	)

staticprivate

Combines a base name and an index into a flag name.

Definition at line 46 of file TrajectoryPointFlags.cxx.

References invalidFlagName(), and util::flags::to_string().

Referenced by initDefaultFlagRangeNames().

 {
   return baseName + std::to_string(flag.index());
 } // recob::TrajectoryPointFlagTraits::decorateFlagName()

void recob::TrajectoryPointFlagTraits::initDefaultFlagRangeNames	(	NameMap_t &	flagNames,
		FlagIndex_t	BeginFlags,
		FlagIndex_t	EndFlags,
		std::string	baseName
	)

staticprivate

Initializes a range of flag names with default (decorated) names.

Definition at line 59 of file TrajectoryPointFlags.cxx.

References decorateFlagName(), and initDefaultFlagsNames().

Referenced by initDefaultFlagsNames().

   {
   if (EndFlags <= BeginFlags) return;
   unsigned int const NFlags = EndFlags - BeginFlags;
   
   // the first flag will have name with index NFlags, the last with name "1"
   for (unsigned int dFlag = 0; dFlag < NFlags; ++dFlag) {
     FlagIndex_t const flag = BeginFlags + dFlag;
     
     flagNames[flag] = decorateFlagName(baseName, NFlags - dFlag);
   } // for
   
 } // recob::TrajectoryPointFlagTraits::initDefaultFlagRangeNames()

void recob::TrajectoryPointFlagTraits::initDefaultFlagsNames ( NameMap_t & flagNames )

staticprivate

Initialises all flag names with a default name.

Definition at line 78 of file TrajectoryPointFlags.cxx.

References BeginExperimentReservedFlags, BeginTrackFlags, BeginTrajectoryFlags, BeginUserReservedFlags, EndExperimentReservedFlags, EndTrackFlags, EndTrajectoryFlags, EndUserReservedFlags, and initDefaultFlagRangeNames().

Referenced by initDefaultFlagRangeNames(), and initNames().

 {
   
   initDefaultFlagRangeNames(
     flagNames, BeginTrajectoryFlags, EndTrajectoryFlags,
     "TrajectoryReserved"
     );
   initDefaultFlagRangeNames(
     flagNames, BeginTrackFlags, EndTrackFlags,
     "TrackReserved"
     );
   initDefaultFlagRangeNames(
     flagNames, BeginExperimentReservedFlags, EndExperimentReservedFlags,
     "ExperimentFlag"
     );
   initDefaultFlagRangeNames(
     flagNames, BeginUserReservedFlags, EndUserReservedFlags,
     "UserFlag"
     );
   
 } // recob::TrajectoryPointFlagTraits::initDefaultFlagsNames()

recob::TrajectoryPointFlagTraits::NameMap_t recob::TrajectoryPointFlagTraits::initNames ( )

static

Returns a map of flag names.

Definition at line 127 of file TrajectoryPointFlags.cxx.

References initDefaultFlagsNames(), and setFlagNames().

                                           {
   
   NameMap_t flagNames; // not initialized
   
   // initialize with default names
   initDefaultFlagsNames(flagNames);
   
   // overwrite custom names
   setFlagNames(flagNames);
   
   // done!
   return flagNames;
   
 } // recob::TrajectoryPointFlagTraits::initNames()

std::string recob::TrajectoryPointFlagTraits::invalidFlagName ( Flag_t flag )

staticprivate

Returns the name of an invalid flag with the specified index.

Definition at line 54 of file TrajectoryPointFlags.cxx.

Referenced by decorateFlagName(), and name().

55 { return "<" + decorateFlagName("InvalidFlag", flag) + ">"; }

recob::TrajectoryPointFlagTraits::decorateFlagName

static std::string decorateFlagName(std::string baseName, Flag_t flag)

Combines a base name and an index into a flag name.

Definition: TrajectoryPointFlags.cxx:46

static constexpr bool recob::TrajectoryPointFlagTraits::isFlag ( Flag_t flag )

inlinestatic

Returns whether the specified index represents a valid flag.

Definition at line 241 of file TrajectoryPointFlags.h.

References MaxFlags.

Referenced by name().

242 { return flag.index() < MaxFlags; }

recob::TrajectoryPointFlagTraits::MaxFlags

static constexpr unsigned int MaxFlags

Number of flags allocated (may be unused and unassigned).

Definition: TrajectoryPointFlags.h:64

static constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::maxFlags ( )

inlinestatic

Number of flags allocated (may be unused and unassigned).

Definition at line 237 of file TrajectoryPointFlags.h.

References MaxFlags.

237 { return MaxFlags; }

recob::TrajectoryPointFlagTraits::MaxFlags

static constexpr unsigned int MaxFlags

Number of flags allocated (may be unused and unassigned).

Definition: TrajectoryPointFlags.h:64

static std::string recob::TrajectoryPointFlagTraits::name ( Flag_t flag )

inlinestatic

Returns a string with the name of the specified flag.

Definition at line 248 of file TrajectoryPointFlags.h.

References invalidFlagName(), isFlag(), and names.

       {
         return isFlag(flag)? names[flag.index()]: invalidFlagName(flag.index());
       }

void recob::TrajectoryPointFlagTraits::setFlagNames ( NameMap_t & flagNames )

staticprivate

Sets the names of the flags after default initialization.

Definition at line 102 of file TrajectoryPointFlags.cxx.

References DeltaRay, DetectorIssue, ExcludedFromFit, HitIgnored, Merged, NoPoint, Reinterpreted, Rejected, Shared, and Suspicious.

Referenced by initNames().

                                                                       {
   
   //
   // set the names of the new flags here
   //
   
   // trajectory flags
   std::get<HitIgnored.index()   >(flagNames) = "HitIgnored"   ;
   std::get<NoPoint.index()      >(flagNames) = "NoPoint"      ;
   std::get<Suspicious.index()   >(flagNames) = "Suspicious"   ;
   std::get<Merged.index()       >(flagNames) = "Merged"       ;
   std::get<DeltaRay.index()     >(flagNames) = "DeltaRay"     ;
   std::get<DetectorIssue.index()>(flagNames) = "DetectorIssue";
   std::get<Shared.index()       >(flagNames) = "Shared"       ;
   
   // track flags
   std::get<ExcludedFromFit.index()>(flagNames) = "ExcludedFromFit";
   std::get<Rejected.index()       >(flagNames) = "Rejected"       ;
   std::get<Reinterpreted.index()  >(flagNames) = "Reinterpreted"  ;
   
 } // recob::TrajectoryPointFlagTraits::initNames()

Member Data Documentation

constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::BeginExperimentReservedFlags = EndTrackFlags

static

First flag reserved to experiment.

Definition at line 216 of file TrajectoryPointFlags.h.

Referenced by initDefaultFlagsNames().

constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::BeginTrackFlags = EndTrajectoryFlags

static

First track flag index.

Definition at line 168 of file TrajectoryPointFlags.h.

Referenced by initDefaultFlagsNames().

constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::BeginTrajectoryFlags = 0

static

First trajectory flag index.

Definition at line 116 of file TrajectoryPointFlags.h.

Referenced by initDefaultFlagsNames().

constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::BeginUserReservedFlags = EndExperimentReservedFlags

static

First flag reserved to users.

Definition at line 228 of file TrajectoryPointFlags.h.

Referenced by initDefaultFlagsNames().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::DeltaRay { 4 }

static

The hit might have contribution from a δ ray.

Definition at line 138 of file TrajectoryPointFlags.h.

Referenced by trkf::TrackKalmanFitter::doFitWork(), and setFlagNames().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::DetectorIssue { 5 }

static

The hit is associated to a problematic channel.

Definition at line 141 of file TrajectoryPointFlags.h.

Referenced by trkf::TrackKalmanFitter::doFitWork(), and setFlagNames().

constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::EndExperimentReservedFlags = 24

static

After-the-last flag reserved to experiment.

Definition at line 219 of file TrajectoryPointFlags.h.

Referenced by initDefaultFlagsNames().

constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::EndTrackFlags = 16

static

After-the-last track flag index.

Definition at line 208 of file TrajectoryPointFlags.h.

Referenced by initDefaultFlagsNames().

constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::EndTrajectoryFlags = 8

static

After-the-last trajectory flag index.

Definition at line 150 of file TrajectoryPointFlags.h.

Referenced by initDefaultFlagsNames().

constexpr FlagIndex_t recob::TrajectoryPointFlagTraits::EndUserReservedFlags = 32

static

After-the-last flag reserved to users.

Definition at line 231 of file TrajectoryPointFlags.h.

Referenced by initDefaultFlagsNames().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::ExcludedFromFit { 8 }

static

The point belongs to this track but it was not included in the fit because dubious in some sense.

Definition at line 172 of file TrajectoryPointFlags.h.

Referenced by trkf::TrackKalmanFitter::doFitWork(), trkf::TrackKalmanFitter::fillResult(), setFlagNames(), and trkf::TrackKalmanFitter::setupInputStates().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::HitIgnored { 0 }

static

Hit was not included for the computation of the trajectory.

Definition at line 119 of file TrajectoryPointFlags.h.

Referenced by trkf::TrackKalmanFitter::doFitWork(), trkf::TrackKalmanFitter::fillResult(), and setFlagNames().

constexpr unsigned int recob::TrajectoryPointFlagTraits::MaxFlags = 32

static

Number of flags allocated (may be unused and unassigned).

Definition at line 64 of file TrajectoryPointFlags.h.

Referenced by isFlag(), and maxFlags().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::Merged { 3 }

static

The hit might have contribution from particles other than this.

Definition at line 135 of file TrajectoryPointFlags.h.

Referenced by trkf::TrackKalmanFitter::doFitWork(), setFlagNames(), and trkf::TrackKalmanFitter::setupInputStates().

const recob::TrajectoryPointFlagTraits::NameMap_t recob::TrajectoryPointFlagTraits::names = recob::TrajectoryPointFlagTraits::initNames()

staticprivate

Names of the flags.

Definition at line 263 of file TrajectoryPointFlags.h.

Referenced by name().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::NoPoint { 1 }

static

The trajectory point is not defined.

Definition at line 122 of file TrajectoryPointFlags.h.

Referenced by lar_pandora::LArPandoraTrackCreation::BuildTrack(), trkf::TrackKalmanFitter::doFitWork(), trkf::TrackKalmanFitter::fillResult(), recob::TrackTrajectory::HasValidPoint(), trkf::KalmanFilterTrajectoryFitter::restoreInputPoints(), trkf::KalmanFilterFinalTrackFitter::restoreInputPoints(), trkmkr::KalmanFilterFitTrackMaker::restoreInputPoints(), and setFlagNames().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::Reinterpreted { 10 }

static

The hit content has been elaborated before being used in the fit.

In this case, it is good practise for the fitting algorithm to associate the fitted point to the new hit. Nevertheless, a simpler code might assume that all associated hits are from the same data product, and fail to find the new one which will necessarily have to belong to a new hit collection.

If you find yourself in the situation where you consider setting this flag, it may be useful to consult with LArSoft experts to determine if further support is needed for your use case.

Definition at line 190 of file TrajectoryPointFlags.h.

Referenced by setFlagNames().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::Rejected { 9 }

static

The hit is extraneous to this track.

Definition at line 175 of file TrajectoryPointFlags.h.

Referenced by trkf::TrackKalmanFitter::doFitWork(), trkf::TrackKalmanFitter::fillResult(), and setFlagNames().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::Shared { 6 }

static

The hit is known to be associated also to another trajectory.

Definition at line 144 of file TrajectoryPointFlags.h.

Referenced by trkf::TrackKalmanFitter::doFitWork(), and setFlagNames().

constexpr recob::TrajectoryPointFlagTraits::Flag_t recob::TrajectoryPointFlagTraits::Suspicious { 2 }

static

The point reconstruction is somehow questionable.

See also: Merged, DeltaRay

For example, the hit might look ambiguous but there is no evidence of another track nearby or a δ ray emission. Reconstruction of the point might be biased, but we can't guess which type of bias we have.

Definition at line 132 of file TrajectoryPointFlags.h.

Referenced by trkf::TrackKalmanFitter::doFitWork(), setFlagNames(), and trkf::TrackKalmanFitter::setupInputStates().

constexpr Flag_t recob::TrajectoryPointFlagTraits::TrackReserved1 { 15 }

static