Interface between the GMT Map-Making Software and R

Description

Interface between the GMT map-making software and R, enabling the user to manipulate geographic data within R and call GMT commands to draw and annotate maps in postscript format.

Details

Initialize GMT session:

Create a map:

Convert and calculate:

Examples:

Internal:

This package provides functions to draw basic maps with GMT, along with helping functions that can be used to add more advanced features to a map.

GMT users typically write shell scripts to draw maps. The gmt package is about interactive data analysis, rapidly visualizing subsets and summaries of geographic data, while performing statistical analysis in the R console.

Author(s)

Arni Magnusson.

References

Wessel, P., Smith, W. H. F., Scharroo, R., Luis, J. and Wobbe, F. The Generic Mapping Tools: GMT documentation. Available at https://docs.generic-mapping-tools.org.

Convert Degrees to Numeric

Description

Convert deg:min:sec string to decimal number.

Usage

deg2num(x)

Arguments

Details

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.

Value

Numeric representation of the degree string(s).

Note

The string format is adopted from Appendix B.1.1 in the GMT manual.

See Also

as.numeric converts strings to numbers when things are straightforward.

deg2num is the opposite of num2deg.

gmt-package gives an overview of the package.

Examples

# The opposite of num2deg() example
deg2num(c("12:30:44.5W", "17.5S", "1:00:05", "200:45E"))

Distance Between Geographic Coordinates

Description

Calculate surface distance between geographic coordinates.

Usage

geodist(Nfrom, Efrom, Nto, Eto, units="km")

Arguments

Details

Latitude and longitude are passed as decimal numbers, e.g. 66.5 for 66^{\circ}30'N. Vectors of coordinates are supported.

Value

Vector of distances.

Note

The surface distance between geographic coordinates is:

D \:=\: \cos^{-1}\!\!\big[\:\!\!\sin\theta_1\sin\theta_2 \,+\, \cos\theta_1\cos\theta_2\cos(\phi_1\;\!\!\!-\!\phi_2)\big]

where distance and coordinates are expressed in radians. \theta_1 and \theta_2 is the latitude of origin and destination, and \phi_1 and \phi_2 is longitude.

The calculations assume a perfect sphere and elevation differences are ignored. The SI definition of a nautical mile is exactly 1.852 km.

See Also

diff, Trig.

gmt-package gives an overview of the package.

Examples

geodist(55.75,37.63, 39.9,116.4)  # Moscow - Beijing
geodist(90,0, -90,0, "nm")        # from pole to pole

Initialize GMT Session

Description

Initialize a GMT session by setting graphical parameters and current postscript file.

Usage

gmt(par=NULL, file="map.ps", style="s", quiet=TRUE)

Arguments

Details

The file argument can be supplied with (recommended) or without a full directory path. Without a path, the R working directory is used (see getwd and setwd).

See the GMT documentation for details on graphical parameters, gmtdefaults, gmtset and other GMT commands.

Value

List containing the current options("gmt.file").

If par is NULL, no GMT parameters are changed, but the current parameter values and postscript filename can be reviewed.

If par is a string (empty "" will do), a GMT configuration file is created in the current map directory, dirname(file).

See Also

options could be used to set gmt.file directly.

gmt, pscoast, psxy, pstext, psbar, and psclose work together to draw maps.

gmt-package gives an overview of the package.

Examples

## Not run: 
# Draw map and save as "map.ps" in R working directory
gmt(demo.par)
pscoast(demo.coast)
psxy(demo.xy)
pstext(demo.text, "-J -R -F+f+a+j -O -K")
psbar(demo.bar, ref=66)
psclose()
# See directory gmt/example for details

## End(Not run)

GMT Example Data

Description

These five objects are provided to demonstrate the functionality of the gmt package.

Usage

demo.par
demo.coast
demo.xy
demo.text
demo.bar

Format

demo.par and demo.coast are simple strings.

demo.xy is a data frame containing:

demo.text is a data frame containing:

demo.bar is a data frame containing:

Details

See the GMT documentation for details on psxy, pstext and other GMT commands.

See Also

gmt-package gives an overview of the package.

Examples

## Not run: 
# Draw map and save as "map.ps" in R working directory
gmt(demo.par)
pscoast(demo.coast)
psxy(demo.xy)
pstext(demo.text, "-J -R -F+f+a+j -O -K")
psbar(demo.bar, ref=66)
psclose()
# See directory gmt/example for details

## End(Not run)

Invoke shell command

Description

This internal function invokes a shell command, possibly directing the output to a file.

Usage

gmt.system(cmd, file=NULL, append=FALSE)

Arguments

Value

Command output as a vector of strings.

Note

gmt.system is a fast platform-independent wrapper for system, supporting redirection to file.

It is mainly called by other functions, but users may find it useful for running various GMT commands.

See Also

system, writeLines.

gmt-package gives an overview of the package.

Examples

## Not run: 
# Assuming bermuda.nc is in R working directory
gmt.system("gmt grdcontour bermuda.nc -JM7i -C250 -A1000 -B2", file="b.ps")

## End(Not run)

Convert Numeric to Degrees

Description

Convert decimal number to deg:min:sec string.

Usage

num2deg(x, lat=NA, dec=FALSE, digits=0, zero=FALSE)

Arguments

Details

Element-specific format is supported, using vectors for lat, digits, and precision.

The resulting string ends with N or S when lat is TRUE, E or W when lat is FALSE, or a number when lat is NA.

Value

deg:min:sec string representation of the number(s).

Note

The string format is adopted from Appendix B.1.1 in the GMT manual.

See Also

as.character converts plain numbers to strings.

num2deg is the opposite of deg2num.

gmt-package gives an overview of the package.

Examples

# The opposite of deg2num() example
num2deg(c(-12.51236, -17.5, 1.00139, 200.75),
        lat=c(FALSE, TRUE,  NA,      FALSE),
        dec=c(FALSE, TRUE,  FALSE,   FALSE),
        digits=c(1,  1,     0,       0))

Add Bars to GMT Mercator Map

Description

Call GMT to add bars to a map and save in postscript format.

Usage

psbar(x, cmd="-J -R -W1p -G180 -O -K", file=getOption("gmt.file"),
      ref=0, digits=getOption("digits"))

Arguments

Details

The data are arranged in four columns: Lon, Lat, Width, and Height, in that order.

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.

This function provides an alternative to psxy -Sb and psxy -Sr for drawing bars on a Mercator map. See the GMT documentation for details on psxy and other GMT commands.

Value

Null, but the map is annotated and saved in postscript format.

The temporary GMT input file ‘bar.gmt’ is saved in directory dirname(tempdir()), for the user to view or edit. It is later removed by psclose().

Note

This function does the necessary calculations to draw bars in standard height given a Mercator-projected map. It is not intended for other projections.

The derivative of the Mercator projection is used to standardize the bar height:

f'\!(\theta) \;=\; \frac{1} {2\tan\;\!\!\!\Big(\!\frac\pi4\!+\!\frac\theta2\!\Big) \cos^2\!\Big(\!\frac\pi4\!+\!\frac\theta2\!\Big)}

where \theta is latitude in radians and f(\theta) is the y-axis coordinate. The bar height at a given latitude is h\times f'(\theta_{\mathrm{ref}})/f'(\theta), where h is the height passed by the user and \theta_{\mathrm{ref}} is a reference latitude where h\!=\!1 renders a bar 1 degree high.

See Also

Similar to barplot and postscript in native R graphics.

gmt, pscoast, psxy, pstext, psbar, and psclose work together to draw maps.

gmt-package gives an overview of the package.

Examples

## Not run: 
# Draw map and save as "map.ps" in R working directory
gmt(demo.par)
pscoast(demo.coast)
psxy(demo.xy)
pstext(demo.text, "-J -R -F+f+a+j -O -K")
psbar(demo.bar, ref=66)
psclose()
# See directory gmt/example for details

## End(Not run)

Finalize GMT Map

Description

Call GMT to finalize a map and save in postscript format.

Usage

psclose(file=getOption("gmt.file"), trailer=TRUE)

Arguments

Details

A closing trailer is required if the last plotting command included -K (default behaviour).

Value

NULL, but the map is finalized and saved in postscript format.

Note

This function performs two tasks:

1. Appends a closing trailer to the postscript file (optional).

2. Removes GMT files in temporary directory.

See Also

Analogous to dev.off and postscript in native R graphics.

gmt, pscoast, psxy, pstext, psbar, and psclose work together to draw maps.

gmt-package gives an overview of the package.

Examples

## Not run: 
# Draw map and save as "map.ps" in R working directory
gmt(demo.par)
pscoast(demo.coast)
psxy(demo.xy)
pstext(demo.text, "-J -R -F+f+a+j -O -K")
psbar(demo.bar, ref=66)
psclose()
# See directory gmt/example for details

## End(Not run)

Draw GMT Map

Description

Call GMT to draw a map (coastlines, borders, rivers) and save in postscript format.

Usage

pscoast(cmd, file=getOption("gmt.file"))

Arguments

Details

The file argument can be supplied with (recommended) or without a full directory path. Without a path, the current working directory is used (see getwd and setwd).

See the GMT documentation for details on pscoast and other GMT commands.

Value

NULL, but a map is drawn and saved in postscript format.

See Also

Similar to plot and postscript in native R graphics.

gmt, pscoast, psxy, pstext, psbar, and psclose work together to draw maps.

gmt-package gives an overview of the package.

Examples

## Not run: 
# Draw map and save as "map.ps" in current working directory
gmt(demo.par)
pscoast(demo.coast)
psxy(demo.xy)
pstext(demo.text, "-J -R -F+f+a+j -O -K")
psbar(demo.bar, ref=66)
psclose()
# See directory gmt/example for details

# Map in one call
pscoast("-JM12c -R7E/38E/29N/48N -G100 -B5", "x.ps")

## End(Not run)

Add Text/Symbols to GMT Map

Description

Call GMT to add text/symbols to a map and save in postscript format.

Usage

pstext(x, cmd="-J -R -O -K", file=getOption("gmt.file"))

Arguments

Details

The cmd argument can be used to specify the data columns:

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.

See the GMT documentation for details on pstext and other GMT commands.

Value

NULL, but the map is annotated and saved in postscript format.

The temporary GMT input file ‘text.gmt’ is saved in directory dirname(tempdir()), for the user to view or edit. It is later removed by psclose().

See Also

Similar to text and postscript in native R graphics.

gmt, pscoast, psxy, pstext, psbar, and psclose work together to draw maps.

gmt-package gives an overview of the package.

Examples

## Not run: 
# Draw map and save as "map.ps" in current working directory
gmt(demo.par)
pscoast(demo.coast)
psxy(demo.xy)
pstext(demo.text, "-J -R -F+f+a+j -O -K")
psbar(demo.bar, ref=66)
psclose()
# See directory gmt/example for details

## End(Not run)

Add Lines/Symbols to GMT Map

Description

Call GMT to add lines/symbols to a map and save in postscript format.

Usage

psxy(x, cmd="-J -R -Scp -W2p -O -K", file=getOption("gmt.file"))

Arguments

Details

The data are arranged in two (Lon, Lat) or more columns, depending on the -S argument.

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.

See the GMT documentation for details on psxy and other GMT commands.

Value

NULL, but the map is annotated and saved in postscript format.

The temporary GMT input file ‘xy.gmt’ is saved in directory dirname(tempdir()), for the user to view or edit. It is later removed by psclose().

See Also

Similar to points, lines, and postscript in native R graphics.

gmt, pscoast, psxy, pstext, psbar, and psclose work together to draw maps.

gmt-package gives an overview of the package.

Examples

## Not run: 
# Draw map and save as "map.ps" in current working directory
gmt(demo.par)
pscoast(demo.coast)
psxy(demo.xy)
pstext(demo.text, "-J -R -F+f+a+j -O -K")
psbar(demo.bar, ref=66)
psclose()
# See directory gmt/example for details

# Simple map and circles
pscoast("-JM12c -R158/192/-42/-8 -Di -Gdarkgreen -B10f5 -A2000 -K", "quake.ps")
psxy(data.frame(lon=quakes$lon, lat=quakes$lat, mag=10^quakes$mag/1e6),
     "-J -R -Scp -W0.5p,red -O", "quake.ps")

## End(Not run)

Prepare Data for GMT

Description

This internal function reads data, from a filename or R object, and writes them to a GMT input file.

Usage

r2gmt(x, datafile, append=FALSE)

Arguments

Details

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.

Value

The data frame that was written to datafile.

Note

r2gmt is like write.table, except it allows x to be a filename, and appends tables with the GMT > separator.

It is mainly called by other functions, but users may find it useful for writing input data for GMT commands.

See Also

scan, read.table, write, write.table.

gmt-package gives an overview of the package.

Examples

LonLat1 <- data.frame(Lon=1:3, Lat=4:6)
LonLat2 <- data.frame(Lon=7:8, Lat=9:10)
## Not run: 
r2gmt(LonLat1, "temp.gmt")
r2gmt(LonLat2, "temp.gmt", append=TRUE)

## End(Not run)