{smcl}
{* *! version 1.0.0  31jan2017}{...}
{cmd:help geo2xy_albers}
{hline}

{title:Title}

{phang}
{cmd:geo2xy} {hline 2} Convert latitude and longitude to cartesian (x,y) coordinates


{title:Map projection}

{phang}
Albers equal-area conic projection - ellipsoid model


{title:Syntax}

{p 8 16 2}
{cmd:geo2xy}
{it:lat_var lon_var} 
{ifin} 
{cmd:,}
{c -(}{opt gen:erate(y_lat x_lon)}{c |}{opt replace}{c )-}
[ 
{opt proj:ection}{cmd:(}{opt albers}
[,{help geo2xy##proj_name:proj_opts}]{cmd:)}
{opt ti:ssot} ]


{synoptset 40 tabbed}{...}
{synopthdr}
{synoptline}
{p2coldent :* {opt gen:erate(y_lat x_lon)}}New variable names for the projected coordinates (note the order!){p_end}
{p2coldent :* {opt replace}}Replace the values in {it:lat_var lon_var} with the projected coordinates{p_end}
{synopt :{opt proj:ection(albers_sphere [,proj_opts])}}Specifies the projection and, optionally, projection parameters{p_end}
{synopt :{opt ti:ssot}}Append Tissot's indicatrices (grid of circles){p_end}
{synoptline}
{pstd}* Either {opt gen:erate(y_lat x_lon)} or {opt replace} is required.
{p2colreset}


{synoptset 15 tabbed}{...}
{synopthdr :proj_opts}
{synoptline}
{synopt :{it:a}}semi-major axis of reference ellipsoid (default is 6378137){p_end}
{synopt :{it:f}}inverse flattening of reference ellipsoid (default is 298.257223563){p_end}
{synopt :{it:lat1}}1st standard parallel (default is minlat + (maxlat - minlat) / 6){p_end}
{synopt :{it:lat2}}2nd standard parallel (default is maxlat - (maxlat - minlat) / 6){p_end}
{synopt :{it:lat0}}projection's origin (default is 0){p_end}
{synopt :{it:lon0}}central meridian (default is mid-longitude){p_end}
{synoptline}
{p2colreset}

{pstd}
Projection parameters are optional. To specify some, 
all parameters must be specified and appear in the following order

{p 8 16 2}
{opt proj:ection}{hi:(albers} {it:, a f lat1 lat2 lat0 lon0})


{title:Description}

{pstd}
This projection transfers locations on the spheroid to a
cone that intersects the spheroid at the two standard parallels.
On the map, meridians are straight lines and equally spaced.
Parallels are arcs of circles with a common center point
located at the intersection of the meridian lines. 
A meridian intersects a parallel at a right angle.
Parallels are not equally spaced and are farther apart
between the standard parallels.
The poles are represented using an arc of a circle.

{pstd}
The algorithm to automatically select the first and second standard
parallels follows Deetz and Adams's (1934, p. 91) suggestion
(1/6 of meridional distance).

{pstd}
This is an equal area projection, which means that
the area of a shape on the map is proportional 
to the area of the shape on earth.
This projection is particularly appropriate 
when creating thematic maps. 


{title:Spheroid and (x,y) coordinates units}

{pstd}
This projection assumes that the geographic latitude and longitude
describe locations on an ellipsoid. If parameters are not
specified, {bf:geo2xy} uses the reference ellipsoid of the WGS 84 datum,
the same that is used in GPS devices.
The projected coordinates reflect distances in meters.
Distances are only accurate along the standard parallels.


{title:Examples}

{pstd}
These examples require {cmd:geo2xy}'s ancillary datasets
in the current directory. Click 
{stata `"net get geo2xy, from("http://fmwww.bc.edu/repec/bocode/g")"':here}
to download them.

{pstd}
{cmd: geo2xy} will automatically select appropriate values for the
first and second parallel and for the central meridian.
The algorithms work quite well for the conterminous United States.

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - albers_us}{...}
	use "geo2xy_us_coor.dta", clear
	drop if inlist(_ID, 14, 39, 42) // Alaska, Puerto Rico, Hawaii

	geo2xy _Y _X, gen(ylat xlon) projection(albers)
	
	// show the projection details and compute the plot's height
	return list
	local yheight = 6 * `r(aspect)'
	
	line ylat xlon, lwidth(vthin) lcolor(gray) cmissing(n) ///
		xsize(6) ysize(`yheight') ///
		ylabel(minmax, nogrid) yscale(off) ///
		xlabel(minmax, nogrid) xscale(off) ///
		plotregion(margin(small)) graphregion(margin(small)) ///
		legend(off) name(albers_us, replace)
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run albers_us using geo2xy_albers.hlp, requires("geo2xy_us_coor.dta") preserve:click to run})}
{* example_start - albers_us_t}{...}
{* 	use "geo2xy_us_coor.dta", clear}{...}
{* 	drop if inlist(_ID, 14, 39, 42) // Alaska, Puerto Rico, Hawaii}{...}
{* }{...}
{* 	geo2xy _Y _X, gen(ylat xlon) projection(albers) tissot}{...}
{* 	}{...}
{* 	// show the projection details and compute the plot's height}{...}
{* 	return list}{...}
{* 	local yheight = 6 * `r(aspect)'}{...}
{* 	}{...}
{* 	line ylat xlon if !mi(_ID), lwidth(vthin) lcolor(gray) cmissing(n) ///}{...}
{* 	||  ///}{...}
{* 	line ylat xlon if mi(_ID), lwidth(vthin) lcolor(eltblue) cmissing(n) ///}{...}
{* 		xsize(6) ysize(`yheight') ///}{...}
{* 		ylabel(minmax, nogrid) yscale(off) ///}{...}
{* 		xlabel(minmax, nogrid) xscale(off) ///}{...}
{* 		plotregion(margin(small)) graphregion(margin(small)) ///}{...}
{* 		legend(off) name(albers_us_t, replace)}{...}
{* example_end}{...}
{space 8}{it:({stata geo2xy_run albers_us_t using geo2xy_albers.hlp, requires("geo2xy_us_coor.dta") preserve:click to run with Tissot's indicatrices})}

{pstd}
Redo using standard parallels of 29.5 and 45.5.
These are the values used by the 
the {it:{browse "https://en.wikipedia.org/wiki/United_States_Geological_Survey":USGS}}.
Use the same central meridian that was computed in the example
above (mid-longitude is -95.837867).

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - albers_usgs}{...}
	use "geo2xy_us_coor.dta", clear
	drop if inlist(_ID, 14, 39, 42) // Alaska, Puerto Rico, Hawaii

	geo2xy _Y _X , gen(ylat xlon) proj(albers, 6378137 298.257223563 29.5 45.5 0 -95.837867)
	
	// show the projection details and compute the plot's height
	return list
	local yheight = 6 * `r(aspect)'
	
	line ylat xlon, lwidth(vthin) lcolor(gray) cmissing(n) ///
		xsize(6) ysize(`yheight') ///
		ylabel(minmax, nogrid) yscale(off) ///
		xlabel(minmax, nogrid) xscale(off) ///
		plotregion(margin(small)) graphregion(margin(small)) ///
		legend(off) name(albers_usgs, replace)
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run albers_usgs using geo2xy_albers.hlp, requires("geo2xy_us_coor.dta") preserve:click to run})}
{* example_start - albers_usgs_t}{...}
{* 	use "geo2xy_us_coor.dta", clear}{...}
{* 	drop if inlist(_ID, 14, 39, 42) // Alaska, Puerto Rico, Hawaii}{...}
{* }{...}
{* 	geo2xy _Y _X , gen(ylat xlon) proj(albers, 6378137 298.257223563 29.5 45.5 0 -95.837867) tissot}{...}
{* 	}{...}
{* 	// show the projection details and compute the plot's height}{...}
{* 	return list}{...}
{* 	local yheight = 6 * `r(aspect)'}{...}
{* 	}{...}
{* 	line ylat xlon if !mi(_ID), lwidth(vthin) lcolor(gray) cmissing(n) ///}{...}
{* 	||  ///}{...}
{* 	line ylat xlon if mi(_ID), lwidth(vthin) lcolor(eltblue) cmissing(n) ///}{...}
{* 		xsize(6) ysize(`yheight') ///}{...}
{* 		ylabel(minmax, nogrid) yscale(off) ///}{...}
{* 		xlabel(minmax, nogrid) xscale(off) ///}{...}
{* 		plotregion(margin(small)) graphregion(margin(small)) ///}{...}
{* 		legend(off) name(albers_usgs_t, replace)}{...}
{* example_end}{...}
{space 8}{it:({stata geo2xy_run albers_usgs_t using geo2xy_albers.hlp, requires("geo2xy_us_coor.dta") preserve:click to run with Tissot's indicatrices})}

{pstd}
The following example replicates the map of the world included
in the Wikipedia entry for the 
{it:{browse "https://en.wikipedia.org/wiki/Albers_projection":Albers projection}}.
The map was projected using standard parallels of 20 degrees north and 50 degrees north. 
The map does not include Antarctica.
For a more complete example that replicates the distorted map borders
and graticule (major latitude and longitude grid lines), see
{cmd:geo2xy}'s {help geo2xy_fun_with_maps##world_wiki:Fun with maps} help file.

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - albers_world}{...}
	use "geo2xy_world_coor.dta", clear
	drop if _ID == 7 // Antarctica
	
	geo2xy _Y _X , gen(ylat xlon) proj(albers, 6378137 298.257223563 20 50 0 0)
	
	// show the projection details and compute the plot's height
	return list
	local yheight = 6 * `r(aspect)'
	
	twoway area ylat xlon if !mi(_ID), lwidth(vthin) lcolor(gs12) ///
		color("20 70 40") cmissing(n) nodropbase ///
		xsize(6) ysize(`yheight') ///
		ylabel(minmax, nogrid) yscale(off) ///
		xlabel(minmax, nogrid) xscale(off) ///
		plotregion(margin(small)) graphregion(margin(small)) ///
		legend(off) name(albers_world, replace)
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run albers_world using geo2xy_albers.hlp, requires("geo2xy_world_coor.dta"):click to run})}


{title:Certification}

{pstd}
The equations for this projection are from pages 101-102 of Snyder (1987).
The numerical example at pp. 292-293 is used to certify {bf:geo2xy}'s
implementation:

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - certify}{...}
	clear
	input double(_Y _X)
	35 -75
	end
	
	// compute the inverse flattening from e = .0822719, see Snyder p. 13
	local f = 1 / (1 - (1-.0822719^2)^.5)

	geo2xy _Y _X, gen(y x) proj(albers, 6378206.4 `f' 29.5 45.5 23 -96)
	return list
	list
	
	assert string(x,"%10.1f") ==  "1885472.7"
	assert string(y,"%10.1f") ==  "1535925.0"
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run certify using geo2xy_albers.hlp, preserve:click to run})}


{title:References and further reading}

{pstd}
Deetz, Charles Henry, and Oscar Sherman Adams. 
{it:Elements of map projection with applications to map and chart construction. No. 68}. 
US Government Printing Office, 1921.

{pstd}
National Imagery and Mapping Agency,
{it}
Department of Defense World Geodetic System 1984 - 
Its Definition and Relationships with Local Geodetic Systems{sf},
NIMA Technical Report 8350.2, Third Edition, 2000.
[{it:{browse "http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf":download}}]

{pstd}
Snyder, John P., 
{it:Map projections: A working manual}.
U.S. Geological Survey Professional Paper 1395, 1987.
[{it:{browse "http://pubs.er.usgs.gov/publication/pp1395":download}}].

{pstd}
U.S. Department of the Interior; U.S. Geological Survey,
{it:{browse "https://egsc.usgs.gov/isb//pubs/MapProjections/projections.html#albers":Albers Equal Area Conic}}.
Web page, reviewed 1/31/2017.

{pstd}
Wikipedia, {it:{browse "https://en.wikipedia.org/wiki/Albers_projection":Albers projection}}.
Web page, reviewed 1/31/2017.


{title:Author}

{pstd}Robert Picard{p_end}
{pstd}picard@netbox.com{p_end}
