-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsphdist.hlp
132 lines (101 loc) · 5.67 KB
/
sphdist.hlp
1
.-Help for ^sphdist^ Bill Rising.-Computes distances on a sphere (Earth as default)------------------------------------------------- ^sphdist^ [^if^ exp] [^in^ range]^, gen(^newvar^)^ ^lat1(^varlist^)^ ^lon1(^varlist^)^ ^lat2(^varlist^)^ ^lon2(^varlist^)^ [^ew1(^varname^)^ ^sn1(^varname^)^ ^ew2(^varname^)^ ^sn2(^varname^)^ ^radians^ ^radius(^number^)^ ^units(^{^km^ | ^mi^ | ^naut^}) ^thin^]Description-----------This is used to find the distance between two points on a sphere for eachobservation in a dataset. Typically this would be used to find distancesbetween points on Earth, though it will work just as well for points on,say, the moon or a basketball. Options-------Most of the options are not optional! They are specified as options toallow flexibility.^gen^ is the name of the variable which holds the results. This is a requiredoption.^lat1^, ^lon1^, ^lat2^, and ^lon2^ hold the variable or variables which specify thelatitudes (angles above or below the equator) and longitudes (angles eastor west of Greenwich). By default, the angles are expressed in degrees. Upto three variables (corresponding to degrees, minutes, and seconds of arc)are allowed for each latitude and longitude. Note, however, that the numberof variables for each need not be the same, so the precision of measurementdoes not need to be identical. The command will use however many arespecified. If the angles are expressed in radians, only one variable foreach latitude and longitude may be specified. The latitudes and longitudesare required options. Note: if all the measurements are from the samequarter-sphere, there is no trouble -- all may be positive. If not, see theimmediately following set of options. These are all required.^ew1^, ^sn1^, ^ew2^, and ^sn2^ options allow specification of variables which canbe used to indicate the hemisphere for each observation. Typically, forthose of us from the intersection of the northern and western hemispheres(or the NW quartisphere), this would mean that the ew variable(s) would befilled with -1 for east and 1 for west, while the sn variable(s) wouldcontain -1 for south and +1 for north, respectively. These options areincluded for those whose data contain a mix of degree/minute/second datafrom multiple hemispheres.^radians^ states that the angles are in radians, rather than indegrees. This, of course, means that just one variable can be given foreach of the latitude and longitude options.^radius^ gives the radius of the sphere. If not specified, this defaults tothe radius of the Earth.^units^ specifies the units of the final answer. This option has twopurposes. If a radius is not specified, the units are used to compute theproper radius of the earth. In this case, the units default to ^km^, becauseeveryone except the U.S. and, uh, Liberia(?) uses the metric system. (Thismust be why the system in the US is called either the Standard or theEnglish system.) Other acceptable choices here are ^mi^ for miles and ^naut^for nautical miles. If a radius is specified, the units are merely used formaking a variable label for the newly generated distance variable.^thin^ is an arcane option used if the dataset already takes up most of thememory. It alters the data by dropping the variables used to specify thelatitudes and longitudes. So... use it with care.Example(s)---------- ^sphdist, lat1(deg1nth min1nth sec1nth) lon1(deg1wst min1wst sec1wst) ^lat2(deg2nth min2nth sec2nth) lon2(deg2wst min2wst sec2wst) ^gen(kmdist) generates the new variable ^kmdist^ from the above latitude and longitude variables. The latitudes and longitudes are measured in degrees, minutes and seconds, and are either assumed to all be in a single quartisphere, or are negative in the proper places. The final result will be in kilometers of distance on the surface of the Earth. ^sphdist, lat1(degnth1) lon1(degwst1 minwst1) lat2(degnth2 minnth2 secnth2) lon2(degwst2) ^gen(nautdist) units(naut) ew1(ewlong) generates the new variable ^nautdist^ from the above latitude and longitude variables. The latitudes and longitudes are measured in varying ways using some or all of the degrees, minutes and seconds. All the latitudes are from the same hemisphere. All of the longitudes for the 'second' variables are in the same hemisphere, and the ewlong variable is 1 for observations in this same hemisphere, and -1 in the opposite one. The final result will be in nautical miles.Notes----- No error checking is done to be sure that there aren't fractional degreestogether with minutes and seconds, so it would be possible to feed theprogram a point whose latitude is 34.56 degrees, 27.2 minutes and 70000seconds.If all the points are in one quartisphere (there is no English word forquarter-of-the-globe), all angles can be expressed as positive numbers.If anyone has a better way of treating observations which crass the equatoror the prime meridian, please let the author know. He is used to easydistances in one quartisphere. No, he's never had data from the end of theAleutian islands.If anyone knows the real name for a quartisphere, please let the authorknow.For those who, like the author, wonder why kids in the US are still stucklearning that there are 12 inches to a foot, three feet to a yard, and 1760yards to a mile, there is a special unit of distance which can also bespecified. It was added in a fit of pro-metric mania: the erca, which isequal to the square root of an acre.Author------Bill Rising (brising@@jhsph.edu)Dept. of BiostatisticsJohns Hopkins University615 N. Wolfe St.Baltimore, MD 21205-2179