counting module

counting.py

Functions for the Back-Propagation Counting method.

This module provides tools to process pixelated silicon detector data, including prior computation, frame counting using PyTorch optimization, and storage in HDF5 format.

counting.compute_conditional_probabilities(lam_grid)[source]

Compute conditional probabilities P(n >= 2 | n >= 1) for a grid of “lambda” values (average electron hit probabilities).

Parameters:

lam_grid (ndarray) – A numpy array of lambda values (Poisson parameter).

Returns:

A numpy array of conditional probabilities P(n >= 2 | n >= 1).

Return type:

ndarray

Notes

Uses the Poisson distribution to calculate probabilities, with safeguards against division by zero.

counting.compute_prior(frames_file, nframes, baseline, gauss_A)[source]

Compute the “prior” from a set of frames. The prior consists of the average number of electron hits at each pixel in the frame and has the same dimensions as a single frame.

Parameters:

  • frames_file (str) – Path to the HDF5 file containing the frames dataset.

  • nframes (int) – Number of frames to use for computing the prior.

  • baseline (float) – Baseline value to subtract from each frame.

  • gauss_A (float) – Amplitude of the Gaussian profile for a single electron.

Returns:

The computed “prior” frame.

Return type:

ndarray

Notes

The prior is computed by summing frames, normalizing, and eliminating negative values.

counting.construct_modeled_frame_pytorch(frame_ct, splash_kernel)[source]

Construct a frame from the count grid by applying a Gaussian electron strike profile (kernel) via convolution.

Parameters:

  • frame_ct (torch.Tensor) – The count grid tensor (batch of 2D arrays).

  • splash_kernel (torch.Tensor) – The Gaussian kernel for convolution.

Returns:

The modeled frame after applying the Gaussian splash.

Return type:

torch.Tensor

counting.count_frame_pytorch(frame_bls, frame_ct, gauss_A, gauss_sigma, n_steps_max=5000, loss_lim=1, min_loss_patience=10, min_loss_improvement=0.01)[source]

Count electrons in a frame using PyTorch optimization.

Parameters:

  • frame_bls (ndarray) – Baseline-subtracted frame data.

  • frame_ct (ndarray) – Initial guess for the counted frame.

  • gauss_A (float) – Amplitude of the Gaussian profile.

  • gauss_sigma (float) – Standard deviation of the Gaussian profile.

  • n_steps_max (int, optional) – Maximum number of optimization steps (default: 5000).

  • loss_lim (float, optional) – Loss threshold to stop optimization (default: 1).

  • min_loss_patience (int, optional) – Number of steps to wait for loss improvement (default: 10).

  • min_loss_improvement (float, optional) – Minimum relative loss improvement to continue (default: 0.01).

Returns:

  • ndarray: The counted frame.

  • ndarray: The modeled frame, which is the counted frame convoluted with the Gaussian profile (kernel).

  • ndarray: Loss values at each step.

Return type:

tuple

counting.count_frames(frames_file, counted_file, frames_per_batch, th_single_elec, baseline, gauss_A, gauss_sigma, n_steps_max=5000, loss_per_frame_stop=1, min_loss_patience=10, min_loss_improvement=0.01, batch_start=0, batch_end=-1, nframes_prior=0, record_loss_curves=True)[source]

Count electrons in frames and save results to an HDF5 file.

Parameters:

  • frames_file (str) – Path to the input HDF5 file with raw frames.

  • counted_file (str) – Path to the output HDF5 file for counted data.

  • frames_per_batch (int) – Number of frames to process per batch.

  • th_single_elec (float) – Threshold for single electron detection.

  • baseline (float) – Baseline value to subtract from frames.

  • gauss_A (float) – Gaussian amplitude for electron profile.

  • gauss_sigma (float) – Gaussian standard deviation for electron profile.

  • n_steps_max (int, optional) – Maximum optimization steps (default: 5000).

  • loss_per_frame_stop (float, optional) – Loss per frame threshold to stop (default: 1).

  • min_loss_patience (int, optional) – Patience for loss improvement (default: 10).

  • min_loss_improvement (float, optional) – Minimum loss improvement (default: 0.01).

  • batch_start (int, optional) – Starting batch index (default: 0).

  • batch_end (int, optional) – Ending batch index (default: -1, meaning all batches).

  • nframes_prior (int, optional) – Number of frames for prior computation (default: 0).

  • record_loss_curves (bool, optional) – Whether to record loss curves (default: True).

Returns:

  • list: Loss curves for each batch.

  • ndarray: Last batch’s counted frames.

  • ndarray: Last batch’s modeled frames (counted frames convoluted with Gaussian profile).

Return type:

tuple

counting.frame_to_indices_weights(counted_frames)[source]

Convert counted frames to lists of linear indices and weights.

Parameters:

counted_frames (ndarray) – Batch of 2D counted frames.

Returns:

  • list: Linear indices of non-zero pixels for each frame.

  • list: Weights (counts) at those indices.

Return type:

tuple

counting.gaussian_splash_pytorch(A, sigma, size=3)[source]

Create a Gaussian “splash” kernel for convolution in PyTorch.

Parameters:

  • A (float) – Amplitude of the Gaussian.

  • sigma (float) – Standard deviation of the Gaussian.

  • size (int, optional) – Size of the kernel (default: 3).

Returns:

4D tensor representing the Gaussian kernel.

Return type:

torch.Tensor

counting.update_counted_data_hdf5(file_path, nframes, batch_start_idx, frames_indices, frames_weights, scan_shape, frame_shape, group_name='electron_events')[source]

Update an HDF5 file with counted frame data.

Parameters:

  • file_path (str) – Path to the HDF5 file.

  • nframes (int) – Total number of frames.

  • batch_start_idx (int) – Starting index for the current batch.

  • frames_indices (list) – List of arrays with pixel indices for each frame.

  • frames_weights (list) – List of arrays with weights for each frame.

  • scan_shape (tuple) – Shape of the scan grid (Ny, Nx).

  • frame_shape (tuple) – Shape of each frame (Ny, Nx).

  • group_name (str, optional) – HDF5 group name (default: ‘electron_events’).