mapmate (version 0.3.1)

gc_arcs: Generate a table of great circle arcs

Description

Expand a table of pairs of great circle arc endpoint coordinates to a larger table also containing a series of points in between.

Usage

gc_arcs(data, lon0, lat0, lon1, lat1, n = 50, breakAtDateLine = FALSE,
  addStartEnd = TRUE)

Arguments

data

a data frame.

lon0

character, the column in data referring to starting longitudes.

lat0

character, the column in data referring to starting latitudes.

lon1

character, the column in data referring to ending longitudes.

lat1

character, the column in data referring to ending latitudes.

n

an integer scalar or vector, or character. The number of points along the shorter great circle arc between two endpoints in data or the name of a column in data. See details.

breakAtDateLine

logical, for flat maps it is important to break a line at the international dateline into two separate lines. Defaults to FALSE.

addStartEnd

logical, include the original endpoints rather than just the n points in between them. Defaults to TRUE.

Value

a data frame.

Details

gc_arcs takes a data frame as generated by gc_endpoints and fills in a series of points between each pair of endpoints (each row) in the input data frame. The amount by which this expands the data frame depends on n, the number of points in between the endpoints. The total points will be \(n+2\) if addStartEnd=TRUE.

n can be different for each arc if a vector is supplied or if n refers to a column in data. This is useful, for example, to allow longer arcs to be composed of more points, scaling n based on some function of distance between endpoints. A scalar integer value can be supplied (defaults to n=50) if all arcs are to be composed of the same number of points regardless of the distance they cover.

In the context of animating a sequence of plot frames, and holding other factors constant, the general rule of thumb is animations will appear to traverse the path of longer great circle arcs with greater speed than of shorter great circle arcs, taking about the same amount of time (number of frames) to complete the journey from endpoint to endpoint because each arc is composed of the same number of points. On the other hand, the more points an arc consists of, the slower it will be traversed. Another factor is the length of each segment along the path of the arc and how much each successive segment is allowed to overlap the previous one from one plot to the next. See gc_paths regarding this latter factor.

Overall, there is an interplay between the number of points composing an entire arc, the segment length (number of points composing the successive subsets of an arc), and degree of segment overlap (how the arc is broken into segments to trace the path along the arc). Longer segments made up of more points means the arc is traversed more quickly. More segment overlap will slow down the journey. More points composing the entire arc shrinks the distance covered by each segment.

Examples

# NOT RUN {
library(dplyr)
set.seed(192)
data(network)
distFun <- function(x) 1 - x / max(x) # simple inverse distance weighting
endpoints <- gc_endpoints(network, "lon", "lat")
endpoints <- mutate(endpoints, Dist_wts=distFun(Dist))

# take a weighted sample, e.g., favoring larger averaged populations and shorter distances
endpoints <- sample_n(endpoints, 500, replace=TRUE, weight=(Pop_wts0 + Pop_wts1)/2 + Dist_wts)

# expand data frame from endpoints to arcs, each composed of a sequence of points
arcs <- gc_arcs(endpoints, "lon0", "lat0", "lon1", "lat1")
# }