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

docs/src/python/pedestal/pyFastPedestal.rst

@@ -1,7 +1,7 @@
 FastPedestal
 ============
 
-``FastPedestal`` calculates a running mean, variance and standard deviation for each pixel in a
+``FastPedestal`` calculates a running mean and standard deviation for each pixel in a
 series of frames. The python binding only exposes ``uint16`` input but the underlying
 C++ class is templated. Initialize it with ``n_samples`` frames using
 ``add_init_frame()``. Once ``ready`` is true, use ``push_ema()`` to update the exponential 
@@ -18,7 +18,10 @@ The public factory selects the bound C++ specialization from ``dtype``:
 * ``numpy.float32`` creates ``FastPedestal_f``
 * ``numpy.int16`` creates ``FastPedestal_i16``
 
-The internal calculations are done with double, but the cached mean and on demand var and std are returned in the specified type.
+Internal moments and variance are calculated in double precision. Variance is
+private and stays in double precision through the square root; the cached mean
+and on-demand standard deviation are returned in the specified type. Negative
+variance caused by floating-point roundoff is clamped to zero.
 
 Factory
 -------

docs/src/python/pedestal/pyPedestal.rst

@@ -1,30 +1,57 @@
 Pedestal
 ========
 
-``Pedestal`` calculates a running mean and variance for each pixel in a series
-of ``uint16`` frames. ``push()`` updates the cached mean immediately. For
-faster batch initialization, use ``push_no_update()`` for each frame and call
-``update_mean()`` after the batch.
+``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.
 
-Three specializations are available from :mod:`aare`:
+``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.
 
-* ``Pedestal_d`` uses ``float64`` storage
-* ``Pedestal_f`` uses ``float32`` storage
-* ``Pedestal_i16`` uses ``int16`` storage
+Internal sums and sums of squares always use ``float64``. Three
+specializations are available from :mod:`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
+-------
+
+.. py:currentmodule:: aare
+
+.. autofunction:: Pedestal
 
 Example
 -------
 
 .. code-block:: python
 
-   from aare import Pedestal_d
+   import numpy as np
+   from aare import Pedestal
 
-   pedestal = Pedestal_d(512, 1024, 100)
+   pedestal = Pedestal(512, 1024, n_samples=100, dtype=np.float32)
 
    for frame in initialization_frames:
-       pedestal.push_no_update(frame)
+       pedestal.push(frame)
 
-   pedestal.update_mean()
    mean = pedestal.mean()
    noise = pedestal.std()