File Statistics.h

namespace lsst

Class for a simple mapping implementing a generic AstrometryTransform.

Remove all non-astronomical counts from the Chunk Exposure’s pixels.

Forward declarations for lsst::utils::Cache

For details on the Cache class, see the Cache.h file.

It uses a template rather than a pointer so that the derived classes can use the specifics of the transform. The class simplePolyMapping overloads a few routines.

A base class for image defects

Numeric constants used by the Integrate.h integrator routines.

Compute Image Statistics

Note

Gauss-Kronrod-Patterson quadrature coefficients for use in quadpack routine qng. These coefficients were calculated with 101 decimal digit arithmetic by L. W. Fullerton, Bell Labs, Nov 1981.

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.

namespace afw
namespace math

Typedefs

typedef lsst::afw::image::VariancePixel WeightPixel

Enums

enum Property

control what is calculated

Values:

NOTHING = 0x0

We don’t want anything.

ERRORS = 0x1

Include errors of requested quantities.

NPOINT = 0x2

number of sample points

MEAN = 0x4

estimate sample mean

STDEV = 0x8

estimate sample standard deviation

VARIANCE = 0x10

estimate sample variance

MEDIAN = 0x20

estimate sample median

IQRANGE = 0x40

estimate sample inter-quartile range

MEANCLIP = 0x80

estimate sample N-sigma clipped mean (N set in StatisticsControl, default=3)

STDEVCLIP = 0x100

estimate sample N-sigma clipped stdev (N set in StatisticsControl, default=3)

VARIANCECLIP = 0x200

estimate sample N-sigma clipped variance (N set in StatisticsControl, default=3)

MIN = 0x400

estimate sample minimum

MAX = 0x800

estimate sample maximum

SUM = 0x1000

find sum of pixels in the image

MEANSQUARE = 0x2000

find mean value of square of pixel values

ORMASK = 0x4000

get the or-mask of all pixels used.

NCLIPPED = 0x8000

number of clipped points

NMASKED = 0x10000

number of masked points

Functions

Property stringToStatisticsProperty(std::string const property)

Conversion function to switch a string to a Property (see Statistics.h)

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

template<typename ValueT>
class ImageImposter
#include <Statistics.h>

A vector wrapper to provide a vector with the necessary methods and typedefs to be processed by Statistics as though it were an Image.

Public Types

typedef std::vector<ValueT>::const_iterator x_iterator
typedef std::vector<ValueT>::const_iterator fast_iterator
typedef ValueT Pixel

Public Functions

ImageImposter(std::vector<ValueT> const &v)
ImageImposter(ImageImposter<ValueT> const &img)
x_iterator row_begin(int) const
x_iterator row_end(int) const
int getWidth() const
int getHeight() const
lsst::geom::Extent2I getDimensions() const
bool empty() const

Private Functions

std::vector<ValueT> const &_getVector() const

Private Members

std::vector<ValueT> const &_v
template<typename ValueT>
class infinite_iterator : public boost::iterator_adaptor<infinite_iterator<ValueT>, const ValueT *, const ValueT, boost::forward_traversal_tag>
#include <Statistics.h>

This iterator will never increment. It is returned by row_begin() in the MaskImposter class (below) to allow phony mask pixels to be iterated over for non-mask images within Statistics.

Public Functions

infinite_iterator()
infinite_iterator(const ValueT *p)

Private Functions

void increment()

Friends

friend lsst::afw::math::boost::iterator_core_access
template<typename ValueT>
class MaskImposter
#include <Statistics.h>

A Mask wrapper to provide an infinite_iterator for Mask::row_begin(). This allows a fake Mask to be passed in to Statistics with a regular (non-masked) Image.

Public Types

typedef infinite_iterator<ValueT> x_iterator

Public Functions

MaskImposter(ValueT val = 0)
x_iterator row_begin(int) const

Private Members

template<>
ValueT _val[1]
class Statistics
#include <Statistics.h>

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

Private Functions

template<typename ImageT, typename MaskT, typename VarianceT, typename WeightT>
void doStatistics(ImageT const &img, MaskT const &msk, VarianceT const &var, WeightT const &weights, int const flags, StatisticsControl const &sctrl)

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

Private Members

long _flags
int _n
Value _mean
Value _variance
double _min
double _max
double _sum
Value _meanclip
Value _varianceclip
Value _median
int _nClipped
int _nMasked
double _iqrange
lsst::afw::image::MaskPixel _allPixelOrMask
StatisticsControl _sctrl
bool _weightsAreMultiplicative

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

class StatisticsControl
#include <Statistics.h>

Pass parameters to a Statistics object

A class to pass parameters which control how the stats are calculated.

Unnamed Group

double getMaskPropagationThreshold(int bit) const

When pixels with the given bit are rejected, we count what fraction the rejected pixels would have contributed (including the weights, if any) if those pixels had not been rejected, and set that bit in the return value of Statistics::getOrMask() if it exceeds the given threshold.

void setMaskPropagationThreshold(int bit, double threshold)

Public Types

enum WeightsBoolean

Values:

WEIGHTS_FALSE = 0
WEIGHTS_TRUE = 1
WEIGHTS_NONE

Public Functions

StatisticsControl(double numSigmaClip = 3.0, int numIter = 3, lsst::afw::image::MaskPixel andMask = 0x0, bool isNanSafe = true, WeightsBoolean useWeights = WEIGHTS_NONE)

Parameters

  • numSigmaClip: number of standard deviations to clip at

  • numIter: Number of iterations

  • andMask: and-Mask: defines which mask bits cause a value to be ignored

  • isNanSafe: flag NaNs & Infs

  • useWeights: use weighted statistics (via a vector or an inverse variance)

double getNumSigmaClip() const
int getNumIter() const
int getAndMask() const
int getNoGoodPixelsMask() const
bool getNanSafe() const
bool getWeighted() const
bool getWeightedIsSet() const
bool getCalcErrorFromInputVariance() const
void setNumSigmaClip(double numSigmaClip)
void setNumIter(int numIter)
void setAndMask(int andMask)
void setNoGoodPixelsMask(int noGoodPixelsMask)
void setNanSafe(bool isNanSafe)
void setWeighted(bool useWeights)
void setCalcErrorFromInputVariance(bool calcErrorFromInputVariance)

Private Members

double _numSigmaClip
int _numIter
int _andMask
int _noGoodPixelsMask
bool _isNanSafe
WeightsBoolean _useWeights
bool _calcErrorFromInputVariance
std::vector<double> _maskPropagationThresholds

Friends

friend lsst::afw::math::Statistics