{smcl}
{* *! version 1.0.1  31jan2017}{...}
{cmd:help geo2xy_lambert_sphere}
{hline}

{title:Title}

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


{title:Map projection}

{phang}
Lambert conformal conic projection - Spherical 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 lambert_sphere}
[,{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(lambert_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: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:(lambert_sphere} {it:, lat1 lat2 lat0 lon0})


{title:Description}

{pstd}
The Lambert Conformal Conic Projection provides good directional and shape relationships
for mid-latitude regions having a mainly east-to-west extent.
It is widely used for general maps of Canada at small scales.

{pstd}
This projection transfers locations on a sphere to a
cone that intersects the sphere 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 closer together
between the standard parallels.
If the pole is in the same hemisphere as the standard
parallels, it is represented as a point and the other
pole is at infinity.

{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).


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

{pstd}
This projection assumes that the geographic latitude and longitude
describe locations on a sphere.
The computations are performed on a unit sphere (radius of 1)
and projected coordinates are returned without further scaling.
If you want the units to reflect distances on Earth, you need to
multiply the coordinates by an appropriate radius 
(e.g. 6371 km, 3958.76 miles, 20,902,231 feet, etc.).
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}
Google Maps uses a 
{it:{help geo2xy_web_mercator:Web Mercator}}
projection. It is not well suited for
maps that include features near the poles because it stretches vertical
dimensions to compensate for longitude lines that converge at the poles
(at the poles, the stretch is infinite). For example, a map of Canadian
boundaries appears significantly distorted:

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - canada_mercator}{...}
	use "geo2xy_Canada_coor.dta", clear
	
	geo2xy _Y _X , gen(ylat xlon)
	
	// 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(canada_mercator, replace)
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run canada_mercator using geo2xy_lambert_sphere.hlp, requires("geo2xy_Canada_coor.dta") preserve:click to run})}
{* example_start - canada_mercator_t}{...}
{* 	use "geo2xy_Canada_coor.dta", clear}{...}
{* 	}{...}
{* 	geo2xy _Y _X , gen(ylat xlon) 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(canada_mercator_t, replace)}{...}
{* example_end}{...}
{space 8}{it:({stata geo2xy_run canada_mercator_t using geo2xy_lambert_sphere.hlp, requires("geo2xy_Canada_coor.dta") preserve:click to run with Tissot's indicatrices})}

{pstd}
The following example implements Statistics Canada's recommendations
for small scale maps using standard parallels of 
49 and 77 degrees north and a central meridian of 91 degrees 52 minutes west.

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - canada_lambert}{...}
	use "geo2xy_Canada_coor.dta", clear
	
	geo2xy _Y _X , gen(ylat xlon) projection(lambert_sphere, 49 77 0 -91.866667)
	
	// 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(canada_lambert, replace)
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run canada_lambert using geo2xy_lambert_sphere.hlp, requires("geo2xy_Canada_coor.dta") preserve:click to run})}
{* example_start - canada_lambert_t}{...}
{* 	use "geo2xy_Canada_coor.dta", clear}{...}
{* 	}{...}
{* 	geo2xy _Y _X , gen(ylat xlon) projection(lambert_sphere, 49 77 0 -91.866667) 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(canada_lambert_t, replace)}{...}
{* example_end}{...}
{space 8}{it:({stata geo2xy_run canada_lambert_t using geo2xy_lambert_sphere.hlp, requires("geo2xy_Canada_coor.dta") preserve:click to run with Tissot's indicatrices})}


{title:Certification}

{pstd}
The equations for this projection are from pages 106-107 of Snyder (1987).
The numerical example at p. 295 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

	geo2xy _Y _X, gen(y x) proj(lambert_sphere, 33 45 23 -96)
	return list
	list
	
	assert string(x,"%10.7f") ==  "0.2966785"
	assert string(y,"%10.7f") ==  "0.2462112"
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run certify using geo2xy_lambert_sphere.hlp, preserve:click to run})}


{title:References}

{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}
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}
Statistics Canada, {it:Map projection}. Last modified November 30 2015. Accessed December 24 2016.
({browse "http://www.statcan.gc.ca/pub/92-195-x/2011001/other-autre/mapproj-projcarte/m-c-eng.htm":link})

{pstd}
Wikipedia, {it:Lambert conformal conic projection}. Accessed December 24 2016.
({browse "http://en.wikipedia.org/wiki/Lambert_conformal_conic_projection":link})


{title:Author}

{pstd}Michael Stepner{p_end}
{pstd}stepner@mit.edu{p_end}


{title:Acknowledgements}

{pstd}This projection is based on Robert Picard's code and documentation for the Albers Equal-Area Conic Projection - Spherical model.
It would not exist without Robert's work and helpful guidance.{p_end}