bgeopdf(x,a,b)

function y = bgeopdf(x,a,b)
%BGEOPDF Beta-geometric probability distribution function.
% Y = BGEOPDF(X,A,B) returns the beta-geometric probability
% density function with parameters A and B at the values in X. 
% Note: The density function is zero unless A and B are integers.
%
% The Beta-geometric distribution is used to model the number of failures
% that will occur in a binomial proccess before the first success is
% observed and where the binomial p is itself a random variable taking a
% Beta(a,b) distribution.
%
% It has been broadly applied in fecundability and manpower or contractual
% studies.
%
% It has the probability density function:
%
%                            B(a+x,b+1)
%                   p(x) = --------------
%                              B(a,b)
%
% where B(a,b) is a beta function.
% (http://mathworld.wolfram.com/BetaBinomialDistribution.html)
% (http://en.wikipedia.org/wiki/Beta-binomial_model)
%
% Syntax: function y = bgeopdf(x,a,b) 
%      
% Inputs:
% x - number of failures before the first success {0,1,2,...)
% a - alpha parameter of Beta function (>0)
% b - beta parameter of Beta function (>0)
%
% Output:
% y - beta-geometric probability value
%
% Example. Suppose we have a sample with a Beta-geometric distribution 
% with parameters alpha = 5, and beta = 7, and we are interested to get
% the probability of get 3 failures before the first success.
%
% Calling on Matlab the function: 
%             y = bgeopdf(3,5,7)
%
% Answer is: (in format long)
%
% y =
%
%   0.04487179487179
%
% Created by A. Trujillo-Ortiz, R. Hernandez-Walls, F.A. Trujillo-Perez
%            and N. Castro-Castro
%            Facultad de Ciencias Marinas
%            Universidad Autonoma de Baja California
%            Apdo. Postal 453
%            Ensenada, Baja California
%            Mexico.
%            [e-mail]
% Copyright. October 01, 2009.
%
% ---Con cario para Ney.----
%
% To cite this file, this would be an appropriate format:
% Trujillo-Ortiz, A., R. Hernandez-Walls, F.A. Trujillo-Perez and 
%   N. Castro-Castro (2009). bgeopdf:Beta-geometric probability 
%   densiy function. A MATLAB file. [WWW document]. URL 
%   http://www.mathworks.com/matlabcentral/fileexchange/25469
%
% Reference:
% Dubey, S.D. (1966), Compound Pascal Distribution. Annals of the Institute
%      of Statistical Mathematics, 18(1):357-365.
%

if nargin < 3, 
    error('bgeopdf:TooFewInputs','Requires three input arguments.'); 
end

[errorcode x a b] = distchck(3,x,a,b);

if errorcode > 0
    error('bgeopdf:InputSizeMismatch',...
        'Requires non-scalar arguments to match in size.');
end

if (length(x)~=1) || (fix(x) ~= x) || (x < 0),
   error('bgeopdf:InvalidData',...
       'BGEOPDF requires that X must be a non-negative and integer.')
end

if (length(a)~=1) || (fix(a) ~= a) || (a < 0),
   error('bgeopdf:InvalidData',...
       'BGEOPDF requires that A must be a non-negative and integer.')
end

if (length(b)~=1) || (fix(b) ~= b) || (b < 0),
   error('bgeopdf:InvalidData',...
       'BGEOPDF requires that B must be a non-negative and integer.')
end

y = beta(a + x,b + 1)/beta(a,b);

%alternatively, using the Gamma function, it can be expressed as:
%
%y = b*(gamma(a + b)*gamma(a + x))/(gamma(a)*gamma(a + b + x + 1));

return,