lsst.afw  21.0.0-44-ge87b71154+532d44eec1
Statistics.h
Go to the documentation of this file.
1 // -*- LSST-C++ -*-
2 
3 /*
4  * LSST Data Management System
5  * Copyright 2008, 2009, 2010 LSST Corporation.
6  *
7  * This product includes software developed by the
8  * LSST Project (http://www.lsst.org/).
9  *
10  * This program is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the LSST License Statement and
21  * the GNU General Public License along with this program. If not,
22  * see <http://www.lsstcorp.org/LegalNotices/>.
23  */
24 
25 #if !defined(LSST_AFW_MATH_STATISTICS_H)
26 #define LSST_AFW_MATH_STATISTICS_H
37 #include <algorithm>
38 #include <cassert>
39 #include <limits>
40 #include "boost/iterator/iterator_adaptor.hpp"
41 #include "boost/tuple/tuple.hpp"
42 #include <memory>
45 
46 namespace lsst {
47 namespace afw {
48 namespace image {
49 template <typename>
50 class Image;
51 template <typename, typename, typename>
52 class MaskedImage;
53 } // namespace image
54 namespace math {
55 template <typename>
56 class MaskedVector; // forward declaration
57 
58 typedef lsst::afw::image::VariancePixel WeightPixel; // Type used for weights
59 
63 enum Property {
64  NOTHING = 0x0,
65  ERRORS = 0x1,
66  NPOINT = 0x2,
67  MEAN = 0x4,
68  STDEV = 0x8,
69  VARIANCE = 0x10,
70  MEDIAN = 0x20,
71  IQRANGE = 0x40,
72  MEANCLIP = 0x80,
73  STDEVCLIP = 0x100,
74  VARIANCECLIP = 0x200,
76  MIN = 0x400,
77  MAX = 0x800,
78  SUM = 0x1000,
79  MEANSQUARE = 0x2000,
80  ORMASK = 0x4000,
81  NCLIPPED = 0x8000,
82  NMASKED = 0x10000
83 };
86 
94 public:
95  enum WeightsBoolean { WEIGHTS_FALSE = 0, WEIGHTS_TRUE = 1, WEIGHTS_NONE }; // initial state is NONE
96 
97  StatisticsControl(double numSigmaClip = 3.0,
98  int numIter = 3,
100  0x0,
101  bool isNanSafe = true,
102  WeightsBoolean useWeights =
103  WEIGHTS_NONE
104  )
105  : _numSigmaClip(numSigmaClip),
106  _numIter(numIter),
107  _andMask(andMask),
108  _noGoodPixelsMask(0x0),
109  _isNanSafe(isNanSafe),
110  _useWeights(useWeights),
111  _calcErrorFromInputVariance(false),
112  _maskPropagationThresholds() {
113  try {
114  _noGoodPixelsMask = lsst::afw::image::Mask<>::getPlaneBitMask("NO_DATA");
116  ; // Mask has no NO_DATA plane defined
117  }
118 
119  assert(_numSigmaClip > 0);
120  assert(_numIter > 0);
121  }
122 
124 
129  double getMaskPropagationThreshold(int bit) const;
130  void setMaskPropagationThreshold(int bit, double threshold);
132 
133  double getNumSigmaClip() const noexcept { return _numSigmaClip; }
134  int getNumIter() const noexcept { return _numIter; }
135  int getAndMask() const noexcept { return _andMask; }
136  int getNoGoodPixelsMask() const noexcept { return _noGoodPixelsMask; }
137  bool getNanSafe() const noexcept { return _isNanSafe; }
138  bool getWeighted() const noexcept { return _useWeights == WEIGHTS_TRUE ? true : false; }
139  bool getWeightedIsSet() const noexcept { return _useWeights != WEIGHTS_NONE ? true : false; }
140  bool getCalcErrorFromInputVariance() const noexcept { return _calcErrorFromInputVariance; }
141 
142  void setNumSigmaClip(double numSigmaClip) {
143  if (!(numSigmaClip > 0)) {
145  "numSigmaClip has to be positive.");
146  }
147  _numSigmaClip = numSigmaClip;
148  }
149  void setNumIter(int numIter) {
150  if (!(numIter > 0)) {
152  "numIter has to be positive.");
153  }
154  _numIter = numIter;
155  }
156  void setAndMask(int andMask) { _andMask = andMask; }
157  void setNoGoodPixelsMask(int noGoodPixelsMask) { _noGoodPixelsMask = noGoodPixelsMask; }
158  void setNanSafe(bool isNanSafe) noexcept { _isNanSafe = isNanSafe; }
159  void setWeighted(bool useWeights) noexcept { _useWeights = useWeights ? WEIGHTS_TRUE : WEIGHTS_FALSE; }
160  void setCalcErrorFromInputVariance(bool calcErrorFromInputVariance) noexcept {
161  _calcErrorFromInputVariance = calcErrorFromInputVariance;
162  }
163 
164 private:
165  friend class Statistics;
166 
167  double _numSigmaClip; // Number of standard deviations to clip at
168  int _numIter; // Number of iterations
169  int _andMask; // and-Mask to specify which mask planes to ignore
170  int _noGoodPixelsMask; // mask to set if no values are acceptable
171  bool _isNanSafe; // Check for NaNs & Infs before running (slower)
172  WeightsBoolean _useWeights; // Calculate weighted statistics (enum because of 3-valued logic)
173  bool _calcErrorFromInputVariance; // Calculate errors from the input variances, if available
174  std::vector<double> _maskPropagationThresholds; // Thresholds for when to propagate mask bits,
175  // treated like a dict (unset bits are set to 1.0)
176 };
177 
222 public:
225 
238  template <typename ImageT, typename MaskT, typename VarianceT>
239  explicit Statistics(ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags,
240  StatisticsControl const &sctrl = StatisticsControl());
241 
250  template <typename ImageT, typename MaskT, typename VarianceT, typename WeightT>
251  explicit Statistics(ImageT const &img, MaskT const &msk, VarianceT const &var, WeightT const &weights,
252  int const flags, StatisticsControl const &sctrl = StatisticsControl());
253 
254  Statistics(Statistics const &) = default;
255  Statistics(Statistics &&) = default;
256  Statistics &operator=(Statistics const &) = default;
258  ~Statistics() noexcept = default;
259 
273  Value getResult(Property const prop = NOTHING) const;
274 
282  double getError(Property const prop = NOTHING) const;
288  double getValue(Property const prop = NOTHING) const;
289  lsst::afw::image::MaskPixel getOrMask() const noexcept { return _allPixelOrMask; }
290 
291 private:
292  long _flags; // The desired calculation
293 
294  int _n; // number of pixels in the image
295  Value _mean; // the image's mean
296  Value _variance; // the image's variance
297  double _min; // the image's minimum
298  double _max; // the image's maximum
299  double _sum; // the sum of all the image's pixels
300  Value _meanclip; // the image's N-sigma clipped mean
301  Value _varianceclip; // the image's N-sigma clipped variance
302  Value _median; // the image's median
303  int _nClipped; // number of pixels clipped
304  int _nMasked; // number of pixels masked
305  double _iqrange; // the image's interquartile range
306  lsst::afw::image::MaskPixel _allPixelOrMask; // the 'or' of all masked pixels
307 
308  StatisticsControl _sctrl; // the control structure
309  bool _weightsAreMultiplicative; // Multiply by weights rather than dividing by them
310 
319  template <typename ImageT, typename MaskT, typename VarianceT, typename WeightT>
320  void doStatistics(ImageT const &img, MaskT const &msk, VarianceT const &var, WeightT const &weights,
321  int const flags, StatisticsControl const &sctrl);
322 };
323 
324 /* ************************************ The factory functions ********************************* */
329 template <typename ValueT>
330 class infinite_iterator : public boost::iterator_adaptor<infinite_iterator<ValueT>, const ValueT *,
331  const ValueT, boost::forward_traversal_tag> {
332 public:
333  infinite_iterator() : infinite_iterator::iterator_adaptor_(0) {}
334  explicit infinite_iterator(const ValueT *p) : infinite_iterator::iterator_adaptor_(p) {}
335 
336 private:
338  void increment() noexcept { ; } // never actually advance the iterator
339 };
344 template <typename ValueT>
346 public:
348  explicit MaskImposter(ValueT val = 0) noexcept { _val[0] = val; }
349  x_iterator row_begin(int) const noexcept { return x_iterator(_val); }
350 
351 private:
352  ValueT _val[1];
353 };
354 
359 template <typename Pixel>
361  lsst::afw::image::Mask<image::MaskPixel> const &msk, int const flags,
362  StatisticsControl const &sctrl = StatisticsControl()) {
364  return Statistics(img, msk, var, flags, sctrl);
365 }
366 
371 template <typename ImageT, typename MaskT, typename VarianceT>
372 Statistics makeStatistics(ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags,
373  StatisticsControl const &sctrl = StatisticsControl()) {
374  return Statistics(img, msk, var, flags, sctrl);
375 }
376 
381 template <typename Pixel>
383  StatisticsControl const &sctrl = StatisticsControl()) {
384  if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
385  return Statistics(*mimg.getImage(), *mimg.getMask(), *mimg.getVariance(), flags, sctrl);
386  } else {
388  return Statistics(*mimg.getImage(), *mimg.getMask(), var, flags, sctrl);
389  }
390 }
391 
396 template <typename Pixel>
398  lsst::afw::image::Image<WeightPixel> const &weights, int const flags,
399  StatisticsControl const &sctrl = StatisticsControl()) {
400  if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance() ||
401  (!sctrl.getWeightedIsSet() && (weights.getWidth() != 0 && weights.getHeight() != 0))) {
402  return Statistics(*mimg.getImage(), *mimg.getMask(), *mimg.getVariance(), weights, flags, sctrl);
403  } else {
405  return Statistics(*mimg.getImage(), *mimg.getMask(), var, weights, flags, sctrl);
406  }
407 }
408 
419  StatisticsControl const &sctrl = StatisticsControl());
420 
425 template <typename Pixel>
427  lsst::afw::image::Image<Pixel> const &img,
428  int const flags,
429  StatisticsControl const &sctrl = StatisticsControl()
430 ) {
431  // make a phony mask that will be compiled out
433  MaskImposter<WeightPixel> const var;
434  return Statistics(img, msk, var, flags, sctrl);
435 }
436 
441 template <typename ValueT>
443 public:
444  // types we'll use in Statistics
447  typedef ValueT Pixel;
448 
449  // constructors for std::vector<>, and copy constructor
450  // These are both shallow! ... no actual copying of values
451  explicit ImageImposter(std::vector<ValueT> const &v) : _v(v) {}
452  explicit ImageImposter(ImageImposter<ValueT> const &img) : _v(img._getVector()) {}
453 
454  // The methods we'll use in Statistics
455  x_iterator row_begin(int) const noexcept { return _v.begin(); }
456  x_iterator row_end(int) const noexcept { return _v.end(); }
457  int getWidth() const noexcept { return _v.size(); }
458  int getHeight() const noexcept { return 1; }
461  }
462 
463  bool empty() const noexcept { return _v.empty(); }
464 
465 private:
466  std::vector<ValueT> const &_v; // a private reference to the data
467  std::vector<ValueT> const &_getVector() const { return _v; } // get the ref for the copyCon
468 };
469 
474 template <typename EntryT>
476  int const flags,
477  StatisticsControl const &sctrl = StatisticsControl()
478 ) {
479  ImageImposter<EntryT> img(v); // wrap the vector in a fake image
480  MaskImposter<lsst::afw::image::MaskPixel> msk; // instantiate a fake mask that will be compiled out.
482  return Statistics(img, msk, var, flags, sctrl);
483 }
484 
489 template <typename EntryT>
491  std::vector<WeightPixel> const &vweights,
492  int const flags,
493  StatisticsControl const &sctrl = StatisticsControl()
494 ) {
495  ImageImposter<EntryT> img(v); // wrap the vector in a fake image
496  MaskImposter<lsst::afw::image::MaskPixel> msk; // instantiate a fake mask that will be compiled out.
498 
499  ImageImposter<WeightPixel> weights(vweights);
500 
501  return Statistics(img, msk, var, weights, flags, sctrl);
502 }
503 
508 template <typename EntryT>
510  int const flags,
511  StatisticsControl const &sctrl = StatisticsControl()
512 ) {
513  if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
514  return Statistics(*mv.getImage(), *mv.getMask(), *mv.getVariance(), flags, sctrl);
515  } else {
517  return Statistics(*mv.getImage(), *mv.getMask(), var, flags, sctrl);
518  }
519 }
520 
525 template <typename EntryT>
527  std::vector<WeightPixel> const &vweights,
528  int const flags,
529  StatisticsControl const &sctrl = StatisticsControl()
530 ) {
531  ImageImposter<WeightPixel> weights(vweights);
532 
533  if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
534  return Statistics(*mv.getImage(), *mv.getMask(), *mv.getVariance(), weights, flags, sctrl);
535  } else {
537  return Statistics(*mv.getImage(), *mv.getMask(), var, weights, flags, sctrl);
538  }
539 }
540 } // namespace math
541 } // namespace afw
542 } // namespace lsst
543 
544 #endif
#define LSST_EXCEPT(type,...)
T begin(T... args)
int getWidth() const
Return the number of columns in the image.
Definition: ImageBase.h:294
int getHeight() const
Return the number of rows in the image.
Definition: ImageBase.h:296
Represent a 2-dimensional array of bitmask pixels.
Definition: Mask.h:77
static MaskPixelT getPlaneBitMask(const std::vector< std::string > &names)
Return the bitmask corresponding to a vector of plane names OR'd together.
Definition: Mask.cc:378
A class to manipulate images, masks, and variance as a single object.
Definition: MaskedImage.h:73
VariancePtr getVariance() const
Return a (shared_ptr to) the MaskedImage's variance.
Definition: MaskedImage.h:1079
MaskPtr getMask() const
Return a (shared_ptr to) the MaskedImage's mask.
Definition: MaskedImage.h:1058
ImagePtr getImage() const
Return a (shared_ptr to) the MaskedImage's image.
Definition: MaskedImage.h:1046
A vector wrapper to provide a vector with the necessary methods and typedefs to be processed by Stati...
Definition: Statistics.h:442
lsst::geom::Extent2I getDimensions() const noexcept
Definition: Statistics.h:459
x_iterator row_begin(int) const noexcept
Definition: Statistics.h:455
ImageImposter(ImageImposter< ValueT > const &img)
Definition: Statistics.h:452
ImageImposter(std::vector< ValueT > const &v)
Definition: Statistics.h:451
std::vector< ValueT >::const_iterator x_iterator
Definition: Statistics.h:445
bool empty() const noexcept
Definition: Statistics.h:463
std::vector< ValueT >::const_iterator fast_iterator
Definition: Statistics.h:446
int getWidth() const noexcept
Definition: Statistics.h:457
x_iterator row_end(int) const noexcept
Definition: Statistics.h:456
int getHeight() const noexcept
Definition: Statistics.h:458
A Mask wrapper to provide an infinite_iterator for Mask::row_begin().
Definition: Statistics.h:345
MaskImposter(ValueT val=0) noexcept
Definition: Statistics.h:348
x_iterator row_begin(int) const noexcept
Definition: Statistics.h:349
infinite_iterator< ValueT > x_iterator
Definition: Statistics.h:347
lsst::afw::image::MaskedImage< EntryT >::VariancePtr getVariance() const
Definition: MaskedVector.h:94
lsst::afw::image::MaskedImage< EntryT >::ImagePtr getImage() const
Definition: MaskedVector.h:88
lsst::afw::image::MaskedImage< EntryT >::MaskPtr getMask() const
Definition: MaskedVector.h:91
Pass parameters to a Statistics object.
Definition: Statistics.h:93
void setNumSigmaClip(double numSigmaClip)
Definition: Statistics.h:142
double getMaskPropagationThreshold(int bit) const
When pixels with the given bit are rejected, we count what fraction the rejected pixels would have co...
Definition: Statistics.cc:727
bool getCalcErrorFromInputVariance() const noexcept
Definition: Statistics.h:140
int getAndMask() const noexcept
Definition: Statistics.h:135
StatisticsControl(double numSigmaClip=3.0, int numIter=3, lsst::afw::image::MaskPixel andMask=0x0, bool isNanSafe=true, WeightsBoolean useWeights=WEIGHTS_NONE)
Definition: Statistics.h:97
void setCalcErrorFromInputVariance(bool calcErrorFromInputVariance) noexcept
Definition: Statistics.h:160
bool getWeightedIsSet() const noexcept
Definition: Statistics.h:139
void setMaskPropagationThreshold(int bit, double threshold)
Definition: Statistics.cc:735
void setWeighted(bool useWeights) noexcept
Definition: Statistics.h:159
double getNumSigmaClip() const noexcept
Definition: Statistics.h:133
bool getWeighted() const noexcept
Definition: Statistics.h:138
int getNoGoodPixelsMask() const noexcept
Definition: Statistics.h:136
int getNumIter() const noexcept
Definition: Statistics.h:134
bool getNanSafe() const noexcept
Definition: Statistics.h:137
void setNoGoodPixelsMask(int noGoodPixelsMask)
Definition: Statistics.h:157
void setNanSafe(bool isNanSafe) noexcept
Definition: Statistics.h:158
A class to evaluate image statistics.
Definition: Statistics.h:221
Statistics makeStatistics(lsst::afw::image::Image< Pixel > const &img, int const flags, StatisticsControl const &sctrl=StatisticsControl())
The makeStatistics() overload to handle regular (non-masked) Images.
Definition: Statistics.h:426
Statistics makeStatistics(std::vector< EntryT > const &v, int const flags, StatisticsControl const &sctrl=StatisticsControl())
The makeStatistics() overload to handle std::vector<>
Definition: Statistics.h:475
Statistics makeStatistics(lsst::afw::image::MaskedImage< Pixel > const &mimg, int const flags, StatisticsControl const &sctrl=StatisticsControl())
Handle MaskedImages, just pass the getImage() and getMask() values right on through.
Definition: Statistics.h:382
std::pair< double, double > Value
The type used to report (value, error) for desired statistics.
Definition: Statistics.h:224
Value getResult(Property const prop=NOTHING) const
Return the value and error in the specified statistic (e.g.
Definition: Statistics.cc:931
Statistics makeStatistics(ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags, StatisticsControl const &sctrl=StatisticsControl())
Handle a straight front-end to the constructor.
Definition: Statistics.h:372
Statistics makeStatistics(lsst::afw::image::Image< Pixel > const &img, lsst::afw::image::Mask< image::MaskPixel > const &msk, int const flags, StatisticsControl const &sctrl=StatisticsControl())
Handle a watered-down front-end to the constructor (no variance)
Definition: Statistics.h:360
double getError(Property const prop=NOTHING) const
Return the error in the desired property (if specified in the constructor)
Definition: Statistics.cc:1058
~Statistics() noexcept=default
Statistics makeStatistics(lsst::afw::math::MaskedVector< EntryT > const &mv, std::vector< WeightPixel > const &vweights, int const flags, StatisticsControl const &sctrl=StatisticsControl())
The makeStatistics() overload to handle lsst::afw::math::MaskedVector<>
Definition: Statistics.h:526
Statistics makeStatistics(lsst::afw::math::MaskedVector< EntryT > const &mv, int const flags, StatisticsControl const &sctrl=StatisticsControl())
The makeStatistics() overload to handle lsst::afw::math::MaskedVector<>
Definition: Statistics.h:509
Statistics & operator=(Statistics const &)=default
Statistics makeStatistics(lsst::afw::image::MaskedImage< Pixel > const &mimg, lsst::afw::image::Image< WeightPixel > const &weights, int const flags, StatisticsControl const &sctrl=StatisticsControl())
Handle MaskedImages, just pass the getImage() and getMask() values right on through.
Definition: Statistics.h:397
Statistics(ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags, StatisticsControl const &sctrl=StatisticsControl())
Constructor for Statistics object.
Definition: Statistics.cc:773
double getValue(Property const prop=NOTHING) const
Return the value of the desired property (if specified in the constructor)
Definition: Statistics.cc:1056
Statistics & operator=(Statistics &&)=default
Statistics makeStatistics(std::vector< EntryT > const &v, std::vector< WeightPixel > const &vweights, int const flags, StatisticsControl const &sctrl=StatisticsControl())
The makeStatistics() overload to handle std::vector<>
Definition: Statistics.h:490
Statistics(Statistics const &)=default
lsst::afw::image::MaskPixel getOrMask() const noexcept
Definition: Statistics.h:289
Statistics(Statistics &&)=default
This iterator will never increment.
Definition: Statistics.h:331
friend class boost::iterator_core_access
Definition: Statistics.h:337
infinite_iterator(const ValueT *p)
Definition: Statistics.h:334
T empty(T... args)
T end(T... args)
Backwards-compatibility support for depersisting the old Calib (FluxMag0/FluxMag0Err) objects.
class[[deprecated("Removed with no replacement (but see lsst::afw::image::TransmissionCurve). Will be " "removed after v22.")]] FilterProperty final
Describe the properties of a Filter (e.g.
Definition: Filter.h:53
std::int32_t MaskPixel
default type for Masks and MaskedImage Masks
float VariancePixel
default type for MaskedImage variance images
Statistics makeStatistics(lsst::afw::image::Image< Pixel > const &img, lsst::afw::image::Mask< image::MaskPixel > const &msk, int const flags, StatisticsControl const &sctrl=StatisticsControl())
Handle a watered-down front-end to the constructor (no variance)
Definition: Statistics.h:360
Property
control what is calculated
Definition: Statistics.h:63
@ ORMASK
get the or-mask of all pixels used.
Definition: Statistics.h:80
@ ERRORS
Include errors of requested quantities.
Definition: Statistics.h:65
@ VARIANCECLIP
estimate sample N-sigma clipped variance (N set in StatisticsControl, default=3)
Definition: Statistics.h:74
@ MEANSQUARE
find mean value of square of pixel values
Definition: Statistics.h:79
@ MIN
estimate sample minimum
Definition: Statistics.h:76
@ NCLIPPED
number of clipped points
Definition: Statistics.h:81
@ NOTHING
We don't want anything.
Definition: Statistics.h:64
@ STDEV
estimate sample standard deviation
Definition: Statistics.h:68
@ NMASKED
number of masked points
Definition: Statistics.h:82
@ STDEVCLIP
estimate sample N-sigma clipped stdev (N set in StatisticsControl, default=3)
Definition: Statistics.h:73
@ VARIANCE
estimate sample variance
Definition: Statistics.h:69
@ MEDIAN
estimate sample median
Definition: Statistics.h:70
@ MAX
estimate sample maximum
Definition: Statistics.h:77
@ SUM
find sum of pixels in the image
Definition: Statistics.h:78
@ IQRANGE
estimate sample inter-quartile range
Definition: Statistics.h:71
@ MEAN
estimate sample mean
Definition: Statistics.h:67
@ MEANCLIP
estimate sample N-sigma clipped mean (N set in StatisticsControl, default=3)
Definition: Statistics.h:72
@ NPOINT
number of sample points
Definition: Statistics.h:66
Property stringToStatisticsProperty(std::string const property)
Conversion function to switch a string to a Property (see Statistics.h)
Definition: Statistics.cc:747
lsst::afw::image::VariancePixel WeightPixel
Definition: Statistics.h:56
Extent< int, 2 > Extent2I
A base class for image defects.
T size(T... args)