gammaDistribution.hpp

Go to the documentation of this file.

/** \file gammaDistribution.hpp
 * \brief The Gamma Distribution.
 * \ingroup gen_math_files
 * \author Jared R. Males (jaredmales@gmail.com)
 *
 */
 
//***********************************************************************//
// Copyright 2023 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef gammaDistribution_hpp
#define gammaDistribution_hpp
 
#include <cmath>
 
#include "gamma.hpp"
 
namespace mx
{
namespace math
{
namespace func
{
 
/// The denominator of the Gamma Distribution
/** Can be used to avoid repeated calculations when the parameters are constant
 *
 * \tparam realT a real floating point type
 *
 * \returns the denominator of the Gamma Distribution.
 *
 * \ingroup gen_math_gammaDist
 */
template <typename realT>
realT gammaDistributionDenom( realT k, ///< [in] shape parameter
                              realT q  ///< [in] the scale parameter
)
{
    try
    {
        realT d = pow( q, k ) * tgamma<realT>( k );
 
        if( !std::isnormal( d ) )
            return std::numeric_limits<realT>::max();
 
        return d;
    }
    catch( ... )
    {
        return std::numeric_limits<realT>::max();
    }
}
 
/// The general shifted Gamma Distribution at a point using an arbitrary peak scaling parameter
/** Calculates the value of the Gamma Distribution at a location specified by x.
 *
 * \tparam realT a real floating point type
 *
 * \returns the value of the Gamma distribution at x.
 *
 * \ingroup gen_math_gammaDist
 */
template <typename realT>
realT gammaDistribution( realT x,    ///< [in] the location at which to calculate the distribution
                         realT x0,   ///< [in] the location parameter
                         realT k,    ///< [in] shape parameter
                         realT q,    ///< [in] the scale parameter
                         realT denom ///< [in] the denominator, or 1/peak-scale.
)
{
    if( x - x0 < 0 )
        return 0;
 
    realT v = pow( x - x0, k - 1 ) * exp( -( x - x0 ) / q ) / denom;
 
    if( !std::isnormal( v ) )
        return 0;
 
    return v;
}
 
/// The general shifted Gamma Distribution at a point.
/** Calculates the value of the Gamma Distribution at a location specified by x.
 *
 * \tparam realT a real floating point type
 *
 * \returns the value of the Gamma distribution at x.
 *
 * \ingroup gen_math_gammaDist
 */
template <typename realT>
realT gammaDistribution( realT x,  ///< [in] the location at which to calculate the distribution
                         realT x0, ///< [in] the location parameter
                         realT k,  ///< [in] shape parameter
                         realT q   ///< [in] the scale parameter
)
{
 
    return gammaDistribution<realT>( x, x0, k, q, gammaDistributionDenom<realT>( k, q ) );
}
 
/// The mean of the Gamma Distribution
/** Calculates the mean of the Gamma Distribution for the given parameters.
 *
 * \tparam realT a real floating point type
 *
 * \returns the mean of the Gamma Distribution.
 *
 * \ingroup gen_math_gammaDist
 */
template <typename realT>
realT gammaDistributionMean( realT x0,   ///< [in] the location parameter
                             realT k,    ///< [in] shape parameter
                             realT theta ///< [in] the scale parameter
)
{
    return x0 + k * theta;
}
 
/// The mode of the Gamma Distribution
/** Calculates the mode of the Gamma Distribution for the given parameters.
 *
 * \tparam realT a real floating point type
 *
 * \returns the mode of the Gamma Distribution.
 *
 * \ingroup gen_math_gammaDist
 */
template <typename realT>
realT gammaDistributionMode( realT x0,   ///< [in] the location parameter
                             realT k,    ///< [in] shape parameter
                             realT theta ///< [in] the scale parameter
)
{
    if( k >= 1 )
        return x0 + ( k - 1 ) * theta;
 
    return 0;
}
 
/// The variance of the Gamma Distribution
/** Calculates the variance of the Gamma Distribution for the given parameters.
 *
 * \tparam realT a real floating point type
 *
 * \returns the variance of the Gamma Distribution.
 *
 * \ingroup gen_math_gammaDist
 */
template <typename realT>
realT gammaDistributionVariance( realT k,    ///< [in] shape parameter
                                 realT theta ///< [in] the scale parameter
)
{
    return k * theta * theta;
}
 
} // namespace func
} // namespace math
} // namespace mx
 
#endif // gammaDistribution_hpp