The gmt Package. October 19, URL

Transcription

1 The gmt Package October 19, 2005 Version Date Title Interface between GMT 4.0 map-making software and R Author Arni Magnusson Maintainer Arni Magnusson <arnima@u.washington.edu> Depends R (>= 2.1.1) LazyData yes Interface between GMT 4.0 map-making software and R, enabling the user to manipulate geographic data within R and call GMT programs to draw and annotate maps in postscript format. License GPL version 2 or newer URL R topics documented: deg2num geodist gmt-package gmt gmt.demo gmt.system psbar psclose pscoast pstext psxy r2gmt Index 15 1

2 2 deg2num deg2num Convert Degrees to Numeric Convert deg:min:sec string to decimal number. deg2num(x) x string or vector of strings. Degrees, minutes and seconds are separated by colons, and each can have a decimal point as well. First character must be a minus sign or number, and last character must be W, E, S, N, or number. Numeric representation of the degree string(s). The string format is adopted from Appendix B.1.1 in the GMT manual. as.numeric. deg2num(c("12:30:44.5w", "17.5S", "1:00:05", "200:45E"))

3 geodist 3 geodist Distance Between Geographic Coordinates Calculate surface distance between geographic coordinates. geodist(nfrom, Efrom, Nto, Eto, units="km") Nfrom Efrom Nto Eto units latitude of origin. longitude of origin. latitude of destination. longitude of destination. how distance is measured: "km" for kilometres, "nm" for nautical miles. Latitude and longitude are passed as decimal numbers, e.g for N. Vectors of coordinates are supported. Vector of distances. The surface distance between geographic coordinates is: D = cos 1[ sin θ 1 sin θ 2 + cos θ 1 cos θ 2 cos(φ 1 φ 2 ) ] where distance and coordinates are expressed in radians. θ 1 and θ 2 is the latitude of origin and destination, and φ 1 and φ 2 is longitude. The calculations assume a perfect sphere and elevation differences are ignored. The SI definition of a nautical mile is exactly km. diff, Trig. geodist(55.75,37.62, 39.9,116.4) geodist(90,0, -90,0, "nm") # Moscow - Beijing # from pole to pole

4 4 gmt-package gmt-package Interface between GMT 4.0 Map-Making Software and R Interface between GMT 4.0 map-making software and R, enabling the user to manipulate geographic data within R and call GMT programs to draw and annotate maps in postscript format. Initialize GMT session: gmt set graphical parameters and postscript file Create a map: pscoast psxy pstext psbar psclose draw annotate annotate annotate finalize Convert and calculate: deg2num geodist degrees to numeric distance between coordinates : demo.par, demo.coast, demo.xy, demo.text, demo.bar strings and data frames that make up a map Internal: gmt.system, r2gmt not really intended for the end user Additional details are found on the help(package="gmt") page. References Wessel, P. and W.H.F. Smith The Generic Mapping Tools: Technical reference and cookbook. Version 4. Available at Other packages that can be used to draw maps include: GRASS, maps and PBSmapping.

5 gmt 5 gmt Initialize GMT Session Initialize a GMT (Generic Mapping Tools) session by setting graphical parameters and current postscript file. gmt(par, style="s", file="map.eps", quiet=false) par style file quiet optional string of the form "PARAMETER1=value1 PARAMETER2=value2...", passed to gmtset. default units and values: "s" for SI (international) or "u" for United States, passed to gmtdefaults. postscript filename used in subsequent calls to GMT plot functions, passed to options() whether current settings should be displayed. File type should be.eps when PAPER_MEDIA is A4+ or letter+, but.ps otherwise. See the GMT documentation for details on graphical parameters, gmtdefaults, gmtset and other GMT commands. List containing the current options("gmt.file"). If par is passed by user (even an empty string "" will do), a file named.gmtdefaults4 is created in the working directory. If quiet=false, the current graphical parameter settings are displayed. Assumes that GMT version 4 is installed, i.e. that gmtset and other commands are in the path, and environment variable GMTHOME is defined. options.

6 6 gmt.demo gmt(demo.par) pscoast(demo.coast) psxy(demo.xy) pstext(demo.text) psbar(demo.bar, ref=64) psclose() gmt.demo GMT Example Data Format These five objects are provided to demonstrate the functionality of the gmt package. demo.par demo.coast demo.xy demo.text demo.bar demo.par and demo.coast are simple strings. demo.xy is a data frame containing: Lon Lat Size Longitude Latitude Size of plot symbol demo.text is a data frame containing: Lon Lat Size Angle Font Justify Text Longitude Latitude Size of plot symbol Angle in degrees counter-clockwise from horizontal Font number Justification code Text label demo.bar is a data frame containing: Lon Lat Width Height Longitude Longitude Bar width in degrees Bar height in degrees

7 gmt.system 7 See the GMT documentation for details on psxy, pstext and other GMT commands. gmt(demo.par) pscoast(demo.coast) psxy(demo.xy) pstext(demo.text) psbar(demo.bar, ref=64) psclose() gmt.system Invoke GMT system command Invoke a system command, possibly directing the output to a file. gmt.system(cmd, file=null, append=false) cmd file append system command to be invoked, as a string. filename to which output should be directed. whether output should be appended to existing file. Command output as a vector of strings. This function is primarily an internal function, but users may find it handy for their own plotting functions. It is platform-independent, unlike the shell function. system, writelines.

8 8 psbar ## Assuming that GMT is in path gmt.system("gmtdefaults -Ds", file=".gmtdefaults4") psbar Add Bars to GMT Mercator Map Call GMT to add bars to the active map and save in postscript format. This function does the necessary calculations to render bars in standard height given a Mercator-projected map. It is not intended for other projections. psbar(x, cmd="-jm -R -W1p -G180 -O -K", file=options("gmt.file"), ref=0, digits=options("digits")) x cmd file ref digits data frame, matrix, or filename containing the data to be plotted. string of arguments passed to psxy. filename where the map is saved. reference latitude where Height=1 renders a bar 1 degree high. precision used when rounding the geographic coordinates. The data are arranged in four columns: Lon, Lat, Width, and Height, in that order. See help(r2gmt) for valid data file format when argument x is a filename. See the GMT documentation for details on psxy and other GMT commands. Null, but the map is annotated and saved in postscript format. As a side product, a temporary file lastbar.gmt is saved in the working directory. Assumes that GMT version 4 is installed, i.e. that psxy and other commands are in the path, and environment variable GMTHOME is defined. The derivative of the Mercator projection is used to standardize the bar height: f (θ) = ( 2 tan π 4 + θ 2 1 ) ( cos 2 π 4 + θ 2 where θ is latitude in radians and f(θ) is the y-axis coordinate. The bar height at a given latitude is h f (θ ref )/f (θ), where h is the height passed by the user and θ ref is a reference latitude where h=1 renders a bar 1 degree high. )

9 psclose 9 barplot, postscript. gmt(demo.par) pscoast(demo.coast) psxy(demo.xy) pstext(demo.text) psbar(demo.bar, ref=64) psclose() psclose Finalize GMT Map Call GMT to finalize the active map by appending a closing trailer and save in postscript format. psclose(file=options("gmt.file")) file filename where the map is saved. See the GMT documentation for details on psxy and other GMT commands. Null, but the map is finalized and saved in postscript format. Assumes that GMT version 4 is installed, i.e. that psxy and other commands are in the path, and environment variable GMTHOME is defined.

10 10 pscoast postscript. gmt(demo.par) pscoast(demo.coast) psxy(demo.xy) pstext(demo.text) psbar(demo.bar, ref=64) psclose() pscoast Draw GMT Map Call GMT to draw a map (coastlines, borders, rivers) and save in postscript format. pscoast(cmd, file=options("gmt.file")) cmd file string of arguments passed to pscoast. filename where the map will be saved. File type should be.eps when PAPER_MEDIA is A4+ or letter+, but.ps otherwise. See the GMT documentation for details on pscoast and other GMT commands. Null, but a map is drawn and saved in postscript format. Assumes that GMT version 4 is installed, i.e. that pscoast and other commands are in the path, and environment variable GMTHOME is defined.

11 pstext 11 plot.default, postscript. gmt(demo.par) pscoast(demo.coast) psxy(demo.xy) pstext(demo.text) psbar(demo.bar, ref=64) psclose() pstext Add Text/Symbols to GMT Map Call GMT to add text/symbols to the active map and save in postscript format. pstext(x, cmd="-jm -R -O -K", file=options("gmt.file")) x cmd file data frame, matrix, or filename containing the data to be plotted. string of arguments passed to pstext. filename where the map is saved. The data are arranged in seven columns: Lon, Lat, Size, Angle, Font, Justify, and Text, in that order. See help(r2gmt) for valid data file format when argument x is a filename. See the GMT documentation for details on pstext and other GMT commands. Null, but the map is annotated and saved in postscript format. As a side product, a temporary file lasttext.gmt is saved in the working directory. Assumes that GMT version 4 is installed, i.e. that pstext and other commands are in the path, and environment variable GMTHOME is defined.

12 12 psxy text, postscript. gmt(demo.par) pscoast(demo.coast) psxy(demo.xy) pstext(demo.text) psbar(demo.bar, ref=64) psclose() psxy Add Lines/Symbols to GMT Map Call GMT to add lines/symbols to the active map and save in postscript format. psxy(x, cmd="-jm -R -Scp -W2p -O -K", file=options("gmt.file")) x cmd file data frame, matrix, or filename containing the data to be plotted. string of arguments passed to psxy. filename where the map is saved. The data are arranged in two (Lon, Lat) or more columns, depending on the -S argument. See help(r2gmt) for valid data file format when argument x is a filename. See the GMT documentation for details on psxy and other GMT commands. Null, but the map is annotated and saved in postscript format. As a side product, a temporary file lastxy.gmt is saved in the working directory. Assumes that GMT version 4 is installed, i.e. that psxy and other commands are in the path, and environment variable GMTHOME is defined.

13 r2gmt 13 lines, points, postscript. gmt(demo.par) pscoast(demo.coast) psxy(demo.xy) pstext(demo.text) psbar(demo.bar, ref=64) psclose() r2gmt Prepare Data for GMT This function handles data that will be annotated on a GMT map, writing them to a temporary file. Although it is an internal function, users may find it handy for some tasks. r2gmt(x, outfile, append=false) x outfile append data frame, matrix, or filename containing the data to be written to a temporary file. filename where the data will be written in GMT format, tab-separated without header. whether data should be appended to an existing file, separating segments with ">" lines. If x is a filename, the data should be tabular with or without a header, separated by commas or whitespace. The first line is interpreted as header if the first non-whitespace character is not minus, point, or number. The data frame that was written to outfile. This function is primarily an internal function, but users may find it handy for their own plotting functions.

14 14 r2gmt scan, read.table, write, write.table. LonLat1 <- data.frame(lon=1:3, Lat=4:6) LonLat2 <- data.frame(lon=7:8, Lat=9:10) r2gmt(lonlat1, "temp.gmt") r2gmt(lonlat2, "temp.gmt", append=true)

15 Index Topic aplot psbar, 7 psclose, 9 pstext, 11 psxy, 12 Topic arith deg2num, 1 Topic character deg2num, 1 Topic classes deg2num, 1 Topic datasets gmt.demo, 5 Topic environment gmt, 4 Topic file gmt.system, 6 r2gmt, 13 Topic hplot gmt-package, 3 pscoast, 10 Topic interface gmt, 4 gmt.system, 6 psbar, 7 psclose, 9 pscoast, 10 pstext, 11 psxy, 12 r2gmt, 13 Topic math geodist, 2 Topic ts gmt-package, 3 as.numeric, 2 barplot, 8 deg2num, 1, 4 demo.bar, 4 demo.bar (gmt.demo), 5 demo.coast, 4 demo.coast (gmt.demo), 5 demo.par, 4 demo.par (gmt.demo), 5 demo.text, 4 demo.text (gmt.demo), 5 demo.xy, 4 demo.xy (gmt.demo), 5 diff, 3 geodist, 2, 4 gmt, 3, 4 gmt-package, 2, 3, 5 13 gmt-package, 3 gmt.demo, 5 gmt.system, 4, 6 lines, 12 options, 5 plot.default, 10 points, 12 postscript, 8 12 psbar, 3, 7 psclose, 3, 9 pscoast, 3, 10 pstext, 3, 11 psxy, 3, 12 r2gmt, 4, 13 read.table, 13 scan, 13 system, 7 text, 11 Trig, 3 write, 13 write.table, 13 writelines, 7 15