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

A class to evaluate image statistics. More...

#include <Statistics.h>

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

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.
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.
double	getError (Property const prop=NOTHING) const
	Return the error in the desired property (if specified in the constructor)
double	getValue (Property const prop=NOTHING) const
	Return the value of the desired property (if specified in the constructor)
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 Symbols
(Note that these are not member symbols.)
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)
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.
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.
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.
Statistics	makeStatistics (lsst::afw::image::Mask< lsst::afw::image::MaskPixel > const &msk, int const flags, StatisticsControl const &sctrl=StatisticsControl())
	Specialization to handle Masks.
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.
template<typename EntryT>
Statistics	makeStatistics (std::vector< EntryT > const &v, int const flags, StatisticsControl const &sctrl=StatisticsControl())
	The makeStatistics() overload to handle std::vector<>
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<>
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<>
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<>

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

The Statistics class itself can only handle lsst::afw::image::MaskedImage() types. The philosophy has been to handle other types by making them look like lsst::afw::image::MaskedImage() and reusing that code. Users should have no need to instantiate a Statistics object directly, but should use the overloaded makeStatistics() factory functions.

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 222 of file Statistics.h.

Member Typedef Documentation

Value

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

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

Definition at line 225 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 788 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 837 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 1099 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");
    }
 
    using Mask = image::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 1087 of file Statistics.cc.

{ return getResult(prop).second; }

getOrMask()

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

inlinenoexcept

Definition at line 290 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 960 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 1085 of file Statistics.cc.

{ return getResult(prop).first; }

operator=() [1/2]

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

default

operator=() [2/2]

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

default

Friends And Related Symbol Documentation

makeStatistics() [1/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 373 of file Statistics.h.

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

makeStatistics() [2/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 427 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() [3/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)

Definition at line 361 of file Statistics.h.

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

makeStatistics() [4/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 1142 of file Statistics.cc.

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

makeStatistics() [5/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 383 of file Statistics.h.

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

makeStatistics() [6/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 398 of file Statistics.h.

                                                                                {
    if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance() || sctrl.getCalcErrorMosaicMode() ||
        (!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() [7/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 510 of file Statistics.h.

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

makeStatistics() [8/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 527 of file Statistics.h.

  {
    ImageImposter<WeightPixel> weights(vweights);
 
    if (sctrl.getWeighted() || sctrl.getCalcErrorFromInputVariance() || sctrl.getCalcErrorMosaicMode()) {
        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);
    }
}

makeStatistics() [9/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 476 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() [10/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 491 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);
}

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-12.0.0/Linux/afw/g7ae74a0b1c+a25e60b391/include/lsst/afw/math/Statistics.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-12.0.0/Linux/afw/g7ae74a0b1c+a25e60b391/src/math/Statistics.cc