* tmap_deviation NJC 1.1.0 14 July 2004 
*! -tmap_deviation-: Deviation maps                                            
*! Version 1.2 - 23 July 2004                                                  
*! Version 1.0 - 24 January 2004                                               
*! Author: Maurizio Pisati                                                     
*! Department of Sociology and Social Research                                 
*! University of Milano Bicocca (Italy)                                        
*! maurizio.pisati@unimib.it                                                   




*  ----------------------------------------------------------------------------
*  1. Define program                                                           
*  ----------------------------------------------------------------------------

program tmap_deviation
version 8.2




*  ----------------------------------------------------------------------------
*  2. Define syntax                                                            
*  ----------------------------------------------------------------------------

syntax varname(numeric) [if] [in],   ///
       Xcoord(varname numeric)       ///
		 Ycoord(varname numeric)       ///
		 Map(string)                   ///
		[Center(string)]               ///
      [SColor(string)]               ///
      [SSIze(real 1)]                ///
      [SSHape(string)]               ///
      [OColor(string)]               ///
      [OSize(string)]                ///
      [FColor(string)]


/*
Center(mean | median)
*/




*  ----------------------------------------------------------------------------
*  3. Check syntax                                                             
*  ----------------------------------------------------------------------------

/* Marksample */
marksample touse
markout `touse' `xcoord' `ycoord' 
qui count if `touse' 
if r(N) == 0 error 2000 

/* Check option map() */
capture confirm file `"`map'"'
if _rc {
	di as err "{p}file `map' specified in option {bf:{ul:m}ap()} does not exist{p_end}"
	exit 498 
}
	
/* Check option center() */
if "`center'" != "" {
	local LIST "mean median"
	local EXIST : list posof `"`center'"' in LIST
	if !`EXIST' {
		di as err "{p}option {bf:{ul:c}enter()} accepts only one of the following keywords: {bf:mean median}{p_end}"
		exit 198 
	}
}

/* Check option sshape() */
if "`sshape'"!="" {
	local LIST "O D T S o d t s"
	local EXIST : list posof `"`sshape'"' in LIST
	if !`EXIST' {
		di as err "{p}option {bf:{ul:ssh}ape()} accepts only solid symbol styles{p_end}"
		exit 198 
	}
}




*  ----------------------------------------------------------------------------
*  4. Define basic objects                                                     
*  ----------------------------------------------------------------------------

/* Preserve data */
preserve
	
/* Keep only relevant cases */
qui keep if `touse' 
	
/* Set default reference value */
if "`center'" == "" local center "mean"
else if "`center'" == "median" local center "p50"

/* Set default symbol color */
if "`scolor'" == "" local scolor "black"

/* Set symbol size */
tempvar SIGN
qui { 
	su `varlist', detail
	replace `varlist' = `varlist' - r(`center')
	gen `SIGN' = 1 + (`varlist' >= 0) 
	replace `varlist' = abs(`varlist')
	su `varlist', meanonly
	replace `varlist' = ((`varlist' - r(min)) / r(max)) + (r(max) - r(min)) / 100
} 	

/* Set default symbol shape */
if "`sshape'" == "" local sshape "O"

/* Set default outline color */
if "`ocolor'" == "" local ocolor "black"

/* Set default outline thickness */
if "`osize'" == "" local osize "thin"

/* Set default fill color */
if "`fcolor'" == "" local fcolor "white"

/* Keep only relevant variables */
keep `varlist' `xcoord' `ycoord' `SIGN'
cap rename `varlist' _attribute
cap rename `xcoord' _x
cap rename `ycoord' _y




*  ----------------------------------------------------------------------------
*  5. Draw map                                                                 
*  ----------------------------------------------------------------------------

/* Calculate plot region */
qui { 
	merge using `"`map'"'
	tempvar ID
	egen `ID'=group(_ID) 
	tab `ID'
	local NPOLY = r(r)
	su _Y, meanonly 
	local ymin = r(min)
	local ymax = r(max)
	su _X, meanonly 
	local xmin = r(min)
	local xmax = r(max)
	local JY = (`ymax' - `ymin') * 0.03
	local JX = (`xmax'-`xmin') * 0.03
	local ymin = `ymin' - `JY'
	local ymax = `ymax' + `JY'
	local xmin = `xmin' - `JX'
	local xmax = `xmax' + `JX'
	local RATIO = (`ymax' - `ymin') / (`xmax'-`xmin')
	local YS = 4
	local XS = 4 / `RATIO'
} 

/* Draw map */
local GRAPHS ""
local OC "`ocolor'"
local OS "`osize'"
local FC "`fcolor'"
if "`OC'" == "none" local OC "`FC'"
forval i = 1/`NPOLY' {
	local GRAPHS "`GRAPHS'(area _Y _X if `ID'==`i', nodropbase blc("`OC'") blw(`OS') bfc("`FC'")) "
}
local GRAPHS "`GRAPHS'(scatter _y _x [fw=_attribute] if `SIGN'==2, "
local GRAPHS "`GRAPHS'ms(`sshape') mc(`scolor') msize(*`ssize')) "
local GRAPHS "`GRAPHS'(scatter _y _x [fw=_attribute] if `SIGN'==1, "
local GRAPHS "`GRAPHS'ms(`sshape'h) mc(`scolor') msize(*`ssize')) "

cap graph twoway `GRAPHS', ysize(`YS') xsize(`XS')                       ///
          yscale(r(`ymin' `ymax') off) xscale(r(`xmin' `xmax') off)      ///
          ylabel(`ymin' `ymax') xlabel(`xmin' `xmax')                    ///
	       ytitle("") xtitle("")                                          ///
	       plotregion(style(none)) scheme(s1mono) legend(off) `options' 

if _rc {
	di as err "{p}invalid syntax{p_end}"
	exit _rc
}




*  ----------------------------------------------------------------------------
*  6. End program                                                              
*  ----------------------------------------------------------------------------

restore
end