clustering — Clustering

Module documentation

Clustering facilities.

class hexsample.clustering.Cluster(x: ndarray, y: ndarray, col: ndarray, row: ndarray, pha: ndarray, adc_to_ev: float, pos_recon_algorithm: str, recon_pars: dict | None = None)

Small container class describing a cluster.

x: ndarray

y: ndarray

col: ndarray

row: ndarray

pha: ndarray

adc_to_ev: float

pos_recon_algorithm: str

recon_pars: dict | None = None

size() → int

Return the size of the cluster.

pulse_height() → float

Return the total pulse height of the cluster.

energy() → float

Return the energy of the cluster in eV.

centroid() → Tuple[float, float]

Return the cluster centroid.

eta(position_cal: PositionCalibrationData, pitch: float) → Tuple[float, float]

Return the cluster reconstructed position using the eta function calibrated for 2 and 3 pixel clusters.

Note

If cluster size is not 2 or 3, the position is reconstructed using the centroid algorithm.

Arguments

position_calPositionCalibrationData

The position calibration data containing the parameters for the eta reconstruction algorithm.

pitchfloat

The pixel pitch.

mle(position_cal: PositionCalibrationData, noise_matrix: CalibrationMatrix, equalization_matrix: CalibrationMatrix, pitch: float) → Tuple[float, float]

Return the cluster reconstructed position using the maximum likelihood estimator.

Arguments

mle_dataMLECalibrationData

The MLE calibration data containing the precomputed charge fraction matrices and other relevant information.

noise_matrixCalibrationMatrix

The noise calibration matrix containing the equalized noise standard deviation for each pixel.

equalization_matrixCalibrationMatrix

The equalization calibration matrix containing the gain correction for each pixel.

pitchfloat

The pixel pitch.

position() → Tuple[float, float]

Return the cluster reconstructed position using the position reconstruction algorithm specified in the constructor.

class hexsample.clustering.ClusteringBase(readout: HexagonalReadoutBase, zero_sup_threshold: float)

Base class for the clustering.

readout: HexagonalReadoutBase

zero_sup_threshold: float

static zero_suppress(array: ndarray, threshold: ndarray) → ndarray

Zero suppress a generic array.

position_suppress(pha: ndarray, col: ndarray, row: ndarray) → Tuple[ndarray, ndarray, ndarray]

Suppress pixels in the cluster that do not satisfy the position requirements.

If the cluster contains 2 or fewer pixels, no action is taken. For clusters with more than 2 pixels, the algorithm retains the two most charged pixels and only one additional neighbor (the one with the highest charge) of the second pixel, discarding all others.

Arguments

phanp.ndarray

The array of pulse heights of the pixels in the cluster, ordered in decreasing order.

colnp.ndarray

The array of column indexes of the pixels in the cluster.

rownp.ndarray

The array of row indexes of the pixels in the cluster.

Returns

phanp.ndarray

The array of pulse heights of the pixels in the cluster after position suppression, ordered in decreasing order.

colnp.ndarray

The array of column indexes of the pixels in the cluster after position suppression, ordered in decreasing order of pulse height.

rownp.ndarray

The array of row indexes of the pixels in the cluster after position suppression, ordered in decreasing order of pulse height.

run(event: DigiEventRectangular) → Cluster

Workhorse method to be reimplemented by derived classes.

class hexsample.clustering.ClusteringNN(readout: HexagonalReadoutBase, zero_sup_threshold: float, num_neighbors: int, pos_recon_algorithm: str, recon_pars: dict | None = None)

Neirest neighbor clustering.

This is a very simple clustering strategy where we use the highest pixel in the event as a seed, loop over the six neighbors (after the zero suppression) and keep the N highest pixels.

Arguments

num_neighborsint

The number of neighbors (between 0 and 6) to include in the cluster.

pos_recon_algorithmstr

The position reconstruction algorithm to use for the cluster position reconstruction. Possible values are “centroid” and “eta”.

recon_parsdict, optional

The parameters for the position reconstruction algorithm. This is not required if pos_recon_algorithm is “centroid”.

num_neighbors: int

pos_recon_algorithm: str

recon_pars: dict | None = None

run(event) → Cluster | None

Overloaded method.

Warning

The loop ever the neighbors might likely be vectorized and streamlined for speed using proper numpy array for the offset indexes.

class hexsample.clustering.ClusteringHex(readout: HexagonalReadoutBase, zero_sup_threshold: float, pos_recon_algorithm: str = 'mle', recon_pars: dict = None)

Hexagonal clustering.

This clustering strategy always takes the six neighbors of the seed pixel, without applying any position suppression. The order of the pixels is fixed, with the seed pixel always in the first position, and the neighbors ordered clockwise, depending on the readout geometry.

Arguments

pos_recon_algorithmstr

The position reconstruction algorithm to use for the cluster position reconstruction. Possible values are “centroid” and “mle”.

recon_parsdict, optional

Dictionary containing the parameters for the position reconstruction algorithm.

pos_recon_algorithm: str = 'mle'

recon_pars: dict = None

run(event) → Cluster | None

Overladed method.