messv_g3.m

计量工具箱

function results = messv_g3(y,x,options,ndraw,nomit,prior,start)
% PURPOSE: Bayesian estimates of the matrix exponential spatial model (mess)
% % [samples values of rho and #neighbors to produce a posterior distribution
%    for these hyperparameters in the problem]
% S*y = X*b + e,           with xflag == 0, or:
% S*y = [i X D*X]*b + e,   with xflag == 1
%          e = N(0,sige*V), V = diag(v1,...,vn)
%          S = e^alpha*D
%          r/vi = ID chi(r)/r, r = Gamma(m,k)
%          B = N(c,T), 
%          1/sige = Gamma(nu,d0), 
%          alpha = N(a,B), (default: diffuse prior) 
% D = a weight matrix constructed from neighbors using:
% D = sum rho^i N_i / sum rho^i, i=1,...,#neighbors
% using a grid of rho values from options.rmin to options.rmax
% and a grid of values options.nmin to options.nmax over the # of neighbors, i
% where i = # neighbors, N_i a matrix with ith nearest neighbors
%-------------------------------------------------------------
% USAGE: results = mess_g3(y,x,options,ndraw,nomit,prior,start)
% where: y = dependent variable vector (nobs x 1)
%        x = independent variables matrix (nobs x nvar)
%  options = a structure variable with:
%  options.latt  = lattitude coordinates (nx1 vector)
%  options.long  = longitude coordinates (nx1 vector)
%  options.mmin = minimum # of neighbors to search over (default = 4)
%  options.mmax = maximum # of neighbors to search over (default = 10)
%  options.rmin  = minimum value of rho to use (0 < rho < 1), (default 0.5)                  
%  options.rmax  = maximum value of rho to use in discounting (default 1)
%  options.xflag = 0 for S*y = X*b + e,         model (default)
%                = 1 for S*y = [i X D*X]*b + e, model
%  options.nflag = 0 for neighbors using 1st and 2nd order Delauney (default)
%                = 1 for neighbors using 3rd and 4th order Delauney
%                  for large nobs, and large # neighbors, used nflag = 1
%  options.q     = # of terms to use in the matrix exponential
%                  expansion (default = 7)
%    ndraw = # of draws
%    nomit = # of initial draws omitted for burn-in            
%    prior = a structure variable with:
%            prior.beta  = prior means for beta,   c above (default 0)
%                          (nvar x 1 vector, D*X terms have diffuse prior =0)
%            priov.bcov  = prior beta covariance , T above (default 1e+12)
%                          (nvar x nvar matrix, D*X terms have diffuse prior)
%            prior.alpha = prior mean for alpha    a above (default uniform)
%            prior.rcov  = prior alpha variance,   B above 
%            prior.nu    = informative Gamma(nu,d0) prior on sige
%            prior.d0    = default: nu=0,d0=0 (diffuse prior)
%            prior.rval  = r prior hyperparameter, default=4
%            prior.m,    = informative Gamma(m,k) prior on r
%            prior.k,    = informative Gamma(m,k) prior on r
%            prior.lflag = 0 (default for marginal likelihood calculations)
%                        = 1 for no marginal likelihood (faster)
%    start = (optional) structure containing starting values: 
%            defaults: beta=ones(k,1),sige=1,rho=0.5, V=ones(n,1)
%            start.b   = beta starting values (nvar x 1)
%            start.a   = alpha starting value (scalar)
%            start.sig = sige starting value  (scalar)
%-------------------------------------------------------------
% RETURNS:  a structure:
%          results.meth   = 'messv_g3'
%          results.bdraw  = bhat draws (ndraw-nomit x nvar)
%          results.bmean  = mean of bhat draws
%          results.bstd   = std of bhat draws
%          results.adraw  = alpha draws (ndraw-nomit x 1)
%          results.amean  = mean of alpha draws
%          results.astd   = std of alpha draws
%          results.sdraw  = sige draws (ndraw-nomit x 1)
%          results.smean  = mean of sige draws
%          results.lmean  = marginal likelihood based on mean of draws
%          results.rmean  = posterior mean of rho
%          results.rstd   = posterior std of rho
%          results.rdraw  = draws for rho
%          results.mmean  = posterior mean of m, the # of neighbors
%          results.mstd   = posterior std of  m, the # of neighbors
%          results.mdraw  = draws for # of neighbors
%          results.vmean  = posterior mean of vi draws
%          results.bprior = b prior means, prior.beta from input
%          results.bpstd  = b prior std deviations sqrt(diag(prior.bcov))
%          results.nobs   = # of observations
%          results.nvar   = # of variables in x-matrix (plus D*X matrix)
%          results.ndraw  = # of draws
%          results.nomit  = # of initial draws omitted
%          results.y      = y-vector from input (nobs x 1)
%          results.r      = value of hyperparameter r (if input)
%          results.rvdraw = r draws (ndraw-nomit x 1) (if m,k input)
%          results.yhat   = mean of posterior predicted (nobs x 1)
%          results.nu     = nu prior parameter
%          results.d0     = d0 prior parameter
%          results.stime  = time for sampling
%          results.time   = total time taken  
%          results.ntime  = time taken for setup mesh over rho,m values
%          results.accept = acceptance rate for alpha <= 0
%          results.rmax   = rmax: default (or user input)
%          results.rmin   = rmin: default (or user input)   
%          results.mmax   = mmax: default (or user input)
%          results.mmin   = mmin: default (or user input)    
%          results.nflag  = nflag value from input (or default)   
%          results.tflag  = 'plevel' (default) for printing p-levels
%                         = 'tstat' for printing bogus t-statistics 
%          results.palpha   = prior for alpha (from input)
%          results.acov   = prior variance for alpha (from input)
%          results.pflag  = 1, if a normal(a,B) prior for alpha, 0 otherwise
%          results.xflag = model flag from input
%          results.q     = q value from input (or default)

% --------------------------------------------------------------
% NOTES: if the model includes a constant term
% it should be entered as the first column in the x-matrix
% that is input to the function
% 1) mess_g1 produces a posterior distribution for # neighbors
% 2) mess_g2 produces a posterior distribution for the hyperparameter rho
% 3) mess_g3 produces posteriors for both rho and # of neighbors
% --------------------------------------------------------------
% SEE ALSO:  mess_g3d, mess_g, mess_g3, messv_g, prt, c_mess, mess
% --------------------------------------------------------------
% REFERENCES: LeSage and Pace (2000) "Bayesian Estimation of the
% Matrix Exponential Spatial Specification", unpublished manuscript
%----------------------------------------------------------------

% written by:
% James P. LeSage, 1/2000
% Dept of Economics
% University of Toledo
% 2801 W. Bancroft St,
% Toledo, OH 43606
% [e-mail]


timet = clock;

% error checking on inputs
[n junk] = size(y);
results.y = y;
[n1 k] = size(x);

if n1 ~= n
error('messv_g3: x-matrix contains wrong # of observations');
end;

% set defaults
q = 7;
xflag = 0;
rmin = 0.5;
rmax = 1.0;
rval = 4;
mmin = 4;
mmax = 10;
neigh = 0;
nflag = 0;
llflag = 0;
pflag = 0; % flag for the presence or absent of a prior on alpha

mm = 0;    % set defaults
nu = 0;    % default diffuse prior for sige
d0 = 0;
sig0 = 1;         % default starting values for sige
astart = -1;      % default starting value for alpha
c = zeros(k,1);   % diffuse prior for beta
T = eye(k)*1e+12;
palpha = -1;
S = 1e+12;
lflag = 0; % default to do marginal likelihood calculations
if nargin == 7
    if ~isstruct(start)
        error('messv_g3: must supply starting values in a structure');
    end;
 % parse starting values entered by the user
 fields = fieldnames(start);
 nf = length(fields);
 for i=1:nf
    if strcmp(fields{i},'b')
        b0 = start.b; 
        [n1 n2] = size(b0); % error checking on user inputs
       if n1 ~= k
        error('messv_g3: starting beta values are wrong');
       elseif n2 ~= 1
        error('messv_g3: starting beta values are wrong');
       end;
    elseif strcmp(fields{i},'sig')
        sig0 = start.sig;
       [n1 n2] = size(sig0); % error checking on user inputs
       if n1 ~= 1
        error('messv_g3: starting sige value is wrong');
       elseif n2 ~= 1
        error('messv_g3: starting sige value is wrong');
       end;
    elseif strcmp(fields{i},'a')
        astart = start.a;
       [n1 n2] = size(astart); % error checking on user inputs
       if n1 ~= 1
        error('messv_g3: starting alpha value is wrong');
       elseif n2 ~= 1
        error('messv_g3: starting alpha value is wrong');
       end;
    end;
 end; % end of for loop
% parse options structure
    if ~isstruct(options)
        error('messv_g3: must supply option values in a structure');
    end;
 fields = fieldnames(options);
 nf = length(fields);
 for i=1:nf
    if strcmp(fields{i},'xflag')
       xflag = options.xflag;
    elseif strcmp(fields{i},'rmin')
        rmin = options.rmin;
    elseif strcmp(fields{i},'rmax')
        rmax = options.rmax;
    elseif strcmp(fields{i},'mmin')
        mmin = options.mmin;
    elseif strcmp(fields{i},'mmax')
        mmax = options.mmax;
    elseif strcmp(fields{i},'nflag')
        nflag = options.nflag;
    elseif strcmp(fields{i},'q')
       q = options.q;
     elseif strcmp(fields{i},'latt')
        latt = options.latt; llflag = llflag + 1;
     elseif strcmp(fields{i},'long')
        long = options.long; llflag = llflag + 1;
     end;
 end; % end of for loop

% parse prior structure variable inputs        
    if ~isstruct(prior)
    error('messv_g3: must supply the prior as a structure variable');
    end;

fields = fieldnames(prior);
nf = length(fields);

for i=1:nf
    if strcmp(fields{i},'beta')
        c = prior.beta;
    elseif strcmp(fields{i},'bcov')
        T = prior.bcov;
    elseif strcmp(fields{i},'alpha')
        palpha = prior.alpha; pflag = 1;
    elseif strcmp(fields{i},'acov')
        S = prior.acov;        
    elseif strcmp(fields{i},'nu')
        nu = prior.nu;
    elseif strcmp(fields{i},'d0')
        d0 = prior.d0;
    elseif strcmp(fields{i},'lflag')
       lflag = prior.lflag; 
    elseif strcmp(fields{i},'m')
        mm = prior.m;
        kk = prior.k;
        rval = gamm_rnd(1,1,mm,kk);    % initial value for rval
    elseif strcmp(fields{i},'rval');
        rval = prior.rval;
    end;
end;


elseif nargin == 6   % we supply default starting values
 fields = fieldnames(prior);
 nf = length(fields);
 for i=1:nf
    if strcmp(fields{i},'beta')
        c = prior.beta;
    elseif strcmp(fields{i},'bcov')
        T = prior.bcov;
    elseif strcmp(fields{i},'m')
        mm = prior.m;
        kk = prior.k;
        rval = gamm_rnd(1,1,mm,kk);    % initial value for rval
    elseif strcmp(fields{i},'alpha')
        palpha = prior.alpha; pflag = 1;
    elseif strcmp(fields{i},'acov')
        S = prior.acov;         
    elseif strcmp(fields{i},'nu')
        nu = prior.nu;
    elseif strcmp(fields{i},'d0')
        d0 = prior.d0;
    elseif strcmp(fields{i},'rval')
       rval = prior.rval; 
    elseif strcmp(fields{i},'lflag')
       lflag = prior.lflag; 
    elseif strcmp(fields{i},'nflag')
        nflag = options.nflag;
    end;
 end;
 
 % parse options
     if ~isstruct(options)
        error('messv_g3: must supply option values in a structure');
    end;
 fields = fieldnames(options);
 nf = length(fields);
 for i=1:nf
    if strcmp(fields{i},'xflag')
       xflag = options.xflag;
    elseif strcmp(fields{i},'rmin')
        rmin = options.rmin;
    elseif strcmp(fields{i},'rmax')
        rmax = options.rmax;
    elseif strcmp(fields{i},'mmin')
        mmin = options.mmin;
    elseif strcmp(fields{i},'mmax')
        mmax = options.mmax;
    elseif strcmp(fields{i},'q')
       q = options.q;
    elseif strcmp(fields{i},'nflag')
        nflag = options.nflag;
     elseif strcmp(fields{i},'latt')
        latt = options.latt; llflag = llflag + 1;
     elseif strcmp(fields{i},'long')
        long = options.long; llflag = llflag + 1;
     end;
 end; % end of for loop



elseif nargin == 5   % we supply all defaults
   % parse options structure
    if ~isstruct(options)
        error('messv_g3: must supply option values in a structure');
    end;
 fields = fieldnames(options);
 nf = length(fields);
 for i=1:nf
    if strcmp(fields{i},'xflag')
       xflag = options.xflag;
    elseif strcmp(fields{i},'rmin')
        rmin = options.rmin;
    elseif strcmp(fields{i},'rmax')
        rmax = options.rmax;
    elseif strcmp(fields{i},'mmin')
        mmin = options.mmin;
    elseif strcmp(fields{i},'mmax')
        mmax = options.mmax;
    elseif strcmp(fields{i},'q')
       q = options.q;
     elseif strcmp(fields{i},'latt')
        latt = options.latt; llflag = llflag + 1;
     elseif strcmp(fields{i},'long')
        long = options.long; llflag = llflag + 1;
    elseif strcmp(fields{i},'nflag')
        nflag = options.nflag;
     end;
 end; % end of for loop

else
error('Wrong # of arguments to messv_g3');
end;
      

% error checking on prior information inputs
[checkk,junk] = size(c);
if checkk ~= k
error('messv_g3: prior means are wrong');
elseif junk ~= 1
error('messv_g3: prior means are wrong');
end;

[checkk junk] = size(T);
if checkk ~= k
error('messv_g3: prior bcov is wrong');
elseif junk ~= k
error('messv_g3: prior bcov is wrong');
end;

[checkk junk] = size(palpha);
if checkk ~= 1
error('messv_g3: prior alpha is wrong');
elseif junk ~= 1
error('messv_g3: prior alpha is wrong');
end;

[checkk junk] = size(S);
if checkk ~= 1
error('messv_g3: prior acov is wrong');
elseif junk ~= 1
error('messv_g: prior acov is wrong');
end;

% make sure the user input latt, long or we really bomb
if llflag ~= 2;
error('messv_g3: no lattitude-longitude coordinates input');
end;

switch xflag % switch on x transformation

   
   case{0} % case where x variables are not transformed


% ====== initializations
% compute this stuff once to save time
TI = inv(T);
TIc = TI*c;

% ========= do up front grid over rho, alpha values
t1 = clock;   % time this operation

results.rmin = rmin;
results.rmax = rmax;
results.mmin = mmin;
results.mmax = mmax;

rgrid = rmin:0.01:rmax;
mgrid = mmin:1:mmax;
nrho = length(rgrid);
nneigh = length(mgrid);


% storage for Y over the grid
Ymat = zeros(n,q,nrho,nneigh); % vectors of Sy for various alpha,rho values

% find index into nearest neighbors
if nflag == 0
nnlistall = find_nn(latt,long,mmax);
elseif nflag == 1
nnlistall = find_nn(latt,long,mmax,3);
else
error('mess_g3: bad nflag option');
end;

% check for empty nnlist columns
chk = find(nnlistall == 0);
if length(chk) > 0; 
 if nflag == 1 % no saving the user here
 error('mess_g3: trying too many neighbors, some do not exist');
 else % we save the user here
 nnlistall = find_nn(latt,long,mmax,4);
 end;
end;

% do grid over rho, neigh values
hwait = waitbar(0,'computing grid over rho and neighbors ...');
ngrid = nneigh*nrho;
iter = 1;

for kk=1:nneigh;
neigh = mgrid(kk);
nnlist = nnlistall(:,1:neigh);
for jj=1:nrho;
rho = rgrid(jj);

tmp = rho.^(0:neigh-1);
tmp = tmp/sum(tmp);

% construct and save Y
wy = y;
Y = y(:,ones(1,q));
for i=2:q;
wy = wy(nnlist)*tmp';
Y(:,i) = wy;
end;
% we can save Y for lookup
Ymat(:,:,jj,kk) = Y;
% save rho
rmat(jj,1) = rho;

end; % end of loop over alpha values 
mmat(kk,1) = neigh;

iter = iter + nrho; 
waitbar(iter/ngrid);         

end; % end of loop over neighbors
close(hwait);

% end of up front stuff with Sy saved in Symat
gtime = etime(clock,t1);

% initializations and starting values for the sampler
rho = 1;
alpha = astart;
neigh = mmax;
cc=0.2;   % initial metropolis value
cnta = 0; % counter for acceptance rate for alpha