Added files tobitpdf, tobitcdf, tobitrnd, tobitinv

toolbox/utilities_stat/tobitcdf.m

@@ -0,0 +1,200 @@
+function tobcdf = tobitcdf(x,   mu,sigma, left, right)
+%tobitcdf returns cumulative distribution function from the tobit model
+%
+%<a href="matlab: docsearchFS('tobitcdf')">Link to the help function</a>
+%
+%
+%
+%  Required input arguments:
+%
+%    x:         Value at which the cdf must be evaluated.
+%               Scalar, vector or matrix 3D array of the same size of mu,
+%               sigma, Lower and Upper
+%               A scalar input functions as a constant matrix of the
+%               same size as the other input.
+%               See "More About:" for details about the tobit
+%               distribution.
+%               Data Types - single | double
+%
+%  Optional input arguments:
+%
+%    mu :       location parameter of the tobit distribution.
+%               Scalar, vector or matrix 3D array of the same size of x and sigma, Lower, Upper.
+%               A scalar input functions as a constant matrix of the same
+%               size as the other input. Default value of mu is 0.
+%               See "More About:" for details about the tobit
+%               distribution.
+%               Example - 'mu',1
+%               Data Types - single | double
+%
+%    sigma :    scale parameter of the tobit distribution.
+%               Scalar, vector or matrix 3D array of the same size of x and sigma, Lower, Upper.
+%               A scalar input functions as a constant matrix of the same
+%               size as the other input. Default value of sigma is 1
+%               See "More About:" for details about the tobit
+%               distribution.
+%               Example - 'sigma',1
+%               Data Types - single | double
+%
+%    left :     lower limit for the censored random variable. Scalar.
+%               If set to -Inf, the random variable is assumed to be not
+%               left-censored; default value of left is zero (classical
+%               tobit model).
+%               Example - 'left',1
+%               Data Types - double
+%
+%    right :    right limit for the censored random variable. Scalar.
+%               If set to Inf, the random variable is assumed to be not
+%               right-censored; default value of left is Inf (classical
+%               tobit model).
+%               Example - 'right',800
+%               Data Types - double
+%
+%  Output:
+%
+%         tobcdf : tobit cdf values. 
+%                  The size of tpdf is the common size of the input
+%                  arguments. A scalar input functions as a constant matrix
+%                  of the same size as the other inputs.
+%
+%
+% See also: tobitpdf, tobitrnd, tobitinv
+%
+% References:
+%
+% Greene, W.H. (2008), "Econometric Analysis, Sixth Edition", Prentice Hall, pp. 871-875.
+%
+% Tobin, J. (1958), Estimation of Relationships for Limited Dependent
+% Variables, "Econometrica", 26, pp. 24-36.
+%
+%
+% Copyright 2008-2024.
+%
+%<a href="matlab: docsearchFS('tobitcdf')">Link to the help function</a>
+%
+%
+%$LastChangedDate::                      $: Date of the last commit
+%
+% Examples:
+%
+
+%{
+    % Example when x is a scalar.
+    x=0;
+    % The default values for mu and sigma are 0, 1
+    % The default values for left and right are 0 Inf
+    y=tobitcdf(x); 
+    ynorm=normcdf(x);
+    assert(y==ynorm,'Tobit cdf is not correct')
+    % Pr(Tobit<=0, mu=0, sigma=1, left=0, right=Inf) = Pr (Z<0)
+%}
+
+%{
+    % In this example mu, and sigma are specified.
+    x=0; mu=2; sigma=1.5;
+    % The default values for left and right are 0 Inf
+    y=tobitcdf(x,mu,sigma); 
+    ynorm=normcdf(x,mu,sigma);
+    assert(y==ynorm,'Tobit cdf is not correct')
+    % Pr(Tobit=0, mu=2, sigma=1.5, left=0, right=Inf) = Pr (Z<0)
+%}
+
+%{
+    % In this example mu, sigma, left and right are specified.
+    x=0; mu=2; sigma=1.5; left=1; right=3;
+    y=tobitcdf(x,mu,sigma,left,right); 
+    ynorm=normcdf(x,mu,sigma);
+    % Pr(Tobit=0, mu=2, sigma=1.5, left=0, right=Inf) = Pr (Z<0)
+%}
+
+%{
+    % Example where x is not a scalar.
+    x=0:10; mu=2; sigma=1.5; left=1; right=3;
+    y=tobitcdf(x,mu,sigma,left,right); 
+    ynorm=normcdf(x,mu,sigma);
+    
+%}
+
+
+%{
+    %% Example of tobit cdf.
+    close all
+    x=(-3:0.0001:3)';
+    left=0;
+    right=2;
+    mu=0.5;
+    sigma=1;
+    x(find(x<left,1,'last'))=NaN;
+    x(find(x>left,1,'first'))=NaN;
+    x(find(x<right,1,'last'))=NaN;
+    x(find(x>right,1,'first'))=NaN;
+    y=tobitcdf(x,mu,sigma,left,right);
+    plot(x,y,'LineWidth',2)
+    hold('on')
+    stem(left,y(x==left),'Color','b')
+    stem(right,y(x==right),'Color','b')
+    title(['Tobit cdf when \mu=' num2str(mu) ', \sigma=' num2str(sigma) ', ' ...
+        'left=' num2str(left)  ', right='  num2str(right)])
+    % x < left
+    xsmallerthanleft=left-rand;
+    text(xsmallerthanleft,tobitcdf(xsmallerthanleft,mu,sigma,left,right)+0.05, ...
+        'Pr(Tobit(\mu,\sigma^2,left,right)<left)=0 ','HorizontalAlignment','right')
+    % x =left
+    text(left,tobitcdf(left,mu,sigma,left,right)-0.01, ...
+        'Pr(Tobit(\mu,\sigma^2,left,right)<=left)=\Phi(left, \mu, sigma^2) ','HorizontalAlignment','right')
+    % left< x <right 
+    xinside=unifrnd(left,right);
+    text(xinside,tobitcdf(xinside,mu,sigma,left,right)+0.01, ...
+        ' Pr(Tobit(\mu,\sigma^2,left,right)<=x)=\Phi(x, \mu, \sigma^2)   when x \in (left right)','HorizontalAlignment','left')
+    % x>=right
+    text(right,tobitcdf(right,mu,sigma,left,right)-0.01, ...
+        ' Pr(Tobit(\mu,\sigma^2,left,right)<=right)=1','HorizontalAlignment','left')
+    ylim([0 1])
+%}
+
+
+%% Beginning of code
+
+if nargin<5
+    right =  Inf;
+end
+
+if nargin<4
+    left =  0;
+end
+
+if nargin<3
+    sigma =  1;
+end
+
+if nargin<2
+    mu =  0;
+end
+
+if nargin < 1
+    error(message('FSDA:tobitpdf:TooFewInputs'));
+end
+
+[errorcode, x, mu, sigma, left, right] = distchck(5,x,mu,sigma,left,right);
+
+if errorcode > 0
+    error(message('FSDA:tobitpdf:InputSizeMismatch'));
+end
+
+% Initialize Y to zero.
+outType = internal.stats.dominantType(x,mu,sigma,left,right);
+tobcdf = zeros(size(x),"like",outType);
+
+for i=1:length(x)
+    if x(i)<left(i) 
+        tobcdf(i) = 0;
+    elseif x(i)>=right(i)
+        tobcdf(i) = 1;
+    else
+        tobcdf(i) = normcdf(x(i),mu(i),sigma(i));
+    end  
+end
+
+end
+
+%FScategory:ProbDist

toolbox/utilities_stat/tobitinv.m

@@ -0,0 +1,169 @@
+function x = tobitinv(p, mu, sigma, left, right)
+%tobitinv computes the inverse of the tobit cumulative distribution function.
+%
+%<a href="matlab: docsearchFS('tobitinv')">Link to the help function</a>
+%
+%  Required input arguments:
+%
+%    p:         Probability at which the inverse of the cdf must be evaluated
+%               $0 \leq p \leq 1$.
+%               Scalar, vector or matrix 3D array of the same size of x and b.
+%               A scalar input functions as a constant matrix of the same
+%               size as the other input.
+%               See the section called "More About:" for more details about
+%               the inverse gamma distribution.
+%               Data Types - single | double
+%
+%
+%  Optional input arguments:
+%
+%    mu :       location parameter of the tobit distribution.
+%               Scalar, vector or matrix 3D array of the same size of x and sigma, Lower, Upper.
+%               A scalar input functions as a constant matrix of the same
+%               size as the other input. Default value of mu is 0.
+%               See "More About:" for details about the tobit
+%               distribution.
+%               Example - 'mu',10
+%               Data Types - single | double
+%
+%    sigma :    scale parameter of the tobit distribution.
+%               Scalar, vector or matrix 3D array of the same size of x and sigma, Lower, Upper.
+%               A scalar input functions as a constant matrix of the same
+%               size as the other input. Default value of sigma is 1
+%               See "More About:" for details about the tobit
+%               distribution.
+%               Example - 'sigma',800
+%               Data Types - single | double
+%
+%    left :     lower limit for the censored random variable. Scalar.
+%               If set to -Inf, the random variable is assumed to be not
+%               left-censored; default value of left is zero (classical
+%               tobit model).
+%               Example - 'left',1
+%               Data Types - double
+%
+%    right :    right limit for the censored random variable. Scalar.
+%               If set to Inf, the random variable is assumed to be not
+%               right-censored; default value of left is Inf (classical
+%               tobit model).
+%               Example - 'right',800
+%               Data Types - double%
+%
+%  Output:
+%
+%    x:         inverse CDF value. Scalar, vector or matrix or 3D array of the same size
+%               of input arguments p, mu, sigma, left, right. $p=\int_0^x f_{tobit}(t | \mu, \sigma, left, right) dt$ is the
+%               inverse of tobit cdf with parameters mu, sigma, left, right
+%               for the corresponding
+%               probabilities in p.
+%
+% More About:
+%
+%
+% The cdf of the tobit distribution defined over the support
+% $x \in R $ with location parameter $mu$, scale parameter $sigma$ and
+% lower and upper censor values left and right
+%  \[
+%  F_{tobit}(x, \mu, \sigma, left, right)  =\int_0^x f(t) dt
+%  \]
+%
+%
+% See also: tobitpdf, tobitcdf, tobitrnd
+%
+% References:
+%
+% Greene, W.H. (2008), "Econometric Analysis, Sixth Edition", Prentice Hall, pp. 871-875.
+%
+% Tobin, J. (1958), Estimation of Relationships for Limited Dependent
+% Variables, "Econometrica", 26, pp. 24-36.
+%
+%
+% Copyright 2008-2024.
+% Written by FSDA team
+%
+%
+%<a href="matlab: docsearchFS('tobitinv')">Link to the help function</a>
+%
+%$LastChangedDate::                      $: Date of the last commit
+%
+
+% Examples:
+%
+
+%{
+ % Using all default options.
+ % In this case we assume that mu=0, sigma=1, left=0, right=Inf
+    x=tobitinv(0.5)
+%}
+
+%{
+ % mu is specified.
+ % In this case we assume that sigma=1, left=0, right=Inf
+    x=tobitinv(0.8,1)
+%}
+
+%{
+ % mu sigma are specified.
+ % In this case we assume that left=0, right=Inf
+    x=tobitinv(0.8,1,0.4)
+%}
+
+%{
+ % mu sigma and left are specified.
+ % In this case we assume that right=Inf
+    x=tobitinv(0.95,2.5,0.4,3)
+%}
+
+
+%{
+    %% Check accuracy of results, monitoring $|x-F_{tobit}^{-1} (F_{tobit}(x))|$.
+    a=100; 
+    b=200;
+    mu=(a+b).*0.6;
+    sigma=40;
+    x=tobitrnd(mu,sigma,a,b,100,1);
+    Y=zeros(length(x),1);
+    Ychk=Y;
+
+    for i=1:length(x)
+        Y(i)=x(i)-tobitinv(tobitcdf(x(i),mu,sigma,a,b),mu,sigma,a,b);
+    end
+    disp('Maximum deviation from 0');
+    disp(max(max(abs(Y))));
+%}
+
+
+%% Beginning of code
+
+if nargin<5
+    right =  Inf;
+end
+
+if nargin<4
+    left =  0;
+end
+
+if nargin<3
+    sigma =  1;
+end
+
+if nargin<2
+    mu =  0;
+end
+
+if nargin < 1
+    error(message('FSDA:tobitinv:TooFewInputs'));
+end
+
+
+x=norminv(p,mu,sigma);
+    xleft=x<left;
+
+x(xleft)=left(xleft);
+
+xright=x>right;
+
+x(xright)=right(xright);
+
+end
+%FScategory:ProbDist