5.2.1   computeStatistics¶

The externally visible computeStatistics function calls an internal detail::translateOptions, which has a series of overloads that reduce runtime function arguments to compile-time template parameters. At the end of this series this results in a call to detail::computeStatistics.

namespace detail {

template <bool useMask, bool useWeight, bool useVariance, bool computeRange, bool computeMedian,
          bool sigmaClipped, typename ImageT, typename MaskT, typename WeightT, typename VarianceT>
StatisticsResult computeStatistics(ImageT const &img, MaskT const &msk, WeightT const &wgt,
                          VarianceT const &var, NewStatisticsControl const &sctrl);

}  // namespace detail

At this point one run (or multiple runs in case of sigma clipping) of SinglePassStatistics are performed and the results are returned.

5.2.2   SinglePassStatistics¶

The default runner is SinglePassStatistics. This implementation uses pairwise summation (combination) down to a baseCaseSize after which it performs a simple linear run through the data. Internally it keeps one instance of Algorithm::ExternalData which is passed to the Algorithm::collect and Algorithm::reduce functions (by reference) where needed.

It takes the following template parameters:

• Validator: A functor that takes image, mask, weight and variance arguments and returns true if the value is to be clipped, or false otherwise.
• Algorithm: The statistics algorithm to execute.

Constructors:

• explicit SinglePassStatistics(const Validator &validator = Validator(), size_t baseCaseSize = 100) Copies of both input parameters are held as private members.
• default copy and move constructors (as well as copy and move assignment operators).

Member functions and operators:

• operator(): Run Algorithm once on provided img, msk, wgt and var using pairwise summation / combination.

template <typename ImageT, typename MaskT, typename WeightT, typename VarianceT,
          typename... AlgorithmArgs>
StatisticsResult operator()(ImageT const &img, MaskT const &msk, WeightT const &wgt,
                  VarianceT const &var);

5.2.3   StandardStatistics¶

The default algorithm is represented by the StandardStatistics class which has the following API

Member type:

• ExternalData : Algorithm specific data that has to be stored across different instances of StandardStatistics, to be provided by the runner.

Template Parameters:

• useMask, bool : Use the provided mask (assume msk is UnusedParameter if not)
• useWeight, bool : Use the provided weights (assume wgt is UnusedParameter if not)
• useVariance, bool : Use the provided variance (assume var is UnusedParameter if not)
• computeRange, bool : Compute min and max values (can be split if desired)
• computeMedian, bool : Compute the median (requires ExternalData to store a copy of good pixel values)

Constructors:

• Default constructor, default copy and move constructors (as well as copy and move assignment operators).

Member functions:

• collect: Gather intermediate products, can be run multiple times to accumulate one or more values.

  template <typename ImageIter, typename MaskIter, typename WeightIter, typename VarianceIter,
            typename Validator>
  void collect(ImageIter img, MaskIter msk, WeightIter wgt, VarianceIter var, size_t n,
               Validator const &validator, ExternalData &externalData);
  

• reduce: Compute intermediate results (e.g. mean, median, or variance, but not stdev which is computed lazily from the variance)

  StatisticsResult reduce(ExternalData &externalData);
  

• combineWith: Combine intermediate products.

  void combineWith(const StandardStatistics &rhs);
  

5.2.4   Validators¶

During a run of Algorithm::collect each set of img, msk, wgt and var values is passed to the provided Validator functor. If its return value is false the pixel is clipped.

Validators are composable. The makeCombinedChecker variadic function creates a single validator out of its provided arguments.

It does this by nesting instances of CheckBoth which itself takes two template arguments First and Second and has an operator() that returns the logical and of First::operator() and Second::operator().

The following building blocks are provided:

• AlwaysTrue: always returns true;
• AlwaysFalse: always returns false;
• CheckMask: returns bitwise and of msk value with mask argument provided at construction;
• CheckFinite: returns true if img is finite (e.g. not NaN or infinity);
• CheckRange: returns true if img is within the interval center +/- limit where center and limit are provided at construction.

5.2.5   Unused parameters¶

Unused parameters (for msk, wgt or var) are given as nullptr (C++) or None (Python) in the API, but for lower layers are given as instances of UnusedParameter. A fake vector / iterator that does nothing. This makes the inner loop in Algorithm::collect straightforward while compiling away into non-existence..