lsst::afw::math::Statistics Class Reference

A class to evaluate image statistics. More...

#include <Statistics.h>

Public Types
typedef std::pair< double, double >	Value
	The type used to report (value, error) for desired statistics. More...

Public Member Functions
template<typename ImageT , typename MaskT , typename VarianceT >
	Statistics (ImageT const &img, MaskT const &msk, VarianceT const &var, int const flags, StatisticsControl const &sctrl=StatisticsControl())
	Constructor for Statistics object. More...
template<typename ImageT , typename MaskT , typename VarianceT , typename WeightT >
	Statistics (ImageT const &img, MaskT const &msk, VarianceT const &var, WeightT const &weights, int const flags, StatisticsControl const &sctrl=StatisticsControl())
	Statistics (Statistics const &)=default
	Statistics (Statistics &&)=default
Statistics &	operator= (Statistics const &)=default
Statistics &	operator= (Statistics &&)=default
	~Statistics () noexcept=default
Value	getResult (Property const prop=NOTHING) const
	Return the value and error in the specified statistic (e.g. More...
double	getError (Property const prop=NOTHING) const
	Return the error in the desired property (if specified in the constructor) More...
double	getValue (Property const prop=NOTHING) const
	Return the value of the desired property (if specified in the constructor) More...
lsst::afw::image::MaskPixel	getOrMask () const noexcept
template<>
	Statistics (image::Mask< image::MaskPixel > const &msk, image::Mask< image::MaskPixel > const &msk2, image::Mask< image::MaskPixel > const &var, int const flags, StatisticsControl const &sctrl)

Related Functions
(Note that these are not member functions.)
template<typename Pixel >
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) More...
template<typename ImageT , typename MaskT , typename VarianceT >
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. More...
template<typename Pixel >
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. More...
template<typename Pixel >
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. More...
Statistics	makeStatistics (lsst::afw::image::Mask< lsst::afw::image::MaskPixel > const &msk, int const flags, StatisticsControl const &sctrl=StatisticsControl())
	Specialization to handle Masks. More...
template<typename Pixel >
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. More...
template<typename EntryT >
Statistics	makeStatistics (std::vector< EntryT > const &v, int const flags, StatisticsControl const &sctrl=StatisticsControl())
	The makeStatistics() overload to handle std::vector<> More...
template<typename EntryT >
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<> More...
template<typename EntryT >
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<> More...
template<typename EntryT >
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<> More...

Detailed Description

A class to evaluate image statistics.

The basic strategy is to construct a Statistics object from an Image and a statement of what we want to know. The desired results can then be returned using Statistics methods. A StatisticsControl object is used to pass parameters. The statistics currently implemented are listed in the enum Properties in Statistics.h.

 // sets NumSigclip (3.0), and NumIter (3) for clipping
 lsst::afw::math::StatisticsControl sctrl(3.0, 3);

 sctrl.setNumSigmaClip(4.0);            // reset number of standard deviations for N-sigma clipping
 sctrl.setNumIter(5);                   // reset number of iterations for N-sigma clipping
 sctrl.setAndMask(0x1);                 // ignore pixels with these mask bits set
 sctrl.setNanSafe(true);                // check for NaNs & Infs, a bit slower (default=true)

 lsst::afw::math::Statistics statobj =
     lsst::afw::math::makeStatistics(*img, afwMath::NPOINT |
                                           afwMath::MEAN | afwMath::MEANCLIP, sctrl);
 double const n = statobj.getValue(lsst::afw::math::NPOINT);
 std::pair<double, double> const mean =
                                  statobj.getResult(lsst::afw::math::MEAN); // Returns (value, error)
 double const meanError = statobj.getError(lsst::afw::math::MEAN);                // just the error

Note

Factory function: We used a helper function, makeStatistics, rather that the constructor directly so that the compiler could deduce the types – cf. std::make_pair()

Inputs: The class Statistics is templated, and makeStatistics() can take either: (1) an image, (2) a maskedImage, or (3) a std::vector<> Overloaded makeStatistics() functions then wrap what they were passed in Image/Mask-like classes and call the Statistics constructor.

Clipping: The clipping is done iteratively with numSigmaClip and numIter specified in the StatisticsControl object. The first clip (ie. the first iteration) is performed at: median +/- numSigmaClip*IQ_TO_STDEV*IQR, where IQ_TO_STDEV=~0.74 is the conversion factor between the IQR and sigma for a Gaussian distribution. All subsequent iterations perform clips at mean +/- numSigmaClip*stdev.

Definition at line 215 of file Statistics.h.

Member Typedef Documentation

Value

typedef std::pair<double, double> lsst::afw::math::Statistics::Value

The type used to report (value, error) for desired statistics.

Definition at line 218 of file Statistics.h.

Constructor & Destructor Documentation

Statistics() [1/5]

template<typename ImageT , typename MaskT , typename VarianceT >

lsst::afw::math::Statistics::Statistics ( ImageT const &  img, MaskT const &  msk, VarianceT const &  var, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

explicit

Constructor for Statistics object.

Parameters

img	Image whose properties we want
msk	Mask to control which pixels are included
var	Variances corresponding to values in Image
flags	Describe what we want to calculate
sctrl	Control how things are calculated

Note

Most of the actual work is done in this constructor; the results are retrieved using getValue etc.

Definition at line 773 of file Statistics.cc.

        : _flags(flags),
          _mean(NaN, NaN),
          _variance(NaN, NaN),
          _min(NaN),
          _max(NaN),
          _sum(NaN),
          _meanclip(NaN, NaN),
          _varianceclip(NaN, NaN),
          _median(NaN, NaN),
          _nClipped(0),
          _nMasked(0),
          _iqrange(NaN),
          _sctrl(sctrl),
          _weightsAreMultiplicative(false) {
    doStatistics(img, msk, var, var, _flags, _sctrl);
}

Statistics() [2/5]

template<typename ImageT , typename MaskT , typename VarianceT , typename WeightT >

lsst::afw::math::Statistics::Statistics ( ImageT const &  img, MaskT const &  msk, VarianceT const &  var, WeightT const &  weights, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

explicit

Parameters

img	Image whose properties we want
msk	Mask to control which pixels are included
var	Variances corresponding to values in Image
weights	Weights to use corresponding to values in Image
flags	Describe what we want to calculate
sctrl	Control how things are calculated

Definition at line 822 of file Statistics.cc.

        : _flags(flags),
          _mean(NaN, NaN),
          _variance(NaN, NaN),
          _min(NaN),
          _max(NaN),
          _sum(NaN),
          _meanclip(NaN, NaN),
          _varianceclip(NaN, NaN),
          _median(NaN, NaN),
          _nClipped(0),
          _nMasked(0),
          _iqrange(NaN),
          _sctrl(sctrl),
          _weightsAreMultiplicative(true) {
    if (!isEmpty(weights)) {
        if (_sctrl.getWeightedIsSet() && !_sctrl.getWeighted()) {
            throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
                              "You must use the weights if you provide them");
        }

        _sctrl.setWeighted(true);
    }
    doStatistics(img, msk, var, weights, _flags, _sctrl);
}

Statistics() [3/5]

lsst::afw::math::Statistics::Statistics ( Statistics const &  )

default

Statistics() [4/5]

lsst::afw::math::Statistics::Statistics ( Statistics &&  )

default

~Statistics()

lsst::afw::math::Statistics::~Statistics ( )

defaultnoexcept

Statistics() [5/5]

template<>

lsst::afw::math::Statistics::Statistics	(	image::Mask< image::MaskPixel > const &	msk,
		image::Mask< image::MaskPixel > const &	msk2,
		image::Mask< image::MaskPixel > const &	var,
		int const	flags,
		StatisticsControl const &	sctrl
	)

Definition at line 1070 of file Statistics.cc.

        : _flags(flags),
          _mean(NaN, NaN),
          _variance(NaN, NaN),
          _min(NaN),
          _max(NaN),
          _meanclip(NaN, NaN),
          _varianceclip(NaN, NaN),
          _median(NaN, NaN),
          _nClipped(0),
          _iqrange(NaN),
          _sctrl(sctrl) {
    if ((flags & ~(NPOINT | SUM)) != 0x0) {
        throw LSST_EXCEPT(pexExceptions::InvalidParameterError,
                          "Statistics<Mask> only supports NPOINT and SUM");
    }

    typedef image::Mask<image::MaskPixel> Mask;

    _n = msk.getWidth() * msk.getHeight();
    if (_n == 0) {
        throw LSST_EXCEPT(pexExceptions::InvalidParameterError, "Image contains no pixels");
    }

    // Check that an int's large enough to hold the number of pixels
    assert(msk.getWidth() * static_cast<double>(msk.getHeight()) < std::numeric_limits<int>::max());

    image::MaskPixel sum = 0x0;
    for (int y = 0; y != msk.getHeight(); ++y) {
        for (Mask::x_iterator ptr = msk.row_begin(y), end = msk.row_end(y); ptr != end; ++ptr) {
            sum |= (*ptr)[0];
        }
    }
    _sum = sum;
}

Member Function Documentation

getError()

double lsst::afw::math::Statistics::getError

(

Property const

prop = NOTHING

)

const

Return the error in the desired property (if specified in the constructor)

Parameters

prop	the afw::math::Property to retrieve. If NOTHING (default) and you only asked for one property in the constructor, that property's error is returned

Note

You may have needed to specify ERROR to the ctor

Definition at line 1058 of file Statistics.cc.

{ return getResult(prop).second; }

getOrMask()

lsst::afw::image::MaskPixel lsst::afw::math::Statistics::getOrMask ( ) const

inlinenoexcept

Definition at line 283 of file Statistics.h.

{ return _allPixelOrMask; }

getResult()

std::pair< double, double > lsst::afw::math::Statistics::getResult

(

Property const

prop = NOTHING

)

const

Return the value and error in the specified statistic (e.g.

MEAN)

Parameters

prop	the afw::math::Property to retrieve. If NOTHING (default) and you only asked for one property (and maybe its error) in the constructor, that property is returned

Note

Only quantities requested in the constructor may be retrieved; in particular errors may not be available if you didn't specify ERROR in the constructor

See also

getValue and getError

Todo:

uncertainties on MEANCLIP,STDEVCLIP are sketchy. _n != _nClip

Definition at line 931 of file Statistics.cc.

                                                                        {
    // if iProp == NOTHING try to return their heart's delight, as specified in the constructor
    Property const prop = static_cast<Property>(((iProp == NOTHING) ? _flags : iProp) & ~ERRORS);

    if (!(prop & _flags)) {  // we didn't calculate it
        throw LSST_EXCEPT(pexExceptions::InvalidParameterError,
                          (boost::format("You didn't ask me to calculate %d") % prop).str());
    }

    Value ret(NaN, NaN);
    switch (prop) {
        case NPOINT:
            ret.first = static_cast<double>(_n);
            if (_flags & ERRORS) {
                ret.second = 0;
            }
            break;

        case NCLIPPED:
            ret.first = static_cast<double>(_nClipped);
            if (_flags & ERRORS) {
                ret.second = 0;
            }
            break;

        case NMASKED:
            ret.first = static_cast<double>(_nMasked);
            if (_flags & ERRORS) {
                ret.second = 0;
            }
            break;

        case SUM:
            ret.first = static_cast<double>(_sum);
            if (_flags & ERRORS) {
                ret.second = 0;
            }
            break;

        // == means ==
        case MEAN:
            ret.first = _mean.first;
            if (_flags & ERRORS) {
                ret.second = ::sqrt(_mean.second);
            }
            break;
        case MEANCLIP:
            ret.first = _meanclip.first;
            if (_flags & ERRORS) {
                ret.second = ::sqrt(_meanclip.second);
            }
            break;

        // == stdevs & variances ==
        case VARIANCE:
            ret.first = _variance.first;
            if (_flags & ERRORS) {
                ret.second = ::sqrt(_variance.second);
            }
            break;
        case STDEV:
            ret.first = sqrt(_variance.first);
            if (_flags & ERRORS) {
                ret.second = 0.5 * ::sqrt(_variance.second) / ret.first;
            }
            break;
        case VARIANCECLIP:
            ret.first = _varianceclip.first;
            if (_flags & ERRORS) {
                ret.second = ret.second;
            }
            break;
        case STDEVCLIP:
            ret.first = sqrt(_varianceclip.first);
            if (_flags & ERRORS) {
                ret.second = 0.5 * ::sqrt(_varianceclip.second) / ret.first;
            }
            break;

        case MEANSQUARE:
            ret.first = (_n - 1) / static_cast<double>(_n) * _variance.first + ::pow(_mean.first, 2);
            if (_flags & ERRORS) {
                ret.second = ::sqrt(2 * ::pow(ret.first / _n, 2));  // assumes Gaussian
            }
            break;

        // == other stats ==
        case MIN:
            ret.first = _min;
            if (_flags & ERRORS) {
                ret.second = 0;
            }
            break;
        case MAX:
            ret.first = _max;
            if (_flags & ERRORS) {
                ret.second = 0;
            }
            break;
        case MEDIAN:
            ret.first = _median.first;
            if (_flags & ERRORS) {
                ret.second = sqrt(geom::HALFPI * _variance.first / _n);  // assumes Gaussian
            }
            break;
        case IQRANGE:
            ret.first = _iqrange;
            if (_flags & ERRORS) {
                ret.second = NaN;  // we're not estimating this properly
            }
            break;

        // no-op to satisfy the compiler
        case ERRORS:
            break;
        // default: redundant as 'ret' is initialized to NaN, NaN
        default:  // we must have set prop to _flags
            assert(iProp == 0);
            throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
                              "getValue() may only be called without a parameter"
                              " if you asked for only one statistic");
    }
    return ret;
}

getValue()

double lsst::afw::math::Statistics::getValue

(

Property const

prop = NOTHING

)

const

Return the value of the desired property (if specified in the constructor)

Parameters

prop	the afw::math::Property to retrieve. If NOTHING (default) and you only asked for one property in the constructor, that property is returned

Definition at line 1056 of file Statistics.cc.

{ return getResult(prop).first; }

operator=() [1/2]

Statistics& lsst::afw::math::Statistics::operator= ( Statistics const &  )

default

operator=() [2/2]

Statistics& lsst::afw::math::Statistics::operator= ( Statistics &&  )

default

Friends And Related Function Documentation

makeStatistics() [1/10]

template<typename Pixel >

Statistics makeStatistics ( lsst::afw::image::Image< Pixel > const &  img, lsst::afw::image::Mask< image::MaskPixel > const &  msk, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

Handle a watered-down front-end to the constructor (no variance)

Examples:

imageStatistics.cc.

Definition at line 354 of file Statistics.h.

                                                                                {
    MaskImposter<WeightPixel> var;
    return Statistics(img, msk, var, flags, sctrl);
}

makeStatistics() [2/10]

template<typename ImageT , typename MaskT , typename VarianceT >

Statistics makeStatistics ( ImageT const &  img, MaskT const &  msk, VarianceT const &  var, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

Handle a straight front-end to the constructor.

Definition at line 366 of file Statistics.h.

                                                                                {
    return Statistics(img, msk, var, flags, sctrl);
}

makeStatistics() [3/10]

template<typename Pixel >

Statistics makeStatistics ( lsst::afw::image::MaskedImage< Pixel > const &  mimg, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

Handle MaskedImages, just pass the getImage() and getMask() values right on through.

Definition at line 376 of file Statistics.h.

                                                                                {
    if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
        return Statistics(*mimg.getImage(), *mimg.getMask(), *mimg.getVariance(), flags, sctrl);
    } else {
        MaskImposter<WeightPixel> var;
        return Statistics(*mimg.getImage(), *mimg.getMask(), var, flags, sctrl);
    }
}

makeStatistics() [4/10]

template<typename Pixel >

Statistics makeStatistics ( lsst::afw::image::MaskedImage< Pixel > const &  mimg, lsst::afw::image::Image< WeightPixel > const &  weights, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

Handle MaskedImages, just pass the getImage() and getMask() values right on through.

Definition at line 391 of file Statistics.h.

                                                                                {
    if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance() ||
        (!sctrl.getWeightedIsSet() && (weights.getWidth() != 0 && weights.getHeight() != 0))) {
        return Statistics(*mimg.getImage(), *mimg.getMask(), *mimg.getVariance(), weights, flags, sctrl);
    } else {
        MaskImposter<WeightPixel> var;
        return Statistics(*mimg.getImage(), *mimg.getMask(), var, weights, flags, sctrl);
    }
}

makeStatistics() [5/10]

Statistics makeStatistics ( lsst::afw::image::Mask< lsst::afw::image::MaskPixel > const &  msk, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

Specialization to handle Masks.

Parameters

msk	Image (or MaskedImage) whose properties we want
flags	Describe what we want to calculate
sctrl	Control how things are calculated

Definition at line 1113 of file Statistics.cc.

                                                          {
    return Statistics(msk, msk, msk, flags, sctrl);
}

makeStatistics() [6/10]

template<typename Pixel >

Statistics makeStatistics ( lsst::afw::image::Image< Pixel > const &  img, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

The makeStatistics() overload to handle regular (non-masked) Images.

Parameters

img	Image (or Image) whose properties we want
flags	Describe what we want to calculate
sctrl	Control calculation

Definition at line 420 of file Statistics.h.

  {
    // make a phony mask that will be compiled out
    MaskImposter<lsst::afw::image::MaskPixel> const msk;
    MaskImposter<WeightPixel> const var;
    return Statistics(img, msk, var, flags, sctrl);
}

makeStatistics() [7/10]

template<typename EntryT >

Statistics makeStatistics ( std::vector< EntryT > const &  v, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

The makeStatistics() overload to handle std::vector<>

Parameters

v	Image (or MaskedImage) whose properties we want
flags	Describe what we want to calculate
sctrl	Control calculation

Definition at line 469 of file Statistics.h.

  {
    ImageImposter<EntryT> img(v);                   // wrap the vector in a fake image
    MaskImposter<lsst::afw::image::MaskPixel> msk;  // instantiate a fake mask that will be compiled out.
    MaskImposter<WeightPixel> var;
    return Statistics(img, msk, var, flags, sctrl);
}

makeStatistics() [8/10]

template<typename EntryT >

Statistics makeStatistics ( std::vector< EntryT > const &  v, std::vector< WeightPixel > const &  vweights, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

The makeStatistics() overload to handle std::vector<>

Parameters

v	Image (or MaskedImage) whose properties we want
vweights	Weights
flags	Describe what we want to calculate
sctrl	Control calculation

Definition at line 484 of file Statistics.h.

  {
    ImageImposter<EntryT> img(v);                   // wrap the vector in a fake image
    MaskImposter<lsst::afw::image::MaskPixel> msk;  // instantiate a fake mask that will be compiled out.
    MaskImposter<WeightPixel> var;

    ImageImposter<WeightPixel> weights(vweights);

    return Statistics(img, msk, var, weights, flags, sctrl);
}

makeStatistics() [9/10]

template<typename EntryT >

Statistics makeStatistics ( lsst::afw::math::MaskedVector< EntryT > const &  mv, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

The makeStatistics() overload to handle lsst::afw::math::MaskedVector<>

Parameters

mv	MaskedVector
flags	Describe what we want to calculate
sctrl	Control calculation

Definition at line 503 of file Statistics.h.

  {
    if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
        return Statistics(*mv.getImage(), *mv.getMask(), *mv.getVariance(), flags, sctrl);
    } else {
        MaskImposter<WeightPixel> var;
        return Statistics(*mv.getImage(), *mv.getMask(), var, flags, sctrl);
    }
}

makeStatistics() [10/10]

template<typename EntryT >

Statistics makeStatistics ( lsst::afw::math::MaskedVector< EntryT > const &  mv, std::vector< WeightPixel > const &  vweights, int const  flags, StatisticsControl const &  sctrl = StatisticsControl()  )

related

The makeStatistics() overload to handle lsst::afw::math::MaskedVector<>

Parameters

mv	MaskedVector
vweights	weights
flags	Describe what we want to calculate
sctrl	Control calculation

Definition at line 520 of file Statistics.h.

  {
    ImageImposter<WeightPixel> weights(vweights);

    if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance()) {
        return Statistics(*mv.getImage(), *mv.getMask(), *mv.getVariance(), weights, flags, sctrl);
    } else {
        MaskImposter<WeightPixel> var;
        return Statistics(*mv.getImage(), *mv.getMask(), var, weights, flags, sctrl);
    }
}

---

The documentation for this class was generated from the following files:

• /j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/include/lsst/afw/math/Statistics.h
• /j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/src/math/Statistics.cc