lsst.afw g2603b601e3+f394777a51
Public Types | Public Member Functions | Related Functions | List of all members
lsst::afw::math::Statistics Class Referencefinal

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. 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
 
Statisticsoperator= (Statistics const &)=default
 
Statisticsoperator= (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
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 216 of file Statistics.h.

Member Typedef Documentation

◆ Value

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

Definition at line 219 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
imgImage whose properties we want
mskMask to control which pixels are included
varVariances corresponding to values in Image
flagsDescribe what we want to calculate
sctrlControl 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 764 of file Statistics.cc.

◆ 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
imgImage whose properties we want
mskMask to control which pixels are included
varVariances corresponding to values in Image
weightsWeights to use corresponding to values in Image
flagsDescribe what we want to calculate
sctrlControl how things are calculated

Definition at line 813 of file Statistics.cc.

◆ 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 1061 of file Statistics.cc.

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
propthe 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 1049 of file Statistics.cc.

◆ getOrMask()

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

Definition at line 284 of file Statistics.h.

◆ 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
propthe 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 922 of file Statistics.cc.

◆ 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
propthe 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 1047 of file Statistics.cc.

◆ 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 Function 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 367 of file Statistics.h.

◆ 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
imgImage (or Image) whose properties we want
flagsDescribe what we want to calculate
sctrlControl calculation

Definition at line 421 of file Statistics.h.

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

Examples
imageStatistics.cc.

Definition at line 355 of file Statistics.h.

◆ 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
mskImage (or MaskedImage) whose properties we want
flagsDescribe what we want to calculate
sctrlControl how things are calculated

Definition at line 1104 of file Statistics.cc.

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

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

◆ 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
mvMaskedVector
flagsDescribe what we want to calculate
sctrlControl calculation

Definition at line 504 of file Statistics.h.

◆ 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
mvMaskedVector
vweightsweights
flagsDescribe what we want to calculate
sctrlControl calculation

Definition at line 521 of file Statistics.h.

◆ 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
vImage (or MaskedImage) whose properties we want
flagsDescribe what we want to calculate
sctrlControl calculation

Definition at line 470 of file Statistics.h.

◆ 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
vImage (or MaskedImage) whose properties we want
vweightsWeights
flagsDescribe what we want to calculate
sctrlControl calculation

Definition at line 485 of file Statistics.h.


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