Assigns clusters to nearest Monte-Carlo truth partons in the hard process. Clusters are drawn from cluster_masks, until each each parton is assigned.

Parameters:¶

particles : ParticleSet¶

Monte-Carlo particle data record for the whole event.

cluster_masks : Sequence[MaskArray]¶

Boolean masks identifying which particles belong to each of the clusterings. These are defined over the final particles, or clustered_pmu, see below.

clustered_pmu : MomentumArray, optional¶

MomentumArray containing the data as passed to the clustering algorithm. This is useful for when cuts have been applied before clustering. If unset, the final state momentum for the whole event will be assumed.

intermediate : bool¶

If True includes partons from the intermediate stage of the hard process. Default is False.

outgoing : bool¶

If True includes partons from the outgoing stage of the hard process. Default is True.

sign_sensitive : bool¶

If False, the sign of PDG codes in the blacklist are ignored. ie. Particles and anti-particles are not distinguished. Default is False.

blacklist : Sequence[int], optional¶

A sequence of PDG codes, identifying particles in the hard process which should not be assigned a cluster.

whitelist : Sequence[int], optional¶

A sequence of PDG codes, identifying particles in the hard process which exclusively should be assigned clusters.

Returns:¶

Mapping of the particle names within the hard process to the assigned closest clusters, with agg_op=OR.

Return type:¶

MaskGroup[MaskArray]

Raises:¶

• ValueError – If intermediate and outgoing are simultaneously set to False, or blacklist and whitelist are simultaneously not None.

• ValueError – If cluster_masks is empty. Additionally, if the elements have a size mismatch with either the number of particles in the final state, or the length of clustered_pmu when passed.

• IndexError – If after applying blacklist or whitelist, no matching partons remain in the hard process.

Examples

Boosted top decay, clustered with anti-kt, and tagged with MC truth:

>>> print(gcl.select.hierarchy(graph))  # hard process tree
MaskGroup(agg_op=OR)
├── W+
│   ├── e+
│   ├── nu(e)
│   └── latent
└── t~
    ├── W-
    │   ├── d
    │   ├── u~
    │   └── latent
    ├── b~
    └── latent
>>> final_pmu = graph.pmu[graph.final]
... clusters = gcl.select.fastjet_clusters(  # anti-kt clusters
...     pmu=final_pmu,
...     radius=0.3,
...     p_val=-1,
...     eta_cut=3.0,
...     pt_cut=10.0,
...     top_k=10,
... )
... tagged_clusters = gcl.select.monte_carlo_tag(
...     particles=graph.particles,
...     cluster_masks=clusters,
...     blacklist=[11, 12],
... )
... tagged_clusters  # subset of anti-kt tagged to MC truth
MaskGroup(masks=["b~", "d", "u~"], agg_op=OR)
>>> # calculate combined mass of clusters from top quark
... np.sum(final_pmu[tagged_clusters], axis=0).mass
array([163.33889956])