00001 /** @file psStats.h 00002 * \brief basic statistical operations 00003 * @ingroup Stats 00004 * 00005 * This file will hold the definition of the histogram and stats data 00006 * structures. It also contains prototypes for procedures which operate 00007 * on those data structures. 00008 * 00009 * XXX: The following stats members are never used, or set in this code. 00010 * stats->robustN50 00011 * stats->clippedNvalues 00012 * stats->binsize 00013 * 00014 * @author GLG, MHPCC 00015 * 00016 * @version $Revision: 1.1.1.1 $ $Name: $ 00017 * @date $Date: 2005/09/14 20:42:48 $ 00018 * 00019 * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii 00020 */ 00021 #ifndef PS_STATS_H 00022 #define PS_STATS_H 00023 00024 #include "psVector.h" 00025 00026 /// @addtogroup Stats 00027 /// @{ 00028 00029 /****************************************************************************** 00030 Statistical functions and data structures. 00031 *****************************************************************************/ 00032 00033 /** enumeration of statistical calculation options 00034 * 00035 * @see psStats, psVectorStats, psImageStats 00036 */ 00037 // XXX: Is PS_STAT_ROBUST_FOR_SAMPLE obsolete? 00038 typedef enum { 00039 PS_STAT_SAMPLE_MEAN = 0x000001, ///< Sample Mean 00040 PS_STAT_SAMPLE_MEDIAN = 0x000002, ///< Sample Median 00041 PS_STAT_SAMPLE_STDEV = 0x000004, ///< Sample Standard Deviation 00042 PS_STAT_SAMPLE_QUARTILE = 0x000008, ///< Sample Quartile 00043 PS_STAT_ROBUST_MEAN = 0x000010, ///< Robust Mean 00044 PS_STAT_ROBUST_MEDIAN = 0x000020, ///< Robust Median 00045 PS_STAT_ROBUST_MODE = 0x000040, ///< Robust Mode 00046 PS_STAT_ROBUST_STDEV = 0x000080, ///< Robust Standarad Deviation 00047 PS_STAT_ROBUST_QUARTILE = 0x000100, ///< Robust Quartile 00048 PS_STAT_CLIPPED_MEAN = 0x000200, ///< Clipped Mean 00049 PS_STAT_CLIPPED_STDEV = 0x000400, ///< Clipped Standard Deviation 00050 PS_STAT_MAX = 0x000800, ///< Maximum 00051 PS_STAT_MIN = 0x001000, ///< Minumum 00052 PS_STAT_USE_RANGE = 0x002000, ///< Range 00053 PS_STAT_USE_BINSIZE = 0x004000, ///< Binsize 00054 } psStatsOptions; 00055 00056 /** This is the generic statistics structure. It contails the data members 00057 for the various statistic values. It also contains the options member to 00058 specifiy which statistics should be calculated. */ 00059 typedef struct 00060 { 00061 double sampleMean; ///< formal mean of sample 00062 double sampleMedian; ///< formal median of sample 00063 double sampleStdev; ///< standard deviation of sample 00064 double sampleUQ; ///< upper quartile of sample 00065 double sampleLQ; ///< lower quartile of sample 00066 double robustMean; ///< robust mean of array 00067 double robustMedian; ///< robust median of array 00068 double robustMode; ///< Robust mode of array 00069 double robustStdev; ///< robust standard deviation of array 00070 double robustUQ; ///< robust upper quartile 00071 double robustLQ; ///< robust lower quartile 00072 int robustN50; ///< Number of points in Gaussian fit. XXX: This is currently never set. 00073 int robustNfit; ///< The number of points between the quartiles. 00074 double clippedMean; ///< Nsigma clipped mean 00075 double clippedStdev; ///< standard deviation after clipping 00076 int clippedNvalues; ///< Number of data points used for clipped mean: This value is never used. 00077 double clipSigma; ///< Nsigma used for clipping; user input 00078 int clipIter; ///< Number of clipping iterations; user input 00079 double min; ///< minimum data value in array 00080 double max; ///< maximum data value in array 00081 double binsize; ///< binsize for robust fit (input/ouput) 00082 psStatsOptions options; ///< bitmask of calculated values 00083 } 00084 psStats; 00085 00086 /** Performs statistical calculations on a vector. 00087 * 00088 * @return psStats* the statistical results as specified by stats->options 00089 */ 00090 psStats* psVectorStats( 00091 psStats* stats, ///< stats structure defines stats to be calculated and how 00092 const psVector* in, ///< Vector to be analysed. 00093 const psVector* errors, ///< Errors. 00094 const psVector* mask, ///< Ignore elements where (maskVector & maskVal) != 0: must be INT or NULL 00095 psMaskType maskVal ///< Only mask elements with one of these bits set in maskVector 00096 ); 00097 00098 /** Allocator of the psStats structure. 00099 * 00100 * @return psStats* A new psStats struct with the options member set to the 00101 * value given. 00102 */ 00103 psStats* psStatsAlloc( 00104 psStatsOptions options ///< Statistics to calculate 00105 ); 00106 00107 00108 /** Checks the type of a particular pointer. 00109 * 00110 * Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. 00111 * 00112 * @return bool: True if the pointer matches a psStats structure, false otherwise. 00113 */ 00114 bool psMemCheckStats( 00115 psPtr ptr ///< the pointer whose type to check 00116 ); 00117 00118 00119 /****************************************************************************** 00120 Histogram functions and data structures. 00121 *****************************************************************************/ 00122 00123 /** The basic histogram structure which contains bounds and bins. 00124 * 00125 * In this structure, the vector bounds specifies the boundaries of the 00126 * histogram bins, and must of type psF32, while nums specifies the number 00127 * of entries in the bin, and must of type psU32. The value of bounds.n must 00128 * therefore be 1 greater than than nums.n. The two values minNum and maxNum 00129 * are the number of data values which fell below the lower limit bound or 00130 * above the upper limit bound, respectively. 00131 */ 00132 typedef struct 00133 { 00134 const psVector* bounds; ///< Bounds for the bins (type F32) 00135 psVector* nums; ///< Number in each of the bins (INT) 00136 int minNum; ///< Number below the minimum 00137 int maxNum; ///< Number above the maximum 00138 bool uniform; ///< Is it a uniform distribution? 00139 } 00140 psHistogram; 00141 00142 /** Allocator for psHistogram where the bounds of the bins are implicitly 00143 * specified through simply specifying an upper and lower limit along with 00144 * the size of the bins. 00145 * 00146 * @return psHistogram* Newly allocated psHistogram 00147 */ 00148 psHistogram* psHistogramAlloc( 00149 float lower, ///< Lower limit for the bins 00150 float upper, ///< Upper limit for the bins 00151 int n ///< Number of bins 00152 ); 00153 00154 00155 /** Checks the type of a particular pointer. 00156 * 00157 * Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. 00158 * 00159 * @return bool: True if the pointer matches a psHistogram structure, false otherwise. 00160 */ 00161 bool psMemCheckHistogram( 00162 psPtr ptr ///< the pointer whose type to check 00163 ); 00164 00165 00166 /** Allocator for psHistogram where the bounds of the bins are explicitly 00167 * specified. 00168 * 00169 * @return psHistogram* Newly allocated psHistogram 00170 */ 00171 psHistogram* psHistogramAllocGeneric( 00172 const psVector* bounds ///< Bounds for the bins 00173 ); 00174 00175 /** Calculate a histogram 00176 * 00177 * The following function populates the histogram bins from the specified 00178 * vector (in). It alters and returns the histogram out structure. The input 00179 * vector may be of types psU8, psU16, psF32, psF64. 00180 * 00181 * @return psHistogram* histogram result 00182 */ 00183 psHistogram* psVectorHistogram( 00184 psHistogram* out, ///< Histogram data 00185 const psVector* values, ///< Vector to analyse 00186 const psVector* errors, ///< Errors 00187 const psVector* mask, ///< Mask dat for input vector 00188 psMaskType maskVal ///< Mask value 00189 ); 00190 00191 /** Extracts the statistic value specified by stats->options. 00192 * 00193 * @return psBool If more than one statistic result is set in stats->options, 00194 * false is returned and the value parameter is not set, 00195 * otherwise true is returned. 00196 */ 00197 psBool p_psGetStatValue( 00198 const psStats* stats, ///< the statistic struct to operate on 00199 00200 psF64 *value ///< if return is true, this is set to the specified statistic value by stats->options 00201 ); 00202 00203 // XXX: Create a single, generic, version of the vector normalize function. 00204 // XXX: Ask IfA for a public psLib function. 00205 00206 /** Normalize the range of a vector containing U8 values */ 00207 void p_psNormalizeVectorRangeU8( 00208 psVector* myData, ///< Vector containing the U8 values 00209 psU8 low, ///< Minimum value 00210 psU8 high ///< Maximum value 00211 ); 00212 00213 /** Normalize the range of a vector containing U16 values */ 00214 void p_psNormalizeVectorRangeU16( 00215 psVector* myData, ///< Vector containing the U16 values 00216 psU16 low, ///< Minimum value 00217 psU16 high ///< Maximum value 00218 ); 00219 00220 /** Normalize the range of a vector containing U32 values */ 00221 void p_psNormalizeVectorRangeU32( 00222 psVector* myData, ///< Vector containing the U32 values 00223 psU32 low, ///< Minimum value 00224 psU32 high ///< Maximum value 00225 ); 00226 00227 /** Normalize the range of a vector containing U64 values */ 00228 void p_psNormalizeVectorRangeU64( 00229 psVector* myData, ///< Vector containing the U64 values 00230 psU64 low, ///< Minimum value 00231 psU64 high ///< Maximum value 00232 ); 00233 00234 /** Normalize the range of a vector containing S8 values */ 00235 void p_psNormalizeVectorRangeS8( 00236 psVector* myData, ///< Vector containing the S8 values 00237 psS8 low, ///< Minimum value 00238 psS8 high ///< Maximum value 00239 ); 00240 00241 /** Normalize the range of a vector containing S16 values */ 00242 void p_psNormalizeVectorRangeS16( 00243 psVector* myData, ///< Vector containing the S16 values 00244 psS16 low, ///< Minimum value 00245 psS16 high ///< Maximum value 00246 ); 00247 00248 /** Normalize the range of a vector containing S32 values */ 00249 void p_psNormalizeVectorRangeS32( 00250 psVector* myData, ///< Vector containing the S32 values 00251 psS32 low, ///< Minimum value 00252 psS32 high ///< Maximum value 00253 ); 00254 00255 /** Normalize the range of a vector containing S64 values */ 00256 void p_psNormalizeVectorRangeS64( 00257 psVector* myData, ///< Vector containing the S64 values 00258 psS64 low, ///< Minimum value 00259 psS64 high ///< Maximum value 00260 ); 00261 00262 /** Normalize the range of a vector containing F32 values */ 00263 void p_psNormalizeVectorRangeF32( 00264 psVector* myData, ///< Vector containing the F32 values 00265 psF32 low, ///< Minimum value 00266 psF32 high ///< Maximum value 00267 ); 00268 00269 /** Normalize the range of a vector containing F64 values */ 00270 void p_psNormalizeVectorRangeF64( 00271 psVector* myData, ///< Vector containing the F64 values 00272 psF64 low, ///< Minimum value 00273 psF64 high ///< Maximum value 00274 ); 00275 00276 /// @} 00277 00278 #endif // #ifndef PS_STATS_H
1.4.2