/** @file  psStats.c
 *  \brief basic statistical operations
 *  @ingroup Stat
 *
 *  This file will hold the definitions of the histogram and stats data
 *  structures.  It also contains prototypes for procedures which operate
 *  on those data structures.
 *
 *  @author GLG, MHPCC
 *
 *  XXX: The following stats members are never used, or set in this code.
 *      stats->clippedNvalues
 *
 * XXX: Must do
 * nSubsample points
 * use ->min and ->max (PS_STAT_USE_RANGE)
 *
 *  @version $Revision: 1.176 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2006-06-30 02:20:06 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
 */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <stdarg.h>
#include <float.h>
#include <math.h>
#include <limits.h>

/*****************************************************************************/
/* INCLUDE FILES                                                             */
/*****************************************************************************/
#include "psMemory.h"
#include "psImage.h"
#include "psVector.h"
#include "psTrace.h"
#include "psLogMsg.h"
#include "psError.h"
#include "psStats.h"
#include "psMinimizeLMM.h"
#include "psMinimizePolyFit.h"
#include "psPolynomial.h"
#include "psAssert.h"
#include "psMathUtils.h"

#include "psErrorText.h"

/*****************************************************************************/
/* DEFINE STATEMENTS                                                         */
/*****************************************************************************/
#define PS_GAUSS_WIDTH 3                // The width of the Gaussian smoothing.
// This corresponds to N in the ADD.
#define PS_CLIPPED_NUM_ITER_LB 1
#define PS_CLIPPED_NUM_ITER_UB 10
#define PS_CLIPPED_SIGMA_LB 1.0
#define PS_CLIPPED_SIGMA_UB 10.0
#define PS_POLY_MEDIAN_MAX_ITERATIONS 30

#define PS_BIN_MIDPOINT(HISTOGRAM, BIN_NUM) \
(0.5 * (HISTOGRAM->bounds->data.F32[(BIN_NUM)] + HISTOGRAM->bounds->data.F32[(BIN_NUM)+1]))
/*****************************************************************************/
/* TYPE DEFINITIONS                                                          */
/*****************************************************************************/

// None

/*****************************************************************************/
/* GLOBAL VARIABLES                                                          */
/*****************************************************************************/

// None

/*****************************************************************************/
/* FILE STATIC VARIABLES                                                     */
/*****************************************************************************/

// None

/*****************************************************************************/
/* FUNCTION IMPLEMENTATION - LOCAL                                           */
/*****************************************************************************/

psBool p_psGetStatValue(const psStats* stats, psF64 *value)
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);
    //    switch (stats->options & ~(PS_STAT_USE_RANGE | PS_STAT_USE_BINSIZE | PS_STAT_ROBUST_FOR_SAMPLE)) {
    switch (stats->options & ~(PS_STAT_USE_RANGE | PS_STAT_USE_BINSIZE)) {
    case PS_STAT_SAMPLE_MEAN:
        *value = stats->sampleMean;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    case PS_STAT_SAMPLE_MEDIAN:
        *value = stats->sampleMedian;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    case PS_STAT_SAMPLE_STDEV:
        *value = stats->sampleStdev;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    case PS_STAT_ROBUST_MEDIAN:
        *value = stats->robustMedian;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    case PS_STAT_ROBUST_STDEV:
        *value = stats->robustStdev;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    case PS_STAT_CLIPPED_MEAN:
        *value = stats->clippedMean;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    case PS_STAT_CLIPPED_STDEV:
        *value = stats->clippedStdev;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    case PS_STAT_MAX:
        *value = stats->max;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    case PS_STAT_MIN:
        *value = stats->min;
        psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
        return true;

    default:
        psTrace(__func__, 4, "---- %s(false) end ----\n", __func__);
        return false;
    }
}

/******************************************************************************
MISC PRIVATE STATISTICAL FUNCTIONS
 
NOTE: it is assumed that any call to these statistical functions will have
been preceded by a call to the psVectorStats() function.  Various sanity tests
will only be performed in psVectorStats().  Should we perform the sanity
checks in each routine anyway?
 
XXX: For many of these private stats routines, what should be done if there
are no acceptable elements in the input vector (if no elements lie within
range, or there are no unmasked elements, or the input vector is NULL)?
Currently we set the value to NAN.
 
XXX: Optimization: many routines have an "empty" boolean variable which keeps
track of whether or not the vector has any valid elements.  This code can
possibly be optimized away.
 *****************************************************************************/
/******************************************************************************
vectorSampleMean(myVector, maskVector, maskVal, stats): calculates the
mean of the input vector.  If there was a problem with the mean calculation,
this routine sets stats->sampleMean to NAN.
 *****************************************************************************/
static bool vectorSampleMean(const psVector* myVector,
                             const psVector* errors,
                             const psVector* maskVector,
                             psMaskType maskVal,
                             psStats* stats)
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);

    psF32 mean = 0.0;                   // The mean
    long count = 0;                     // Number of points contributing to this mean

    // If PS_STAT_USE_RANGE is requested, then we enter a slightly different loop.
    if (!errors) {
        if (stats->options & PS_STAT_USE_RANGE) {
            if (maskVector) {
                // No errors, check range, check mask
                for (long i = 0; i < myVector->n; i++) {
                    // Check if the data is with the specified range
                    if (!(maskVal & maskVector->data.U8[i]) &&
                            (stats->min <= myVector->data.F32[i]) &&
                            (myVector->data.F32[i] <= stats->max)) {
                        mean += myVector->data.F32[i];
                        count++;
                    }
                }

            } else {
                // No errors, check range, no mask
                for (long i = 0; i < myVector->n; i++) {
                    if ((stats->min <= myVector->data.F32[i]) &&
                            (myVector->data.F32[i] <= stats->max)) {
                        mean += myVector->data.F32[i];
                        count++;
                    }
                }
            }
        } else {
            if (maskVector) {
                // No errors, no range check, check mask
                for (long i = 0; i < myVector->n; i++) {
                    if (!(maskVal & maskVector->data.U8[i])) {
                        mean += myVector->data.F32[i];
                        count++;
                    }
                }

            } else {
                // No errors, no range check, no mask
                for (long i = 0; i < myVector->n; i++) {
                    mean += myVector->data.F32[i];
                }
                count = myVector->n;
            }
        }

        if (count > 0) {
            mean /= (psF32)count;
        } else {
            mean = NAN;
        }

    } else {
        psF32 sumWeights = 0.0;         // The sum of the weights
        if (stats->options & PS_STAT_USE_RANGE) {
            if (maskVector != NULL) {
                for (long i = 0; i < myVector->n; i++) {
                    // Check if the data is with the specified range
                    if (!(maskVal & maskVector->data.U8[i]) &&
                            (stats->min <= myVector->data.F32[i]) &&
                            (myVector->data.F32[i] <= stats->max)) {
                        float weight = 1.0 / PS_SQR(errors->data.F32[i]);
                        mean += myVector->data.F32[i] * weight;
                        sumWeights += weight;
                        count++;
                    }
                }
            } else {
                for (long i = 0; i < myVector->n; i++) {
                    if ((stats->min <= myVector->data.F32[i]) &&
                            (myVector->data.F32[i] <= stats->max)) {
                        float weight = 1.0 / PS_SQR(errors->data.F32[i]);
                        mean += myVector->data.F32[i] * weight;
                        sumWeights += weight;
                        count++;
                    }
                }
            }
        } else {
            if (maskVector != NULL) {
                for (long i = 0; i < myVector->n; i++) {
                    if (!(maskVal & maskVector->data.U8[i])) {
                        float weight = 1.0 / PS_SQR(errors->data.F32[i]);
                        mean += myVector->data.F32[i] * weight;
                        sumWeights += weight;
                        count++;
                    }
                }
            } else {
                for (long i = 0; i < myVector->n; i++) {
                    float weight = 1.0 / PS_SQR(errors->data.F32[i]);
                    mean += myVector->data.F32[i] * weight;
                    sumWeights += weight;
                }
                count = myVector->n;
            }
        }

        if (count > 0) {
            mean /= sumWeights;
        } else {
            mean = NAN;
        }
    }

    stats->sampleMean = mean;
    if (isnan(mean)) {
        psTrace(__func__, 4, "---- %s(false) end ----\n", __func__);
        return false;
    }

    psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
    return true;
}

/******************************************************************************
vectorMinMax(myVector, maskVector, maskVal, stats): calculates the minimum and maximum of the input vector.
If there was a problem with the calculation, this routine sets stats->max and stats->min to NAN.  Return the
number of valid values in the vector (those not masked or outside the specified range.
 *****************************************************************************/
static long vectorMinMax(const psVector* myVector,
                         const psVector* maskVector,
                         psMaskType maskVal,
                         psStats* stats
                        )
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);
    psF32 max = -PS_MAX_F32;            // The calculated maximum
    psF32 min = PS_MAX_F32;             // The calculated minimum
    psF32 *vector = myVector->data.F32; // Dereference the vector
    psU8 *mask = NULL;                  // Dereference the mask
    if (maskVector) {
        mask = maskVector->data.U8;
    }
    int num = myVector->n;              // Number of values
    int numValid = 0;                   // Number of valid values

    // If PS_STAT_USE_RANGE is requested, then we enter a different loop.
    if (stats->options & PS_STAT_USE_RANGE) {
        if (mask) {
            // Need to check range and mask
            for (long i = 0; i < num; i++) {
                if (!(maskVal & mask[i]) && vector[i] >= stats->min && vector[i] <= stats->max) {
                    numValid++;
                    if (vector[i] > max) {
                        max = vector[i];
                    }
                    if (vector[i] < min) {
                        min = vector[i];
                    }
                }
            }
        } else {
            // Need to check range
            for (long i = 0; i < num; i++) {
                if (vector[i] >= stats->min && vector[i] <= stats->max) {
                    numValid++;
                    if (vector[i] > max) {
                        max = vector[i];
                    }
                    if (vector[i] < min) {
                        min = vector[i];
                    }
                }
            }
        }
    } else {
        if (mask) {
            // Need to check mask
            for (long i = 0; i < num; i++) {
                if (!(maskVal & mask[i])) {
                    numValid++;
                    if (vector[i] > max) {
                        max = vector[i];
                    }
                    if (vector[i] < min) {
                        min = vector[i];
                    }
                }
            }
        } else {
            // No checks
            for (long i = 0; i < num; i++) {
                if (vector[i] > max) {
                    max = vector[i];
                }
                if (vector[i] < min) {
                    min = vector[i];
                }
            }
            numValid = num;
        }
    }


    if (numValid == 0) {
        stats->max = NAN;
        stats->min = NAN;
    } else {
        stats->max = max;
        stats->min = min;
    }
    psTrace(__func__, 4, "---- %s(%d) end ----\n", __func__, numValid);
    return numValid;
}

#if 0
/******************************************************************************
vectorCheckNonEmpty(myVector, maskVector, maskVal, stats): This routine returns
"true" if the inputPsVector has 1 or more valid elements (a valid element is an
unmasked element within the specified min/max range).  Otherwise, return
"false".
 *****************************************************************************/
static bool vectorCheckNonEmpty(const psVector* myVector,
                                const psVector* maskVector,
                                psMaskType maskVal,
                                psStats* stats)
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);
    PS_ASSERT_VECTOR_NON_NULL(myVector, false);
    PS_ASSERT_PTR_NON_NULL(stats, false);

    if (stats->options & PS_STAT_USE_RANGE) {
        if (maskVector) {
            for (long i = 0; i < myVector->n; i++) {
                if (!(maskVal & maskVector->data.U8[i]) &&
                        (stats->min <= myVector->data.F32[i]) &&
                        (myVector->data.F32[i] <= stats->max)) {
                    psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
                    return true;
                }
            }
        } else {
            for (long i = 0; i < myVector->n; i++) {
                if ((stats->min <= myVector->data.F32[i]) &&
                        (myVector->data.F32[i] <= stats->max)) {
                    psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
                    return true;
                }
            }
        }
    } else {
        if (maskVector != NULL) {
            for (long i = 0; i < myVector->n; i++) {
                if (!(maskVal & maskVector->data.U8[i])) {
                    psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
                    return true;
                }
            }
        } else {
            if (myVector->n > 0) {
                psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
                return true;
            }
        }
    }
    psTrace(__func__, 4, "---- %s(false) end ----\n", __func__);
    return(false);
}
#endif

/******************************************************************************
vectorSampleMedian(myVector, maskVector, maskVal, stats): calculates the median
and quartiles of the input vector.  Returns true on success (including if there
were no valid input vector elements).
 *****************************************************************************/
static bool vectorSampleMedian(const psVector* myVector,
                               const psVector* maskVector,
                               psMaskType maskVal,
                               psStats* stats)
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);

    // Allocate temporary vectors for the data.
    psVector* vector = psVectorAlloc(myVector->n, PS_TYPE_F32); // Vector containing the unmasked values
    long count = 0;                     // Number of valid entries

    // Determine if we must only use data points within a min/max range.
    if (stats->options & PS_STAT_USE_RANGE) {
        // Store all non-masked data points within the min/max range
        // into the temporary vectors.
        if (maskVector != NULL) {
            for (long i = 0; i < myVector->n; i++) {
                if (!(maskVal & maskVector->data.U8[i]) &&
                        (stats->min <= myVector->data.F32[i]) &&
                        (myVector->data.F32[i] <= stats->max)) {
                    vector->data.F32[count] = myVector->data.F32[i];
                    count++;
                }
            }
        } else {
            for (long i = 0; i < myVector->n; i++) {
                if ((stats->min <= myVector->data.F32[i]) &&
                        (myVector->data.F32[i] <= stats->max)) {
                    vector->data.F32[count] = myVector->data.F32[i];
                    count++;
                }
            }
        }
    } else {
        // Store all non-masked data points into the temporary vectors.
        if (maskVector) {
            for (long i = 0; i < myVector->n; i++) {
                if (!(maskVal & maskVector->data.U8[i])) {
                    vector->data.F32[count] = myVector->data.F32[i];
                    count++;
                }
            }
        } else {
            vector = psVectorCopy(vector, myVector, PS_TYPE_F32);
            count = myVector->n;
        }
    }
    vector->n = count;
    if (count == 0) {
        psError(PS_ERR_BAD_PARAMETER_SIZE, true, "No valid data in input vector.\n");
        psFree(vector);
        stats->sampleMedian = NAN;
        return false;
    }

    // Sort the temporary vector.
    vector = psVectorSort(vector, vector); // Sort in-place (since it's a copy, it's OK)
    if (!vector) {
        psError(PS_ERR_UNEXPECTED_NULL,
                false,
                PS_ERRORTEXT_psStats_STATS_SAMPLE_MEDIAN_SORT_PROBLEM);
        psTrace(__func__, 4, "---- %s(false) end ----\n", __func__);
        psFree(vector);
        return false;
    }

    // Calculate the median exactly.  Use the average if the number of samples
    // is even.
    if (count % 2 == 0) {
        stats->sampleMedian = 0.5 * (vector->data.F32[(count / 2) - 1] +
                                     vector->data.F32[count / 2]);
    } else {
        stats->sampleMedian = vector->data.F32[count / 2];
    }

    // Calculate the quartile points exactly.
    stats->sampleUQ = vector->data.F32[3 * (count / 4)];
    stats->sampleLQ = vector->data.F32[count / 4];

    // Free the temporary data structures.
    psFree(vector);

    // Return "true" on success.
    psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
    return true;
}

/******************************************************************************
vectorSmoothHistGaussian(): This routine smoothes the data in the input
robustHistogram with a Gaussian of width sigma.  It returns a psVector of the
smoothed data.
 *****************************************************************************/
psVector *vectorSmoothHistGaussian(psHistogram *histogram,
                                   psF32 sigma)
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);
    psTrace(__func__, 5, "(histogram->nums->n, sigma) is (%d, %.2f\n", (int) histogram->nums->n, sigma);
    PS_ASSERT_PTR_NON_NULL(histogram, NULL);
    PS_ASSERT_PTR_NON_NULL(histogram->bounds, NULL);
    PS_ASSERT_PTR_NON_NULL(histogram->nums, NULL);
    if (psTraceGetLevel(__func__) >= 8) {
        PS_VECTOR_PRINT_F32(histogram->nums);
    }

    long numBins = histogram->nums->n;  // Number of histogram bins
    psVector *smooth = psVectorAlloc(numBins, PS_TYPE_F32); // Smoothed version of histogram bins
    smooth->n = smooth->nalloc;
    const psVector *bounds = histogram->bounds; // The bounds for the histogram bins

    if (!histogram->uniform) {
        //
        // We get here if the histogram is non-uniform.  This code is not tested.
        // However, it is also not used anywhere, yet.
        //
        psLogMsg(__func__, PS_LOG_WARN, "WARNING: vectorSmoothHistGaussian() on non-uniform histograms has not been tested or used.\n");

        for (long i = 0; i < numBins; i++) {
            // Determine the midpoint of bin i.
            float iMid = PS_BIN_MIDPOINT(histogram, i);

            //
            // We determine the bin numbers (jMin:jMax) corresponding to a
            // range of data values surrounding iMid.  The range is of size:
            // 2*PS_GAUSS_WIDTH*sigma
            long jMin, jMax;
            psF32 x = iMid - (PS_GAUSS_WIDTH * sigma);
            for (jMin = i; jMin > 0 && bounds->data.F32[jMin] > x; jMin--)
                ;
            x = iMid + (PS_GAUSS_WIDTH * sigma);
            for (jMax = i; jMax < bounds->n - 1 && bounds->data.F32[jMax + 1] > x; jMax++)
                ;

            //
            // Loop from jMin to jMax, computing the gaussian of data i.
            //
            smooth->data.F32[i] = 0.0;
            for (long j = jMin ; j <= jMax ; j++) {
                float jMid = PS_BIN_MIDPOINT(histogram, j);
                smooth->data.F32[i] +=
                    histogram->nums->data.F32[j] * psGaussian(jMid, iMid, sigma, true);
            }
        }
    } else {
        //
        // We get here if the histogram is uniform.
        //
        for (long i = 0; i < numBins; i++) {
            psF32 binSize = bounds->data.F32[1] - bounds->data.F32[0];
            psS32 gaussWidth = ((PS_GAUSS_WIDTH * sigma) / binSize);

            //
            // XXX: The following is wrong.  However, in practice, the sigma was too
            // large compared to the binSize.  This meant that the smoothing was done
            // over 500 bins in the robust stats algorithm.  This mean that the smoothing
            // took way too long.
            //
            #if 0

            gaussWidth = 10;
            #endif
            //
            // We determine the bin numbers (jMin:jMax) corresponding to a
            // range of data values surrounding iMid.  The range is of size:
            // 2*PS_GAUSS_WIDTH*sigma
            //
            psS32 jMin = PS_MAX(i - gaussWidth, 0);
            psS32 jMax = PS_MIN(i + gaussWidth, bounds->n - 1);

            //
            // Loop from jMin to jMax, computing the gaussian of data i.
            //
            smooth->data.F32[i] = 0.0;
            float iMid = PS_BIN_MIDPOINT(histogram, i);
            for (long j = jMin ; j <= jMax ; j++) {
                float jMid = PS_BIN_MIDPOINT(histogram, j);
                smooth->data.F32[i] +=
                    histogram->nums->data.F32[j] * psGaussian(jMid, iMid, sigma, true);
            }
        }
    }

    if (psTraceGetLevel(__func__) >= 8) {
        PS_VECTOR_PRINT_F32(smooth);
    }
    psTrace(__func__, 4, "---- %s() end ----\n", __func__);
    return(smooth);
}

/******************************************************************************
vectorSampleStdev(myVector, maskVector, maskVal, stats): calculates the
stdev of the input vector.
Inputs
    myVector
    maskVector
    maskVal
    stats
Returns
    NULL
 
 *****************************************************************************/
static bool vectorSampleStdev(const psVector* myVector,
                              const psVector* errors,
                              const psVector* maskVector,
                              psMaskType maskVal,
                              psStats* stats)
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);

    // This procedure requires the mean.  If it has not been already
    // calculated, then call vectorSampleMean()
    if (isnan(stats->sampleMean)) {
        vectorSampleMean(myVector, errors, maskVector, maskVal, stats);
    }
    // If the mean is NAN, then generate a warning and set the stdev to NAN.
    if (isnan(stats->sampleMean)) {
        stats->sampleStdev = NAN;
        psLogMsg(__func__, PS_LOG_WARN, "WARNING: vectorSampleStdev(): vectorSampleMean() reported a NAN mean.\n");
        psTrace(__func__, 4, "---- %s() end ----\n", __func__);
        return false;
    }

    // Accumulate the sums
    double mean = stats->sampleMean;    // The mean
    double sumSquares = 0.0;            // Sum of the squares
    double sumDiffs = 0.0;              // Sum of the differences
    double errorDivisor = 0.0;          // Division for errors
    long count = 0;                     // Number of data points being used
    if (stats->options & PS_STAT_USE_RANGE) {
        if (maskVector) {
            for (long i = 0; i < myVector->n; i++) {
                if (!(maskVal & maskVector->data.U8[i]) &&
                        (stats->min <= myVector->data.F32[i]) &&
                        (myVector->data.F32[i] <= stats->max)) {
                    double diff = myVector->data.F32[i] - mean;
                    sumSquares += PS_SQR(diff);
                    sumDiffs += diff;
                    count++;
                    if (errors) {
                        errorDivisor += 1.0 / PS_SQR(errors->data.F32[i]);
                    }
                }
            }
        } else {
            for (long i = 0; i < myVector->n; i++) {
                if ((stats->min <= myVector->data.F32[i]) && (myVector->data.F32[i] <= stats->max)) {
                    double diff = myVector->data.F32[i] - mean;
                    sumSquares += PS_SQR(diff);
                    sumDiffs += diff;
                    count++;
                    if (errors) {
                        errorDivisor += 1.0 / PS_SQR(errors->data.F32[i]);
                    }
                }
            }
            count = myVector->n;
        }
    } else {
        if (maskVector) {
            for (long i = 0; i < myVector->n; i++) {
                if (!(maskVal & maskVector->data.U8[i])) {
                    double diff = myVector->data.F32[i] - mean;
                    sumSquares += PS_SQR(diff);
                    sumDiffs += diff;
                    count++;
                    if (errors) {
                        errorDivisor += 1.0 / PS_SQR(errors->data.F32[i]);
                    }
                }
            }
        } else {
            for (long i = 0; i < myVector->n; i++) {
                double diff = myVector->data.F32[i] - mean;
                sumSquares += PS_SQR(diff);
                sumDiffs += diff;
                count++;
                if (errors) {
                    errorDivisor += 1.0 / PS_SQR(errors->data.F32[i]);
                }
            }
            count = myVector->n;
        }
    }

    if (count == 0) {
        stats->sampleStdev = NAN;
        psLogMsg(__func__, PS_LOG_WARN, "WARNING: vectorSampleStdev(): no valid psVector elements (%d).  Setting stats->sampleStdev = NAN.\n", count);
        return false;
    }
    if (count == 1) {
        stats->sampleStdev = 0.0;
        psLogMsg(__func__, PS_LOG_WARN, "WARNING: vectorSampleStdev(): only one valid psVector elements (%d).  Setting stats->sampleStdev = 0.0.\n", count);
        return false;
    }

    if (errors) {
        #if 1
        // XXX: The ADD specifies this as the definition of the standard
        // deviation if the errors are known.  Verify this with IfA: none of
        // the data points in the vector are used.  Verify that the masks and
        // data ranges are used correctly.
        stats->sampleStdev = (1.0 / sqrtf(errorDivisor));
        #else

        stats->sampleStdev = sqrt((sumSquares - (sumDiffs * sumDiffs / (float)count)) /
                                  (float)(count - 1));
        #endif

    } else {
        stats->sampleStdev = sqrt((sumSquares - (sumDiffs * sumDiffs / (float)count)) /
                                  (float)(count - 1));

    }
    psTrace(__func__, 4, "---- %s() end ----\n", __func__);

    return true;
}

/******************************************************************************
vectorClippedStats(myVector, errors, maskVector, maskVal, stats): calculates the
clipped stats (mean or stdev) of the input vector.
 
Inputs
    myVector
    maskVector
    maskVal
    stats
Returns
    true for success; false otherwise
 *****************************************************************************/
static bool vectorClippedStats(const psVector* myVector,
                               const psVector* errors,
                               psVector* maskVector,
                               psMaskType maskVal,
                               psStats* stats
                              )
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);
    psTrace(__func__, 4, "Trace level is %d\n", psTraceGetLevel(__func__));

    // Ensure that stats->clipIter is within the proper range.
    PS_ASSERT_INT_WITHIN_RANGE(stats->clipIter,
                               PS_CLIPPED_NUM_ITER_LB,
                               PS_CLIPPED_NUM_ITER_UB, -1);

    // Ensure that stats->clipSigma is within the proper range.
    PS_ASSERT_INT_WITHIN_RANGE(stats->clipSigma,
                               PS_CLIPPED_SIGMA_LB,
                               PS_CLIPPED_SIGMA_UB, -1);

    // Allocate a psStats structure for calculating the mean, median, and
    // stdev.
    psStats *statsTmp = psStatsAlloc(PS_STAT_SAMPLE_MEAN | PS_STAT_SAMPLE_STDEV);

    // We've already copied the mask vector, so it's safe to simply increment the reference counter.
    psVector *tmpMask = NULL;
    if (maskVector) {
        tmpMask = psMemIncrRefCounter(maskVector);
    } else {
        tmpMask = psVectorAlloc(myVector->n, PS_TYPE_U8);
        tmpMask->n = tmpMask->nalloc;
        psVectorInit(tmpMask, 0);
    }

    // 1. Compute the sample median.
    vectorSampleMedian(myVector, tmpMask, maskVal, statsTmp);
    if (isnan(statsTmp->sampleMedian)) {
        psLogMsg(__func__, PS_LOG_WARN, "Call to vectorSampleMedian returned NAN\n");
        stats->clippedMean = NAN;
        stats->clippedStdev = NAN;
        psTrace(__func__, 4, "---- %s(false) end ----\n", __func__);
        psFree(tmpMask);
        psFree(statsTmp);
        return false;
    }
    psTrace(__func__, 6, "The initial sample median is %f\n", statsTmp->sampleMedian);

    // 2. Compute the sample standard deviation.
    vectorSampleStdev(myVector, errors, tmpMask, maskVal, statsTmp);
    if (isnan(statsTmp->sampleStdev)) {
        psLogMsg(__func__, PS_LOG_WARN, "Call to vectorSampleStdev returned NAN\n");
        stats->clippedMean = NAN;
        stats->clippedStdev = NAN;
        psTrace(__func__, 4, "---- %s(false) end ----\n", __func__);
        psFree(tmpMask);
        psFree(statsTmp);
        return false;
    }
    psTrace(__func__, 6, "The initial sample stdev is %f\n", statsTmp->sampleStdev);

    // 3. Use the sample median as the first estimator of the mean X.
    psF32 clippedMean = statsTmp->sampleMedian;

    // 4. Use the sample stdev as the first estimator of the mean stdev.
    psF32 clippedStdev = statsTmp->sampleStdev;

    // 5. Repeat N (stats->clipIter) times:
    long numClipped = 0;                // Number of values clipped
    bool clipped = true;                // Have we clipped anything in this iteration
    for (int iter = 0; iter < stats->clipIter && clipped; iter++) {
        clipped = false;
        psTrace(__func__, 6, "------------ Iteration %d ------------\n", iter);
        // a) Exclude all values x_i for which |x_i - x| > K * stdev
        if (errors) {
            for (long j = 0; j < myVector->n; j++) {
                if (! tmpMask->data.U8[j] & maskVal &&
                        fabsf(myVector->data.F32[j] - clippedMean) > stats->clipSigma * errors->data.F32[j]) {
                    tmpMask->data.U8[j] = 0xff;
                    psTrace(__func__, 10, "Clipped %d: %f +/- %f\n", j,
                            myVector->data.F32[j], errors->data.F32[j]);
                    numClipped++;
                    clipped = true;
                }
            }
        } else {
            for (long j = 0; j < myVector->n; j++) {
                if (! tmpMask->data.U8[j] & maskVal &&
                        fabsf(myVector->data.F32[j] - clippedMean) > (stats->clipSigma * clippedStdev)) {
                    tmpMask->data.U8[j] = 0xff;
                    psTrace(__func__, 10, "Clipped %d: %f\n", j, myVector->data.F32[j]);
                    numClipped++;
                    clipped = true;
                }
            }
        }

        // b) compute new mean and stdev
        vectorSampleMean(myVector, errors, tmpMask, maskVal, statsTmp);
        vectorSampleStdev(myVector, errors, tmpMask, maskVal, statsTmp);
        psTrace(__func__, 6, "The new sample mean is %f\n", statsTmp->sampleMean);
        psTrace(__func__, 6, "The new sample stdev is %f\n", statsTmp->sampleStdev);

        // If the new mean and stdev are NAN, we must exit the loop.
        // Otherwise, use the new results and continue.
        if (isnan(statsTmp->sampleMean) || isnan(statsTmp->sampleStdev)) {
            // Exit loop.
            iter = stats->clipIter;
            psError(PS_ERR_UNKNOWN, true, "vectorSampleMean() or vectorSampleStdev() returned a NAN.\n");
            psFree(tmpMask);
            return false;
        } else {
            clippedMean = statsTmp->sampleMean;
            clippedStdev = statsTmp->sampleStdev;
        }
    }

    // Number of values used in calculation is the total number of data values, minus those we clipped
    stats->clippedNvalues = myVector->n - numClipped;

    // 7. The last calcuated value of x is the clipped mean.
    if (stats->options & PS_STAT_CLIPPED_MEAN) {
        stats->clippedMean = clippedMean;
        psTrace(__func__, 6, "The final clipped mean is %f\n", clippedMean);
    }
    // 8. The last calcuated value of stdev is the clipped stdev.
    if (stats->options & PS_STAT_CLIPPED_STDEV) {
        stats->clippedStdev = clippedStdev;
        psTrace(__func__, 6, "The final clipped stdev is %f\n", clippedStdev);
    }

    psFree(tmpMask);
    psFree(statsTmp);
    psTrace(__func__, 4, "---- %s(true) end ----\n", __func__);
    return true;
}

static psF32 QuadraticInverse(psF32 a,
                              psF32 b,
                              psF32 c,
                              psF32 y,
                              psF32 xLo,
                              psF32 xHi
                             )
{
    psF64 tmp = sqrt((y - c)/a + (b*b)/(4.0 * a * a));

    psF64 x1 = -b/(2.0*a) + tmp;
    psF64 x2 = -b/(2.0*a) - tmp;

    #if 0

    psF64 y1 = (a * x1 * x1) + (b * x1) + c;
    psF64 y2 = (a * x2 * x2) + (b * x2) + c;
    printf("QuadraticInverse: %fx^2 + %fx + %f\n", a, b, c);
    printf("QuadraticInverse: y is %f\n", y);
    printf("QuadraticInverse: (x1, x2) is (%f %f)\n", x1, x2);
    printf("QuadraticInverse: (y1, y2) is (%f %f)\n", y1, y2);
    #endif

    if (xLo <= x1 && x1 <= xHi) {
        return x1;
    }
    if (xLo <= x2 && x2 <= xHi) {
        return x2;
    }
    return 0.5 * (xLo + xHi);
}


/******************************************************************************
fitQuadraticSearchForYThenReturnX(*xVec, *yVec, binNum, yVal): A general
routine which fits a quadratic to three points and returns the x-value
corresponding to the input y-value.  This routine takes psVectors of x/y pairs
as input, and fits a quadratic to the 3 points surrounding element binNum in
the vectors (the midpoint between element i and i+1 is used for x[i]).  It
then determines for what value x does that quadratic f(x) = yVal (the input
parameter).
 
*****************************************************************************/
static psF32 fitQuadraticSearchForYThenReturnX(const psVector *xVec,
        psVector *yVec,
        psS32 binNum,
        psF32 yVal
                                              )
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);
    psTrace(__func__, 5, "binNum, yVal is (%d, %f)\n", binNum, yVal);
    if (psTraceGetLevel(__func__) >= 8) {
        PS_VECTOR_PRINT_F32(xVec);
        PS_VECTOR_PRINT_F32(yVec);
    }

    PS_ASSERT_VECTOR_NON_NULL(xVec, NAN);
    PS_ASSERT_VECTOR_NON_NULL(yVec, NAN);
    PS_ASSERT_VECTOR_TYPE(xVec, PS_TYPE_F32, NAN);
    PS_ASSERT_VECTOR_TYPE(yVec, PS_TYPE_F32, NAN);
    //    PS_ASSERT_VECTORS_SIZE_EQUAL(xVec, yVec, NAN);
    PS_ASSERT_INT_WITHIN_RANGE(binNum, 0, (xVec->n - 1), NAN);
    PS_ASSERT_INT_WITHIN_RANGE(binNum, 0, (yVec->n - 1), NAN);

    psVector *x = psVectorAlloc(3, PS_TYPE_F64);
    psVector *y = psVectorAlloc(3, PS_TYPE_F64);
    x->n = 3;
    y->n = 3;
    psF32 tmpFloat = 0.0f;

    if ((binNum >= 1) && (binNum < (yVec->n - 2)) && (binNum < (xVec->n - 2))) {
        // The general case.  We have all three points.
        x->data.F64[0] = (psF64) (0.5 * (xVec->data.F32[binNum - 1] + xVec->data.F32[binNum]));
        x->data.F64[1] = (psF64) (0.5 * (xVec->data.F32[binNum] + xVec->data.F32[binNum+1]));
        x->data.F64[2] = (psF64) (0.5 * (xVec->data.F32[binNum+1] + xVec->data.F32[binNum+2]));
        y->data.F64[0] = yVec->data.F32[binNum - 1];
        y->data.F64[1] = yVec->data.F32[binNum];
        y->data.F64[2] = yVec->data.F32[binNum + 1];
        psTrace(__func__, 6, "x vec (orig) is (%f %f %f %f)\n", xVec->data.F32[binNum - 1],
                xVec->data.F32[binNum], xVec->data.F32[binNum+1], xVec->data.F32[binNum+2]);
        psTrace(__func__, 6, "x data is (%f %f %f)\n", x->data.F64[0], x->data.F64[1], x->data.F64[2]);
        psTrace(__func__, 6, "y data is (%f %f %f)\n", y->data.F64[0], y->data.F64[1], y->data.F64[2]);

        //
        // Ensure that the y value lies within range of the y values.
        //
        if (! (((y->data.F64[0] <= yVal) && (yVal <= y->data.F64[2])) ||
                ((y->data.F64[2] <= yVal) && (yVal <= y->data.F64[0]))) ) {
            psError(PS_ERR_BAD_PARAMETER_VALUE, true,
                    PS_ERRORTEXT_psStats_YVAL_OUT_OF_RANGE,
                    (psF64)yVal, y->data.F64[0], y->data.F64[2]);
        }

        //
        // Ensure that the y values are monotonic.
        //
        if (((y->data.F64[0] < y->data.F64[1]) && !(y->data.F64[1] <= y->data.F64[2])) ||
                ((y->data.F64[0] > y->data.F64[1]) && !(y->data.F64[1] >= y->data.F64[2]))) {
            psError(PS_ERR_UNKNOWN, true,
                    "This routine must be called with monotonically increasing or decreasing data points.\n");
            psFree(x);
            psFree(y);
            psTrace(__func__, 5, "---- %s() end ----\n", __func__);
            return NAN;
        }

        // Determine the coefficients of the polynomial.
        psPolynomial1D *myPoly = psPolynomial1DAlloc(PS_POLYNOMIAL_ORD, 2);
        myPoly = psVectorFitPolynomial1D(myPoly, NULL, 0, y, NULL, x);
        if (myPoly == NULL) {
            psError(PS_ERR_UNEXPECTED_NULL, false,
                    PS_ERRORTEXT_psStats_STATS_FIT_QUADRATIC_POLYNOMIAL_1D_FIT);
            psFree(x);
            psFree(y);
            psTrace(__func__, 5, "---- %s(NAN) end ----\n", __func__);
            return NAN;
        }
        psTrace(__func__, 6, "myPoly->coeff[0] is %f\n", myPoly->coeff[0]);
        psTrace(__func__, 6, "myPoly->coeff[1] is %f\n", myPoly->coeff[1]);
        psTrace(__func__, 6, "myPoly->coeff[2] is %f\n", myPoly->coeff[2]);
        psTrace(__func__, 6, "Fitted y vec is (%f %f %f)\n",
                (psF32) psPolynomial1DEval(myPoly, (psF64) x->data.F64[0]),
                (psF32) psPolynomial1DEval(myPoly, (psF64) x->data.F64[1]),
                (psF32) psPolynomial1DEval(myPoly, (psF64) x->data.F64[2]));

        psTrace(__func__, 6, "We fit the polynomial, now find x such that f(x) equals %f\n", yVal);
        tmpFloat = QuadraticInverse(myPoly->coeff[2], myPoly->coeff[1], myPoly->coeff[0], yVal,
                                    x->data.F64[0], x->data.F64[2]);
        psFree(myPoly);

        if (isnan(tmpFloat)) {
            psError(PS_ERR_UNEXPECTED_NULL,
                    false, PS_ERRORTEXT_psStats_STATS_FIT_QUADRATIC_POLY_MEDIAN);
            psFree(x);
            psFree(y);
            psTrace(__func__, 5, "---- %s(NAN) end ----\n", __func__);
            return(NAN);
        }
    } else {
        // These are special cases where the bin is at the beginning or end of the vector.
        if (binNum == 0) {
            // We have two points only at the beginning of the vectors x and y.
            tmpFloat = 0.5 * (xVec->data.F32[binNum] +
                              xVec->data.F32[binNum + 1]);
        } else if (binNum == (xVec->n - 1)) {
            // The special case where we have two points only at the end of
            // the vectors x and y.
            // XXX: Is this right?
            tmpFloat = xVec->data.F32[binNum];
        } else if (binNum == (xVec->n - 2)) {
            // XXX: Is this right?
            tmpFloat = 0.5 * (xVec->data.F32[binNum] + xVec->data.F32[binNum + 1]);
        }
    }

    psTrace(__func__, 6, "FIT: return %f\n", tmpFloat);
    psFree(x);
    psFree(y);

    psTrace(__func__, 5, "---- %s(%f) end ----\n", __func__, tmpFloat);
    return tmpFloat;
}

/******************************************************************************
NOTE: We assume unnormalized gaussians.
 *****************************************************************************/
static psF32 minimizeLMChi2Gauss1D(psVector *deriv,
                                   const psVector *params,
                                   const psVector *coords
                                  )
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);
    PS_ASSERT_VECTOR_NON_NULL(params, NAN);
    PS_ASSERT_VECTOR_SIZE(params, 2, NAN);
    PS_ASSERT_VECTOR_TYPE(params, PS_TYPE_F32, NAN);
    PS_ASSERT_VECTOR_NON_NULL(coords, NAN);
    PS_ASSERT_VECTOR_SIZE(coords, 1, NAN);
    PS_ASSERT_VECTOR_TYPE(coords, PS_TYPE_F32, NAN);

    psF32 x = coords->data.F32[0];
    psF32 mean = params->data.F32[0];
    psF32 stdev = params->data.F32[1];

    psF32 gauss = psGaussian(x, mean, stdev, false);
    if (deriv) {
        PS_ASSERT_VECTOR_SIZE(deriv, 2, NAN);
        PS_ASSERT_VECTOR_TYPE(deriv, PS_TYPE_F32, NAN);
        psF32 tmp = (x - mean) * gauss;
        deriv->data.F32[0] = tmp / (stdev * stdev);
        deriv->data.F32[1] = (x - mean) * tmp / (stdev * stdev * stdev);
    }


    psTrace(__func__, 4, "---- %s() end ----\n", __func__);
    return gauss;
}

/******************************************************************************
vectorRobustStats(myVector, maskVector, maskVal, stats): This is the new
version of the robust stats routine.
 
XXX: MUST DO: If the errors in the input values are known, then the same
approach is used, except that the histograms become probability density
functions (PDFs). In this case, the input values are spread out, so that they
do not simply contribute a single unit to the histogram, but rather contribute
a fraction of a value, equivalent to the weight. In the interests of speed, a
boxcar PDF may be used to represent each input value (as opposed to a
Gaussian), where the boxcar width is equal to 2p2 ln 2 times the error and
each input value contributes constant area. Then the robust median and
standard deviation are estimated in the same manner as above.
 
XXX: Check for errors in psLib routines that we call.
 
XXX: Review and ensure that all memory is free'ed at premature exits.
*****************************************************************************/
#define INITIAL_NUM_BINS 1000.0
static bool vectorRobustStats(const psVector* myVector,
                              const psVector* errors,
                              psVector* maskVector,
                              psMaskType maskVal,
                              psStats* stats)
{
    psTrace(__func__, 4, "---- %s() begin ----\n", __func__);
    if (psTraceGetLevel(__func__) >= 8) {
        PS_VECTOR_PRINT_F32(myVector);
    }

    psScalar tmpScalar;                 // Temporary scalar variable, for p_psVectorBinDisect
    tmpScalar.type.type = PS_TYPE_F32;

    // We need a mask for these statistics, so if the one we're given is NULL, make our own.
    psVector *mask = NULL;              // The actual mask we will use
    if (maskVector) {
        mask = psMemIncrRefCounter(maskVector);
    } else {
        mask = psVectorAlloc(myVector->n, PS_TYPE_U8);
        mask->n = myVector->n;
        psVectorInit(mask, 0);
    }

    psStats *statsMinMax = psStatsAlloc(PS_STAT_MIN | PS_STAT_MAX); // Statistics for min and max
    psHistogram *histogram = NULL;      // Histogram of the data
    psHistogram *cumulative = NULL;     // Cumulative histogram of the data
    float min = NAN, max = NAN;         // Mimimum and maximum values
    float sigma = NAN;                  // The robust standard deviation
    long totalDataPoints = 0;           // Total number of (unmasked) data points

    // Iterate to get the best bin size
    for (int iterate = 1; iterate > 0; iterate++) {
        psTrace(__func__, 6,
                "-------------------- Iterating on Bin size.  Iteration number %d --------------------\n",
                iterate);

        // Get the minimum and maximum values
        int numValid = vectorMinMax(myVector, mask, maskVal, statsMinMax); // Number of valid values
        min = statsMinMax->min;
        max = statsMinMax->max;
        if (numValid == 0 || isnan(min) || isnan(max)) {
            // Data range calculation failed
            psError(PS_ERR_UNKNOWN, false, "Failed to calculate the min/max of the input vector.\n");
            psFree(statsMinMax);
            psFree(mask);
            psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
            return false;
        }
        psTrace(__func__, 6, "Data min/max is (%.2f, %.2f)\n", min, max);

        // If all data points have the same value, then we set the appropiate members of stats and return.
        if (fabs(max - min) <= FLT_EPSILON) {
            psTrace(__func__, 5, "All data points have the same value: %f.\n", min);
            if (stats->options & PS_STAT_ROBUST_MEDIAN) {
                stats->robustMedian = min;
            }
            if (stats->options & PS_STAT_ROBUST_QUARTILE) {
                stats->robustUQ = min;
                stats->robustLQ = min;
            }
            stats->robustN50 = numValid;
            psFree(statsMinMax);
            psFree(mask);

            psTrace(__func__, 4, "---- %s(0) end  ----\n", __func__);
            return false;
        }

        float binSize = 0.0;            // Size of bins for histogram
        if ((iterate == 1) && (stats->options & PS_STAT_USE_BINSIZE)) {
            // Set initial bin size to the specified value.
            binSize = stats->binsize;
            psTrace(__func__, 6, "Setting initial robust bin size to %.2f\n", binSize);
        } else {
            // Determine the bin size of the robust histogram, using the pre-defined number of bins
            binSize = (max - min) / INITIAL_NUM_BINS;
        }
        psTrace(__func__, 6, "Initial robust bin size is %.2f\n", binSize);

        // ADD step 0: Construct the histogram with the specified bin size.  NOTE: we can not specify the bin
        // size precisely since the argument to psHistogramAlloc() is the number of bins, not the binSize.  If
        // we get here, we know that binSize != 0.0.
        long numBins = (max - min) / binSize; // Number of bins
        psTrace(__func__, 6, "Numbins is %d\n", numBins);
        psTrace(__func__, 6, "Creating a robust histogram from data range (%.2f - %.2f)\n", min, max);
        // Generate the histogram
        histogram = psHistogramAlloc(min, max, numBins);
        histogram = psVectorHistogram(histogram, myVector, errors, mask, maskVal);
        if (psTraceGetLevel(__func__) >= 8) {
            PS_VECTOR_PRINT_F32(histogram->bounds);
            PS_VECTOR_PRINT_F32(histogram->nums);
        }

        // ADD step 1: Convert the specific histogram to a cumulative histogram
        cumulative = psHistogramAlloc(min, max, numBins);
        cumulative->nums->data.F32[0] = histogram->nums->data.F32[0];
        for (long i = 1; i < histogram->nums->n; i++) {
            cumulative->nums->data.F32[i] = cumulative->nums->data.F32[i-1] + histogram->nums->data.F32[i];
        }
        if (psTraceGetLevel(__func__) >= 8) {
            PS_VECTOR_PRINT_F32(cumulative->bounds);
            PS_VECTOR_PRINT_F32(cumulative->nums);
        }

        // ADD step 2: Find the bin which contains the 50% data point.
        totalDataPoints = cumulative->nums->data.F32[numBins - 1];
        psTrace(__func__, 6, "Total data points is %d\n", totalDataPoints);
        long binMedian;
        if (totalDataPoints/2.0 < cumulative->nums->data.F32[0]) {
            // Special case: the median is in the first bin.  Perhaps we should recode this.
            // XXX: Must try a special case where the median in in the last bin.
            binMedian = 0;
        } else {
            tmpScalar.data.F32 = totalDataPoints/2.0;
            binMedian = 1 + p_psVectorBinDisect(cumulative->nums, &tmpScalar);
            if (binMedian < 0) {
                psError(PS_ERR_UNKNOWN, false,
                        "Failed to calculate the 50 precent data point (%d).\n", binMedian);
                psFree(statsMinMax);
                psFree(histogram);
                psFree(cumulative);
                psFree(mask);
                psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
                return false;
            }
        }
        psTrace(__func__, 6, "The median bin is %d (%.2f to %.2f)\n", binMedian,
                cumulative->bounds->data.F32[binMedian], cumulative->bounds->data.F32[binMedian+1]);

        // ADD step 3: Interpolate to the exact 50% position: this is the robust histogram median.
        stats->robustMedian = fitQuadraticSearchForYThenReturnX(cumulative->bounds, cumulative->nums,
                              binMedian, totalDataPoints/2.0);
        if (isnan(stats->robustMedian)) {
            psError(PS_ERR_UNKNOWN, false,
                    "Failed to fit a quadratic and calculate the 50-percent position.\n");
            psFree(statsMinMax);
            psFree(histogram);
            psFree(cumulative);
            psFree(mask);
            psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
            return false;
        }
        psTrace(__func__, 6, "Current robust median is %f\n", stats->robustMedian);

        // ADD step 4: Find the bins which contains the 15.8655% and 84.1345% data points.
        long binLo = 0;                 // Bin containing the 15.8655% mark
        tmpScalar.data.F32 = totalDataPoints * 0.158655f;
        if (tmpScalar.data.F32 > cumulative->nums->data.F32[0]) {
            // NOTE: the (+1) here is because of the way p_psVectorBinDisect is defined.
            binLo = 1 + p_psVectorBinDisect(cumulative->nums, &tmpScalar);
            if (binLo > cumulative->nums->n-1) {
                binLo = cumulative->nums->n-1;
            }
        }

        long binHi = 0;                 // Bin containing the 84.1345% mark
        tmpScalar.data.F32 = totalDataPoints * 0.841345f;
        if (tmpScalar.data.F32 > cumulative->nums->data.F32[0]) {
            // NOTE: the (+1) here is because of the way p_psVectorBinDisect is defined.
            binHi = 1 + p_psVectorBinDisect(cumulative->nums, &tmpScalar);
            if (binHi > cumulative->nums->n-1) {
                binHi = cumulative->nums->n-1;
            }
        }
        psTrace(__func__, 6, "The 15.8655%% and 84.1345%% data point bins are (%d, %d).\n",
                binLo, binHi);
        psTrace(__func__, 6, "binLo midpoint is %f\n", PS_BIN_MIDPOINT(cumulative, binLo));
        psTrace(__func__, 6, "binHi midpoint is %f\n", PS_BIN_MIDPOINT(cumulative, binHi));

        if ((binLo < 0) || (binHi < 0)) {
            psError(PS_ERR_UNKNOWN, false, "Failed to calculate the 15.8655%% and 84.1345%% data points.\n");
            psFree(statsMinMax);
            psFree(histogram);
            psFree(cumulative);
            psFree(mask);
            psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
            return false;
        }

        // ADD step 4b: Interpolate Sigma to find these two positions exactly: these are the 1sigma positions.
        #if 0
        // XXX: I am overriding the ADD for now.  The following code implements the ADD exactly and is having
        // problems fitting a 2nd-order polynomial to data y-values suchs as (1, 1, 100).  Therefore, I
        // commented out the code and am doing simply linear interpolation.

        // Value for the 15.8655% mark
        float binLoF32 = fitQuadraticSearchForYThenReturnX(cumulative->bounds, cumulative->nums, binLo,
                         totalDataPoints * 0.158655f);
        // Value for the 84.1345% mark
        float binHiF32 = fitQuadraticSearchForYThenReturnX(cumulative->bounds, cumulative->nums, binHi,
                         totalDataPoints * 0.841345f);
        psTrace(__func__, 6, "The exact 15.8655%% and 84.1345%% data point positions are: (%f, %f)\n",
                binLoF32, binHiF32);
        #else
        // This code basically interpolates to find the positions exactly.
        psTrace(__func__, 6, "binLo is %d.  Nums at that bin and the next are (%.2f, %.2f)\n",
                binLo, cumulative->nums->data.F32[binLo], cumulative->nums->data.F32[binLo+1]);
        psTrace(__func__, 6, "binHi is %d.  Nums at that bin and the next are (%.2f, %.2f)\n",
                binHi, cumulative->nums->data.F32[binHi], cumulative->nums->data.F32[binHi+1]);

        float deltaBounds = cumulative->bounds->data.F32[binLo+1] - cumulative->bounds->data.F32[binLo];
        float deltaNums;
        float prevPixels;
        if (binLo == 0) {
            deltaNums = cumulative->nums->data.F32[0];
            prevPixels = 0;
        } else {
            deltaNums = cumulative->nums->data.F32[binLo] - cumulative->nums->data.F32[binLo-1];
            prevPixels = cumulative->nums->data.F32[binLo-1];
        }
        float percentNums = (totalDataPoints * 0.158655f) - prevPixels;
        float base = cumulative->bounds->data.F32[binLo];
        float binLoF32 = base + (deltaBounds / deltaNums) * percentNums; // Value for the 15.8655% mark
        psTrace(__func__, 6,
                "(base, deltaBounds, deltaNums, prevPixels, percentNums) is (%.2f %.2f %.2f %.2f %.2f)\n",
                base, deltaBounds, deltaNums, prevPixels, percentNums);

        deltaBounds = cumulative->bounds->data.F32[binHi+1] - cumulative->bounds->data.F32[binHi];
        if (binHi == 0) {
            deltaNums = cumulative->nums->data.F32[0];
            prevPixels = 0;
        } else {
            deltaNums = cumulative->nums->data.F32[binHi] - cumulative->nums->data.F32[binHi-1];
            prevPixels = cumulative->nums->data.F32[binHi-1];
        }
        percentNums = (totalDataPoints * 0.841345f) - prevPixels;
        base = cumulative->bounds->data.F32[binHi];
        float binHiF32 = base + (deltaBounds / deltaNums) * percentNums; // Value for the 84.1345% mark
        psTrace(__func__, 6,
                "(base, deltaBounds, deltaNums, prevPixels, percentNums) is (%.2f %.2f %.2f %.2f %.2f)\n",
                base, deltaBounds, deltaNums, prevPixels, percentNums);
        psTrace(__func__, 6,
                "The exact 15.8655 and 84.1345 percent data point positions are: (%f, %f)\n",
                binLoF32, binHiF32);
        #endif

        // ADD step 5: Determine SIGMA as 1/2 of the distance between these positions.
        sigma = (binHiF32 - binLoF32) / 2.0;
        psTrace(__func__, 6, "The current sigma is %f.\n", sigma);
        stats->robustStdev = sigma;

        // ADD step 6: If the measured SIGMA is less than 2 times the bin size, exclude points which are more
        // than 25 bins from the median, recalculate the bin size, and perform the algorithm again.
        if (sigma < (2 * binSize)) {
            psTrace(__func__, 6, "*************: Do another iteration (%f %f).\n", sigma, binSize);
            long maskLo = PS_MAX(0, (binMedian - 25)); // Low index for masking region
            long maskHi = PS_MIN(histogram->bounds->n - 1, (binMedian + 25)); // High index for masking
            psF32 medianLo = histogram->bounds->data.F32[maskLo]; // Value at low index
            psF32 medianHi = histogram->bounds->data.F32[maskHi]; // Value at high index
            psTrace(__func__, 6, "Masking data more than 25 bins from the median\n");
            psTrace(__func__, 6,
                    "The median is at bin number %d.  We mask bins outside the bin range (%d:%d)\n",
                    binMedian, maskLo, maskHi);
            psTrace(__func__, 6, "Masking data outside (%f %f)\n", medianLo, medianHi);
            for (long i = 0 ; i < myVector->n ; i++) {
                if ((myVector->data.F32[i] < medianLo) || (myVector->data.F32[i] > medianHi)) {
                    mask->data.U8[i] = 0xff;
                    psTrace(__func__, 6, "Masking element %d is %f\n", i, myVector->data.F32[i]);
                }
            }
            // Free the histograms; they will be recreated on the next iteration, with new bounds
            psFree(histogram);
            psFree(cumulative);
        } else {
            // We've got the bin size correct now
            psTrace(__func__, 6, "*************: No more iteration.  sigma is %f\n", sigma);
            iterate = -1;
        }
    }
    psFree(histogram);

    // ADD step 7: Find the bins which contains the 25% and 75% data points.
    long binLo25 = 0;                   // Bin containing the 25% value
    long binHi25 = 0;                   // Bin containing the 75% value

    tmpScalar.data.F32 = totalDataPoints * 0.25f;
    if (tmpScalar.data.F32 <= cumulative->nums->data.F32[0]) {
        // Special case where its in first bin.  The last bin should be handled automatically.
        binLo25 = 0;
    } else {
        binLo25 = 1 + p_psVectorBinDisect(cumulative->nums, &tmpScalar);
    }
    tmpScalar.data.F32 = totalDataPoints * 0.75f;
    if (tmpScalar.data.F32 <= cumulative->nums->data.F32[0]) {
        // Special case where its in first bin.  The last bin should be handled automatically.
        binHi25 = 0;
    } else {
        binHi25 = 1 + p_psVectorBinDisect(cumulative->nums, &tmpScalar);
    }
    if ((binLo25 < 0) || (binHi25 < 0)) {
        psError(PS_ERR_UNKNOWN, false, "Failed to calculate the 25 and 75 percent data points\n");
        psFree(statsMinMax);
        psFree(cumulative);
        psFree(mask);
        psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
        return false;
    }
    psTrace(__func__, 6, "The 25-percent and 75-precent data point bins are (%d, %d).\n", binLo25, binHi25);

    // ADD step 8: Interpolate to find these two positions exactly: these are the upper and lower quartile
    // positions.
    psF32 binLo25F32 = fitQuadraticSearchForYThenReturnX(cumulative->bounds, cumulative->nums,
                       binLo25, totalDataPoints * 0.25f);
    psF32 binHi25F32 = fitQuadraticSearchForYThenReturnX(cumulative->bounds, cumulative->nums,
                       binHi25, totalDataPoints * 0.75f);
    psFree(cumulative);

    if (isnan(binLo25F32) || isnan(binHi25F32)) {
        psError(PS_ERR_UNKNOWN, false,
                "could not determine the robustUQ: fitQuadraticSearchForYThenReturnX() returned a NAN.\n");
        psFree(statsMinMax);
        psFree(mask);
        psTrace(__func__, 4, "---- %s(1) end  ----\n", __func__);
        return false;
    }

    stats->robustLQ = binLo25F32;
    stats->robustUQ = binHi25F32;
    psTrace(__func__, 6, "The 25 and 75 percent data point exact positions are (%f, %f).\n",
            binLo25F32, binHi25F32);
    long N50 = 0;
    for (long i = 0 ; i < myVector->n ; i++) {
        if (!(mask->data.U8[i] & maskVal) &&
                (binLo25F32 <= myVector->data.F32[i]) && (binHi25F32 >= myVector->data.F32[i])) {
            N50++;
        }
    }
    stats->robustN50 = N50;
    psTrace(__func__, 6, "The robustN50 is %d.\n", N50);


    // Fitted statistics
    if (stats->options & PS_STAT_FITTED_MEAN || stats->options & PS_STAT_FITTED_STDEV) {
        // New algorithm for calculated mean and stdev.

        // XXX: Where is this documented?
        psF32 dN = 0.17 * N50;
        if (dN < 1.0) {
            dN = 1.0;
        } else if (dN > 4.0) {
            dN = 4.0;
        }
        psF32 newBinSize = sigma / dN;

        // Determine the min/max of the vector (which prior outliers masked out)
        int numValid = vectorMinMax(myVector, mask, maskVal, statsMinMax); // Number of values
        min = statsMinMax->min;
        max = statsMinMax->max;
        if (numValid == 0 || isnan(min) || isnan(max)) {
            psError(PS_ERR_UNKNOWN, false, "Failed to calculate the min/max of the input vector.\n");
            psFree(statsMinMax);
            psFree(mask);
            psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
            return false;
        }

        // Calculate the number of bins.
        long numBins = (max - min) / newBinSize;
        psTrace(__func__, 6, "The new min/max values are (%f, %f).\n", min, max);
        psTrace(__func__, 6, "The new bin size is %f.\n", newBinSize);
        psTrace(__func__, 6, "The numBins is %d\n", numBins);

        psHistogram *histogram = psHistogramAlloc(min, max, numBins); // A new histogram (without outliers)
        histogram = psVectorHistogram(histogram, myVector, errors, mask, maskVal);
        if (psTraceGetLevel(__func__) >= 8) {
            PS_VECTOR_PRINT_F32(histogram->nums);
        }

        // Smooth the resulting histogram with a Gaussian with sigma_s = 1 bin.
        psVector *smoothed = vectorSmoothHistGaussian(histogram, newBinSize); // Smoothed histogram
        if (psTraceGetLevel(__func__) >= 8) {
            PS_VECTOR_PRINT_F32(smoothed);
        }

        // Find the bin with the peak value in the range 2 sigma of the robust histogram median.
        long binMin = 0;                // Low bin to check
        long binMax = 0;                // High bin to check
        tmpScalar.data.F32 = stats->robustMedian - (2.0 * sigma);
        if (tmpScalar.data.F32 <= histogram->bounds->data.F32[0]) {
            binMin = 0;
        } else {
            binMin = p_psVectorBinDisect(histogram->bounds, &tmpScalar);
        }

        tmpScalar.data.F32 = stats->robustMedian + (2.0 + sigma);
        if (tmpScalar.data.F32 >= histogram->bounds->data.F32[histogram->bounds->n-1]) {
            binMax = histogram->bounds->n-1;
        } else {
            binMax = p_psVectorBinDisect(histogram->bounds, &tmpScalar);
        }
        if ((binMin < 0) || (binMax < 0)) {
            psError(PS_ERR_UNKNOWN, false, "Failed to calculate the +/- 2.0 * sigma bins\n");
            psFree(statsMinMax);
            psFree(histogram);
            psFree(mask);
            psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
            return false;
        }

        long binNum = binMin;           // Bin number containing the peak
        psF32 binMaxNums = smoothed->data.F32[binNum]; // The peak value
        for (psS32 i = binMin+1 ; i <= binMax ; i++) {
            if (smoothed->data.F32[i] > binMaxNums) {
                binNum = i;
                binMaxNums = smoothed->data.F32[i];
            }
        }
        psTrace(__func__, 6, "The peak bin is %d, with %f data.n", binNum, binMaxNums);

        // Fit a Gaussian to the bins in the range 20 sigma of the robust histogram median.
        tmpScalar.data.F32 = stats->robustMedian - (20.0 * sigma);
        if (tmpScalar.data.F32 < min) {
            binMin = 0;
        } else {
            binMin = p_psVectorBinDisect(histogram->bounds, &tmpScalar);
        }
        tmpScalar.data.F32 = stats->robustMedian + (20.0 * sigma);
        if (tmpScalar.data.F32 > max) {
            binMax = smoothed->n - 1;
        } else {
            binMax = p_psVectorBinDisect(histogram->bounds, &tmpScalar);
        }
        if (binMin < 0 || binMax < 0) {
            psError(PS_ERR_UNKNOWN, false, "Failed to calculate the +/- 20.0 * sigma bins\n");
            psFree(statsMinMax);
            psFree(histogram);
            psFree(mask);
            psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
            return false;
        }

        // Generate the variables that will be used in the Gaussian fitting
        psVector *y = psVectorAlloc((1 + (binMax - binMin)), PS_TYPE_F32); // Vector of coordinates
        psArray *x = psArrayAlloc((1 + (binMax - binMin))); // Array of ordinates
        y->n = y->nalloc;
        x->n = x->nalloc;
        for (long i = binMin, j = 0; i <= binMax ; i++, j++) {
            y->data.F32[j] = smoothed->data.F32[i];
            psVector *ordinate = psVectorAlloc(1, PS_TYPE_F32); // The ordinate value
            ordinate->n = 1;
            ordinate->data.F32[0] = PS_BIN_MIDPOINT(histogram, i);
            x->data[j] = ordinate;
        }
        if (psTraceGetLevel(__func__) >= 8) {
            // XXX: Print the x array somehow.
            PS_VECTOR_PRINT_F32(y);
        }
        psFree(smoothed);
        psFree(histogram);

        numValid = vectorMinMax(y, NULL, 0, statsMinMax); // Number of valid values
        min = statsMinMax->min;
        max = statsMinMax->max;
        if (numValid == 0 || isnan(min) || isnan(max)) {
            psError(PS_ERR_UNKNOWN, false, "Failed to calculate the min/max of the input vector.\n");
            psFree(mask);
            psFree(histogram);
            psFree(statsMinMax);
            psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
            return false;
        }

        // Normalize y to [0.0:1.0] (since the psMinimizeLMChi2Gauss1D() functions is [0.0:1.0])
        p_psNormalizeVectorRange(y, 0.0, 1.0);

        // Fit a Gaussian to the data.
        psMinimization *minimizer = psMinimizationAlloc(100, 0.01); // The minimizer information
        psVector *params = psVectorAlloc(2, PS_TYPE_F32); // Parameters for the Gaussian
        params->n = params->nalloc;
        // Initial guess for the mean (index 0) and standard dev (index 1).
        params->data.F32[0] = stats->robustMedian;
        params->data.F32[1] = sigma;
        if (psTraceGetLevel(__func__) >= 8) {
            PS_VECTOR_PRINT_F32(params);
            PS_VECTOR_PRINT_F32(y);
        }
        if (!psMinimizeLMChi2(minimizer, NULL, params, NULL, x, y, NULL, minimizeLMChi2Gauss1D)) {
            psError(PS_ERR_UNKNOWN, false, "Failed to fit a gaussian to the robust histogram.\n");
            psFree(statsMinMax);
            psFree(x);
            psFree(y);
            psFree(minimizer);
            psFree(params);
            psFree(mask);
            psTrace(__func__, 4, "---- %s(false) end  ----\n", __func__);
            return false;
        }
        if (psTraceGetLevel(__func__) >= 8) {
            PS_VECTOR_PRINT_F32(params);
        }

        // The fitted mean is the Gaussian mean.
        stats->fittedMean = params->data.F32[0];
        psTrace(__func__, 6, "The fitted mean is %f.\n", params->data.F32[0]);

        // The fitted standard deviation, SIGMA_r is determined by subtracting the smoothing scale in
        // quadrature: SIGMA_r^2 = SIGMA^2 - sigma_s^2
        stats->fittedStdev = sqrt(PS_SQR(params->data.F32[1]) - PS_SQR(newBinSize));
        psTrace(__func__, 6, "The fitted stdev is %f.\n", stats->fittedStdev);

        // Clean up after fitting
        psFree(x);
        psFree(y);
        psFree(minimizer);
        psFree(params);
    }

    // Clean up
    psFree(statsMinMax);
    psFree(mask);

    psTrace(__func__, 4, "---- %s(0) end  ----\n", __func__);
    return true;
}

/*****************************************************************************/

/* FUNCTION IMPLEMENTATION - PUBLIC                                          */

/*****************************************************************************/

static void histogramFree(psHistogram* myHist);

// We keep statsFree so that we can identify statistics pointers from the memblock
static void statsFree(psStats *newStruct)
{
    // There are non dynamic allocated items
}

/******************************************************************************
    psStatsAlloc(): This routine must create a new psStats data structure.
 *****************************************************************************/
psStats* psStatsAlloc(psStatsOptions options)
{
    psTrace(__func__, 3,"---- %s() begin  ----\n", __func__);
    psStats* newStruct = NULL;

    newStruct = (psStats* ) psAlloc(sizeof(psStats));
    psMemSetDeallocator(newStruct, (psFreeFunc)statsFree);
    newStruct->sampleMean = NAN;
    newStruct->sampleMedian = NAN;
    newStruct->sampleStdev = NAN;
    newStruct->sampleUQ = NAN;
    newStruct->sampleLQ = NAN;
    newStruct->robustMedian = NAN;
    newStruct->robustStdev = NAN;
    newStruct->robustUQ = NAN;
    newStruct->robustLQ = NAN;
    newStruct->robustN50 = -1;
    newStruct->fittedMean = NAN;
    newStruct->fittedStdev = NAN;
    newStruct->fittedNfit = -1;
    newStruct->clippedMean = NAN;
    newStruct->clippedStdev = NAN;
    newStruct->clippedNvalues = -1;     // XXX: This is never used
    newStruct->clipSigma = 3.0;
    newStruct->clipIter = 3;
    newStruct->min = NAN;
    newStruct->max = NAN;
    newStruct->binsize = NAN;
    newStruct->nSubsample = 100000;
    newStruct->options = options;

    psTrace(__func__, 3, "---- %s() end  ----\n", __func__);
    return (newStruct);
}


bool psMemCheckStats(psPtr ptr)
{
    return ( psMemGetDeallocator(ptr) == (psFreeFunc)statsFree );
}



/******************************************************************************
psHistogramAlloc(lower, upper, n): allocate a uniform histogram structure
with the specifed upper and lower limits, and the specifed number of bins.
This routine will also set the bounds for each of the bins.
 
Input:
    lower
    upper
    n
Returns:
    The histogram structure
 *****************************************************************************/
psHistogram* psHistogramAlloc(float lower, float upper, int n)
{
    psTrace(__func__, 3, "---- %s() begin  ----\n", __func__);
    psTrace(__func__, 5, "(lower, upper, n) is (%f, %f, %d)\n", lower, upper, n);
    PS_ASSERT_INT_POSITIVE(n, NULL);
    PS_ASSERT_FLOAT_LARGER_THAN_OR_EQUAL(upper, lower, NULL);

    // Allocate memory for the new histogram structure.  If there are N bins, then there are N+1 bounds to
    // those bins.
    psHistogram *newHist = (psHistogram* ) psAlloc(sizeof(psHistogram)); // The new histogram structure
    psMemSetDeallocator(newHist, (psFreeFunc) histogramFree);
    psVector* newBounds = psVectorAlloc(n + 1, PS_TYPE_F32);
    newHist->bounds = newBounds;
    newBounds->n = newHist->bounds->nalloc;

    // Calculate the bounds for each bin.
    psF32 binSize = (upper - lower) / (psF32)n; // The histogram bin size
    // XXX: Is the following necessary? It prevents the max data point from being in a non-existant bin.
    binSize += FLT_EPSILON;
    for (long i = 0; i < n + 1; i++) {
        newBounds->data.F32[i] = lower + (binSize * (psF32)i);
    }

    // Allocate the bins, and initialize them to zero.
    newHist->nums = psVectorAlloc(n, PS_TYPE_F32);
    for (long i = 0; i < newHist->nums->nalloc; i++) {
        newHist->nums->data.F32[i] = 0.0;
        newHist->nums->n++;
    }

    // Initialize the other members.
    newHist->minNum = 0;
    newHist->maxNum = 0;
    newHist->uniform = true;

    psTrace(__func__, 3, "---- %s() end  ----\n", __func__);
    return newHist;
}

/******************************************************************************
psHistogramAllocGeneric(bounds): allocate a non-uniform histogram structure
with the specifed bounds.
 
Input:
    bounds
Returns:
    The histogram structure
 *****************************************************************************/
psHistogram* psHistogramAllocGeneric(const psVector* bounds)
{
    psTrace(__func__, 3, "---- %s() begin  ----\n", __func__);
    PS_ASSERT_VECTOR_NON_NULL(bounds, NULL);
    PS_ASSERT_VECTOR_TYPE(bounds, PS_TYPE_F32, NULL);
    PS_ASSERT_INT_LARGER_THAN_OR_EQUAL(bounds->n, 2, NULL);

    // Allocate memory for the new histogram structure.
    psHistogram *newHist = (psHistogram* ) psAlloc(sizeof(psHistogram)); // The new histogram structure
    psMemSetDeallocator(newHist, (psFreeFunc) histogramFree);
    psVector* newBounds = psVectorAlloc(bounds->n, PS_TYPE_F32);
    newHist->bounds = newBounds;
    newBounds->n = newHist->bounds->nalloc;
    for (long i = 0; i < bounds->n; i++) {
        newBounds->data.F32[i] = bounds->data.F32[i];
    }

    // Allocate the bins, and initialize them to zero.  If there are N bounds,
    // then there are N-1 bins.
    newHist->nums = psVectorAlloc((bounds->n) - 1, PS_TYPE_F32);
    for (long i = 0; i < newHist->nums->nalloc; i++) {
        newHist->nums->data.F32[i] = 0.0;
        newHist->nums->n++;
    }

    // Initialize the other members.
    newHist->minNum = 0;
    newHist->maxNum = 0;
    newHist->uniform = false;

    psTrace(__func__, 3, "---- %s() end  ----\n", __func__);
    return (newHist);
}

static void histogramFree(psHistogram* myHist)
{
    psFree(myHist->bounds);
    psFree(myHist->nums);
}


bool psMemCheckHistogram(psPtr ptr)
{
    return ( psMemGetDeallocator(ptr) == (psFreeFunc)histogramFree );
}



/*****************************************************************************
UpdateHistogramBins(binNum, out, data, error): This routine is to be used when
updating the histogram in the presence of errors in the input data.  We treat
the data point as a boxcar PDF and update a range of points surrounding the
histogram bin which contains the point.  The width of that boxcar is defined
as 2.35 * error.
 
XXX: Must test this.
 *****************************************************************************/
static bool UpdateHistogramBins(long binNum, // Bin number of the data point
                                psHistogram* out, // The histogram to be updated
                                psF32 data, // The data point value
                                psF32 error // The error in the data point
                               )
{
    psTrace(__func__, 3, "---- %s() begin  ----\n", __func__);
    PS_ASSERT_PTR_NON_NULL(out, false);
    PS_ASSERT_PTR_NON_NULL(out->bounds, false);
    PS_ASSERT_PTR_NON_NULL(out->nums, false);
    PS_ASSERT_INT_WITHIN_RANGE(binNum, 0, ((out->nums->n)-1), false);
    PS_ASSERT_FLOAT_LARGER_THAN_OR_EQUAL(error, 0.0, false);
    PS_ASSERT_FLOAT_WITHIN_RANGE(data, out->bounds->data.F32[0],
                                 out->bounds->data.F32[(out->bounds->n)-1], false);

    psF32 boxcarWidth = 2.35 * error;   // Width of the boxcar
    psF32 boxcarCenter = (out->bounds->data.F32[binNum] +
                          out->bounds->data.F32[binNum+1]) / 2.0; // Centre of the boxcar
    psF32 boxcarLeft = boxcarCenter - (boxcarWidth / 2.0); // Left endpoint of the boxcar for the PDF
    psF32 boxcarRight = boxcarCenter + (boxcarWidth / 2.0); // Right endpoint of the boxcar for the PDF
    psS32 boxcarLeftBinNum = 0;         // Bin number for left endpoint
    psS32 boxcarRightBinNum = 0;        // Bin number for right endpoint

    // Determine the left endpoint of the boxcar for the PDF.
    for (long bin = binNum; bin >= 0; bin--) {
        if (out->nums->data.F32[bin] <= boxcarLeft) {
            boxcarLeftBinNum = bin;
            break;
        }
    }

    // Determine the right endpoint of the boxcar for the PDF.
    for (long bin = binNum; bin < out->nums->n; bin++) {
        if (out->nums->data.F32[bin] >= boxcarRight) {
            boxcarRightBinNum = bin;
            break;
        }
    }

    // If the boxcar fits entirely inside this bin, then simply add 1.0 to the
    // bin and return.
    if (boxcarLeftBinNum == boxcarRightBinNum) {
        out->nums->data.F32[binNum] += 1.0;
        psTrace(__func__, 3, "---- %s(true) end  ----\n", __func__);
        return true;
    }

    // If we get here, multiple bins must be updated.  We handle the left-most endpoint, and right-most
    // endpoints differently.
    out->nums->data.F32[boxcarLeftBinNum] +=
        (out->bounds->data.F32[boxcarLeftBinNum+1] - boxcarLeft) / boxcarWidth;

    // Loop through the center bins, if any.
    for (long bin = boxcarLeftBinNum + 1; bin < (boxcarRightBinNum - 1); bin++) {
        out->nums->data.F32[bin] +=
            (out->bounds->data.F32[bin+1] - out->bounds->data.F32[bin]) / boxcarWidth;
    }

    // Handle the right endpoint differently.
    out->nums->data.F32[boxcarRightBinNum]+=
        (boxcarRight - out->bounds->data.F32[boxcarRightBinNum]) / boxcarWidth;

    psTrace(__func__, 3, "---- %s(true) end  ----\n", __func__);
    return true;
}


/*****************************************************************************
psVectorHistogram(out, in, errors, mask, maskVal): this procedure takes as
input a preallocated and initialized histogram structure.  It fills the bins
in that histogram structure in accordance with the input data "in" and the,
possibly NULL, mask vector.
 
Inputs:
    out
    in
    mask
    maskVal
Returns:
    The histogram structure "out".
 *****************************************************************************/
psHistogram* psVectorHistogram(psHistogram* out,
                               const psVector* values,
                               const psVector* errors,
                               const psVector* mask,
                               psMaskType maskVal)
{
    psTrace(__func__, 3, "---- %s() begin  ----\n", __func__);
    PS_ASSERT_PTR_NON_NULL(out, NULL);
    PS_ASSERT_VECTOR_NON_NULL(out->bounds, NULL);
    PS_ASSERT_VECTOR_TYPE(out->bounds, PS_TYPE_F32, NULL);
    PS_ASSERT_INT_NONNEGATIVE(out->bounds->n, NULL);
    PS_ASSERT_VECTOR_NON_NULL(out->nums, NULL);
    PS_ASSERT_VECTOR_TYPE(out->nums, PS_TYPE_F32, NULL);
    PS_ASSERT_INT_NONNEGATIVE(out->nums->n, NULL);
    PS_ASSERT_VECTOR_NON_NULL(values, out);
    if (mask) {
        PS_ASSERT_VECTORS_SIZE_EQUAL(values, mask, NULL);
        PS_ASSERT_VECTOR_TYPE(mask, PS_TYPE_U8, NULL);
    }
    if (errors) {
        PS_ASSERT_VECTORS_SIZE_EQUAL(values, errors, NULL);
        PS_ASSERT_VECTOR_TYPE(errors, values->type.type, NULL);
    }

    long binNum = 0;                    // A temporary bin number
    long numBins = out->nums->n;        // The total number of bins
    psScalar tmpScalar;
    tmpScalar.type.type = PS_TYPE_F32;

    // Convert input and errors vectors to F32 if necessary.
    psVector* inF32 = NULL;             // F32 version of input vector
    if (values->type.type == PS_TYPE_F32) {
        inF32 = psMemIncrRefCounter((psPtr)values);
    } else {
        values = psVectorCopy(NULL, values, PS_TYPE_F32);
    }
    psVector* errorsF32 = NULL;         // F32 version of errors vector
    if (errors) {
        if (errors->type.type == PS_TYPE_F32) {
            errorsF32 = psMemIncrRefCounter((psPtr)errors);
        } else {
            errorsF32 = psVectorCopy(NULL, errors, PS_TYPE_F32);
        }
    }

    for (long i = 0; i < inF32->n; i++) {
        // Check if this pixel is masked, and if so, skip it.
        if (!mask || (mask && (!(mask->data.U8[i] & maskVal)))) {
            if (inF32->data.F32[i] < out->bounds->data.F32[0]) {
                // If this pixel is below minimum value, count it, then skip.
                out->minNum++;
            } else if (inF32->data.F32[i] > out->bounds->data.F32[numBins]) {
                // If this pixel is above maximum value, count it, then skip.
                out->maxNum++;
            } else {
                // If this is a uniform histogram, determining the correct
                // number is trivial.
                if (out->uniform == true) {
                    float binSize = out->bounds->data.F32[1] - out->bounds->data.F32[0]; // Histogram bin size
                    binNum = (inF32->data.F32[i] - out->bounds->data.F32[0]) / binSize;
                    if (errorsF32) {
                        if (!UpdateHistogramBins(binNum, out, inF32->data.F32[i], errorsF32->data.F32[i])) {
                            psLogMsg(__func__, PS_LOG_WARN, "WARNING: Failed to update the histogram "
                                     "bins with the errors vector.\n");
                        }
                    } else {
                        // This if-statement really shouldn't be necessary.
                        // However, due to numerical lack of precision, we
                        // occasionally produce a binNum outside the range.
                        if (binNum >= out->nums->n) {
                            binNum = out->nums->n - 1;
                        }
                        (out->nums->data.F32[binNum])+= 1.0;
                    }

                } else {
                    // If this is a non-uniform histogram, determining the
                    // correct bin number requires a bit more work.
                    tmpScalar.data.F32 = inF32->data.F32[i];
                    binNum = p_psVectorBinDisect( *(psVector* *)&out->bounds, &tmpScalar);
                    if (binNum < 0) {
                        psLogMsg(__func__, PS_LOG_WARN,
                                 "WARNING: psVectorHistogram(): element outside histogram bounds.\n");
                    } else {
                        if (errorsF32 != NULL) {
                            if (!UpdateHistogramBins(binNum, out, inF32->data.F32[i], errors->data.F32[i])) {
                                psLogMsg(__func__, PS_LOG_WARN, "WARNING: Failed to update the histogram "
                                         "bins with the errors vector.\n");
                            }
                        } else {
                            out->nums->data.F32[binNum] += 1.0;
                        }
                    }
                }
            }
        }
    }

    psFree(inF32);
    psFree(errorsF32);

    psTrace(__func__, 3, "---- %s() end  ----\n", __func__);
    return (out);
}

/******************************************************************************
psVectorStats(myVector, maskVector, maskVal, stats): this is the public API
function which calls the above private stats functions based on what bits
were set in stats->options.
 
Inputs
    myVector
    maskVector
    maskVal
    stats
Returns
    The stats structure.
 
XXX: Should we free stats if the asserts fail?
 *****************************************************************************/
psStats* psVectorStats(
    psStats* stats,
    const psVector* in,
    const psVector* errors,
    const psVector* mask,
    psMaskType maskVal)
{
    psTrace(__func__, 3,"---- %s() begin  ----\n", __func__);
    PS_ASSERT_PTR_NON_NULL(stats, NULL);
    PS_ASSERT_VECTOR_NON_NULL(in, NULL);
    if (mask) {
        PS_ASSERT_VECTORS_SIZE_EQUAL(mask, in, stats);
        PS_ASSERT_VECTOR_TYPE(mask, PS_TYPE_U8, stats);
    }
    if (errors) {
        PS_ASSERT_VECTORS_SIZE_EQUAL(errors, in, stats);
        PS_ASSERT_VECTOR_TYPE(errors, in->type.type, stats);
    }

    // Convert types, as necessary
    psVector *inF32 = NULL;             // Input vector of values, F32 version
    if (in->type.type == PS_TYPE_F32) {
        inF32 = psMemIncrRefCounter((psPtr)in);
    } else {
        inF32 = psVectorCopy(NULL, in, PS_TYPE_F32);
    }
    psVector *errorsF32 = NULL;         // Input vector of errors, F32 version
    if (errors) {
        if (errors->type.type == PS_TYPE_F32) {
            errorsF32 = psMemIncrRefCounter((psPtr)errors);
        } else {
            errorsF32 = psVectorCopy(NULL, errors, PS_TYPE_F32);
        }
    }
    psVector *maskU8 = NULL;            // Input mask vector, U8 version
    if (mask) {
        // We want a copy of the mask, since we may change values
        maskU8 = psVectorCopy(NULL, mask, PS_TYPE_U8);
    } else {
        maskU8 = psVectorAlloc(in->n, PS_TYPE_U8);
        maskU8->n = in->n;
        memset(maskU8->data.U8, 0, in->n * sizeof(psU8));
    }

    // Mask bad data
    for (long i = 0; i < inF32->n; i++) {
        if (!isfinite(inF32->data.F32[i])) {
            maskU8->data.U8[i] = 0xff;
        }
    }

    if ((stats->options & PS_STAT_USE_RANGE) && (stats->min >= stats->max)) {
        PS_ASSERT_FLOAT_LARGER_THAN_OR_EQUAL(stats->max, stats->min, stats);
    }

    if ((stats->options & PS_STAT_USE_BINSIZE) && (stats->min >= stats->max)) {
        PS_ASSERT_FLOAT_LARGER_THAN_OR_EQUAL(stats->binsize, 0.0, stats);
    }

    // ************************************************************************
    if (stats->options & PS_STAT_SAMPLE_MEAN) {
        if (!vectorSampleMean(inF32, errorsF32, maskU8, maskVal, stats)) {
            psLogMsg(__func__, PS_LOG_WARN, "WARNING: vectorSampleMean() returned an error.\n");
            stats->sampleMean = NAN;
        }
    }

    // ************************************************************************
    if (stats->options & (PS_STAT_SAMPLE_MEDIAN | PS_STAT_SAMPLE_QUARTILE)) {
        if (!vectorSampleMedian(inF32, maskU8, maskVal, stats)) {
            psLogMsg(__func__, PS_LOG_WARN, "WARNING: vectorSampleMedian() returned an error.\n");
            stats->sampleMedian = NAN;
            stats->sampleUQ = NAN;
            stats->sampleLQ = NAN;
        }
    }

    // ************************************************************************
    if (stats->options & PS_STAT_SAMPLE_STDEV) {
        if (!vectorSampleMean(inF32, errorsF32, maskU8, maskVal, stats)) {
            psLogMsg(__func__, PS_LOG_WARN, "WARNING: vectorSampleMean() returned an error.\n");
            stats->sampleMean = NAN;
        } else {
            vectorSampleStdev(inF32, errorsF32, maskU8, maskVal, stats);
        }
    }

    // ************************************************************************
    if (stats->options & (PS_STAT_ROBUST_MEDIAN | PS_STAT_ROBUST_STDEV | PS_STAT_ROBUST_QUARTILE |
                          PS_STAT_FITTED_MEAN | PS_STAT_FITTED_STDEV)) {
        if (!vectorRobustStats(inF32, errorsF32, maskU8, maskVal, stats)) {
            psError(PS_ERR_UNKNOWN, false, PS_ERRORTEXT_psStats_STATS_FAILED);
            psFree(stats);
            psFree(inF32);
            psFree(errorsF32);
            psTrace(__func__, 3,"---- %s(NULL) end  ----\n", __func__);
            return(NULL);
        }
    }

    // ************************************************************************
    if ((stats->options & PS_STAT_CLIPPED_MEAN) || (stats->options & PS_STAT_CLIPPED_STDEV)) {
        if (!vectorClippedStats(inF32, errorsF32, maskU8, maskVal, stats)) {
            psError(PS_ERR_UNKNOWN, false, "Failed to calculate clipped statistics for input psVector.\n");
            stats->clippedMean = NAN;
            stats->clippedStdev = NAN;
        }
    }

    // ************************************************************************
    if (stats->options & (PS_STAT_MAX | PS_STAT_MIN)) {
        if (vectorMinMax(inF32, maskU8, maskVal, stats) == 0) {
            psError(PS_ERR_UNKNOWN, false, "Failed to calculate vector minimum and maximum");
        }
    }

    psFree(inF32);
    psFree(errorsF32);
    psFree(maskU8);
    psTrace(__func__, 3,"---- %s() end  ----\n", __func__);
    return (stats);
}

