* tmap_dot NJC 1.1.0 14 July 2004 
*! -tmap_dot-: Dot 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_dot
version 8.2




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

syntax [if] [in], Xcoord(varname numeric)     ///
			         Ycoord(varname numeric)     ///
			         Map(string)                 ///
			        [BY(varname)]                ///
			        [MARker(string)]             ///
                 [SColor(string)]             ///
                 [SSIze(real 1)]              ///
                 [SSHape(string)]             ///
                 [OColor(string)]             ///
                 [OSize(string)]              ///
                 [FColor(string)]             ///
                 [LEGPos(integer 7)]          ///
                 [LEGTitle(string)]           ///
                 [LEGBox]                     ///
                 [noLEGend]


/*
MARker(color | shape)
*/




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

/* Marksample */
marksample touse
markout `touse' `xcoord' `ycoord' 
if "`by'" != "" { 
	markout `touse' `by', strok 
} 	
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 
}




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

/* Preserve data */
preserve

/* Set default marker */
if "`marker'" == "" local marker "color"

/* Set default symbol shape list and single color */
if "`marker'" == "shape" {
 	if "`sshape'" == "" local SSLIST "o oh s sh t th d dh x"
	else local SSLIST "`sshape'"
	if "`scolor'" == "" local COL "black"
	else local COL : word 1 of `scolor'
}

/* Set default symbol color list and single shape */
if "`marker'" == "color" {
	if "`scolor'" == "" local SCLIST "black red blue green orange ltblue lime sienna yellow"
	else local SCLIST "`scolor'"
	if "`sshape'" == "" local SHP "o"
	else local SHP : word 1 of `sshape'
}


/* 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 cases */
qui keep if `touse'
	
/* Keep only relevant variables */
keep `xcoord' `ycoord' `by'
cap rename `xcoord' _x
cap rename `ycoord' _y
if "`by'" == ""  { 
	gen _class = 1
	local NC=1
}
else { 
	egen _class = group(`by'), label lname(_class)
	qui tab _class
	local NC=r(r)
	qui drop `by'
}
qui drop if missing(_class)




*  ----------------------------------------------------------------------------
*  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'
} 

/* Make up legend */
if `NC' == 1 | "`legend'" != "" local LEGEND "legend(off)"

if `NC' > 1 & "`legend'" == "" {
	forval i = 1/`NC' {
		local X = `i' + `NPOLY'
		local KEYS "`KEYS'`X' "
	}
		
	forval i = 1/`NC' {
		local LBL : label (_class) `i'
		local RANGE `"`RANGE'"`LBL'" "'	
	}

	forval i = 1/`NC' {
		local K = `i' + `NPOLY'
		local R : word `i' of `RANGE'
		local LABEL `"`LABEL'lab(`K' "`R'") "'
	}

	local BOX = cond("`legbox'" == "", "none", "0 0 0") 

	if "`legtitle'" != "" local TITLE `"subtitle("`legtitle'", size(*0.5))"'

	local LEGEND `"legend( cols(1) order(`KEYS') `LABEL' size(*0.5)"'
	local LEGEND `"`LEGEND' region(lc("`BOX'") fc(none)) `TITLE'"'
	local LEGEND `"`LEGEND' symy(1.7) symx(3) keygap(1) rowgap(0.5) forces"'
	local LEGEND `"`LEGEND' ring(0) position(`legpos') )"'
}

/* Draw map */
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'")) "
}
forval i = 1/`NC' {
	if "`marker'" == "shape" {
		local SHP : word `i' of `SSLIST'
	}
	else local COL : word `i' of `SCLIST'
	local GRAPHS "`GRAPHS'(scatter _y _x if _class == `i', "
	local GRAPHS "`GRAPHS'ms(`SHP') mc(`COL') msize(*`ssize') mlw(thin)) "
}

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' `options' 

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




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

restore
end