Index: trunk/psLib/src/dataManip/psStats.h =================================================================== --- trunk/psLib/src/dataManip/psStats.h (revision 1441) +++ trunk/psLib/src/dataManip/psStats.h (revision 1470) @@ -10,6 +10,6 @@ * @author George Gusciora, MHPCC * - * @version $Revision: 1.24 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-08-09 23:40:55 $ + * @version $Revision: 1.25 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-08-11 19:16:04 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -26,4 +26,9 @@ Statistical functions and data structures. *****************************************************************************/ + +/** enumeration of statistical calculation options + * + * @see psStats, psVectorStats, psImageStats + */ typedef enum { PS_STAT_SAMPLE_MEAN = 0x000001, @@ -46,6 +51,6 @@ /** This is the generic statistics structure. It contails the data members - for the various statistic values. It contains the options member to - specifiy which statistics must be calculated. */ + for the various statistic values. It also contains the options member to + specifiy which statistics should be calculated. */ typedef struct { @@ -76,15 +81,30 @@ psStats; -/** Do Statistics on an array. Returns a status value. \ingroup MathGroup */ -psStats* psVectorStats(psStats* stats, ///< stats structure defines stats to be calculated and how - psVector* in, ///< Vector to be analysed: must be F32 - psVector* mask, ///< Ignore elements where (maskVector & maskVal) != 0: must be INT - // or NULL - unsigned int maskVal ///< Only mask elements with one of these bits set in - // maskVector - ); +/** Performs statistical calculations on a vector. + * + * @return psStats* the statistical results as specified by stats->options + */ +psStats* psVectorStats( + psStats* stats, + ///< stats structure defines stats to be calculated and how -/** A constructor for the stats structure.*/ -psStats* psStatsAlloc(psStatsOptions options); ///< Statistics to measure + psVector* in, + ///< Vector to be analysed: must be F32 + + psVector* mask, + ///< Ignore elements where (maskVector & maskVal) != 0: must be INT or NULL + + unsigned int maskVal + ///< Only mask elements with one of these bits set in maskVector +); + +/** Allocator of the psStats structure. + * + * @return psStats* A new psStats struct with the options member set to the + * value given. + */ +psStats* psStatsAlloc( + psStatsOptions options ///< Statistics to calculate +); /****************************************************************************** @@ -92,30 +112,72 @@ *****************************************************************************/ -/** The basic histogram structure which contains bounds and bins. */ +/** The basic histogram structure which contains bounds and bins. + * + * In this structure, the vector bounds specifies the boundaries of the + * histogram bins, and must of type psF32, while nums specifies the number + * of entries in the bin, and must of type psU32. The value of bounds.n must + * therefore be 1 greater than than nums.n. The two values minNum and maxNum + * are the number of data values which fell below the lower limit bound or + * above the upper limit bound, respectively. + */ typedef struct { - psVector* bounds; ///< Bounds for the bins (type F32) - psVector* nums; ///< Number in each of the bins (INT) - int minNum; ///< Number below the minimum - int maxNum; ///< Number above the maximum - bool uniform; ///< Is it a uniform distribution? + psVector* bounds; ///< Bounds for the bins (type F32) + psVector* nums; ///< Number in each of the bins (INT) + int minNum; ///< Number below the minimum + int maxNum; ///< Number above the maximum + bool uniform; ///< Is it a uniform distribution? } psHistogram; -/** Constructor \ingroup MathGroup */ -psHistogram* psHistogramAlloc(float lower, ///< Lower limit for the bins - float upper, ///< Upper limit for the bins - int n); ///< Number of bins +/** Allocator for psHistogram where the bounds of the bins are implicitly + * specified through simply specifying an upper and lower limit along with + * the size of the bins. + * + * @return psHistogram* Newly allocated psHistogram + */ +psHistogram* psHistogramAlloc( + float lower, ///< Lower limit for the bins + float upper, ///< Upper limit for the bins + int n ///< Number of bins +); -/** Generic constructor \ingroup MathGroup */ -psHistogram* psHistogramAllocGeneric(const psVector* restrict bounds); ///< Bounds for the bins +/** Allocator for psHistogram where the bounds of the bins are explicitly + * specified. + * + * @return psHistogram* Newly allocated psHistogram + */ +psHistogram* psHistogramAllocGeneric( + const psVector* restrict bounds ///< Bounds for the bins +); -/** Calculate a histogram \ingroup MathGroup **/ -psHistogram* psVectorHistogram(psHistogram* out, ///< Histogram data - const psVector* restrict in, ///< Vector to analyse - const psVector* restrict mask, ///< Mask dat for input vector - unsigned int maskVal); ///< Mask value +/** Calculate a histogram + * + * The following function populates the histogram bins from the specified + * vector (in). It alters and returns the histogram out structure. The input + * vector may be of types psU8, psU16, psF32, psF64. + * + * @return psHistogram* histogram result + */ +psHistogram* psVectorHistogram( + psHistogram* out, ///< Histogram data + const psVector* restrict in, ///< Vector to analyse + const psVector* restrict mask, ///< Mask dat for input vector + unsigned int maskVal ///< Mask value +); -bool p_psGetStatValue(const psStats* stats, double *value); +/** Extracts the statistic value specified by stats->options. + * + * @return bool If more than one statistic result is set in stats->options, + * false is returned and the value parameter is not set, + * otherwise true is returned. + */ +bool p_psGetStatValue( + const psStats* stats, + ///< the statistic struct to operate on + + double *value + ///< if return is true, this is set to the specified statistic value by stats->options +); /// @}