classdef DirichletD
%%DIRICHLETD Functions to handle the Dirichlet distribution.
%Implemented methods are: mean, cov, PDF, rand
%
%(UNCLASSIFIED) DISTRIBUTION STATEMENT A. Approved for public release.

methods(Static)
    
function val=mean(alph)
%%MEAN Obtain the mean of the Dirichlet distribution for the given
%      concentration parameters.
%
%INPUTS: alph An NX1 vector of positive, real concentration parameters.
%             The length of alpha determines the length of the random
%             vector. If one wishes for the mean of all of the parameters
%             to be equal, then just set alph to all ones.
%
%OUTPUTS: val  The mean of the Dirichlet distribution under consideration.
%
%October 2013 David F. Crouse, Naval Research Laboratory, Washington D.C.

    val=alph/sum(alph);
end

function covMat=cov(alph)
%%VAR Obtain the covariance matrix of the Dirichlet distribution for the
%     given concentration parameters.
%
%INPUTS: alph An NX1 vector of positive, real concentration parameters. The
%             length of alpha determines the length of the random vector.
%             If one wishes for the mean of all of the parameters to be
%             equal, then just set alph to all ones.
%
%OUTPUTS: covMat The covariance matrix of the Dirichlet distribution under
%                consideration.
%
%Note that since the elements of the Dirichlet random variable must sum to
%one (i.e. are somewhat dependent), the covariance matrix is singular.
%
%October 2013 David F. Crouse, Naval Research Laboratory, Washington D.C.

    numVals=length(alph);
    alpha0=sum(alph);
    denom=alpha0^2*(alpha0+1);
    
    %First, fill in the diagonal elements.
    covMat=diag(alph.*(alpha0-alph)/denom);
    
    %Then, fill in the off-diagonal elements.
    for curRow=1:numVals
       for curCol=(curRow+1):numVals
           covMat(curRow,curCol)=-alph(curRow)*alph(curCol)/denom;
           covMat(curCol,curRow)=covMat(curRow,curCol);
       end
    end
end
    
function val=PDF(X,alph)
%%PDF Evaluate the PDF of the Dirichlet distribution at a particular vector
%     for the given concentration parameters.
%
%INPUTS: X An NX1 dirichlet random variable. Its elements must sum to one.
%     alph An NX1 vector of positive, real concentration parameters. If one
%          wishes for the mean of all of the parameters to be equal, then
%          just set alph to all ones.
%
%OUTPUTS: val  The value of the Dirichlet distribution at X given alph.
%
%The Dirichlet distribution is given in Appendix B of [1].
%
%REFERENCES:
%[1] C. M. Bishop, Pattern Recognition and Machine Learning. Cambridge,
%    United Kingdom: Springer, 2007.
%
%October 2013 David F. Crouse, Naval Research Laboratory, Washington D.C.

    C=gamma(sum(alph))/prod(gamma(alph));
    val=C*prod(X.^(alph-1));
end

function val=rand(alph)
%%RAND Generate a Dirichlet random vector with concentration vector
%      parameter vector alpha.
%
%INPUTS: alph An NX1 vector of positive, real concentration parameters. The
%             length of alpha determines the length of the random vector
%             generated. If one wishes for the mean of all of the
%             parameters to be equal, then just set alph to all ones.
%
%OUTPUTS: val An NX1 Dirichlet random vector.
%
%Dirichlet random vectors have elements that sum to one and whose
%elements are bounded between 0 and 1. Thus, Dirichlet random vectors are
%useful for generating weights for random mixture distributions.
%
%The Dirichlet random vector is generated by transforming a set of gamma
%distributed random variables. The relationship between the Dirichlet
%distribution and the gamma distribution is discussed in [1].
%
%REFERENCES:
%[1] B. A. Frigyik, A. Kapila, and M. R. Gupta, "Introduction to the
%    Dirichlet Distribution and Related processes", University of
%    Washington Technical Report, No. UWEETR-20-0006, Dec. 2010.
%    https://www.ee.washington.edu/techsite/papers/documents/UWEETR-2010-0006.pdf
%
%October 2013 David F. Crouse, Naval Research Laboratory, Washington D.C.

    numVals=length(alph);
    gVals=zeros(numVals,1);
    for curVal=1:numVals
       gVals(curVal)=randGamma(1,alph(curVal),1);
    end
    
    val=gVals/sum(gVals);
end
    
end
end

%LICENSE:
%
%The source code is in the public domain and not licensed or under
%copyright. The information and software may be used freely by the public.
%As required by 17 U.S.C. 403, third parties producing copyrighted works
%consisting predominantly of the material produced by U.S. government
%agencies must provide notice with such work(s) identifying the U.S.
%Government material incorporated and stating that such material is not
%subject to copyright protection.
%
%Derived works shall not identify themselves in a manner that implies an
%endorsement by or an affiliation with the Naval Research Laboratory.
%
%RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE
%SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY THE NAVAL
%RESEARCH LABORATORY FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE ACTIONS
%OF RECIPIENT IN THE USE OF THE SOFTWARE.
