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

{title:Title}

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


{title:Map projection}

{phang}
Equidistant cylindrical 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 geo2xy_equidistant_cylindrical}
[,{help geo2xy##proj_name:proj_opts}]{cmd:)}
{opt ti:ssot} ]


{synoptset 50 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(equidistant_cylindrical [,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}}standard parallel (default is mid-latitude){p_end}
{synopt :{it:lon0}}projection's origin (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:(equidistant_cylindrical} {it:, lat1 lon0})


{title:Description}

{pstd}
This is a very simple projection where latitudes are
converted to radians (all vertical distances on the map
are equal to the distance on a unit sphere) and longitudes are scaled such that the
horizontal distance is accurate at the standard parallel ({it:lat1}).
By default, this is mid-latitude in terms of all the points
on the map. 

{pstd}
If the map represents an area in the northern hemisphere,
horizontal distances are exaggerated above the standard parallel
and compressed below the standard parallel. The inverse is true
for maps in the southern hemisphere.


{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.).
Vertical distances are accurate along longitude lines. 
Horizontal distances are only accurate along the standard
parallel.


{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}
This projection works well if the map area is not too large or near the poles.
Note that the {opt tissot} polygons generated by {cmd:geo2xy} do not have a feature
identifier (e.g. {cmd:_ID} is missing).

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - equidistant_cylindrical_us}{...}
	use "geo2xy_us_coor.dta", clear
	keep if _ID == 11  // the state of Michigan
	
	geo2xy _Y _X, gen(ylat xlon) project(equidistant_cylindrical) 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(equidistant_cylindrical_us, replace)
			
	summarize
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run equidistant_cylindrical_us using geo2xy_equidistant_cylindrical.hlp, requires("geo2xy_us_coor.dta") preserve:click to run})}

{pstd}
This is not the best choice for representing the state of Alaska (note
that the longitudes must be flipped because the state spans the
international date line):

{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - equidistant_cylindrical_ak}{...}
	use "geo2xy_us_coor.dta", clear
	keep if _ID == 14 // the state of Alaska
	
	gen double _XX = cond(_X > 0, _X - 180, _X + 180)

	geo2xy _Y _XX , gen(ylat xlon) proj(equidistant_cylindrical) 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(equidistant_cylindrical_ak, replace)
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run equidistant_cylindrical_ak using geo2xy_equidistant_cylindrical.hlp, requires("geo2xy_us_coor.dta") preserve:click to run})}


{title:Certification}

{pstd}
The equations for this projection are from pages 90-91 of Snyder (1987).

{pstd}
As Snyder puts it on p. 91: 
"Numerical examples are omitted in the appendix, due to 
simplicity".

{pstd}
Nevertheless, here's an example that double-checks
{cmd:geo2xy} computations.
The standard parallel is set to
the mid-latitude, in this case 40 degrees.


{space 8}{hline 27} {it:example do-file content} {hline 27}
{cmd}{...}
{* example_start - certify}{...}
	clear
	input double(_Y _X)
	35 -75
	45  75
	end
	
	geo2xy _Y _X, gen(y x) proj(equidistant_cylindrical)
	return list
	
	// short-cut to convert decimal degrees to radians
	local d2r _pi / 180
	
	gen double x2 = _X * `d2r' * cos(40 * `d2r')
	gen double y2 = _Y * `d2r'
	list
	
	assert x ==  x2
	assert y ==  y2
{* example_end}{...}
{txt}{...}
{space 8}{hline 80}
{space 8}{it:({stata geo2xy_run certify using geo2xy_equidistant_cylindrical.hlp, preserve:click to run})}


{title:References and further reading}

{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}
Wikipedia, {it:{browse "http://en.wikipedia.org/wiki/Equirectangular_projection":Equirectangular projection}}.
Web page, reviewed 1/31/2017.


{title:Author}

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