Merge branch 'release/v0.70beta2'

map_shapefiles/county1990_maptile.ado

@@ -1,11 +1,11 @@
-*! 31jan2014, Michael Stepner, michaelstepner@gmail.com
+*! 6feb2014, Michael Stepner, michaelstepner@gmail.com
 
 program define _maptile_county1990
 	syntax , [  geofolder(string) ///
 				mergedatabase ///
 				map var(varname) legopt(string) min(string) clbreaks(string) max(string) mapcolors(string) ndfcolor(string) ///
 					savegraph(string) replace resolution(string) map_restriction(string) spopt(string) ///
-					stateoutline ///
+					stateoutline(string) ///
 			 ]
 
 	if ("`mergedatabase'"!="") {
@@ -17,7 +17,7 @@ program define _maptile_county1990
 
 		if ("`stateoutline'"!="") {
 			cap confirm file `"`geofolder'/state_coords_clean.dta"'
-			if (_rc==0) local polygon polygon(data(`"`geofolder'/state_coords_clean"') ocolor(black) osize(thin ...))
+			if (_rc==0) local polygon polygon(data(`"`geofolder'/state_coords_clean"') ocolor(black) osize(`stateoutline' ...))
 			else if (_rc==601) {
 				di as error `"stateoutline option requires 'state_coords_clean.dta' in the geofolder"'
 				exit 198				

map_shapefiles/county1990_maptile.smcl

@@ -0,0 +1,34 @@
+{smcl}
+
+{pstd}
+{hi:maptile {hline 2} Geography: county1990}
+
+
+{marker description}{...}
+{title:Description}
+
+{pstd}
+{hi:county1990} generates a map of United States counties using 1990 boundaries.
+
+{pstd}It displays Alaska and Hawaii rescaled and moved to the bottom left of the map, below the continental US, for ease of viewing.
+
+
+{marker idvar}{...}
+{title:Geographic ID variable}
+
+{pstd}
+{hi:county} {hline 2} FIPS county codes
+
+
+{marker geooptions}{...}
+{title:Geography-Specific Options}
+
+{synoptset 32 tabbed}{...}
+{synopt :{opth stateoutline(linewidthstyle)}}overlays the map with a (potentially thicker) line on state boundaries{p_end}
+
+
+{marker author}{...}
+{title:Author}
+
+{pstd}Michael Stepner{p_end}
+{pstd}stepner@mit.edu{p_end}

map_shapefiles/cz_maptile.ado

@@ -1,11 +1,11 @@
-*! 31jan2014, Michael Stepner, michaelstepner@gmail.com
+*! 6feb2014, Michael Stepner, michaelstepner@gmail.com
 
 program define _maptile_cz
 	syntax , [  geofolder(string) ///
 				mergedatabase ///
 				map var(varname) legopt(string) min(string) clbreaks(string) max(string) mapcolors(string) ndfcolor(string) ///
 					savegraph(string) replace resolution(string) map_restriction(string) spopt(string) ///
-					stateoutline ///
+					stateoutline(string) ///
 			 ]
 
 	if ("`mergedatabase'"!="") {
@@ -17,7 +17,7 @@ program define _maptile_cz
 
 		if ("`stateoutline'"!="") {
 			cap confirm file `"`geofolder'/state_coords_clean.dta"'
-			if (_rc==0) local polygon polygon(data(`"`geofolder'/state_coords_clean"') ocolor(black) osize(thin ...))
+			if (_rc==0) local polygon polygon(data(`"`geofolder'/state_coords_clean"') ocolor(black) osize(`stateoutline' ...))
 			else if (_rc==601) {
 				di as error `"stateoutline option requires 'state_coords_clean.dta' in the geofolder"'
 				exit 198				

map_shapefiles/cz_maptile.smcl

@@ -0,0 +1,34 @@
+{smcl}
+
+{pstd}
+{hi:maptile {hline 2} Geography: cz}
+
+
+{marker description}{...}
+{title:Description}
+
+{pstd}
+{hi:cz} generates a map of United States 1990 Commuting Zones.
+
+{pstd}It displays Alaska and Hawaii rescaled and moved to the bottom left of the map, below the continental US, for ease of viewing.
+
+
+{marker idvar}{...}
+{title:Geographic ID variable}
+
+{pstd}
+{hi:cz} {hline 2} 1990 Commuting Zone codes
+
+
+{marker geooptions}{...}
+{title:Geography-Specific Options}
+
+{synoptset 32 tabbed}{...}
+{synopt :{opth stateoutline(linewidthstyle)}}overlays the map with a (potentially thicker) line on state boundaries{p_end}
+
+
+{marker author}{...}
+{title:Author}
+
+{pstd}Michael Stepner{p_end}
+{pstd}stepner@mit.edu{p_end}

map_shapefiles/state_maptile.ado

@@ -1,4 +1,4 @@
-*! 31jan2014, Michael Stepner, michaelstepner@gmail.com
+*! 6feb2014, Michael Stepner, michaelstepner@gmail.com
 
 program define _maptile_state
 	syntax , [  geofolder(string) ///

map_shapefiles/state_maptile.smcl

@@ -0,0 +1,36 @@
+{smcl}
+
+{pstd}
+{hi:maptile {hline 2} Geography: state}
+
+
+{marker description}{...}
+{title:Description}
+
+{pstd}
+{hi:state} generates a map of U.S. states.
+
+{pstd}It displays Alaska and Hawaii rescaled and moved to the bottom left of the map, below the continental US, for ease of viewing.
+
+
+{marker idvar}{...}
+{title:Geographic ID variables}
+
+{synoptset 12 tabbed}{...}
+{synopt :{hi:state}} 2-letter state abbreviations{p_end}
+{synopt :{hi:statefips}} 2-digit state FIPS codes{p_end}
+{synopt :{hi:statename}} unabbreviated state names{p_end}
+
+
+{marker geooptions}{...}
+{title:Geography-Specific Options}
+
+{synoptset 22 tabbed}{...}
+{synopt :{opth geoid(varname)}}specifies the geographic ID variable to use; default is {hi:geoid(state)}{p_end}
+
+
+{marker author}{...}
+{title:Author}
+
+{pstd}Michael Stepner{p_end}
+{pstd}stepner@mit.edu{p_end}

map_shapefiles/zip3_maptile.ado

@@ -1,11 +1,11 @@
-*! 31jan2014, Michael Stepner, michaelstepner@gmail.com
+*! 6feb2014, Michael Stepner, michaelstepner@gmail.com
 
 program define _maptile_zip3
 	syntax , [  geofolder(string) ///
 				mergedatabase ///
 				map var(varname) legopt(string) min(string) clbreaks(string) max(string) mapcolors(string) ndfcolor(string) ///
 					savegraph(string) replace resolution(string) map_restriction(string) spopt(string) ///
-					stateoutline ///
+					stateoutline(string) ///
 			 ]
 
 	if ("`mergedatabase'"!="") {
@@ -17,7 +17,7 @@ program define _maptile_zip3
 
 		if ("`stateoutline'"!="") {
 			cap confirm file `"`geofolder'/state_coords_clean.dta"'
-			if (_rc==0) local polygon polygon(data(`"`geofolder'/state_coords_clean"') ocolor(black) osize(thin ...))
+			if (_rc==0) local polygon polygon(data(`"`geofolder'/state_coords_clean"') ocolor(black) osize(`stateoutline' ...))
 			else if (_rc==601) {
 				di as error `"stateoutline option requires 'state_coords_clean.dta' in the geofolder"'
 				exit 198				

map_shapefiles/zip3_maptile.smcl

@@ -0,0 +1,36 @@
+{smcl}
+
+{pstd}
+{hi:maptile {hline 2} Geography: zip3}
+
+
+{marker description}{...}
+{title:Description}
+
+{pstd}
+{hi:zip3} generates a map of United States 3-digit ZIP Code Tabulation Areas (ZCTAs), using the Census 2000 definition.
+
+{pstd}It displays Alaska and Hawaii rescaled and moved to the bottom left of the map, below the continental US, for ease of viewing.
+
+{pstd}
+For information on how ZCTAs are different from ZIP codes, see the U.S. Census Bureau's {browse "http://www.census.gov/geo/reference/zctas.html":information page} and {browse "http://www.census.gov/geo/reference/zctafaq.html":FAQ}.
+
+{marker idvar}{...}
+{title:Geographic ID variable}
+
+{pstd}
+{hi:zip3} {hline 2} the first 3-digits of a ZIP code
+
+
+{marker geooptions}{...}
+{title:Geography-Specific Options}
+
+{synoptset 32 tabbed}{...}
+{synopt :{opth stateoutline(linewidthstyle)}}overlays the map with a (potentially thicker) line on state boundaries{p_end}
+
+
+{marker author}{...}
+{title:Author}
+
+{pstd}Michael Stepner{p_end}
+{pstd}stepner@mit.edu{p_end}

map_shapefiles/zip5_maptile.ado

@@ -1,11 +1,11 @@
-*! 31jan2014, Michael Stepner, michaelstepner@gmail.com
+*! 6feb2014, Michael Stepner, michaelstepner@gmail.com
 
 program define _maptile_zip5
 	syntax , [  geofolder(string) ///
 				mergedatabase ///
 				map var(varname) legopt(string) min(string) clbreaks(string) max(string) mapcolors(string) ndfcolor(string) ///
 					savegraph(string) replace resolution(string) map_restriction(string) spopt(string) ///
-					stateoutline ///
+					stateoutline(string) ///
 			 ]
 
 	if ("`mergedatabase'"!="") {
@@ -17,7 +17,7 @@ program define _maptile_zip5
 
 		if ("`stateoutline'"!="") {
 			cap confirm file `"`geofolder'/state_coords_clean.dta"'
-			if (_rc==0) local polygon polygon(data(`"`geofolder'/state_coords_clean"') ocolor(black) osize(thin ...))
+			if (_rc==0) local polygon polygon(data(`"`geofolder'/state_coords_clean"') ocolor(black) osize(`stateoutline' ...))
 			else if (_rc==601) {
 				di as error `"stateoutline option requires 'state_coords_clean.dta' in the geofolder"'
 				exit 198				

map_shapefiles/zip5_maptile.smcl

@@ -0,0 +1,36 @@
+{smcl}
+
+{pstd}
+{hi:maptile {hline 2} Geography: zip5}
+
+
+{marker description}{...}
+{title:Description}
+
+{pstd}
+{hi:zip5} generates a map of United States 5-digit ZIP Code Tabulation Areas (ZCTAs), using the Census 2000 definition.
+
+{pstd}It displays Alaska and Hawaii rescaled and moved to the bottom left of the map, below the continental US, for ease of viewing.
+
+{pstd}
+For information on how ZCTAs are different from ZIP codes, see the U.S. Census Bureau's {browse "http://www.census.gov/geo/reference/zctas.html":information page} and {browse "http://www.census.gov/geo/reference/zctafaq.html":FAQ}.
+
+{marker idvar}{...}
+{title:Geographic ID variable}
+
+{pstd}
+{hi:zip5} {hline 2} 5-digit ZIP code
+
+
+{marker geooptions}{...}
+{title:Geography-Specific Options}
+
+{synoptset 32 tabbed}{...}
+{synopt :{opth stateoutline(linewidthstyle)}}overlays the map with a (potentially thicker) line on state boundaries{p_end}
+
+
+{marker author}{...}
+{title:Author}
+
+{pstd}Michael Stepner{p_end}
+{pstd}stepner@mit.edu{p_end}

maptile.ado

@@ -1,4 +1,4 @@
-*! version 0.70beta1  3feb2014  Michael Stepner, stepner@mit.edu
+*! version 0.70beta2  6feb2014  Michael Stepner, stepner@mit.edu
 
 /*** Unlicence (abridged):
 This is free and unencumbered software released into the public domain.
@@ -9,7 +9,7 @@ For the full legal text of the Unlicense, see <http://unlicense.org>
 
 * Why did I include a formal license? Jeff Atwood gives good reasons:
 *  http://www.codinghorror.com/blog/2007/04/pick-a-license-any-license.html
-
+
 
 program define maptile, rclass
 	version 11

maptile.sthlp

@@ -1,5 +1,5 @@
 {smcl}
-{* *! version 0.70beta1  3feb2014}{...}
+{* *! version 0.70beta2  6feb2014}{...}
 {vieweralsosee "spmap" "help spmap"}{...}
 {viewerjumpto "Syntax" "maptile##syntax"}{...}
 {viewerjumpto "Description" "maptile##description"}{...}
@@ -26,6 +26,13 @@
 {varname} {ifin}{cmd:,}
  {cmdab:geo:graphy(}{it:{help maptile##usegeo:geoname}}{cmd:)} [{it:options}]
 
+
+{pstd} Helper programs:
+{bf:{help maptile##cmd_install:maptile_install}},
+{bf:{help maptile##cmd_geolist:maptile_geolist}},
+{bf:{help maptile##cmd_geohelp:maptile_geohelp}}
+
+
 {synoptset 35 tabbed}{...}
 {synopthdr :options}
 {synoptline}
@@ -88,6 +95,7 @@ Additionally, the geography templates can be easily shared and used by others.
 {pstd}
 {cmd:maptile} geography templates are distributed as .ZIP files.  Many are available {browse "http://michaelstepner.com/maptile/geographies":from maptile's website}.
 
+{marker cmd_install}{...}
 {pstd}
 1) To install a new geography template automatically, use:
 
@@ -112,23 +120,29 @@ Then direct {cmd:maptile} to look in that folder using the {opt geofolder(folder
 
 {pstd}1) Specify the geography name ({it:geoname})
 
-{p 9 9 2}Each time you run {cmd:maptile} you need to specify the name of a geography template to use with the option {opt geo:graphy(geoname)}. To list the names of currently installed geographies, use:
+{p 9 9 2}Each time you run {cmd:maptile} you need to specify the name of a geography template to use with the option {opt geo:graphy(geoname)}.
+
+{marker cmd_geolist}{...}
+{p 9 9 2}To list the names of currently installed geographies, use:
 
 {p 15 22 2}
-{cmd:maptile_geolist} [{it:folder_name}]
+{cmd:maptile_geolist} [, {opt geofolder(folder_name)}]
 
-{p 9 9 2}By default, {cmd:maptile_geolist} will list geographies in the {bf:{help sysdir:PERSONAL}}/maptile_geographies folder, which is where {cmd:maptile} loads geographies from automatically.
+{p 9 9 2}Running {cmd:maptile_geolist} without any options will list geographies in the {bf:{help sysdir:PERSONAL}}/maptile_geographies folder, which is where {cmd:maptile} loads geographies from automatically.
 
 
+{marker geoid}{...}
 {pstd}2) Ensure your dataset contains the correct geographic ID variable
 
 {p 9 9 2}Your dataset must contain a geographic identifier variable, which associates each observation with an area on the map.
 
-{p 9 9 2}Each geography will expect a specific geographic ID variable. For example, the geography for U.S. states might require a variable named "state" containing 2-letter state abbreviations.
+{p 9 9 2}Each geography will expect a specific geographic ID variable. For example, the geography for U.S. states might require a variable named "state" containing 2-letter state abbreviations. The required geographic ID variable will be indicated in the geography's help file.
+
+{marker cmd_geohelp}{...}
+{p 9 9 2} To see a geography's help file, use:
 
-{p 9 9 2}The required geographic ID variable should be indicated by the website or documentation from which you acquired the geography.
-For instance, the {browse "http://michaelstepner.com/maptile/geographies":database of geographies on maptile's website}
-contains ID variable name and required contents for each geography listed.
+{p 15 22 2}
+{cmd:maptile_geohelp} {it:geoname} [, {opt geofolder(folder_name)}]
 
 
 {marker geo_options}{...}
@@ -137,9 +151,9 @@ contains ID variable name and required contents for each geography listed.
 {p 9 9 2}Some geographies provide additional options which you can add to the {cmd:maptile} command.
 
 {p 9 9 2}For example, a geography may provide an option that lets the user specify the coding format of the geographic ID variable (ex: US state 2-letter abbreviations or 2-digit FIPS codes).
-As a second example, some geographies of the United States allow a {opt stateoutline} option, which overlays the map with a heavier line on state borders.
+As a second example, some geographies of the United States provide an option to place a heavier line on state borders.
 
-{p 9 9 2}These additional options should be detailed by the website or documentation from which you acquired the geography.
+{p 9 9 2}These additional options will be detailed in the {help maptile##cmd_geohelp:geography's help file}.
 
 
 {marker makegeo}{...}