**************************************************************************
* bvsgs_spg: Bayesian Variable Selection - Gibbs Sampler, Selection prior
*            Models with groups of variables considered as a whole.     
**************************************************************************
			(Matlab version 5 required)

REFERENCE: 
---------
_ Brown, P.J., Vannucci, M. and Fearn, T.,
  Multivariate Bayesian variable selection and prediction
  Journal of the Royal Statistical Society B, 60(3), 1998, pp. 627-641.
  
_ Delouille,V., Bayesian variable selection with related predictors,
  MSc thesis, University of Kent at Canterbury, UK, 1998.

		************************
		LIST OF MATLAB FUNCTIONS
		************************

bvsgs_spg.m	--	Main program
gibbs_sp.m	--	Gibbs sampler
itergs_sp.m     --	called by gibbs_sp
bernoulli.m	--	called by itergs_sp
gofg_sp.m	--	log relative probability function
Complete.m      --      called by gofg_sp
priormef.m      --      log-prior probability function - called by gofg_sp
repliche.m   	--	search for replicates
probord.m	--	posterior and marginal probs + ordering
pbvs_spg.m	--	prediction



		*****
		USAGE
		*****

[Gamma, GammD, logProb, logProbD, PostGamD, MargGam, SWITCH]= ...
bvsgs_spg(gamprec, X,Y, delta,k, w, v1,pm,nDum)

Inputs:		gamprec,	starting binary vector.
-------				If gamprec=[] the program asks for r 
				to select a starting vector with first r
				elements equal to 1
 		X,		independent variables, n by p
 		Y,            	response variables, n by q
 		delta, k,     	hyperparameters Inverse Wishart
 		w,		Bernoulli priors with 
				w_1 = prior probability that an
				independent effect is active,
				w_i = prior probability that the (i-1)th
				group of variables is active,i=2:length(w)  
 		v1,            	hyperparameter normal selection prior
		                (column vector (p by 1) of standard deviations)
 		pm,             number of independent effects (i.e. number
				of variables that are not grouped).
		nDum,           vector whose components give the actual
				number of variables in each group.


Outputs:	Gamma,        	all visited vectors (in sparse form)
--------			(Gamma(1,:) contains the starting vector)
		GammaD,		distinct visited vectors, ordered according 
				to their (normalized) relative post prob
				(matrix in sparse form)
 		logProb,	log-relative post probs of all visited
				vectors
		logProbD        log-relative posterior probabilities
               			of distinct visited vectors
 		PostGamD	normalized ordered relative probs
               			of distinct visited vectors
 		MargGam 	marginal probs of components
 		SWITCH,		number of component switches (out of p) 
				from iteration to iteration


Functions called by BVS_GSsPg:
-----------------------------
gofg_sp, gibbs_sp, repliche, probord


Notes:
------
_ Data must be centered
_ In the X matrix, the independent effects must be provided first,
  followed by the grouped variables. If, for examples, `nDum=[4 2]', it
  means that:
    - there are two groups of variable,  
    - the first group contains 4 variables,
    - the second group contains 2 variables.
  The order of the columns in the matrix X is important: after the
  independent effects, the next columns must be occupied by the first
  group of variable, followed by the second group, and so on. That is,
  the order in `nDum' must correspond to the order of the columns in the
  matrix X.
_ The programs asks for possible permuting of the data and for the
  Gibbs parameters (initial number of variables included, number of
  iterations)
_ QR matrices updated every m iterations (m provided by the user).
_ Programs use sparse matrices. To convert to the full form use
  the Matlab function full.m



			**********
			PREDICTION
			**********

[BayesPred,LSPred,ILS,IB]=pbvs_spg(X,Y,Xf,Yf,PostGamD,GammaD,...
numero,v1,pm,nDum)

Inputs:
-------
 X,            independent variables - calibration data
 Y,            response variables - calibration data
 Xf,           independent variables - future data
 Yf,           response variables - future data
 PostGamD,     normalized ordered relative probabilities
               of distinct visited vectors
 GammaD,       distinct visited vectors, ordered according to
               their (normalized) relative post. prob. (PostGamD)
 numero,       number of most likely models for Bayes prediction
 v1,           hyperparameter - normal selection prior
               (column vector (p by 1) of standard deviations)
 pm,           number of independent effects
 nDum,         vector whose components give the actual number of
               variables in each group.

Outputs:
--------
 BayesPred     Bayes prediction with the 'numero' most likely models
 LSPred        Least Squares prediction with the best model
 ILS           Indices of selected variables for LS prediction
 IB	       Indices of selected variables for Bayes prediction

                
                                
                        ***************
                        PARALLEL CHAINS
                        ***************

Use BVS_GSsP.m to obtain the chains
(ex. [Gamma1, GammD1, logProb1, logProbD1, PostGamD1, MargGam1, SWITCH1]= ...
		bvsgs_spg(gamprec, X,Y, delta,k, w, v1,pm,nDum)
     [Gamma2, GammD2, logProb2, logProbD2, PostGamD2, MargGam2, SWITCH2]= ...
		bvsgs_spg(gamprec, X,Y, delta,k, w, v1,pm,nDum)  )	

Pool together distinct visited vectors
(ex. Gamma = [GammaD1' GammaD2']';   )

Pool together log-relative post probabilities of distinct visited vectors
(ex. logProb = cat(2, logProbD1, logProbD2);   )

Use repliche.m to search for replications
(ex. [GammaD, logProbD]=repliche(Gamma, logProb);  )

Use ProbOrd.m to get normalized posterior and marginal probs and
to order the distinct visited vectors according to probability
(ex. [GammaD, logProbD, PostGamD, MargGam]=probord(logProbD, GammaD,pm,nDum); )

Do prediction using PostGamD and GammaD


***************************************
Copyright (c) 1997 Marina Vannucci
Modified by Veronique Delouille (1998)
***************************************
