diff --git a/src/Distributions.jl b/src/Distributions.jl index fcf699434..67415ca77 100644 --- a/src/Distributions.jl +++ b/src/Distributions.jl @@ -222,8 +222,10 @@ export logdiffcdf, # log of difference between cdf at two values logdetcov, # log-determinant of covariance loglikelihood, # log probability of array of IID draws + logulikelihood, # unnormalized log probability of array of IID draws logpdf, # log probability density logpdf!, # evaluate log pdf to provided storage + logupdf, # unnormalized log probability density invscale, # Inverse scale parameter sqmahal, # squared Mahalanobis distance to Gaussian center @@ -267,10 +269,11 @@ export succprob, # the success probability support, # the support of a distribution (or a distribution type) truncated, # truncate a distribution with a lower and upper bound + updf, # unnormalized probability density var, # variance of distribution varlogx, # variance of log(x) expected_logdet, # expected logarithm of random matrix determinant - gradlogpdf, # gradient (or derivative) of logpdf(d,x) wrt x + gradlogpdf, # gradient (or derivative) of logpdf(d,x) and logupdf(d,x) wrt x # reexport from StatsBase sample, sample!, # sample from a source array diff --git a/src/common.jl b/src/common.jl index 899cca41d..70ad5c372 100644 --- a/src/common.jl +++ b/src/common.jl @@ -215,7 +215,7 @@ Instead of `pdf` one should implement `_pdf(d, x)` which does not have to check `x`. However, since the default definition of `pdf(d, x)` falls back to `logpdf(d, x)` usually it is sufficient to implement `logpdf`. -See also: [`logpdf`](@ref). +See also: [`logpdf`](@ref), [`updf`](@ref) """ @inline function pdf( d::Distribution{ArrayLikeVariate{N}}, x::AbstractArray{<:Real,M} @@ -243,6 +243,19 @@ function _pdf(d::Distribution{ArrayLikeVariate{N}}, x::AbstractArray{<:Real,N}) return exp(@inbounds logpdf(d, x)) end +""" + updf(d::Distribution, x) + +Evaluate the unnormalized probability density function of `d` at `x`. + +The unnormalized probability density function contains all terms in the probability density +function that are dependent on `x` and not necessarily constant terms or other terms +dependent on parameters of the distribution. + +See also: [`pdf`](@ref), [`logupdf`](@ref) +""" +updf(d::Distribution, x) = pdf(d, x) + """ logpdf(d::Distribution{ArrayLikeVariate{N}}, x::AbstractArray{<:Real,N}) where {N} @@ -256,7 +269,7 @@ be disabled by using `@inbounds`. Instead of `logpdf` one should implement `_logpdf(d, x)` which does not have to check the size of `x`. -See also: [`pdf`](@ref), [`gradlogpdf`](@ref). +See also: [`pdf`](@ref), [`logupdf`](@ref), [`gradlogpdf`](@ref). """ @inline function logpdf( d::Distribution{ArrayLikeVariate{N}}, x::AbstractArray{<:Real,M} @@ -280,14 +293,27 @@ See also: [`pdf`](@ref), [`gradlogpdf`](@ref). end end +""" + logupdf(d::Distribution, x) + +Evaluate the logarithm of the unnormalized probability density function of `d` at `x`. + +The result is equivalent to `log(updf(d, x))` but may be more numerically stable. + +See also: [`updf`](@ref), [`logpdf`](@ref), [`gradlogpdf`](@ref) +""" +logupdf(d::Distribution, x) = logpdf(d, x) + """ gradlogpdf(d::Distribution, x) Evaluate the gradient of the logarithm of the probability density function of `d` at `x`. +Note that this is the gradient of both [`logpdf`](@ref) and [`logupdf`](@ref). + For univariate distributions, return the derivative. -See also: [`logpdf`](@ref). +See also: [`logpdf`](@ref), [`logupdf`](@ref) """ function gradlogpdf end @@ -481,6 +507,20 @@ Base.@propagate_inbounds function loglikelihood( return sum(Base.Fix1(logpdf, d), x) end +""" + logulikelihood(d::Distribution, x) + +The unnormalized log-likelihood of distribution `d` with respect to all variate(s) contained +in `x`. + +The unnormalized log-likelihood contains all terms in the log-likelihood that are dependent +on the parameters of the distribution and not necessarily constant terms or other terms +dependent on `x`. + +See also: [`loglikelihood`](@ref) +""" +logulikelihood(d::Distribution, x) = loglikelihood(d, x) + ## TODO: the following types need to be improved abstract type SufficientStats end abstract type IncompleteDistribution end