document update

doc/source/extends.rst

@@ -135,6 +135,9 @@ Following methods need to be implemented for each univariate distribution type (
 
     Again, the package provides vectorized version of ``logpdf!`` and ``logpdf``. One may override ``logpdf!`` to provide more efficient vectorized evaluation.
 
+    Furthermore, the generic ``loglikelihood`` function delegates to ``_loglikelihood``, which repeatedly calls ``logpdf``. If there is a better way to compute log-likelihood, one should override ``_loglikelihood``.
+
+
 .. function:: cdf(d::D, x::Real)
 
     Evaluate the cumulative probability at ``x``.
@@ -209,18 +212,18 @@ Following methods need to be implemented for each univariate distribution type (
 
     .. code-block:: julia
 
-        _pdf(d::MultivariateDistribution, x::AbstractVector) = exp(_logpdf(d, x))
+        _pdf(d::MultivariateDistribution, X::AbstractVector) = exp(_logpdf(d, X))
 
-        function logpdf(d::MultivariateDistribution, x::AbstractVector)
-            length(d) == length(x) ||
+        function logpdf(d::MultivariateDistribution, X::AbstractVector)
+            length(X) == length(d) || 
                 throw(DimensionMismatch("Inconsistent array dimensions."))
-            _logpdf(d, x)
+            _logpdf(d, X)
         end
 
-        function pdf(d::MultivariateDistribution, x::AbstractVector)
-            length(d) == length(x) ||
+        function pdf(d::MultivariateDistribution, X::AbstractVector)
+            length(X) == length(d) || 
                 throw(DimensionMismatch("Inconsistent array dimensions."))
-            _pdf(d, x)
+            _pdf(d, X)
         end
 
     If there are better ways that can directly evaluate pdf values, one should override ``_pdf`` (*NOT* ``pdf``).
@@ -229,46 +232,48 @@ Following methods need to be implemented for each univariate distribution type (
 
     .. code-block:: julia
 
-        function _logpdf!(r::AbstractArray, d::MultivariateDistribution, x::DenseMatrix)
-            for i = 1:size(x,2)
-                @inbounds r[i] = _logpdf(d, view(x, :, i))
+        function _logpdf!(r::AbstractArray, d::MultivariateDistribution, X::DenseMatrix)
+            for i in 1 : size(X,2)
+                @inbounds r[i] = logpdf(d, view(X,:,i))
             end
             return r
         end
 
-        function _pdf!(r::AbstractArray, d::MultivariateDistribution, x::DenseMatrix)
-            for i = 1:size(x,2)
-                @inbounds r[i] = _pdf(d, view(x, :, i))
+        function _pdf!(r::AbstractArray, d::MultivariateDistribution, X::DenseMatrix)
+            for i in 1 : size(X,2)
+                @inbounds r[i] = pdf(d, view(X,:,i))
             end
             return r
         end
 
-        function logpdf!(r::AbstractArray, d::MultivariateDistribution, x::DenseMatrix)
-            size(x) == (length(d), length(r)) ||
+        function logpdf!(r::AbstractArray, d::MultivariateDistribution, X::DenseMatrix)
+            size(X) == (length(d), length(r)) ||
                 throw(DimensionMismatch("Inconsistent array dimensions."))
-            _logpdf!(r, d, x)
+            _logpdf!(r, d, X)
         end
 
-        function pdf!(r::AbstractArray, d::MultivariateDistribution, x::DenseMatrix)
-            size(x) == (length(d), length(r)) ||
+        function pdf!(r::AbstractArray, d::MultivariateDistribution, X::DenseMatrix)
+            size(X) == (length(d), length(r)) ||
                 throw(DimensionMismatch("Inconsistent array dimensions."))
-            _pdf!(r, d, x)
+            _pdf!(r, d, X)
         end
 
-        function logpdf(d::MultivariateDistribution, x::DenseMatrix)
-            size(x,1) == length(d) ||
+        function logpdf(d::MultivariateDistribution, X::DenseMatrix)
+            size(X, 1) == length(d) ||
                 throw(DimensionMismatch("Inconsistent array dimensions."))
-            _logpdf!(Array(eltype(d), size(x,2)), d, x)
+            _logpdf!(Array(Float64, size(X,2)), d, X)
         end
 
-        function pdf(d::MultivariateDistribution, x::DenseMatrix)
-            size(x,1) == length(d) ||
+        function pdf(d::MultivariateDistribution, X::DenseMatrix)
+            size(X, 1) == length(d) ||
                 throw(DimensionMismatch("Inconsistent array dimensions."))
-            _pdf!(Array(eltype(d), size(x,2)), d, x)
+            _pdf!(Array(Float64, size(X,2)), d, X)
         end
 
     Note that if there exists faster methods for batch evaluation, one should override ``_logpdf!`` and ``_pdf!``.
 
+    Furthermore, the generic ``loglikelihood`` function delegates to ``_loglikelihood``, which repeatedly calls ``_logpdf``. If there is a better way to compute log-likelihood, one should override ``_loglikelihood``.
+
 It is also recommended that one also implements the following statistics functions: 
 
 - ``mean``: compute the mean vector.

doc/source/multivariate.rst

@@ -53,19 +53,22 @@ Computation of statistics
 Probability evaluation
 ~~~~~~~~~~~~~~~~~~~~~~~
 
+.. function:: insupport(d, x)
+
+    If ``x`` is a vector, it returns whether x is within the support of ``d``. 
+    If ``x`` is a matrix, it returns whether every column in ``x`` is within the support of ``d``. 
+
 .. function:: pdf(d, x)
 
     Return the probability density of distribution ``d`` evaluated at ``x``.
 
     - If ``x`` is a vector, it returns the result as a scalar. 
     - If ``x`` is a matrix with n columns, it returns a vector ``r`` of length n, where ``r[i]`` corresponds to ``x[:,i]`` (i.e. treating each column as a sample).
 
-
 .. function:: pdf!(r, d, x)
 
     Evaluate the probability densities at columns of x, and write the results to a pre-allocated array r. 
 
-
 .. function:: logpdf(d, x)
 
     Return the logarithm of probability density evaluated at ``x``.
@@ -77,6 +80,9 @@ Probability evaluation
 
     Evaluate the logarithm of probability densities at columns of x, and write the results to a pre-allocated array r. 
 
+.. function:: loglikelihood(d, x)
+
+    The log-likelihood of distribution ``d`` w.r.t. all columns contained in matrix ``x``.
 
 **Note:** For multivariate distributions, the pdf value is usually very small or large, and therefore direct evaluating the pdf may cause numerical problems. It is generally advisable to perform probability computation in log-scale.
 

doc/source/univariate.rst

@@ -55,10 +55,26 @@ Let ``d`` be a distribution:
 
     Return the excess kurtosis of distribution ``d``.
 
+.. function:: isplatykurtic(d)
+
+    Return whether ``d`` is platykurtic (*i.e* ``kurtosis(d) > 0``).
+
+.. function:: isleptokurtic(d)
+
+    Return whether ``d`` is leptokurtic (*i.e* ``kurtosis(d) < 0``).
+
+.. function:: ismesokurtic(d)
+
+    Return whether ``d`` is leptokurtic (*i.e* ``kurtosis(d) == 0``).
+
 .. function:: entropy(d)
 
     Return the entropy value of distribution ``d``.
 
+.. function:: entropy(d, base)
+
+    Return the entropy value of distribution ``d``, w.r.t. a given base. 
+
 .. function:: mgf(d, t)
 
     Evaluate the moment generating function of distribution ``d``.
@@ -85,6 +101,10 @@ Probability Evaluation
 
     **Node:** The internal implementation may directly evaluate logpdf instead of first computing pdf and then taking the logarithm, for better numerical stability or efficiency.
 
+.. function:: loglikelihood(d, x)
+
+    The log-likelihood of distribution ``d`` w.r.t. all samples contained in array ``x``.
+
 .. function:: cdf(d, x)
 
     The cumulative distribution function evaluated at ``x``.

src/deprecates.jl

@@ -6,6 +6,11 @@ function dim(d::MultivariateDistribution)
 	return length(d)
 end
 
+function binaryentropy(d::UnivariateDistribution) 
+	Base.depwarn("binaryentropy is deprecated. Please use entropy(d, 2).", :binaryentropy)
+	return entropy(d) / log(2)
+end
+
 @Base.deprecate logpmf logpdf
 @Base.deprecate logpmf! logpmf!
 @Base.deprecate pmf pdf

src/multivariates.jl

@@ -18,6 +18,8 @@ insupport{D<:MultivariateDistribution}(d::Union(D,Type{D}), X::AbstractMatrix) =
 
 ## statistics
 
+entropy(d::MultivariateDistribution, b::Real) = entropy(d) / log(b)
+
 function cor(d::MultivariateDistribution)
     C = cov(d)
     n = size(C, 1)
@@ -93,14 +95,20 @@ end
 
 ## log likelihood
 
-function loglikelihood(d::MultivariateDistribution, X::DenseMatrix)
+function _loglikelihood(d::MultivariateDistribution, X::DenseMatrix)
     ll = 0.0
     for i in 1:size(X, 2)
         ll += _logpdf(d, view(X,:,i))
     end
     return ll
 end
 
+function loglikelihood(d::MultivariateDistribution, X::DenseMatrix)
+    size(X,1) == length(d) ||
+        throw(DimensionMismatch("Inconsistent array dimensions."))
+    _loglikelihood(d, X)
+end
+
 
 ##### Specific distributions #####
 

src/univariates.jl

@@ -27,7 +27,7 @@ insupport{D<:UnivariateDistribution}(d::Union(D,Type{D}), X::AbstractArray) =
 std(d::UnivariateDistribution) = sqrt(var(d))
 median(d::UnivariateDistribution) = quantile(d, 0.5)
 modes(d::UnivariateDistribution) = [mode(d)]
-binaryentropy(d::UnivariateDistribution) = entropy(d) / log(2)
+entropy(d::UnivariateDistribution, b::Real) = entropy(d) / log(b)
 
 isplatykurtic(d::UnivariateDistribution) = kurtosis(d) > 0.0
 isleptokurtic(d::UnivariateDistribution) = kurtosis(d) < 0.0
@@ -88,15 +88,16 @@ end
 
 ## loglikelihood
 
-function loglikelihood(d::UnivariateDistribution, X::AbstractArray)
+function _loglikelihood(d::UnivariateDistribution, X::AbstractArray)
     ll = 0.0
     for i in 1:length(X)
         @inbounds ll += logpdf(d, X[i])
     end
     return ll
 end
 
-
+loglikelihood(d::UnivariateDistribution, X::AbstractArray) = 
+    _loglikelihood(d, X)
 
 ##### specific distributions #####