waypoints: Geographic Waypoint Class

Description

as_waypoints() creates an object of class "waypoints", a robust representation of a series of geographic or GPS waypoints of paired latitude and longitude values.

Usage

as_waypoints(object, ...)
# S3 method for default
as_waypoints(object, ..., fmt = 1L)

Value

An object of classes "waypoints" and "data.frame", comprising the original data frame argument object, with additional attributes: –

"class": the character string "waypoints".
"fmt": an integer indicating the coordinate format.
"namescol": an integer indicating the position of a waypoint names column, if present.
"llcols": a length 2 integer vector indicating the positions of latitude and longitude columns.
"validlat" and "validlon": logical vectors indicating whether individual latitude and longitude values are valid geographic locations.

Arguments

object: a data frame with each row representing a waypoint, comprising at least two numeric columns containing values of latitude and longitude, and optionally a character column of waypoint names (see Details).
...: further arguments passed to or from other methods.
fmt: integer, 1L, 2L or 3L, specifying the required coordinate format.

Details

Data frame argument object should have numeric vector latitude and longitude columns with individual values having a decimal point after the number of whole degrees in the case of decimal degrees, after the number of whole minutes in the case of degrees and minutes, and after the number of whole seconds in the case of degrees, minutes and seconds. These should be the first two columns of the data frame, or the second and third columns if the first column contains waypoints names (see below). Alternative columns may be specified for the latitude and longitude by setting "llcols" as a length 2 integer vector attribute of object indicating their positions in the data frame.

The fmt argument should be 1L to represent decimal degrees, 2L for degrees and minutes, and 3L for degrees, minutes and seconds and is used to provide the format of values in data frame argument object to be converted to class "waypoints".

If the waypoints have names, these should be included in a "Name" column of data frame argument object, by default immediately before (on the left-hand side of) the latitude and longitude columns. An alternative column for waypoint names may be specified by setting an integer attribute named "namescol" indicating its position in object, while setting this attribute to NA supresses printing of waypoint names. If neither a "Name" column nor a "namescol" attribute is present in object, row.names are used for waypoint names.

The latitude and longitude values of a newly created "waypoints" object are checked to ensure they are valid geographic locations as described under validate().

Examples

Run this code

## Dataframe representing waypoint names, and latitude and longitude values
## in degrees, minutes and seconds
wp1 <- data.frame(
    name = c("Nelson's Column", "Ostravice", "Tally Ho", "Washington Monument", "Null Island",
             "Tristan da Cunha", "Mawson Peak", "Silvio Pettirossi International Airport"),
    lat = c(513027.95, 493246.36, 480626.04, 385322.18, 0, -370642.26, -530617.21, -251424.56),
    lon = c(-00740.53, 182354.82, -1224643.22, -770206.87, 0, -121719.07, 733102.22, -573109.21)
)

## Create "waypoints" object of degrees, minutes and seconds (fmt = 3)
as_waypoints(wp1, fmt = 3)

## Show as an ordinary R data frame
as.data.frame(wp1)

###

## Dataframe representing unnamed latitude and longitude
## values in decimal degrees
wp2 <- data.frame(
    lat = c(51.507765, 49.54621, 48.107232, 38.889494, 0, -37.11174, -53.104781, -25.240156),
    lon = c(-0.127924, 18.398562, -122.778671, -77.035242, 0, -12.28863, 73.517283, -57.519227)
)

## Create unnamed "waypoints" object of decimal degrees (default fmt = 1)
as_waypoints(wp2)

## Add waypoint names as row.names
row.names(wp2) <-
    c("Nelson's Column", "Ostravice", "Tally Ho", "Washington Monument", "Null Island",
      "Tristan da Cunha", "Mawson Peak", "Silvio Pettirossi International Airport")

wp2

## Show as an ordinary R data frame
as.data.frame(wp2)

rm(wp1, wp2)