rug.ado

/*

 ## Create a rug plot
_____________________
CreatedBy:	Steve Harris

CreatedAt: 	111291
ModifiedAt:	120701

Log
---
131122	- modify rug plot so that it is copes with massive data sets

Filename:	rug.ado
Project:

## Description

Make a rug plot to add to histograms etc

## Dependencies

- takes a single variable and produces a rug plot
- options
	- levels specifies the number of shades used to represent the density
		- 16 means no shading
	- transform(log) adjusts the freqency scale for the shading by log
	- zero specifies the y height of the rug
	- axis specifes against which axis to draw this

____

*/

cap program drop rug
program rug , rclass
	di as result "Preparing rug plot ..."
	syntax varlist(min=1) [if/] , [levels(integer 16)] ///
	[transform(name)] [zero(real 0)] [GRANularity(real 1000)] ///
	[noshade] [axis(integer 1)] [clock(integer 0)] 

	args rugvar
	// if command is written rug myvar, options then "myvar," is variable!!
	if substr("`rugvar'",-1,1) == "," {
		local rugvar = subinstr("`rugvar'",",","",.)
	}

	di "`if'"
	tempvar   rugcount
	cap drop `rugsave'
	cap drop rugzero

	cap drop ruglabel
	cap drop `rugvar'_rug
	cap drop `rugvar'_pickone
	cap drop `rugvar'_cat

	gen `rugvar'_rug=`rugvar'
	su `rugvar'_rug,d
	local roundto=3/`granularity'
	replace `rugvar'_rug=round((`rugvar'_rug-r(mean))/r(sd),0.003)
	gen rugzero=`zero'

	if "`if'"=="" local my_touse "!missing(`rugvar'_rug)"
	if "`if'"!="" local my_touse "(`if') & !missing(`rugvar'_rug)"

	cap gen ruglabel="|" if `my_touse'
	egen `rugvar'_pickone= tag(`rugvar'_rug) if `my_touse'

	if "`noshade'"=="shade" | `levels'!=16 | ///
		`granularity'!=1000 | "`transfrom'"!="" {
		di as result "*** Producing shaded rug plot ***"



		duplicates report `rugvar'_rug if `my_touse'
		duplicates tag `rugvar'_rug if `my_touse', gen(`rugcount')

		if "`transform'"=="log" ///
			replace `rugcount'=log(`rugcount') if `my_touse'

		local maxlevels `levels'
		local llevel0 0
		su `rugcount' if `my_touse',d
		local dup_range=r(max)-r(min)
		local dup_step=round(`dup_range'/`maxlevels',1)
		gen `rugvar'_cat=.
		local iimax=`maxlevels'+1

		forvalues ii=`llevel0'(1)`iimax' {
			replace `rugvar'_cat=`ii' /// 
			if `rugvar'_cat==. & `rugcount'<=(`ii' * `dup_step') & `my_touse'
		}


		*egen `rugcat'=cut(`rugcount'), group(`maxlevels')
		levelsof `rugvar'_cat, local(llevels)
		*local llevels: list llevels - llevel0

		tabstat `rugvar' if `my_touse', ///
			by(`rugvar'_cat) s(n min mean max) col(stat)
		tab `rugvar'_cat if `my_touse'
		local ssteps=floor(`maxlevels'/`r(r)')
		local rrug
		local ssize: list sizeof llevels

		foreach llevel of local llevels {
			local pposition: list posof "`llevel'" in llevels
			local rposition = `ssize'-`pposition'+1
			local iintensity=1-(0.7*((`rposition')/`maxlevels'))
			local rrug "`rrug' (scatter rugzero `rugvar'" 
			local rrug "`rrug' if `rugvar'_pickone &"
			local rrug "`rrug' `rugvar'_cat==`llevel' & `my_touse',"
			local rrug "`rrug' xaxis(`axis') msymbol(none) mlab(ruglabel)"
			local rrug "`rrug' mlabcolor(*`iintensity')"
			local rrug "`rrug' mlabposition(`clock') )"

		}

	}
	else {
		local rrug "`rrug' (scatter rugzero `rugvar'"
		local rrug "`rrug' if `rugvar'_pickone & `my_touse', xaxis(`axis')"
		local rrug "`rrug' msymbol(none) mlab(ruglabel) mlabcolor(*1)"
		local rrug "`rrug' mlabposition(`clock'))"
	}

	di as text "Twoway command (colour coded) stored as r(rugcommand): " ///
		 as result "`rrug'"
	di as text "*** Stored in global rugcommand for now ***"

	return local rugcommand = "`rrug'"
	global rugcommand  "`rrug'"


end