USGS Astrogeology Isis API

This class is used to accumulate a histogram on double arrays. In particular, it is highly useful for obtaining a histogram on cube data. Parameters which can be computed are the 1) median, 2) mode, and 3) skew. The histogram consists of a fixed set of distinct bins. When an object is created the programmer must provide a minimum and maximum which defines how data is further placed in the bins. The minimum is mapped to the left edge of the first bin [0] and the maximum is mapped to the right edge of the last bin [Bins()-1]. There are a set of methods which return bin information such as 1) count, 2) size, 3) middle value, 4) range, and 5) maximum bin count.

Definition at line 64 of file Histogram.h.


Public Member Functions
	Histogram (const double minimum, const double maximum, const int bins=1024)
	Constructs a histogram object.
	Histogram (Cube &cube, const int band, Progress *progress=NULL)
	Constructs a histogram object using a cube.
	~Histogram ()
	Destructs a histogram object.
void	SetBins (const int bins)
	Change the number of bins in the histogram and reset counters.
void	Reset ()
	Resets histogram counters to zero.
void	AddData (const double *data, const unsigned int count)
	Add an array of doubles to the histogram counters.
void	RemoveData (const double *data, const unsigned int count)
	Remove an array of doubles from the histogram counters.
double	Median () const
	Returns the median.
double	Mode () const
	Returns the mode.
double	Percent (const double percent) const
	Computes and returns the value at X percent of the histogram.
double	Skew () const
	Computes and returns the skew.
BigInt	BinCount (const int index) const
	Returns the count at a bin position in the histogram.
void	BinRange (const int index, double &low, double &high) const
	Returns the left edge and right edge values of a bin.
double	BinMiddle (const int index) const
	Returns the value represented by a bin.
double	BinSize () const
	Returns the size of an individual bin.
int	Bins () const
	Returns the number of bins in the histogram.
BigInt	MaxBinCount () const
	Returns the highest bin count.
double	BinRangeStart () const
double	BinRangeEnd () const
void	SetBinRange (double binStart, double binEnd)
void	AddData (const double data)
	Add a double to the accumulators and counters.
void	RemoveData (const double data)
void	SetValidRange (const double minimum=Isis::ValidMinimum, const double maximum=Isis::ValidMaximum)
double	ValidMinimum () const
double	ValidMaximum () const
bool	InRange (const double value)
bool	AboveRange (const double value)
bool	BelowRange (const double value)
double	Average () const
	Computes and returns the average.
double	StandardDeviation () const
	Computes and returns the standard deviation.
double	Variance () const
	Computes and returns the variance.
double	Minimum () const
	Returns the absolute minimum double found in all data passed through the AddData method.
double	Maximum () const
	Returns the absolute maximum double found in all data passed through the AddData method.
double	ChebyshevMinimum (const double percent=99.5) const
	This method returns a minimum such that X percent of the data will fall with K standard deviations of the average (Chebyshev's Theorem).
double	ChebyshevMaximum (const double percent=99.5) const
	This method returns a maximum such that X percent of the data will fall with K standard deviations of the average (Chebyshev's Theorem).
double	BestMinimum (const double percent=99.5) const
	This method returns the better of the absolute minimum or the Chebyshev minimum.
double	BestMaximum (const double percent=99.5) const
	This method returns the better of the absolute maximum or the Chebyshev maximum.
double	ZScore (const double value) const
	This method returns the better of the z-score of the given value.
BigInt	TotalPixels () const
	Returns the total number of pixels processed (valid and invalid).
BigInt	ValidPixels () const
	Returns the total number of valid pixels processed.
BigInt	OverRangePixels () const
	Returns the total number of pixels over the valid range encountered.
BigInt	UnderRangePixels () const
	Returns the total number of pixels under the valid range encountered.
BigInt	NullPixels () const
	Returns the total number of NULL pixels encountered.
BigInt	LisPixels () const
	Returns the total number of low instrument saturation (LIS) pixels encountered.
BigInt	LrsPixels () const
	Returns the total number of low representation saturation (LRS) pixels encountered.
BigInt	HisPixels () const
	Returns the total number of high instrument saturation (HIS) pixels encountered.
BigInt	HrsPixels () const
	Returns the total number of high representation saturation (HRS) pixels encountered.
BigInt	OutOfRangePixels () const
	Returns the total number of pixels outside of the valid range encountered.
double	Sum () const
	Returns the sum of all the data.
double	SumSquare () const
	Returns the sum of all the squared data.
Private Member Functions
void	InitializeFromCube (Cube &cube, const int band, Progress *progress)
Private Attributes
std::vector< BigInt >	p_bins
	The array of counts.
double	p_binRangeStart
double	p_binRangeEnd

Constructor & Destructor Documentation

Isis::Histogram::Histogram	(	const double	minimum,
		const double	maximum,
		const int	nbins = `1024`
	)

Constructs a histogram object.

Only data between the minimum and maximum will be binned, and the bin range will be from the minimum to the maximum.

Parameters:

	minimum	Minimum value for binning the data into the histogram.
	maximum	Maximum value for binning the data into the histogram.
	nbins	The number of bins to use

Definition at line 40 of file Histogram.cpp.

References SetBinRange(), SetBins(), and Isis::Statistics::SetValidRange().

Isis::Histogram::Histogram	(	Cube &	cube,
		const int	band,
		Progress *	progress = `NULL`
	)

Constructs a histogram object using a cube.

This constructor computes the minimum, maximum for the binning range and number of bins automatically. All statistics will still be collected, though data at either end of the histogram will be put into one bin in order to attempt to achieve better histogram statistics.

Parameters:

	cube	The cube to used to determine min/max and bins
	band	The band number the histogram will be collected from
	progress	The Isis::Progress object to be used to output the percent processed information

Definition at line 60 of file Histogram.cpp.

References cube, and InitializeFromCube().

Isis::Histogram::~Histogram ( )

Destructs a histogram object.

Definition at line 142 of file Histogram.cpp.

Member Function Documentation

void Isis::Statistics::AddData ( const double data ) [inline, inherited]

Add a double to the accumulators and counters.

This method can be invoked multiple times (for example: once for each pixel in a cube) before obtaining statistics.

Parameters:

data

The data to be added to the data set used for statistical calculations.

Definition at line 92 of file Statistics.h.

void Isis::Histogram::AddData	(	const double *	data,
		const unsigned int	count
	)

Add an array of doubles to the histogram counters.

This method can be invoked multiple times. For example, once for each line in a cube, before obtaining statistics and histogram information.

Parameters:

	data	Pointer to array of double to add.
	count	Number of doubles to process.

Reimplemented from Isis::Statistics.

Definition at line 180 of file Histogram.cpp.

References Isis::Statistics::AddData(), BinRangeEnd(), BinRangeStart(), Isis::Statistics::InRange(), Isis::IsValidPixel(), and p_bins.

Referenced by Qisis::StretchTool::calculateHistogramFromCube(), Qisis::HistogramTool::changePlot(), and Isis::Cube::Histogram().

double Isis::Statistics::Average ( ) const [inherited]

Computes and returns the average.

If there are no valid pixels, then NULL8 is returned.

Returns:: The Average

Definition at line 140 of file Statistics.cpp.

References Isis::NULL8, Isis::Statistics::p_sum, and Isis::Statistics::p_validPixels.

Referenced by Isis::OverlapNormalization::AddOverlap(), Qisis::HistogramTool::changePlot(), Isis::Statistics::ChebyshevMaximum(), Isis::Statistics::ChebyshevMinimum(), Isis::MultivariateStatistics::Covariance(), Isis::operator<<(), Qisis::VisualDisplay::paintPixmap(), Isis::AutoReg::Reduce(), Skew(), Isis::Gruen::StatsLog(), and Isis::Statistics::ZScore().

double Isis::Statistics::BestMaximum ( const double percent = 99.5 ) const [inherited]

This method returns the better of the absolute maximum or the Chebyshev maximum.

The better value is considered the value closest to the mean.

Parameters:

percent

The probability that the maximum is within K standard deviations of the mean (Used to compute the Chebyshev maximum). Default value = 99.5.

Returns:: Best of absolute and Chebyshev maximums

See also:: Statistics::Maximum Statistics::ChebyshevMaximum

Definition at line 401 of file Statistics.cpp.

References Isis::Statistics::ChebyshevMaximum(), Isis::Statistics::Maximum(), Isis::NULL8, and Isis::Statistics::p_validPixels.

Referenced by Qisis::MosaicItem::getStretch(), InitializeFromCube(), Qisis::VisualDisplay::setPixelData(), Qisis::StretchTool::stretchBuffer(), and Qisis::StretchTool::stretchEntireCube().

double Isis::Statistics::BestMinimum ( const double percent = 99.5 ) const [inherited]

This method returns the better of the absolute minimum or the Chebyshev minimum.

The better value is considered the value closest to the mean.

Parameters:

percent

The probability that the minimum is within K standard deviations of the mean (Used to compute the Chebyshev minimum). Default value = 99.5.

Returns:: Best of absolute and Chebyshev minimums

See also:: Statistics::Minimum Statistics::ChebyshevMinimum

Definition at line 379 of file Statistics.cpp.

References Isis::Statistics::ChebyshevMinimum(), Isis::Statistics::Minimum(), Isis::NULL8, and Isis::Statistics::p_validPixels.

Referenced by Qisis::MosaicItem::getStretch(), InitializeFromCube(), Qisis::VisualDisplay::setPixelData(), Qisis::StretchTool::stretchBuffer(), and Qisis::StretchTool::stretchEntireCube().

BigInt Isis::Histogram::BinCount ( const int index ) const

Returns the count at a bin position in the histogram.

Parameters:

index

Index of the desired bin 0 to Bins()-1.

Returns:: The count at a bin position in the histogram.

Definition at line 315 of file Histogram.cpp.

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), Isis::iException::Message(), and p_bins.

Referenced by Qisis::HistogramTool::changePlot(), Qisis::StretchTool::getHistogramPercent(), Qisis::QHistogram::Load(), and Qisis::HistogramWidget::setHistogram().

double Isis::Histogram::BinMiddle ( const int index ) const

Returns the value represented by a bin.

This is not the count, but the actual data value at the middle of the bin.

Parameters:

index

Index of the desired bin 0 to Bins()-1.

Returns:: The middle value of the bin.

Definition at line 357 of file Histogram.cpp.

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), BinRange(), high, low, Isis::iException::Message(), and p_bins.

Referenced by Qisis::HistogramTool::changePlot(), Qisis::StretchTool::getHistogramPercent(), Qisis::QHistogram::Load(), Mode(), Percent(), and Qisis::HistogramWidget::setHistogram().

void Isis::Histogram::BinRange	(	const int	index,
		double &	low,
		double &	high
	)			const

Returns the left edge and right edge values of a bin.

That is the range of data the bin covers.

Exceptions:

Isis::iException

The programmer has passed in an index outside of 0 to Bins()-1.

Parameters:

	index	Index of the desired bin 0 to Bins()-1.
	low	The value at the left edge of the requested bin.
	high	The value at the right edge of the requested bin.

Definition at line 336 of file Histogram.cpp.

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), BinRangeEnd(), BinRangeStart(), Isis::iException::Message(), and p_bins.

Referenced by BinMiddle(), and BinSize().

int Isis::Histogram::Bins ( ) const

Returns the number of bins in the histogram.

Returns:: The number of bins in the histogram.

Definition at line 388 of file Histogram.cpp.

References p_bins.

Referenced by Qisis::HistogramTool::changePlot(), Isis::GaussianStretch::GaussianStretch(), Qisis::StretchTool::getHistogramPercent(), Qisis::QHistogram::Load(), and Qisis::HistogramWidget::setHistogram().

double Isis::Histogram::BinSize ( ) const

Returns the size of an individual bin.

Essentially, the difference of the high and low edge values (BinRange) of a bin. This value is constant for all bins.

Returns:: The size of the individual bin.

Definition at line 376 of file Histogram.cpp.

References BinRange(), high, and low.

Referenced by Qisis::HistogramTool::changePlot(), and Qisis::HistogramWidget::setHistogram().

double Isis::Statistics::ChebyshevMaximum ( const double percent = 99.5 ) const [inherited]

This method returns a maximum such that X percent of the data will fall with K standard deviations of the average (Chebyshev's Theorem).

It can be used to obtain a minimum that does not include statistical outliers.

Parameters:

percent

The probability that the maximum is within K standard deviations of the mean. Default value = 99.5.

Returns:: maximum value excluding statistical outliers

Exceptions:

Isis::iException::Message

Definition at line 354 of file Statistics.cpp.

References _FILEINFO_, Isis::Statistics::Average(), Isis::iException::Message(), Isis::NULL8, Isis::Statistics::p_validPixels, and Isis::Statistics::StandardDeviation().

Referenced by Isis::Statistics::BestMaximum().

double Isis::Statistics::ChebyshevMinimum ( const double percent = 99.5 ) const [inherited]

This method returns a minimum such that X percent of the data will fall with K standard deviations of the average (Chebyshev's Theorem).

It can be used to obtain a minimum that does not include statistical outliers.

Parameters:

percent

The probability that the minimum is within K standard deviations of the mean. Default value = 99.5.

Returns:: Minimum value (excluding statistical outliers)

Exceptions:

Isis::iException::Message

Definition at line 328 of file Statistics.cpp.

References _FILEINFO_, Isis::Statistics::Average(), Isis::iException::Message(), Isis::NULL8, Isis::Statistics::p_validPixels, and Isis::Statistics::StandardDeviation().

Referenced by Isis::Statistics::BestMinimum().

BigInt Isis::Statistics::HisPixels ( ) const [inherited]

Returns the total number of high instrument saturation (HIS) pixels encountered.

Returns:: The number of HIS pixels (data) processed

Definition at line 289 of file Statistics.cpp.

References Isis::Statistics::p_hisPixels.

BigInt Isis::Statistics::HrsPixels ( ) const [inherited]

Returns the total number of high representation saturation (HRS) pixels encountered.

Returns:: The number of HRS pixels (data) processed

Definition at line 299 of file Statistics.cpp.

References Isis::Statistics::p_hrsPixels.

BigInt Isis::Statistics::LisPixels ( ) const [inherited]

Returns the total number of low instrument saturation (LIS) pixels encountered.

Returns:: The number of LIS pixels (data) processed

Definition at line 269 of file Statistics.cpp.

References Isis::Statistics::p_lisPixels.

BigInt Isis::Statistics::LrsPixels ( ) const [inherited]

Returns the total number of low representation saturation (LRS) pixels encountered.

Returns:: The number of LRS pixels (data) processed

Definition at line 279 of file Statistics.cpp.

References Isis::Statistics::p_lrsPixels.

BigInt Isis::Histogram::MaxBinCount ( ) const

Returns the highest bin count.

Returns:: The highest bin count.

Definition at line 398 of file Histogram.cpp.

References p_bins.

double Isis::Statistics::Maximum ( ) const [inherited]

Returns the absolute maximum double found in all data passed through the AddData method.

If there are no valid pixels, then NULL8 is returned.

Returns:: Current maximum value in data set

Exceptions:

Isis::iException::Message

The data set is blank, so the maximum is invalid.

Definition at line 202 of file Statistics.cpp.

References _FILEINFO_, Isis::iException::Message(), Isis::NULL8, Isis::Statistics::p_maximum, Isis::Statistics::p_removedData, and Isis::Statistics::p_validPixels.

Referenced by Isis::Statistics::BestMaximum(), Qisis::PlotTool::changePlot(), Qisis::HistogramTool::changePlot(), Isis::AutoReg::ComputeChipZScore(), Isis::GaussianStretch::GaussianStretch(), Qisis::VisualDisplay::paintPixmap(), Qisis::HistogramWidget::setHistogram(), Qisis::StretchTool::setStretch(), Isis::Gruen::StatsLog(), Qisis::StretchTool::stretchBuffer(), Qisis::StretchTool::stretchEntireCube(), Qisis::StretchTool::updateTool(), and Isis::Statistics::ZScore().

double Isis::Histogram::Median ( ) const

Returns the median.

Returns:: The median

Definition at line 238 of file Histogram.cpp.

References Percent().

Referenced by Qisis::HistogramTool::changePlot(), Isis::ProcessExport::SetInputRange(), and Skew().

double Isis::Statistics::Minimum ( ) const [inherited]

Returns the absolute minimum double found in all data passed through the AddData method.

If there are no valid pixels, then NULL8 is returned.

Returns:: Current minimum value in data set.

Exceptions:

Isis::iException::Message

The data set is blank, so the minimum is invalid.

Definition at line 182 of file Statistics.cpp.

References _FILEINFO_, Isis::iException::Message(), Isis::NULL8, Isis::Statistics::p_minimum, Isis::Statistics::p_removedData, and Isis::Statistics::p_validPixels.

Referenced by Isis::Statistics::BestMinimum(), Qisis::PlotTool::changePlot(), Qisis::HistogramTool::changePlot(), Isis::AutoReg::ComputeChipZScore(), Isis::GaussianStretch::GaussianStretch(), Qisis::VisualDisplay::paintPixmap(), Qisis::HistogramWidget::setHistogram(), Qisis::StretchTool::setStretch(), Isis::Gruen::StatsLog(), Qisis::StretchTool::stretchBuffer(), Qisis::StretchTool::stretchEntireCube(), and Qisis::StretchTool::updateTool().

double Isis::Histogram::Mode ( ) const

Returns the mode.

Returns:: The mode

Definition at line 247 of file Histogram.cpp.

References BinMiddle(), Isis::NULL8, and p_bins.

Referenced by Qisis::HistogramTool::changePlot().

BigInt Isis::Statistics::NullPixels ( ) const [inherited]

Returns the total number of NULL pixels encountered.

Returns:: The number of NULL pixels (data) processed

Definition at line 259 of file Statistics.cpp.

References Isis::Statistics::p_nullPixels.

BigInt Isis::Statistics::OutOfRangePixels ( ) const [inherited]

Returns the total number of pixels outside of the valid range encountered.

Returns:: The number of Out of Range pixels (data) processed

Definition at line 309 of file Statistics.cpp.

References Isis::Statistics::p_overRangePixels, and Isis::Statistics::p_underRangePixels.

BigInt Isis::Statistics::OverRangePixels ( ) const [inherited]

Returns the total number of pixels over the valid range encountered.

Returns:: The number of pixels less than the ValidMaximum() processed

Definition at line 240 of file Statistics.cpp.

References Isis::Statistics::p_overRangePixels.

double Isis::Histogram::Percent ( const double percent ) const

Computes and returns the value at X percent of the histogram.

For example, Percent(50.0) is equivalent to the computing the median. While Percent(0.5) and Percent(99.5) would obtain a minimum and maximum for the data that could be used for a good contrast stretch.

Parameters:

percent

X percent of the histogram to compute.

Returns:: The value at X percent of the histogram.

Definition at line 269 of file Histogram.cpp.

References _FILEINFO_, BinMiddle(), Isis::iException::Message(), Isis::NULL8, p_bins, and Isis::Statistics::ValidPixels().

Referenced by Isis::GaussianStretch::GaussianStretch(), Qisis::StretchTool::getHistogramDN(), Median(), Isis::Stretch::Parse(), Isis::ProcessExport::SetInputRange(), Qisis::StretchTool::stretchBuffer(), and Qisis::StretchTool::stretchEntireCube().

void Isis::Histogram::RemoveData	(	const double *	data,
		const unsigned int	count
	)

Remove an array of doubles from the histogram counters.

Note that this invalidates the absolute minimum and maximum. They will no longer be useable.

See also:: Stats

Parameters:

	data	Pointer to array of doubles to remove.
	count	number of doubles to process.

Reimplemented from Isis::Statistics.

Definition at line 211 of file Histogram.cpp.

References BinRangeEnd(), BinRangeStart(), Isis::IsValidPixel(), p_bins, and Isis::Statistics::RemoveData().

void Isis::Histogram::Reset ( )

Resets histogram counters to zero.

Reimplemented from Isis::Statistics.

Definition at line 158 of file Histogram.cpp.

References p_bins, and Isis::Statistics::Reset().

Referenced by SetBins().

void Isis::Histogram::SetBins ( const int bins )

Change the number of bins in the histogram and reset counters.

Definition at line 167 of file Histogram.cpp.

References p_bins, and Reset().

Referenced by Histogram(), and InitializeFromCube().

double Isis::Histogram::Skew ( ) const

Computes and returns the skew.

If there are no valid pixels then NULL8 is returned. Recognize that because of the binning which occurs, in order to generate the histogram, the skew may not be precise but will be very close.