lsst.afw g9029821c7d+1f5ff3162d
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
27
28#include <algorithm>
29#include <cassert>
30#include <limits>
31#include "boost/iterator/iterator_adaptor.hpp"
32#include <memory>
35
36namespace lsst {
37namespace afw {
38namespace image {
39template <typename>
40class Image;
41template <typename, typename, typename>
42class MaskedImage;
43} // namespace image
44namespace math {
45template <typename>
46class MaskedVector; // forward declaration
47
48using WeightPixel = lsst::afw::image::VariancePixel; // Type used for weights
49
54 NOTHING = 0x0,
55 ERRORS = 0x1,
56 NPOINT = 0x2,
57 MEAN = 0x4,
58 STDEV = 0x8,
59 VARIANCE = 0x10,
60 MEDIAN = 0x20,
61 IQRANGE = 0x40,
62 MEANCLIP = 0x80,
63 STDEVCLIP = 0x100,
64 VARIANCECLIP = 0x200,
66 MIN = 0x400,
67 MAX = 0x800,
68 SUM = 0x1000,
69 MEANSQUARE = 0x2000,
70 ORMASK = 0x4000,
71 NCLIPPED = 0x8000,
72 NMASKED = 0x10000
73};
76
84public:
85 enum WeightsBoolean { WEIGHTS_FALSE = 0, WEIGHTS_TRUE = 1, WEIGHTS_NONE }; // initial state is NONE
86
87 StatisticsControl(double numSigmaClip = 3.0,
88 int numIter = 3,
90 0x0,
91 bool isNanSafe = true,
92 WeightsBoolean useWeights =
94 )
95 : _numSigmaClip(numSigmaClip),
96 _numIter(numIter),
97 _andMask(andMask),
98 _noGoodPixelsMask(0x0),
99 _isNanSafe(isNanSafe),
100 _useWeights(useWeights),
101 _calcErrorFromInputVariance(false),
102 _maskPropagationThresholds() {
103 try {
104 _noGoodPixelsMask = lsst::afw::image::Mask<>::getPlaneBitMask("NO_DATA");
106 ; // Mask has no NO_DATA plane defined
107 }
108
109 assert(_numSigmaClip > 0);
110 assert(_numIter > 0);
111 }
112
114
119 double getMaskPropagationThreshold(int bit) const;
120 void setMaskPropagationThreshold(int bit, double threshold);
122
123 double getNumSigmaClip() const noexcept { return _numSigmaClip; }
124 int getNumIter() const noexcept { return _numIter; }
125 int getAndMask() const noexcept { return _andMask; }
126 int getNoGoodPixelsMask() const noexcept { return _noGoodPixelsMask; }
127 bool getNanSafe() const noexcept { return _isNanSafe; }
128 bool getWeighted() const noexcept { return _useWeights == WEIGHTS_TRUE ? true : false; }
129 bool getWeightedIsSet() const noexcept { return _useWeights != WEIGHTS_NONE ? true : false; }
130 bool getCalcErrorFromInputVariance() const noexcept { return _calcErrorFromInputVariance; }
131
132 void setNumSigmaClip(double numSigmaClip) {
133 if (!(numSigmaClip > 0)) {
135 "numSigmaClip has to be positive.");
136 }
137 _numSigmaClip = numSigmaClip;
138 }
139 void setNumIter(int numIter) {
140 if (!(numIter > 0)) {
142 "numIter has to be positive.");
143 }
144 _numIter = numIter;
145 }
146 void setAndMask(int andMask) { _andMask = andMask; }
147 void setNoGoodPixelsMask(int noGoodPixelsMask) { _noGoodPixelsMask = noGoodPixelsMask; }
148 void setNanSafe(bool isNanSafe) noexcept { _isNanSafe = isNanSafe; }
149 void setWeighted(bool useWeights) noexcept { _useWeights = useWeights ? WEIGHTS_TRUE : WEIGHTS_FALSE; }
150 void setCalcErrorFromInputVariance(bool calcErrorFromInputVariance) noexcept {
151 _calcErrorFromInputVariance = calcErrorFromInputVariance;
152 }
153
154private:
155 friend class Statistics;
156
157 double _numSigmaClip; // Number of standard deviations to clip at
158 int _numIter; // Number of iterations
159 int _andMask; // and-Mask to specify which mask planes to ignore
160 int _noGoodPixelsMask; // mask to set if no values are acceptable
161 bool _isNanSafe; // Check for NaNs & Infs before running (slower)
162 WeightsBoolean _useWeights; // Calculate weighted statistics (enum because of 3-valued logic)
163 bool _calcErrorFromInputVariance; // Calculate errors from the input variances, if available
164 std::vector<double> _maskPropagationThresholds; // Thresholds for when to propagate mask bits,
165 // treated like a dict (unset bits are set to 1.0)
166};
167
216class Statistics final {
217public:
220
233 template <typename ImageT, typename MaskT, typename VarianceT>
234 explicit Statistics(ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags,
235 StatisticsControl const &sctrl = StatisticsControl());
236
245 template <typename ImageT, typename MaskT, typename VarianceT, typename WeightT>
246 explicit Statistics(ImageT const &img, MaskT const &msk, VarianceT const &var, WeightT const &weights,
247 int const flags, StatisticsControl const &sctrl = StatisticsControl());
248
249 Statistics(Statistics const &) = default;
250 Statistics(Statistics &&) = default;
251 Statistics &operator=(Statistics const &) = default;
253 ~Statistics() noexcept = default;
254
268 Value getResult(Property const prop = NOTHING) const;
269
277 double getError(Property const prop = NOTHING) const;
283 double getValue(Property const prop = NOTHING) const;
284 lsst::afw::image::MaskPixel getOrMask() const noexcept { return _allPixelOrMask; }
285
286private:
287 long _flags; // The desired calculation
288
289 int _n; // number of pixels in the image
290 Value _mean; // the image's mean
291 Value _variance; // the image's variance
292 double _min; // the image's minimum
293 double _max; // the image's maximum
294 double _sum; // the sum of all the image's pixels
295 Value _meanclip; // the image's N-sigma clipped mean
296 Value _varianceclip; // the image's N-sigma clipped variance
297 Value _median; // the image's median
298 int _nClipped; // number of pixels clipped
299 int _nMasked; // number of pixels masked
300 double _iqrange; // the image's interquartile range
301 lsst::afw::image::MaskPixel _allPixelOrMask; // the 'or' of all masked pixels
302
303 StatisticsControl _sctrl; // the control structure
304 bool _weightsAreMultiplicative; // Multiply by weights rather than dividing by them
305
314 template <typename ImageT, typename MaskT, typename VarianceT, typename WeightT>
315 void doStatistics(ImageT const &img, MaskT const &msk, VarianceT const &var, WeightT const &weights,
316 int const flags, StatisticsControl const &sctrl);
317};
318
319/* ************************************ The factory functions ********************************* */
324template <typename ValueT>
325class infinite_iterator : public boost::iterator_adaptor<infinite_iterator<ValueT>, const ValueT *,
326 const ValueT, boost::forward_traversal_tag> {
327public:
328 infinite_iterator() : infinite_iterator::iterator_adaptor_(0) {}
329 explicit infinite_iterator(const ValueT *p) : infinite_iterator::iterator_adaptor_(p) {}
330
331private:
333 void increment() noexcept { ; } // never actually advance the iterator
334};
339template <typename ValueT>
341public:
343 explicit MaskImposter(ValueT val = 0) noexcept { _val[0] = val; }
344 x_iterator row_begin(int) const noexcept { return x_iterator(_val); }
345
346private:
347 ValueT _val[1];
348};
349
354template <typename Pixel>
356 lsst::afw::image::Mask<image::MaskPixel> const &msk, int const flags,
357 StatisticsControl const &sctrl = StatisticsControl()) {
359 return Statistics(img, msk, var, flags, sctrl);
360}
361
366template <typename ImageT, typename MaskT, typename VarianceT>
367Statistics makeStatistics(ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags,
368 StatisticsControl const &sctrl = StatisticsControl()) {
369 return Statistics(img, msk, var, flags, sctrl);
370}
371
376template <typename Pixel>
378 StatisticsControl const &sctrl = StatisticsControl()) {
379 if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
380 return Statistics(*mimg.getImage(), *mimg.getMask(), *mimg.getVariance(), flags, sctrl);
381 } else {
383 return Statistics(*mimg.getImage(), *mimg.getMask(), var, flags, sctrl);
384 }
385}
386
391template <typename Pixel>
393 lsst::afw::image::Image<WeightPixel> const &weights, int const flags,
394 StatisticsControl const &sctrl = StatisticsControl()) {
395 if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance() ||
396 (!sctrl.getWeightedIsSet() && (weights.getWidth() != 0 && weights.getHeight() != 0))) {
397 return Statistics(*mimg.getImage(), *mimg.getMask(), *mimg.getVariance(), weights, flags, sctrl);
398 } else {
400 return Statistics(*mimg.getImage(), *mimg.getMask(), var, weights, flags, sctrl);
401 }
402}
403
414 StatisticsControl const &sctrl = StatisticsControl());
415
420template <typename Pixel>
423 int const flags,
424 StatisticsControl const &sctrl = StatisticsControl()
425) {
426 // make a phony mask that will be compiled out
429 return Statistics(img, msk, var, flags, sctrl);
430}
431
436template <typename ValueT>
437class ImageImposter final {
438public:
439 // types we'll use in Statistics
442 using Pixel = ValueT;
443
444 // constructors for std::vector<>, and copy constructor
445 // These are both shallow! ... no actual copying of values
446 explicit ImageImposter(std::vector<ValueT> const &v) : _v(v) {}
447 explicit ImageImposter(ImageImposter<ValueT> const &img) : _v(img._getVector()) {}
448
449 // The methods we'll use in Statistics
450 x_iterator row_begin(int) const noexcept { return _v.begin(); }
451 x_iterator row_end(int) const noexcept { return _v.end(); }
452 int getWidth() const noexcept { return _v.size(); }
453 int getHeight() const noexcept { return 1; }
456 }
457
458 bool empty() const noexcept { return _v.empty(); }
459
460private:
461 std::vector<ValueT> const &_v; // a private reference to the data
462 std::vector<ValueT> const &_getVector() const { return _v; } // get the ref for the copyCon
463};
464
469template <typename EntryT>
471 int const flags,
472 StatisticsControl const &sctrl = StatisticsControl()
473) {
474 ImageImposter<EntryT> img(v); // wrap the vector in a fake image
475 MaskImposter<lsst::afw::image::MaskPixel> msk; // instantiate a fake mask that will be compiled out.
477 return Statistics(img, msk, var, flags, sctrl);
478}
479
484template <typename EntryT>
486 std::vector<WeightPixel> const &vweights,
487 int const flags,
488 StatisticsControl const &sctrl = StatisticsControl()
489) {
490 ImageImposter<EntryT> img(v); // wrap the vector in a fake image
491 MaskImposter<lsst::afw::image::MaskPixel> msk; // instantiate a fake mask that will be compiled out.
493
494 ImageImposter<WeightPixel> weights(vweights);
495
496 return Statistics(img, msk, var, weights, flags, sctrl);
497}
498
503template <typename EntryT>
505 int const flags,
506 StatisticsControl const &sctrl = StatisticsControl()
507) {
508 if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
509 return Statistics(*mv.getImage(), *mv.getMask(), *mv.getVariance(), flags, sctrl);
510 } else {
512 return Statistics(*mv.getImage(), *mv.getMask(), var, flags, sctrl);
513 }
514}
515
520template <typename EntryT>
522 std::vector<WeightPixel> const &vweights,
523 int const flags,
524 StatisticsControl const &sctrl = StatisticsControl()
525) {
526 ImageImposter<WeightPixel> weights(vweights);
527
528 if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
529 return Statistics(*mv.getImage(), *mv.getMask(), *mv.getVariance(), weights, flags, sctrl);
530 } else {
532 return Statistics(*mv.getImage(), *mv.getMask(), var, weights, flags, sctrl);
533 }
534}
535} // namespace math
536} // namespace afw
537} // namespace lsst
538
539#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:412
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:1051
MaskPtr getMask() const
Return a (shared_ptr to) the MaskedImage's mask.
Definition: MaskedImage.h:1030
ImagePtr getImage() const
Return a (shared_ptr to) the MaskedImage's image.
Definition: MaskedImage.h:1018
A vector wrapper to provide a vector with the necessary methods and typedefs to be processed by Stati...
Definition: Statistics.h:437
lsst::geom::Extent2I getDimensions() const noexcept
Definition: Statistics.h:454
x_iterator row_begin(int) const noexcept
Definition: Statistics.h:450
typename std::vector< ValueT >::const_iterator fast_iterator
Definition: Statistics.h:441
ImageImposter(ImageImposter< ValueT > const &img)
Definition: Statistics.h:447
ImageImposter(std::vector< ValueT > const &v)
Definition: Statistics.h:446
typename std::vector< ValueT >::const_iterator x_iterator
Definition: Statistics.h:440
bool empty() const noexcept
Definition: Statistics.h:458
int getWidth() const noexcept
Definition: Statistics.h:452
x_iterator row_end(int) const noexcept
Definition: Statistics.h:451
int getHeight() const noexcept
Definition: Statistics.h:453
A Mask wrapper to provide an infinite_iterator for Mask::row_begin().
Definition: Statistics.h:340
infinite_iterator< ValueT > x_iterator
Definition: Statistics.h:342
MaskImposter(ValueT val=0) noexcept
Definition: Statistics.h:343
x_iterator row_begin(int) const noexcept
Definition: Statistics.h:344
lsst::afw::image::MaskedImage< EntryT >::VariancePtr getVariance() const
Definition: MaskedVector.h:94
lsst::afw::image::MaskedImage< EntryT >::MaskPtr getMask() const
Definition: MaskedVector.h:91
lsst::afw::image::MaskedImage< EntryT >::ImagePtr getImage() const
Definition: MaskedVector.h:88
Pass parameters to a Statistics object.
Definition: Statistics.h:83
void setNumSigmaClip(double numSigmaClip)
Definition: Statistics.h:132
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:718
bool getCalcErrorFromInputVariance() const noexcept
Definition: Statistics.h:130
int getAndMask() const noexcept
Definition: Statistics.h:125
StatisticsControl(double numSigmaClip=3.0, int numIter=3, lsst::afw::image::MaskPixel andMask=0x0, bool isNanSafe=true, WeightsBoolean useWeights=WEIGHTS_NONE)
Definition: Statistics.h:87
void setCalcErrorFromInputVariance(bool calcErrorFromInputVariance) noexcept
Definition: Statistics.h:150
bool getWeightedIsSet() const noexcept
Definition: Statistics.h:129
void setMaskPropagationThreshold(int bit, double threshold)
Definition: Statistics.cc:726
void setWeighted(bool useWeights) noexcept
Definition: Statistics.h:149
double getNumSigmaClip() const noexcept
Definition: Statistics.h:123
bool getWeighted() const noexcept
Definition: Statistics.h:128
int getNoGoodPixelsMask() const noexcept
Definition: Statistics.h:126
int getNumIter() const noexcept
Definition: Statistics.h:124
bool getNanSafe() const noexcept
Definition: Statistics.h:127
void setNoGoodPixelsMask(int noGoodPixelsMask)
Definition: Statistics.h:147
void setNanSafe(bool isNanSafe) noexcept
Definition: Statistics.h:148
A class to evaluate image statistics.
Definition: Statistics.h:216
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:421
Statistics makeStatistics(std::vector< EntryT > const &v, int const flags, StatisticsControl const &sctrl=StatisticsControl())
The makeStatistics() overload to handle std::vector<>
Definition: Statistics.h:470
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:377
Statistics & operator=(Statistics const &)=default
Value getResult(Property const prop=NOTHING) const
Return the value and error in the specified statistic (e.g.
Definition: Statistics.cc:922
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:367
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:355
double getError(Property const prop=NOTHING) const
Return the error in the desired property (if specified in the constructor)
Definition: Statistics.cc:1049
Statistics & operator=(Statistics &&)=default
~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:521
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:504
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:392
Statistics(ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags, StatisticsControl const &sctrl=StatisticsControl())
Constructor for Statistics object.
Definition: Statistics.cc:764
double getValue(Property const prop=NOTHING) const
Return the value of the desired property (if specified in the constructor)
Definition: Statistics.cc:1047
std::pair< double, double > Value
The type used to report (value, error) for desired statistics.
Definition: Statistics.h:219
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:485
Statistics(Statistics const &)=default
lsst::afw::image::MaskPixel getOrMask() const noexcept
Definition: Statistics.h:284
Statistics(Statistics &&)=default
This iterator will never increment.
Definition: Statistics.h:326
friend class boost::iterator_core_access
Definition: Statistics.h:332
infinite_iterator(const ValueT *p)
Definition: Statistics.h:329
T empty(T... args)
T end(T... args)
float VariancePixel
default type for MaskedImage variance images
std::int32_t MaskPixel
default type for Masks and MaskedImage Masks
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:355
Property
control what is calculated
Definition: Statistics.h:53
@ ORMASK
get the or-mask of all pixels used.
Definition: Statistics.h:70
@ ERRORS
Include errors of requested quantities.
Definition: Statistics.h:55
@ VARIANCECLIP
estimate sample N-sigma clipped variance (N set in StatisticsControl, default=3)
Definition: Statistics.h:64
@ MEANSQUARE
find mean value of square of pixel values
Definition: Statistics.h:69
@ MIN
estimate sample minimum
Definition: Statistics.h:66
@ NCLIPPED
number of clipped points
Definition: Statistics.h:71
@ NOTHING
We don't want anything.
Definition: Statistics.h:54
@ STDEV
estimate sample standard deviation
Definition: Statistics.h:58
@ NMASKED
number of masked points
Definition: Statistics.h:72
@ STDEVCLIP
estimate sample N-sigma clipped stdev (N set in StatisticsControl, default=3)
Definition: Statistics.h:63
@ VARIANCE
estimate sample variance
Definition: Statistics.h:59
@ MEDIAN
estimate sample median
Definition: Statistics.h:60
@ MAX
estimate sample maximum
Definition: Statistics.h:67
@ SUM
find sum of pixels in the image
Definition: Statistics.h:68
@ IQRANGE
estimate sample inter-quartile range
Definition: Statistics.h:61
@ MEAN
estimate sample mean
Definition: Statistics.h:57
@ MEANCLIP
estimate sample N-sigma clipped mean (N set in StatisticsControl, default=3)
Definition: Statistics.h:62
@ NPOINT
number of sample points
Definition: Statistics.h:56
Property stringToStatisticsProperty(std::string const property)
Conversion function to switch a string to a Property (see Statistics.h)
Definition: Statistics.cc:738
lsst::afw::image::VariancePixel WeightPixel
Definition: Statistics.h:48
Extent< int, 2 > Extent2I
T size(T... args)