Cleaned up Pedestal (#370)

- renamed pedestal.hpp to bind_Pedestal.hpp for python bindings
- variance is now always calculated in double and made private
- cost correctness in a few places
- removed push_fast and explicit updates of mean from Pedestal. If
performance is needed use FastPedestal
- Pedestal no longer caches std

python/src/bind_FastPedestal.hpp

@@ -15,8 +15,7 @@ void define_fast_pedestal_bindings(py::module &m, const std::string &name) {
 
     py::class_<FastPedestal<SUM_TYPE>>(
         m, name.c_str(),
-        "Maintain a per-pixel running mean, population variance, and "
-        "standard deviation.",
+        "Maintain a per-pixel running mean and population standard deviation.",
         py::buffer_protocol())
         .def(py::init<uint32_t, uint32_t, uint32_t>(), py::arg("rows"),
              py::arg("cols"), py::arg("n_samples"),
@@ -33,15 +32,6 @@ void define_fast_pedestal_bindings(py::module &m, const std::string &name) {
                 return return_image_data(mean);
             },
             "Return a copy of the cached mean. The pedestal must be ready.")
-        .def(
-            "var",
-            [](FastPedestal<SUM_TYPE> &self) {
-                auto variance = new NDArray<SUM_TYPE, 2>{};
-                *variance = self.variance();
-                return return_image_data(variance);
-            },
-            "Return the population variance, normalized by n_samples, as a "
-            "NumPy array. The pedestal must be ready.")
         .def(
             "std",
             [](FastPedestal<SUM_TYPE> &self) {

python/src/bind_Pedestal.hpp

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: MPL-2.0
+
+#include "aare/Pedestal.hpp"
+#include "np_helper.hpp"
+
+#include <cstdint>
+#include <filesystem>
+#include <pybind11/numpy.h>
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+namespace py = pybind11;
+
+template <typename SUM_TYPE>
+void define_pedestal_bindings(py::module &m, const std::string &name) {
+
+    py::class_<Pedestal<SUM_TYPE>>(
+        m, name.c_str(),
+        "Maintain a per-pixel running mean and population standard deviation. "
+        "Statistics are available during initialization and are zero for empty "
+        "pixels.",
+        py::buffer_protocol())
+        .def(py::init<uint32_t, uint32_t, uint32_t>(), py::arg("rows"),
+             py::arg("cols"), py::arg("n_samples"),
+             "Construct an empty pedestal. Each pixel accumulates n_samples "
+             "values before switching to exponential updates.")
+        .def(py::init<uint32_t, uint32_t>(), py::arg("rows"), py::arg("cols"),
+             "Construct an empty pedestal with n_samples=1000.")
+        .def(
+            "mean",
+            [](Pedestal<SUM_TYPE> &self) {
+                auto mea = new NDArray<SUM_TYPE, 2>{};
+                *mea = self.mean();
+                return return_image_data(mea);
+            },
+            "Return a copy of the cached mean. Empty pixels return zero.")
+        .def(
+            "view",
+            [](py::object self_py) {
+                return py::module_::import("numpy").attr("asarray")(self_py);
+            },
+            "Return a non-owning, non-writable NumPy view of the cached mean.")
+        .def(
+            "std",
+            [](Pedestal<SUM_TYPE> &self) {
+                auto std = new NDArray<SUM_TYPE, 2>{};
+                *std = self.std();
+                return return_image_data(std);
+            },
+            "Return the population standard deviation as a NumPy array. "
+            "Empty pixels return zero.")
+        .def(
+            "__array_ufunc__",
+            [](py::object self, py::object ufunc, const std::string &method,
+               py::args inputs, py::kwargs kwargs) -> py::object {
+                if (method != "__call__" || inputs.size() != 2 ||
+                    inputs[1].ptr() != self.ptr() ||
+                    py::cast<std::string>(ufunc.attr("__name__")) !=
+                        "subtract") {
+                    return py::reinterpret_borrow<py::object>(
+                        Py_NotImplemented);
+                }
+
+                auto mean =
+                    py::module_::import("builtins").attr("memoryview")(self);
+                return ufunc(inputs[0], mean, **kwargs);
+            },
+            "Support subtracting a Pedestal from a NumPy array.")
+        .def("clear", py::overload_cast<>(&Pedestal<SUM_TYPE>::clear),
+             "Reset all statistics and per-pixel sample counts to zero.")
+        .def_property_readonly("rows", &Pedestal<SUM_TYPE>::rows,
+                               "Number of image rows.")
+        .def_property_readonly("cols", &Pedestal<SUM_TYPE>::cols,
+                               "Number of image columns.")
+        .def_property_readonly(
+            "n_samples", &Pedestal<SUM_TYPE>::n_samples,
+            "Initialization sample count per pixel and steady-state "
+            "update-weight denominator.")
+        .def(
+            "clone",
+            [&](Pedestal<SUM_TYPE> &pedestal) {
+                return Pedestal<SUM_TYPE>(pedestal);
+            },
+            "Return an independent copy of the pedestal and its state.")
+        // TODO! add push for other data types
+        .def(
+            "push",
+            [](Pedestal<SUM_TYPE> &pedestal,
+               py::array_t<uint16_t, py::array::c_style> &f) {
+                if (f.ndim() != 2) {
+                    throw py::value_error("Frame must be 2-dimensional");
+                }
+                auto v = make_view_2d(f);
+                pedestal.push(v);
+            },
+            py::arg("frame").noconvert(),
+            "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.")
+        .def(
+            "push_with_threshold",
+            [](Pedestal<SUM_TYPE> &pedestal,
+               py::array_t<uint16_t, py::array::c_style> &f,
+               py::array_t<SUM_TYPE, py::array::c_style> &threshold) {
+                if (f.ndim() != 2) {
+                    throw py::value_error("Frame must be 2-dimensional");
+                }
+                if (threshold.ndim() != 2) {
+                    throw py::value_error("Threshold must be 2-dimensional");
+                }
+                auto frame_view = make_view_2d(f);
+                auto threshold_view = make_view_2d(threshold);
+                pedestal.push_with_threshold(frame_view, threshold_view);
+            },
+            py::arg("frame").noconvert(), py::arg("threshold").noconvert(),
+            "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.")
+        .def_buffer([](Pedestal<SUM_TYPE> &self) {
+            auto mean = self.view();
+            return py::buffer_info(
+                const_cast<SUM_TYPE *>(mean.data()), sizeof(SUM_TYPE),
+                py::format_descriptor<SUM_TYPE>::format(), 2,
+                {static_cast<py::ssize_t>(mean.shape(0)),
+                 static_cast<py::ssize_t>(mean.shape(1))},
+                {static_cast<py::ssize_t>(mean.strides()[0] * sizeof(SUM_TYPE)),
+                 static_cast<py::ssize_t>(mean.strides()[1] *
+                                          sizeof(SUM_TYPE))},
+                true);
+        });
+}

python/src/module.cpp

@@ -16,6 +16,7 @@
 #include "bind_FastPedestal.hpp"
 #include "bind_Interpolator.hpp"
 #include "bind_MultiThreadedFileReader.hpp"
+#include "bind_Pedestal.hpp"
 #include "bind_PedestalTrackingPixelHistogram.hpp"
 #include "bind_PixelHistogram.hpp"
 #include "bind_PixelMap.hpp"
@@ -27,7 +28,6 @@
 #include "file.hpp"
 #include "fit.hpp"
 #include "jungfrau_data_file.hpp"
-#include "pedestal.hpp"
 #include "raw_master_file.hpp"
 #include "raw_sub_file.hpp"
 #include "var_cluster.hpp"

python/src/pedestal.hpp

@@ -1,125 +0,0 @@
-// SPDX-License-Identifier: MPL-2.0
-
-#include "aare/Pedestal.hpp"
-#include "np_helper.hpp"
-
-#include <cstdint>
-#include <filesystem>
-#include <pybind11/numpy.h>
-#include <pybind11/pybind11.h>
-#include <pybind11/stl.h>
-
-namespace py = pybind11;
-
-template <typename SUM_TYPE>
-void define_pedestal_bindings(py::module &m, const std::string &name) {
-
-    py::class_<Pedestal<SUM_TYPE>>(m, name.c_str(), py::buffer_protocol())
-        .def(py::init<int, int, int>())
-        .def(py::init<int, int>())
-        .def("mean",
-             [](Pedestal<SUM_TYPE> &self) {
-                 auto mea = new NDArray<SUM_TYPE, 2>{};
-                 *mea = self.mean();
-                 return return_image_data(mea);
-             })
-        .def("view",
-             [](py::object self_py) {
-                 auto &self = self_py.cast<Pedestal<SUM_TYPE> &>();
-                 auto v = self.view();
-                 std::array<py::ssize_t, 2> shape{
-                     static_cast<py::ssize_t>(v.shape(0)),
-                     static_cast<py::ssize_t>(v.shape(1))};
-                 std::array<py::ssize_t, 2> byte_strides{
-                     static_cast<py::ssize_t>(v.strides()[0]) *
-                         static_cast<py::ssize_t>(sizeof(SUM_TYPE)),
-                     static_cast<py::ssize_t>(v.strides()[1]) *
-                         static_cast<py::ssize_t>(sizeof(SUM_TYPE))};
-                 auto arr = py::array_t<SUM_TYPE>(shape, byte_strides, v.data(),
-                                                  self_py);
-                 arr.attr("setflags")(py::arg("write") = false);
-                 return arr;
-             })
-        .def("variance",
-             [](Pedestal<SUM_TYPE> &self) {
-                 auto var = new NDArray<SUM_TYPE, 2>{};
-                 *var = self.variance();
-                 return return_image_data(var);
-             })
-        .def("std",
-             [](Pedestal<SUM_TYPE> &self) {
-                 auto std = new NDArray<SUM_TYPE, 2>{};
-                 *std = self.std();
-                 return return_image_data(std);
-             })
-        .def("cached_std",
-             [](Pedestal<SUM_TYPE> &self) {
-                 auto standard_deviation = new NDArray<SUM_TYPE, 2>{};
-                 *standard_deviation = self.cached_std();
-                 return return_image_data(standard_deviation);
-             })
-        .def(
-            "__array_ufunc__",
-            [](py::object self, py::object ufunc, const std::string &method,
-               py::args inputs, py::kwargs kwargs) -> py::object {
-                if (method != "__call__" || inputs.size() != 2 ||
-                    inputs[1].ptr() != self.ptr() ||
-                    py::cast<std::string>(ufunc.attr("__name__")) !=
-                        "subtract") {
-                    return py::reinterpret_borrow<py::object>(
-                        Py_NotImplemented);
-                }
-
-                auto mean =
-                    py::module_::import("builtins").attr("memoryview")(self);
-                return ufunc(inputs[0], mean, **kwargs);
-            },
-            "Support subtracting a Pedestal from a NumPy array.")
-        .def("clear", py::overload_cast<>(&Pedestal<SUM_TYPE>::clear))
-        .def_property_readonly("rows", &Pedestal<SUM_TYPE>::rows)
-        .def_property_readonly("cols", &Pedestal<SUM_TYPE>::cols)
-        .def_property_readonly("n_samples", &Pedestal<SUM_TYPE>::n_samples)
-        .def_property_readonly("sum", &Pedestal<SUM_TYPE>::get_sum)
-        .def_property_readonly("sum2", &Pedestal<SUM_TYPE>::get_sum2)
-        .def("clone",
-             [&](Pedestal<SUM_TYPE> &pedestal) {
-                 return Pedestal<SUM_TYPE>(pedestal);
-             })
-        // TODO! add push for other data types
-        .def("push",
-             [](Pedestal<SUM_TYPE> &pedestal, py::array_t<uint16_t> &f) {
-                 auto v = make_view_2d(f);
-                 pedestal.push(v);
-             })
-        .def(
-            "push_with_threshold",
-            [](Pedestal<SUM_TYPE> &pedestal,
-               py::array_t<uint16_t, py::array::c_style> &f,
-               py::array_t<SUM_TYPE, py::array::c_style> &threshold) {
-                auto frame_view = make_view_2d(f);
-                auto threshold_view = make_view_2d(threshold);
-                pedestal.push_with_threshold(frame_view, threshold_view);
-            },
-            py::arg("frame").noconvert(), py::arg("threshold").noconvert())
-        .def(
-            "push_no_update",
-            [](Pedestal<SUM_TYPE> &pedestal,
-               py::array_t<uint16_t, py::array::c_style> &f) {
-                auto v = make_view_2d(f);
-                pedestal.push_no_update(v);
-            },
-            py::arg().noconvert())
-        .def("update_mean", &Pedestal<SUM_TYPE>::update_mean)
-        .def_buffer([](Pedestal<SUM_TYPE> &self) {
-            auto mean = self.view();
-            return py::buffer_info(
-                const_cast<SUM_TYPE *>(mean.data()), sizeof(SUM_TYPE),
-                py::format_descriptor<SUM_TYPE>::format(), 2,
-                {static_cast<py::ssize_t>(mean.shape(0)),
-                 static_cast<py::ssize_t>(mean.shape(1))},
-                {static_cast<py::ssize_t>(mean.strides()[0] * sizeof(SUM_TYPE)),
-                 static_cast<py::ssize_t>(mean.strides()[1] *
-                                          sizeof(SUM_TYPE))},
-                true);
-        });
-}