BaseHistogram.h

// BaseHistogram.h:
// ----------------
//

#ifndef __IPSDKMATH_BASEHISTOGRAM_H__
#define __IPSDKMATH_BASEHISTOGRAM_H__

// suppression warnings
// warning C4251: 'ipsdk::math::BaseHistogram::_histogramPopulation': class 'std::vector<ipsdk::ipUInt64,std::allocator<_Ty>>' needs to have dll-interface to be used by clients of class 'ipsdk::math::BaseHistogram'
#pragma warning (push)
#pragma warning (disable : 4251)

#include <IPSDKMath/IPSDKMathExports.h>
#include <IPSDKUtil/BaseCollections.h>
#include <IPSDKUtil/Tools/ForceInline.h>
#include <IPSDKMath/Statistics/HistogramTypes.h>
#include <IPSDKMath/Statistics/BasicStatistics.h>
#include <IPSDKMath/Estimation/EstimationUtils.h>
#include <IPSDKMath/Clustering/KMeansClusteringConfig.h>
#include <IPSDKMath/Clustering/KernelKMeansClusteringConfig.h>
#include <IPSDKSerialization/Engine/BaseSerializationObject.h>
#include <vector>

namespace ipsdk {
namespace math {


class IPSDKMATH_API BaseHistogram : public BaseSerializationObject
{
    // declare serial class
    IPSDK_DECLARE_ABSTRACT_SERIAL_WITH_COPY(IPSDKMath, BaseHistogram)

public:
    BaseHistogram();
    virtual ~BaseHistogram() = 0;

// methods
public:
    bool                                    isInit() const;

    //--------------------------------
    //--------------------------------

    void                                    initFromExisting(const ipReal64 firstHistoValue,
                                                             const ipReal64 lastHistoValue,
                                                             const ipReal64 binWidth,
                                                             const UInt64Vector& histogramPopulation,
                                                             const eHistogramOutOfBoundsPolicy& outOfBoundsPolicy = eHistogramOutOfBoundsPolicy::eHOOBP_Ignored);

    //------------------------------------
    //------------------------------------

    void                                    clearData();

    //-----------------------
    //-----------------------

    virtual ipBool                          areDataIntegral() const = 0;

    ipReal64                                getFirstValue() const;

    ipReal64                                getLastValue() const;

    ipReal64                                getLowerBound() const;

    ipReal64                                getUpperBound() const;

    ipReal64                                getRange() const;

    ipReal64                                getBinWidth() const;

    ipUInt32                                getNbClasses() const;

    ipUInt32                                getNbBins() const;

    ipUInt32                                getLowerOutOfBoundsBinIdx() const;

    ipUInt32                                getUpperOutOfBoundsBinIdx() const;

    ipUInt32                                getInBoundsBinOffset() const;

    const UInt64Vector&                     getHistogramPopulation() const;

    ipUInt64                                getTotalPopulation() const;

    UInt64Vector                            getHistogramClassPopulation() const;

    ipReal64                                getBinStartValue(const ipUInt32 binIdx) const;

    ipReal64                                getBinMidValue(const ipUInt32 binIdx) const;

    ipReal64                                getBinEndValue(const ipUInt32 binIdx) const;

    ipReal64                                getClassStartValue(const ipUInt32 classIdx) const;

    ipReal64                                getClassMidValue(const ipUInt32 classIdx) const;

    ipReal64                                getClassEndValue(const ipUInt32 classIdx) const;

    ipUInt64                                getClassPopulation(const ipUInt32 classIdx) const;

    ipReal64                                getClassFrequency(const ipUInt32 classIdx) const;

    ipUInt64                                getClassCumulatedPopulation(const ipUInt32 classIdx) const;

    ipReal64                                getClassCumulatedFrequency(const ipUInt32 classIdx) const;

    ipBool                                  isOutOfBounds(const ipReal64 value) const;

    ipBool                                  isOutOfLowerBound(const ipReal64 value) const;

    ipBool                                  isOutOfUpperBound(const ipReal64 value) const;

    ipBool                                  canBeAggregated(const ipReal64 value) const;

    ipUInt32                                getBinIdx(const ipReal64 value) const;

    ipUInt64                                getPopulation(const ipReal64 value) const;

    ipReal64                                getFrequency(const ipReal64 value) const;

    ipUInt64                                getCumulatedPopulation(const ipReal64 value) const;

    ipReal64                                getCumulatedFrequency(const ipReal64 value) const;

    void                                    getFrequencies(Real64Vector& frequencies) const;

    Real64Vector                            getFrequencies() const;

    void                                    getCumulatedFrequencies(Real64Vector& cumulatedFrequencies) const;

    Real64Vector                            getCumulatedFrequencies() const;

    Real64Vector                            getBinMidValues() const;

    ipUInt32                                getQuantileClassIdx(const ipReal64 quantileValue) const;

    ipUInt32                                getMaxPopulationClassIdx()  const;

    //----------------------
    //----------------------

    UInt32Vector                            findLocalMaxima(const bool bStrictExtrema = true,
                                                            const eExtremaBorderPolicy& extremaBorderPolicy = eExtremaBorderPolicy::eEBP_Keeped,
                                                            const ipReal64 minDistance = 0,
                                                            const ipUInt64 populationThreshold = 0) const;

    UInt32Vector                            findLocalMinima(const bool bStrictExtrema = true,
                                                            const eExtremaBorderPolicy& extremaBorderPolicy = eExtremaBorderPolicy::eEBP_Keeped,
                                                            const ipReal64 minDistance = 0,
                                                            const ipUInt64 populationThreshold = NumericLimits<ipUInt64>::max()) const;

    HistogramExtremaColl                    findLocalDilatedMaxima(const ipUInt64 dilateFactor,
                                                                   const eExtremaBorderPolicy& extremaBorderPolicy = eExtremaBorderPolicy::eEBP_Keeped,
                                                                   const ipReal64 minDistance = 0,
                                                                   const ipUInt64 populationThreshold = 0) const;

    HistogramExtremaColl                    findLocalDilatedMinima(const ipUInt64 dilateFactor,
                                                                   const eExtremaBorderPolicy& extremaBorderPolicy = eExtremaBorderPolicy::eEBP_Keeped,
                                                                   const ipReal64 minDistance = 0,
                                                                   const ipUInt64 populationThreshold = NumericLimits<ipUInt64>::max()) const;

    HistogramGaussianCurveFit               fitGaussianCurve(const EstimationConfig& config = createNonRobustConfig(),
                                                             const bool bIncludeOutOfBoundsData = false) const;

    clustering::KMeansClusteringPtr         applyKMeansClustering(const ipUInt32 nbClusters,
                                                                  const bool bIncludeOutOfBoundsData = false,
                                                                  const clustering::KMeansClusteringConfig& clusteringConfig = clustering::KMeansClusteringConfig()) const;

    template <typename KernelType>
    boost::shared_ptr<clustering::KernelKMeansClustering<KernelType> >
                                            applyKernelKMeansClustering(const ipUInt32 nbClusters,
                                                                        const KernelType& kernel,
                                                                        const bool bIncludeOutOfBoundsData = false,
                                                                        const clustering::KernelKMeansClusteringConfig& clusteringConfig = clustering::KernelKMeansClusteringConfig()) const;

    template <typename KernelType>
    boost::shared_ptr<clustering::SpectralClustering<KernelType> >
                                            applySpectralClustering(const ipUInt32 nbClusters,
                                                                    const KernelType& kernel,
                                                                    const bool bIncludeOutOfBoundsData = false,
                                                                    const clustering::KernelKMeansClusteringConfig& clusteringConfig = clustering::KernelKMeansClusteringConfig()) const;

    void                                    clear();

protected:
    void                checkInit() const;

    void                checkClassIdx(const ipUInt32 classIdx) const;

    void                checkBinIdx(const ipUInt32 classIdx) const;

    void                updateHistogramParams(const ipReal64 firstHistoValue,
                                              const ipReal64 lastHistoValue,
                                              const ipReal64 binWidth,
                                              const eHistogramOutOfBoundsPolicy& outOfBoundsPolicy);

    void                updateHistogramParams(const ipReal64 firstHistoValue,
                                              const ipReal64 lastHistoValue,
                                              const ipUInt32 nbClasses,
                                              const eHistogramOutOfBoundsPolicy& outOfBoundsPolicy);

    ipBool              insertDataInternal(const ipReal64 value);

    void                clearCumulatedData();

    void                collectClusteringData(const bool bIncludeOutOfBoundsData,
                                              clustering::VectorColl& inputDataColl) const;

private:
    ipUInt32            retrieveBinIdx(const ipReal64 value) const;

    void                updateCumulatedIfNeeded() const;

    void                updateCumulated() const;

// attributes
private:
    ipReal64                    _firstHistoValue;

    ipReal64                    _lastHistoValue;
    
    ipReal64                    _binWidth;

    ipUInt32                    _nbClasses;

    ipUInt32                    _lowerOutOfBoundsBinIdx;

    ipUInt32                    _upperOutOfBoundsBinIdx;

    ipUInt32                    _inBoundsBinOffset;

    UInt64Vector                _histogramPopulation;

    mutable UInt64Vector        _cumulatedHistogramPopulation;
};


IPSDK_FORCEINLINE bool
BaseHistogram::isInit() const
{
    return _nbClasses != 0;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getFirstValue() const
{
    // check for initialization
    checkInit();

    return _firstHistoValue;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getLastValue() const
{
    // check for initialization
    checkInit();

    return _lastHistoValue;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getLowerBound() const
{
    return getFirstValue();
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getUpperBound() const
{
    if (areDataIntegral() == true)
        return getLastValue() + 1;
    else
        return getLastValue();
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getRange() const
{
    return getUpperBound() - _firstHistoValue;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getBinWidth() const
{
    // check for initialization
    checkInit();

    return _binWidth;
}

IPSDK_FORCEINLINE ipUInt32
BaseHistogram::getNbClasses() const
{
    // check for initialization
    checkInit();

    return _nbClasses;
}

IPSDK_FORCEINLINE ipUInt32
BaseHistogram::getNbBins() const
{
    // check for initialization
    checkInit();

    return static_cast<ipUInt32>(_histogramPopulation.size());
}

IPSDK_FORCEINLINE ipUInt32
BaseHistogram::getLowerOutOfBoundsBinIdx() const
{
    // check for initialization
    checkInit();

    return _lowerOutOfBoundsBinIdx;
}

IPSDK_FORCEINLINE ipUInt32
BaseHistogram::getUpperOutOfBoundsBinIdx() const
{
    // check for initialization
    checkInit();

    return _upperOutOfBoundsBinIdx;
}

IPSDK_FORCEINLINE ipUInt32
BaseHistogram::getInBoundsBinOffset() const
{
    // check for initialization
    checkInit();

    return _inBoundsBinOffset;
}

IPSDK_FORCEINLINE const UInt64Vector&
BaseHistogram::getHistogramPopulation() const
{
    // check for initialization
    checkInit();

    return _histogramPopulation;
}

IPSDK_FORCEINLINE ipUInt64
BaseHistogram::getTotalPopulation() const
{
    // update of cumulated data if needeed
    updateCumulatedIfNeeded();

    return _cumulatedHistogramPopulation.back();
}

IPSDK_FORCEINLINE UInt64Vector
BaseHistogram::getHistogramClassPopulation() const
{
    // check for initialization
    checkInit();

    return UInt64Vector(_histogramPopulation.begin() + _inBoundsBinOffset,
                        _histogramPopulation.begin() + _nbClasses);
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getBinStartValue(const ipUInt32 binIdx) const
{
    // check for bin index validity
    checkBinIdx(binIdx);

    return _firstHistoValue + (static_cast<ipReal64>(binIdx) - _inBoundsBinOffset)  * _binWidth;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getBinMidValue(const ipUInt32 binIdx) const
{
    // check for bin index validity
    checkBinIdx(binIdx);

    if (binIdx > _inBoundsBinOffset && (binIdx-_inBoundsBinOffset) == _nbClasses-1)
        return (_firstHistoValue + (static_cast<ipReal64>(binIdx) - _inBoundsBinOffset)  * _binWidth + _lastHistoValue) / 2;
    else
        return _firstHistoValue + (static_cast<ipReal64>(binIdx) - _inBoundsBinOffset + 0.5)  * _binWidth;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getBinEndValue(const ipUInt32 binIdx) const
{
    // check for bin index validity
    checkBinIdx(binIdx);

    if (binIdx > _inBoundsBinOffset && (binIdx-_inBoundsBinOffset) == _nbClasses-1)
        return _lastHistoValue;
    else
        return _firstHistoValue + (static_cast<ipReal64>(binIdx) - _inBoundsBinOffset + 1) * _binWidth;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getClassStartValue(const ipUInt32 classIdx) const
{
    // check for class index validity
    checkClassIdx(classIdx);

    return _firstHistoValue + classIdx * _binWidth;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getClassMidValue(const ipUInt32 classIdx) const
{
    // check for class index validity
    checkClassIdx(classIdx);

    if (classIdx == _nbClasses-1)
        return (_firstHistoValue + classIdx * _binWidth + _lastHistoValue) / 2;
    else
        return _firstHistoValue + (classIdx + 0.5) * _binWidth;
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getClassEndValue(const ipUInt32 classIdx) const
{
    // check for class index validity
    checkClassIdx(classIdx);

    if (classIdx == _nbClasses-1)
        return _lastHistoValue;
    else
        return _firstHistoValue + (classIdx + 1) * _binWidth;
}

IPSDK_FORCEINLINE ipUInt64
BaseHistogram::getClassPopulation(const ipUInt32 classIdx) const
{
    // check for class index validity
    checkClassIdx(classIdx);

    return _histogramPopulation[classIdx + _inBoundsBinOffset];
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getClassFrequency(const ipUInt32 classIdx) const
{
    // check for class index validity
    checkClassIdx(classIdx);

    return static_cast<ipReal64>(_histogramPopulation[classIdx + _inBoundsBinOffset]) /
           static_cast<ipReal64>(getTotalPopulation());
}

IPSDK_FORCEINLINE ipUInt64
BaseHistogram::getClassCumulatedPopulation(const ipUInt32 classIdx) const
{
    // check for class index validity
    checkClassIdx(classIdx);

    // update of cumulated data
    updateCumulatedIfNeeded();

    return _cumulatedHistogramPopulation[classIdx + _inBoundsBinOffset];
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getClassCumulatedFrequency(const ipUInt32 classIdx) const
{
    // check for class index validity
    checkClassIdx(classIdx);

    // update of cumulated data
    updateCumulatedIfNeeded();

    return static_cast<ipReal64>(_cumulatedHistogramPopulation[classIdx + _inBoundsBinOffset]) /
           static_cast<ipReal64>(getTotalPopulation());
}

IPSDK_FORCEINLINE ipBool
BaseHistogram::isOutOfBounds(const ipReal64 value) const
{
    // check for initialization
    checkInit();

    return value < _firstHistoValue || value > _lastHistoValue;
}

IPSDK_FORCEINLINE ipBool
BaseHistogram::isOutOfLowerBound(const ipReal64 value) const
{
    return value < getFirstValue();
}

IPSDK_FORCEINLINE ipBool
BaseHistogram::isOutOfUpperBound(const ipReal64 value) const
{
    return value > getLastValue();
}

IPSDK_FORCEINLINE ipBool
BaseHistogram::canBeAggregated(const ipReal64 value) const
{
    // check for initialization
    checkInit();

    if (value < _firstHistoValue && _lowerOutOfBoundsBinIdx == NumericLimits<ipUInt32>::max())
        return false;
    if (value > _lastHistoValue && _upperOutOfBoundsBinIdx == NumericLimits<ipUInt32>::max())
        return false;

    return true;
}

IPSDK_FORCEINLINE ipUInt32
BaseHistogram::getBinIdx(const ipReal64 value) const
{
    // check for initialization
    checkInit();

    return retrieveBinIdx(value);
}

IPSDK_FORCEINLINE ipUInt64
BaseHistogram::getPopulation(const ipReal64 value) const
{
    const ipUInt32 binIdx = getBinIdx(value);
    if (value != NumericLimits<ipUInt32>::max())
        return _histogramPopulation[binIdx];
    else
        return NumericLimits<ipUInt64>::max();
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getFrequency(const ipReal64 value) const
{
    // computation of requested frequency
    const ipUInt32 binIdx = getBinIdx(value);
    if (value != NumericLimits<ipUInt32>::max())
        return static_cast<ipReal64>(_histogramPopulation[binIdx]) /
               static_cast<ipReal64>(getTotalPopulation());
    else
        return 0;
}

IPSDK_FORCEINLINE ipUInt64
BaseHistogram::getCumulatedPopulation(const ipReal64 value) const
{
    // update of cumulated data
    updateCumulatedIfNeeded();

    // comutation of associated cumulated population
    const ipUInt32 binIdx = getBinIdx(value);
    if (value != NumericLimits<ipUInt32>::max())
        return _cumulatedHistogramPopulation[binIdx];
    else
        return NumericLimits<ipUInt64>::max();
}

IPSDK_FORCEINLINE ipReal64
BaseHistogram::getCumulatedFrequency(const ipReal64 value) const
{
    // update of cumulated data
    updateCumulatedIfNeeded();

    // computation of requested frequency
    const ipUInt32 binIdx = getBinIdx(value);
    if (value != NumericLimits<ipUInt32>::max())
        return static_cast<ipReal64>(_cumulatedHistogramPopulation[binIdx]) /
               static_cast<ipReal64>(getTotalPopulation());
    else
        return 0;
}

IPSDK_FORCEINLINE Real64Vector
BaseHistogram::getFrequencies() const
{
    Real64Vector frequencies;
    getFrequencies(frequencies);

    return frequencies;
}

IPSDK_FORCEINLINE Real64Vector
BaseHistogram::getCumulatedFrequencies() const
{
    Real64Vector cumulatedFrequencies;
    getCumulatedFrequencies(cumulatedFrequencies);

    return cumulatedFrequencies;
}

IPSDK_FORCEINLINE ipBool
BaseHistogram::insertDataInternal(const ipReal64 value)
{
    // retrieve bin index associated to value
    const ipUInt32 binIdx = retrieveBinIdx(value);
    if (binIdx != NumericLimits<ipUInt32>::max()) {

        _histogramPopulation[binIdx] += 1;
        return true;
    }
    else
        return false;
}

IPSDK_FORCEINLINE void
BaseHistogram::clearCumulatedData()
{
    _cumulatedHistogramPopulation.clear();
}

IPSDK_FORCEINLINE ipUInt32
BaseHistogram::retrieveBinIdx(const ipReal64 value) const
{
    // case of lower out of bounds values
    if (value < _firstHistoValue)
        return _lowerOutOfBoundsBinIdx;

    // case of upper out of bounds values
    if (value > _lastHistoValue)
        return _upperOutOfBoundsBinIdx;

    // case of in bounds values
    const ipReal64 offset = value - _firstHistoValue;
    ipUInt32 binIdx = static_cast<ipUInt32>(offset / _binWidth);
    if (binIdx == _nbClasses)
        binIdx -= 1;

    return binIdx + _inBoundsBinOffset;
}

IPSDK_FORCEINLINE void
BaseHistogram::updateCumulatedIfNeeded() const
{
    // check for initialization
    checkInit();

    // check for update need
    if (_cumulatedHistogramPopulation.empty() == true)
        updateCumulated();
}


} // end of namespace math
} // end of namespace ipsdk

#pragma warning (pop)

#endif // __IPSDKMATH_BASEHISTOGRAM_H__