Pedestal¶

Pedestal calculates a running mean and population standard deviation for each pixel in a series of uint16 frames. push() updates the cached mean immediately; std() calculates the noise from the current statistics.

push() and push_with_threshold() require C-contiguous, two-dimensional NumPy frames with dtype uint16 and shape matching the pedestal. push_with_threshold() also requires a C-contiguous, two-dimensional threshold array with the pedestal’s output dtype and shape. Noncontiguous inputs raise TypeError; inputs with the wrong number of dimensions raise ValueError. Mismatched frame or threshold shapes raise RuntimeError. Use numpy.ascontiguousarray() to copy a sliced or transposed array into the required layout when needed.

Internal sums and sums of squares always use float64. Three specializations are available from aare for the mean and standard deviation output types:

Pedestal_d returns float64
Pedestal_f returns float32
Pedestal_i16 returns int16

The public Pedestal factory selects the specialization from dtype, defaulting to numpy.float64.

Constructor dimensions and n_samples must be positive integers. Negative values raise TypeError and zero values raise RuntimeError. Internally, negative variance caused by floating-point roundoff is clamped to zero before taking its square root, keeping the standard deviation finite for nearly constant inputs. Only the final standard deviation is converted to the output dtype.

Factory¶

aare.Pedestal(rows, cols, n_samples=1000, dtype=<class 'numpy.float64'>)¶

Create an empty per-pixel running pedestal.

This factory hides the dtype suffix used by the templated C++ bindings. Call push() to update the statistics and cached mean for each frame. Statistics are available during initialization and are zero for empty pixels. Internal moments and variance always use double precision.

Parameters:

rows – Number of image rows.
cols – Number of image columns.
n_samples – Number of samples accumulated before switching to steady-state updates with weight 1 / n_samples.
dtype – Output dtype for the mean and standard deviation. Supported values are np.float64, np.float32, and np.int16.

Example¶

import numpy as np
from aare import Pedestal

pedestal = Pedestal(512, 1024, n_samples=100, dtype=np.float32)

for frame in initialization_frames:
    pedestal.push(frame)

mean = pedestal.mean()
noise = pedestal.std()

Complete API¶

The API below is for the float64 specialization. All dtype variants share the same API.

class aare._aare.Pedestal_d¶

Bases: pybind11_object

Maintain a per-pixel running mean and population standard deviation. Statistics are available during initialization and are zero for empty pixels.

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: aare._aare.Pedestal_d, rows: typing.SupportsInt | typing.SupportsIndex, cols: typing.SupportsInt | typing.SupportsIndex, n_samples: typing.SupportsInt | typing.SupportsIndex) -> None

Construct an empty pedestal. Each pixel accumulates n_samples values before switching to exponential updates.

__init__(self: aare._aare.Pedestal_d, rows: typing.SupportsInt | typing.SupportsIndex, cols: typing.SupportsInt | typing.SupportsIndex) -> None

Construct an empty pedestal with n_samples=1000.

clear(self: aare._aare.Pedestal_d) → None¶: Reset all statistics and per-pixel sample counts to zero.

clone(self: aare._aare.Pedestal_d) → aare._aare.Pedestal_d¶: Return an independent copy of the pedestal and its state.

property cols¶: Number of image columns.

mean(self: aare._aare.Pedestal_d) → numpy.ndarray¶: Return a copy of the cached mean. Empty pixels return zero.

property n_samples¶: Initialization sample count per pixel and steady-state update-weight denominator.

push(self: aare._aare.Pedestal_d, frame: numpy.typing.NDArray[numpy.uint16]) → None¶: Accumulate or exponentially update every pixel from a C-contiguous uint16 frame matching the pedestal shape. After n_samples values per pixel, new values have weight 1 / n_samples.

push_with_threshold(self: aare._aare.Pedestal_d, frame: numpy.typing.NDArray[numpy.uint16], threshold: numpy.typing.NDArray[numpy.float64]) → None¶: Push only pixels where abs(frame - mean) is strictly less than threshold. Both arrays must be C-contiguous with the pedestal shape; frame must be uint16 and threshold must use the output dtype. Rejected pixels keep their statistics and sample counts.

property rows¶: Number of image rows.

std(self: aare._aare.Pedestal_d) → numpy.ndarray¶: Return the population standard deviation as a NumPy array. Empty pixels return zero.

view(self: object) → object¶: Return a non-owning, non-writable NumPy view of the cached mean.