Class Statistics

Class Documentation

class Statistics

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()

Note

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.

Note

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.

Public Types

typedef std::pair<double, double> Value

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

Public 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

Note

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

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

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())

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

Statistics(Statistics const&)
Statistics(Statistics&&)
Statistics &operator=(Statistics const&)
Statistics &operator=(Statistics&&)
~Statistics()
Value getResult(Property const prop = NOTHING) const

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

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

getValue and getError

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

double getError(Property const prop = NOTHING) const

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

Note

You may have needed to specify ERROR to the ctor

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

double 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

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

Related

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

Parameters

  • msk: Image (or MaskedImage) whose properties we want

  • flags: Describe what we want to calculate

  • sctrl: Control how things are calculated

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

Parameters

  • img: Image (or Image) whose properties we want

  • flags: Describe what we want to calculate

  • sctrl: Control calculation

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())

Parameters

  • v: Image (or MaskedImage) whose properties we want

  • flags: Describe what we want to calculate

  • sctrl: Control calculation

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())

Parameters

  • v: Image (or MaskedImage) whose properties we want

  • vweights: Weights

  • flags: Describe what we want to calculate

  • sctrl: Control calculation

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())

Parameters

  • mv: MaskedVector

  • flags: Describe what we want to calculate

  • sctrl: Control calculation

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())

Parameters

  • mv: MaskedVector

  • vweights: weights

  • flags: Describe what we want to calculate

  • sctrl: Control calculation

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