Merge branch 'ld-mc-primary-vertex' into 'master'

Add primary vertex functor collection

See merge request !1002

Phys/FunTuple/python/FunTuple/functorcollections.py

@@ -559,6 +559,9 @@ def MCVertexInfo(
     Args:
         mctruth_alg (DaVinciMCTools.MCTruthAndBkgCat, optional): An instance of the `MCTruthAndBkgCat` helper class
             that is used for retrieving monte-carlo truth information of a reconstructed particle. Defaults to None.
+        If no argument is provided, i.e. mctruth_alg==None, this collection creates functors that apply to MCParticles;
+        otherwise, the functors created are assumed to apply to Particles,
+        which will find the associated MCParticle automatically using the input truth matching.
 
     Example:
         from FunTuple import FunTuple_Particles as Funtuple
@@ -585,7 +588,7 @@ def MCVertexInfo(
     else:
         MCTRUTH = mctruth_alg
 
-    MCVertexInfo = {
+    functor_dictionary = {
         "TRUEORIGINVERTEX_X": MCTRUTH(F.ORIGIN_VX),
         "TRUEORIGINVERTEX_Y": MCTRUTH(F.ORIGIN_VY),
         "TRUEORIGINVERTEX_Z": MCTRUTH(F.ORIGIN_VZ),
@@ -593,12 +596,39 @@ def MCVertexInfo(
         "TRUEENDVERTEX_Y": MCTRUTH(F.END_VY),
         "TRUEENDVERTEX_Z": MCTRUTH(F.END_VZ),
     }
-    return FunctorCollection(MCVertexInfo)
+    return FunctorCollection(functor_dictionary)
+
+
+def MCPrimaryVertexInfo(
+    *, mctruth_alg: Optional[DaVinciMCTools.MCTruthAndBkgCat] = None
+) -> FunctorCollection:
+    """
+    Candidate-level collection of functors yielding the X, Y and Z positions of the primary vertex of the
+    (related) MC particle.
+
+    Args:
+        mctruth_alg (DaVinciMCTools.MCTruthAndBkgCat, optional): An instance of the `MCTruthAndBkgCat` helper class
+            that is used for retrieving monte-carlo truth information of a reconstructed particle. Defaults to None.
+        )
+        If none, no call is made to the truth-matching. This is suitable for use only for tuples which
+        directly run on MCParticles (MCTuples).
+    """
+    if mctruth_alg is None:
+        MCTRUTH = lambda func: func
+    else:
+        MCTRUTH = mctruth_alg
+
+    mc_primary_vertex_info_functors = {
+        "TRUEPRIMARYVERTEX_X": MCTRUTH(F.MC_PV_VX),
+        "TRUEPRIMARYVERTEX_Y": MCTRUTH(F.MC_PV_VY),
+        "TRUEPRIMARYVERTEX_Z": MCTRUTH(F.MC_PV_VZ),
+    }
+    return FunctorCollection(mc_primary_vertex_info_functors)
 
 
 def MCPrimaries(*, mc_header: DataHandle) -> FunctorCollection:
     """
-    Event-level collection of functors to store the properties (X,Y,Z,T) of MC primary vertices.
+    Event-level collection of functors to store the properties (X,Y,Z,T) of all MC primary vertices.
 
     Args:
         mc_header (DataHandle): The TES location of the `MCHeader` object,