* tmap_label NJC 1.1.0 14 July 2004
*! -tmap_label-: Label 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_label
version 8.2




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

syntax varname [if] [in],        ///
		 Xcoord(varname numeric)   ///
		 Ycoord(varname numeric)   ///
		 Map(string)               ///
      [LColor(string)]           ///
      [LSize(real 1)]            ///
      [LLength(integer 12)]      ///
      [OColor(string)]           ///
      [OSize(string)]            ///
      [FColor(string)]




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

/* Marksample */
marksample touse, strok
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
}




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

/* Preserve data */
preserve

/* Set default label color */
if "`lcolor'" == "" local lcolor "black"

/* 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 `varlist' `xcoord' `ycoord'
cap rename `varlist' _label
cap rename `xcoord' _x
cap rename `ycoord' _y

/* Create label variable */
qui {
	local N = _N
	local TYPE : type _label
	local TYPE = substr("`TYPE'",1,3)
	if "`TYPE'" != "str" {
		local VALLBL : value label _label
		if "`VALLBL'" == "" {
			tostring _label, replace force usedisplayformat
		}
		else {
			rename _label TEMP
			decode TEMP, gen(_label)
		}
	}
	replace _label = substr(_label,1,`llength')
}




*  ----------------------------------------------------------------------------
*  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 LC "`lcolor'"
local LS = 0.9 * `lsize'
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 LABELS "mlabel(_label) mlabcol(`LC') mlabsize(*`LS') msymbol(i) mlabpos(0)"
local GRAPHS "`GRAPHS'(scatter _y _x, `LABELS') "

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