*************************************************************************
* bvsgs_spi: Bayesian Variable Selection - Gibbs Sampler, Selection prior
*             Models with interactions.       
*************************************************************************
			(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_spi.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
prior.m         --      log-prior probability function - called by gofg_sp
priorgam.m      --      called by prior
priorweak.m     --      called by prior
gamprod.m       --      called by priorgam, priorweak
gamsum.m        --      called by priorweak     
repliche.m   	--	search for replicates
probord.m	--	posterior and marginal probs + ordering
pbvs_sp.m	--	prediction
processing.m    --      pre-processing of the data


		*****
		USAGE
		*****

[Gamma, GammaD, logProb, logProbD, PostGamD, MargGam, SWITCH]= ...
bvsgs_spi(gamprec, X,Y, delta,k, w, v1)

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,              hyperparameters Bernoulli prior.
                For STRONG HEREDITY principle, i.e. if 
		a 2-way interaction effect X_iX_k (denoted X_ik) is
		allowed  to be selected (or present) only when both 
		X_i and X_k  are selected, w is decomposed as [wm p11 eta]
		where:
                wm = hyperparam Bernoulli prior for main effects; other
                hyperparameters Bernoulli prior are:  
                p11 = prob(X_ik present|X_i and X_k present) (i may be equal to k);
                eta = prob(X_ik present |X_i absent and/or g_k absent), eta is
		taken small (e.g. eta = 0.00001).

                For WEAK HEREDITY principle, i.e. if
                a 2-way interaction effect  X_ik is
                allowed  to be selected (or present) when one or both of
                X_i and X_k  are selected, w is decomposed as 
		w= [wm p11 p10  p00] where:
                wm = hyperparameter Bernoulli prior for main effects; other
		hyperparameters Bernoulli prior are:
                p11 = prob(X_ik present|X_i and X_k present);
                p10 = prob(X_ik present|X_i present, X_k absent)   
		    = prob(X_ik present|X_i absent, X_k present);
                p00 = prob(X_ik present|X_i and X_k absent), p00 is taken 
		small (e.g. p00 = 0.00001);

v1,            	hyperparameter normal selection prior
		(column vector (p by 1) of standard deviations)
                (e.g. v1=c*sqrt(diag(pinv(X'*X))), with c a 'well chosen'
                constant, for example c=1, 0.1 or 10)


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_GSsPi:
---------------------------
gofg_sp, gibbs_sp, repliche, probord


Notes:
------
_ Data must be centered
_ In the matrix X, the columns variables must be ordered as   
  X_1,...,X_pm,X_1^2, X_1X_2, X_1X_3,...,X_1X_pm,X_2^2,X_2X_3,...,X_pm^2.
  The program `processing.m' generates the second-order terms in the
  correct order and centers the reponses and explanatory variables (see
  below). 
_ The programs checks if w has the correct number of components (3 or 4)
  and asks for the number of (independent) main effects, pm.
_ The programs asks also 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_sp(X,Y,Xf,Yf,PostGamD,GammaD,numero, v1)

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)

             
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_spi(gamprec, X,Y, delta,k, w, v1)
     [Gamma2, GammD2, logProb2, logProbD2, PostGamD2, MargGam2, SWITCH2]= ...
		bvsgs_spi(gamprec, X,Y, delta,k, w, v1)	)

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);  )

Do prediction using PostGamD and GammaD

                        **************************
                        PRE-PROCESSING OF THE DATA
                        **************************  
[Y,X,pm,combin]=processing(nbresp,YX)

Inputs:
-------
 nbresp,    number of response variables.
 YX,        matrix of raw data, with in the first `nbresp' columns the
            variables response Y and in the other columns the independent
predictors
            (main effects)

 
Outputs:
--------
 Y,        matrix of centered response variables;
 X,        matrix of regressors where the main effects have been
           centered; and the quadratic and 2-way interactions
           terms have been added.
 pm,       number of main effects;
 combin,   contains the link between index of the variables and the 
           corresponding main effect or interaction term.  


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