A templated agglomerative clustering algorithm. More...

#include <TemplatedClusterFinder.h>

Public Types
using	ClusterType = WorkingCluster<HitType>

Public Member Functions
void	add (const HitType &hit)
	Add a hit to be clustered using its stored position.

void	add (const HitType *hit)
	Add a hit to be clustered using its stored position.

void	add (const HitType *hit, double x, double y, double z)
	Add a hit with explicit position (e.g., from geometry).

void	cluster (double seed_threshold, double cutoff)
	Run the clustering algorithm.

double	getYMax () const
	Get the final weight (minimum distance between remaining clusters).

int	getNSeeds () const
	Get the number of seed clusters found.

int	getNLoops () const
	Get the number of iterations performed.

std::map< int, double >	getWeights () const
	Get the transition weights (cluster count -> minimum weight at that step).

std::vector< ClusterType >	getClusters () const
	Get the final clusters after filtering by seed threshold.

std::vector< ClusterType >	getAllClusters () const
	Get all clusters including empty ones (for debugging).

Static Public Member Functions
static bool	compClusters (const ClusterType &a, const ClusterType &b)
	Compare clusters by energy (descending order).

Private Attributes
WeightClass	wgt_

double	finalwgt_ {0}

int	nseeds_ {0}

int	loops_ {0}

std::map< int, double >	transition_weights_

std::vector< ClusterType >	clusters_

std::vector< ClusterType >	final_clusters_

Detailed Description

template<class HitType, class WeightClass>
class recon::TemplatedClusterFinder< HitType, WeightClass >

A templated agglomerative clustering algorithm.

This class implements a hierarchical agglomerative clustering algorithm for calorimeter hits. It is templated on:

HitType: The type of hit being clustered (must inherit from CalorimeterHit)
WeightClass: A functor that computes the "distance" between two clusters

The algorithm works by:

Starting with each hit as its own cluster
Repeatedly merging the two closest clusters until no pair is closer than the cutoff
Returning clusters that have at least seed_threshold energy

Template Parameters

HitType	The type of hit (e.g., EcalHit, HcalHit)
WeightClass	A functor with operator()(const WorkingCluster<HitType>&, const WorkingCluster<HitType>&) -> double

Definition at line 37 of file TemplatedClusterFinder.h.

Member Typedef Documentation

◆ ClusterType

template<class HitType , class WeightClass >

using recon::TemplatedClusterFinder< HitType, WeightClass >::ClusterType = WorkingCluster<HitType>

Definition at line 39 of file TemplatedClusterFinder.h.

Member Function Documentation

◆ add() [1/3]

template<class HitType , class WeightClass >

void recon::TemplatedClusterFinder< HitType, WeightClass >::add ( const HitType & hit )

inline

Add a hit to be clustered using its stored position.

Parameters

hit	Reference to the hit to add

Definition at line 46 of file TemplatedClusterFinder.h.

46{ clusters_.push_back(ClusterType(hit)); }

Referenced by ecal::EcalClusterProducer::produce(), and hcal::HcalClusterProducer::produce().

◆ add() [2/3]

template<class HitType , class WeightClass >

void recon::TemplatedClusterFinder< HitType, WeightClass >::add ( const HitType * hit )

inline

Add a hit to be clustered using its stored position.

Parameters

hit	Pointer to the hit to add

Definition at line 53 of file TemplatedClusterFinder.h.

                               {
    if (hit) {
      clusters_.push_back(ClusterType(hit));
    }
  }

◆ add() [3/3]

template<class HitType , class WeightClass >

void recon::TemplatedClusterFinder< HitType, WeightClass >::add	(	const HitType *	hit,
		double	x,
		double	y,
		double	z )

inline

Add a hit with explicit position (e.g., from geometry).

Parameters

hit	Pointer to the hit to add
x	X position
y	Y position
z	Z position

Definition at line 67 of file TemplatedClusterFinder.h.

                                                             {
    if (hit) {
      ClusterType cluster;
      cluster.add(hit, x, y, z);
      clusters_.push_back(cluster);
    }
  }

References recon::WorkingCluster< HitType >::add(), and recon::TemplatedClusterFinder< HitType, WeightClass >::cluster().

◆ cluster()

template<class HitType , class WeightClass >

void recon::TemplatedClusterFinder< HitType, WeightClass >::cluster	(	double	seed_threshold,
		double	cutoff )

inline

Run the clustering algorithm.

Parameters

seed_threshold	Minimum energy for a cluster to be considered a seed
cutoff	Maximum weight (distance) for merging two clusters

Definition at line 88 of file TemplatedClusterFinder.h.

                                                     {
    int ncluster = clusters_.size();
    double minwgt = cutoff;
 
    // Sort by energy (highest first)
    std::sort(clusters_.begin(), clusters_.end(), compClusters);
 
    loops_ = 0;
    do {
      bool any = false;
      size_t mi(0), mj(0);
      int nseeds = 0;
 
      for (size_t i = 0; i < clusters_.size(); i++) {
        if (clusters_[i].empty()) continue;
 
        bool iseed = (clusters_[i].energy() >= seed_threshold);
        if (iseed) {
          nseeds++;
        } else {
          // Since we sorted initially, if we find a hit below seed threshold
          // there will be no seeds after.
          break;
        }
 
        for (size_t j = i + 1; j < clusters_.size(); j++) {
          if (clusters_[j].empty() ||
              (!iseed && clusters_[j].energy() < seed_threshold))
            continue;
 
          double wgt = wgt_(clusters_[i], clusters_[j]);
          if (!any || wgt < minwgt) {
            any = true;
            minwgt = wgt;
            mi = i;
            mj = j;
          }
        }
      }
 
      nseeds_ = nseeds;
      transition_weights_.insert(std::pair<int, double>(ncluster, minwgt));
 
      if (any && minwgt < cutoff) {
        // Put the bigger one in mi
        if (clusters_[mi].energy() < clusters_[mj].energy()) {
          std::swap(mi, mj);
        }
        // Merge the smaller into the bigger
        clusters_[mi].add(clusters_[mj]);
        clusters_[mj].clear();
        // Decrement cluster count
        ncluster--;
      }
      loops_++;
    } while (minwgt < cutoff && ncluster > 1);
 
    finalwgt_ = minwgt;
 
    // Collect final clusters that pass the seed threshold
    for (const auto& cl : clusters_) {
      if (!cl.empty() && cl.energy() >= seed_threshold) {
        final_clusters_.push_back(cl);
      } else if (cl.energy() < seed_threshold) {
        break;  // Clusters are sorted, so safe to break
      }
    }
  }

References recon::TemplatedClusterFinder< HitType, WeightClass >::compClusters().

Referenced by recon::TemplatedClusterFinder< HitType, WeightClass >::add(), ecal::EcalClusterProducer::produce(), and hcal::HcalClusterProducer::produce().

◆ compClusters()

template<class HitType , class WeightClass >

static bool recon::TemplatedClusterFinder< HitType, WeightClass >::compClusters	(	const ClusterType &	a,
		const ClusterType &	b )

inlinestatic

Compare clusters by energy (descending order).

Definition at line 78 of file TemplatedClusterFinder.h.

                                                                       {
    return a.energy() > b.energy();
  }

References recon::WorkingCluster< HitType >::energy().

Referenced by recon::TemplatedClusterFinder< HitType, WeightClass >::cluster().

◆ getAllClusters()

template<class HitType , class WeightClass >

std::vector< ClusterType > recon::TemplatedClusterFinder< HitType, WeightClass >::getAllClusters ( ) const

inline

Get all clusters including empty ones (for debugging).

Definition at line 185 of file TemplatedClusterFinder.h.

185{ return clusters_; }

◆ getClusters()

template<class HitType , class WeightClass >

std::vector< ClusterType > recon::TemplatedClusterFinder< HitType, WeightClass >::getClusters ( ) const

inline

Get the final clusters after filtering by seed threshold.

Definition at line 180 of file TemplatedClusterFinder.h.

180{ return final_clusters_; }

Referenced by ecal::EcalClusterProducer::produce(), and hcal::HcalClusterProducer::produce().

◆ getNLoops()

template<class HitType , class WeightClass >

int recon::TemplatedClusterFinder< HitType, WeightClass >::getNLoops ( ) const

inline

Get the number of iterations performed.

Definition at line 170 of file TemplatedClusterFinder.h.

170{ return loops_; }

◆ getNSeeds()

template<class HitType , class WeightClass >

int recon::TemplatedClusterFinder< HitType, WeightClass >::getNSeeds ( ) const

inline

Get the number of seed clusters found.

Definition at line 165 of file TemplatedClusterFinder.h.

165{ return nseeds_; }

Referenced by ecal::EcalClusterProducer::produce().

◆ getWeights()

template<class HitType , class WeightClass >

std::map< int, double > recon::TemplatedClusterFinder< HitType, WeightClass >::getWeights ( ) const

inline

Get the transition weights (cluster count -> minimum weight at that step).

Definition at line 175 of file TemplatedClusterFinder.h.

175{ return transition_weights_; }

Referenced by ecal::EcalClusterProducer::produce().

◆ getYMax()

template<class HitType , class WeightClass >

double recon::TemplatedClusterFinder< HitType, WeightClass >::getYMax ( ) const

inline

Get the final weight (minimum distance between remaining clusters).

Definition at line 160 of file TemplatedClusterFinder.h.

160{ return finalwgt_; }

Member Data Documentation

◆ clusters_

template<class HitType , class WeightClass >

std::vector<ClusterType> recon::TemplatedClusterFinder< HitType, WeightClass >::clusters_

private

Definition at line 193 of file TemplatedClusterFinder.h.

◆ final_clusters_

template<class HitType , class WeightClass >

std::vector<ClusterType> recon::TemplatedClusterFinder< HitType, WeightClass >::final_clusters_

private

Definition at line 194 of file TemplatedClusterFinder.h.

◆ finalwgt_

template<class HitType , class WeightClass >

double recon::TemplatedClusterFinder< HitType, WeightClass >::finalwgt_ {0}

private

Definition at line 189 of file TemplatedClusterFinder.h.

189{0};

◆ loops_

template<class HitType , class WeightClass >

int recon::TemplatedClusterFinder< HitType, WeightClass >::loops_ {0}

private

Definition at line 191 of file TemplatedClusterFinder.h.

191{0};

◆ nseeds_

template<class HitType , class WeightClass >

int recon::TemplatedClusterFinder< HitType, WeightClass >::nseeds_ {0}

private

Definition at line 190 of file TemplatedClusterFinder.h.

190{0};

◆ transition_weights_

template<class HitType , class WeightClass >

std::map<int, double> recon::TemplatedClusterFinder< HitType, WeightClass >::transition_weights_

private

Definition at line 192 of file TemplatedClusterFinder.h.

◆ wgt_

template<class HitType , class WeightClass >

WeightClass recon::TemplatedClusterFinder< HitType, WeightClass >::wgt_

private

Definition at line 188 of file TemplatedClusterFinder.h.

The documentation for this class was generated from the following file:

Recon/include/Recon/TemplatedClusterFinder.h

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ ClusterType

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ cluster()

◆ compClusters()

◆ getAllClusters()

◆ getClusters()

◆ getNLoops()

◆ getNSeeds()

◆ getWeights()

◆ getYMax()

Member Data Documentation

◆ clusters_

◆ final_clusters_

◆ finalwgt_

◆ loops_

◆ nseeds_

◆ transition_weights_

◆ wgt_