assign_to_grid {ebirdst}

Assign points to a spacetime grid

Description

Given a set of points in space and (optionally) time, define a regular grid with given dimensions, and return the grid cell index for each point.

Usage

assign_to_grid(
  points,
  coords = NULL,
  is_lonlat = FALSE,
  res,
  jitter_grid = TRUE,
  grid_definition = NULL
)

Arguments

points

data frame; points with spatial coordinates x and y, and an optional time coordinate t.

coords

character; names of the spatial and temporal coordinates in the input dataframe. Only provide these names if you want to overwrite the default coordinate names: c("x", "y", "t") or c("longitude", "latitude", "t") if is_lonlat = TRUE.

is_lonlat

logical; if the points are in unprojected, lon-lat coordinates. In this case, the input data frame should have columns "longitude" and "latitude" and the points will be projected to an equal area Eckert IV CRS prior to grid assignment.

res

numeric; resolution of the grid in the x, y, and t dimensions, respectively. If only 2 dimensions are provided, a space only grid will be generated. The units of res are the same as the coordinates in the input data unless is_lonlat is true in which case the x and y resolution should be provided in meters.

jitter_grid

logical; whether to jitter the location of the origin of the grid to introduce some randomness.

grid_definition

list; object defining the grid via the origin and resolution components. To assign multiple sets of points to exactly the same grid, assign_to_grid() returns a data frame with a grid_definition attribute that can be passed to subsequent calls to assign_to_grid(). res and jitter are ignored if grid_definition is provided.

Value

Data frame with the indices of the space-only and spacetime grid cells. This data frame will have a grid_definition attribute that can be used to reconstruct the grid.

Examples

set.seed(1)

# generate some example points
points_xyt <- data.frame(x = runif(100), y = runif(100), t = rnorm(100))
# assign to grid
cells <- assign_to_grid(points_xyt, res = c(0.1, 0.1, 0.5))

# assign a second set of points to the same grid
assign_to_grid(points_xyt, grid_definition = attr(cells, "grid_definition"))

# assign lon-lat points to a 10km space-only grid
points_ll <- data.frame(longitude = runif(100, min = -180, max = 180),
                        latitude = runif(100, min = -90, max = 90))
assign_to_grid(points_ll, res = c(10000, 10000), is_lonlat = TRUE)

# overwrite default coordinate names, 5km by 1 week grid
points_names <- data.frame(lon = runif(100, min = -180, max = 180),
                           lat = runif(100, min = -90, max = 90),
                           day = sample.int(365, size = 100))
assign_to_grid(points_names,
               res = c(5000, 5000, 7),
               coords = c("lon", "lat", "day"),
               is_lonlat = TRUE)