psStats.h

Go to the documentation of this file.

/* @file  psStats.h
 * @brief basic statistical operations
 *
 * This file will hold the definition of the histogram and stats data
 * structures.  It also contains prototypes for procedures which operate
 * on those data structures.
 *
 * @author GLG, MHPCC
 *
 * @version $Revision: 1.59 $ $Name:  $
 * @date $Date: 2007/01/23 22:47:23 $
 * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_STATS_H
#define PS_STATS_H

/// @addtogroup MathOps Mathematical Operations
/// @{

/******************************************************************************
    Statistical functions and data structures.
 *****************************************************************************/

/** enumeration of statistical calculation options
 *
 *  @see psStats, psVectorStats, psImageStats
 */
typedef enum {
    PS_STAT_NONE            = 0x000000, ///< Empty set
    PS_STAT_SAMPLE_MEAN     = 0x000001, ///< Sample Mean
    PS_STAT_SAMPLE_MEDIAN   = 0x000002, ///< Sample Median
    PS_STAT_SAMPLE_STDEV    = 0x000004, ///< Sample Standard Deviation
    PS_STAT_SAMPLE_QUARTILE = 0x000008, ///< Sample Quartile
    PS_STAT_ROBUST_MEDIAN   = 0x000010, ///< Robust Median
    PS_STAT_ROBUST_STDEV    = 0x000020, ///< Robust Standarad Deviation
    PS_STAT_ROBUST_QUARTILE = 0x000040, ///< Robust Quartile
    PS_STAT_FITTED_MEAN     = 0x000080, ///< Fitted Mean
    PS_STAT_FITTED_STDEV    = 0x000100, ///< Fitted Standard Deviation
    PS_STAT_CLIPPED_MEAN    = 0x000200, ///< Clipped Mean
    PS_STAT_CLIPPED_STDEV   = 0x000400, ///< Clipped Standard Deviation
    PS_STAT_MAX             = 0x000800, ///< Maximum
    PS_STAT_MIN             = 0x001000, ///< Minumum
    PS_STAT_USE_RANGE       = 0x002000, ///< Range
    PS_STAT_USE_BINSIZE     = 0x004000, ///< Binsize
    PS_STAT_FITTED_MEAN_V2  = 0x008000, ///< Fitted Mean
    PS_STAT_FITTED_STDEV_V2 = 0x010000, ///< Fitted Standard Deviation
    PS_STAT_FITTED_MEAN_V3  = 0x020000, ///< Fitted Mean
    PS_STAT_FITTED_STDEV_V3 = 0x040000, ///< Fitted Standard Deviation
} psStatsOptions;

/** This is the generic statistics structure.  It contails the data members
    for the various statistic values.  It also contains the options member to
    specifiy which statistics should be calculated. */
typedef struct
{
    double sampleMean;                 ///< formal mean of sample
    double sampleMedian;               ///< formal median of sample
    double sampleStdev;                ///< standard deviation of sample
    double sampleUQ;                   ///< upper quartile of sample
    double sampleLQ;                   ///< lower quartile of sample
    double robustMedian;               ///< robust median of array
    double robustStdev;                ///< robust standard deviation of array
    double robustUQ;                   ///< robust upper quartile
    double robustLQ;                   ///< robust lower quartile
    long robustN50;                    ///< Number of points in Gaussian fit; XXX: This is currently unused.
    double fittedMean;                 ///< robust mean of data
    double fittedStdev;                ///< robust standard deviation of data
    long fittedNfit;                   ///< Number of points in Gaussian fit; XXX: This is currently unused
    double clippedMean;                ///< Nsigma clipped mean
    double clippedStdev;               ///< standard deviation after clipping
    long clippedNvalues;               ///< Number of data points used for clipped mean.
    double clipSigma;                  ///< Nsigma used for clipping; user input
    int clipIter;                      ///< Number of clipping iterations; user input
    double min;                        ///< minimum data value in array
    double max;                        ///< maximum data value in array
    double binsize;                    ///< binsize for robust fit (input/ouput)
    long nSubsample;                   ///< maxinum number of measurements (input)
    psStatsOptions options;            ///< bitmask of values requested
    psStatsOptions results;            ///< bitmask of values calculated
}
psStats;

/** Performs statistical calculations on a vector.
 *
 *  @return psStats*    the statistical results as specified by stats->options
 */
bool psVectorStats(
    psStats* stats,                    ///< stats structure defines stats to be calculated and how
    const psVector* in,                ///< Vector to be analysed.
    const psVector* errors,            ///< Errors.
    const psVector* mask,              ///< Ignore elements where (maskVector & maskVal) != 0: must be INT or NULL
    psMaskType 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
);


/** Checks the type of a particular pointer.
 *
 *  Uses the appropriate deallocation function in psMemBlock to check the ptr datatype.
 *
 *  @return bool:       True if the pointer matches a psStats structure, false otherwise.
 */
bool psMemCheckStats(
    psPtr ptr                          ///< the pointer whose type to check
);

// Get the statistics option from a string
psStatsOptions psStatsOptionFromString(const char *string);
// Write a string from the statistics options
psString psStatsOptionToString(psStatsOptions option);
// Generate a psStats from a string of statistics options
psStats *psStatsFromString(const char *string);
// Generate a string of statistics options from a psStats
psString psStatsToString(const psStats *stats);
// Is only a single statistics option set?
psStatsOptions psStatsSingleOption(psStatsOptions option);
// Return a particular stats value
double psStatsGetValue(const psStats *stats, psStatsOptions option);

/// @}
#endif // #ifndef PS_STATS_H

/*
 * private stats functions used in psStats.c:
 *
 * vectorSampleMean
   (none)
 * vectorMinMax
   (none)
 * vectorSampleMedian (also yields SAMPLE_QUARTILE)
   (none) 
 * vectorSampleStdev
   (vectorSampleMean)
 * vectorClippedStats
   (vectorSampleMedian)
   (vectorSampleMean (*also subset))
   (vectorSampleStdev (*also subset))
 * vectorRobustStats
   (vectorMinMax (*only subset))
 * vectorFittedStats
   (vectorRobustStats)
 
 * private stats functions called by other private stats functions are automatically called by
 * those functions.  since they set the stats->results flags, they are not called multiple
 * times.
 
 * the private stats functions do not test for their corresponding stats flags: it is not
 * necessary to request them if they are called within this function.
 
*/

---