Package 'rapr'

Description

Two sets of 'Rangeland Analysis Platform' (RAP) products are available (see source argument). "rap-30m" is Landsat-derived and has approximately 30 meter resolution in WGS84 decimal degrees ("EPSG:4326"). This is the data source that has been used in the 'rapr' package since 2022. A newer source (2025), "rap-10m", is Sentinel 2-derived and has 10 meter resolution in the local WGS84 UTM zone ("EPSG:326XX", where XX is the two digit UTM zone number). See Details for the products and bands available for the different resolutions and sources.

Usage

get_rap(
  x,
  years,
  product,
  filename = NULL,
  ...,
  source = "rap-30m",
  version = "v3",
  vrt = FALSE,
  sds = FALSE,
  legacy = FALSE,
  verbose = TRUE
)

Arguments

Details

Sources, Products, and Band Information

For "rap-30m" you can query several Landsat derived annual biomass, cover, and Net Primary Productivity products from 1986 to present:

• product = "vegetation-biomass" returns two layers per year:

  • 2 Bands:"annual forb and grass", "perennial forb and grass" (lbs / acre)

• product = "vegetation-cover" returns six layers per year:

  • 6 Bands: "annual forb and grass", "bare ground", "litter", "perennial forb and grass", "shrub", "tree" (% cover)

• product = "vegetation-npp" returns four layers per year:

  • 4 Bands: "annual forb and grass", "perennial forb and grass", "shrub", "tree" (NPP; kg*C/m^2)

For "rap-10m" you can query several Sentinel 2 derived cover products at 10 meter resolution from 2018 to present:

• product = "pft" returns fractional cover estimates of plant functional types:

  • 6 Bands: "annual forb and grass", "bare ground", "litter", "perennial forb and grass", "shrub", "tree" (% cover)

• product = "gap" returns canopy gap estimates for four canopy gap size classes:

  • 4 Bands: "Gaps 25-50 cm", "Gaps 51-100 cm", "Gaps 100-200 cm", "Gaps >200 cm" (% cover)

• product = "arte" returns cover estimates of Artemisia species, including A. arbuscula, A. cana, A. nova, A. tridentata, and A. tripartita.

  • 1 Band: "Artemisia spp." (% cover)

• product = "iag" returns fractional cover estimates of Bromus tectorum, B. arvensis, B. rubens, B. hordeaceus, Eremopyrum triticeum, Schismus spp., Taeniatherum caput-medusae, and Ventenata dubia.

  • 1 Band: "invasive annual grass" (% cover)

• product = "pj" returns fractional cover estimates of Juniperus monosperma, J. occidentalis, J. osteosperma, J. scopulorum, Pinus edulis, and P. monophylla.

  • 1 Band: "pinyon-juniper" (% cover)

Temporary Files

Large requests may generate intermediate objects that will be stored as temporary files. See terra::tmpFiles() to view the file paths. These files will be removed when an R session ends.

Alternate Specification of Area of Interest

In lieu of a spatial object from {terra}, {raster}, {sf} or {sp} packages you may specify a bounding box using a numeric vector containing the top-left and bottom-right coordinates (xmin, ymax, xmax, ymin) in WGS84 longitude/latitude decimal degrees. This corresponds to the conventional order used in the gdal_translate -projwin option. e.g. get_rap(x = c(-120, 37, -119.99, 36.99), ...).

(1: xmin, 2: ymax)--------------------------|
        |                                   |
        |         TARGET EXTENT             |
        |  x = c(xmin, ymax, xmax, ymin)    |
        |                                   |
        |---------------------------(3: xmax, 4: ymin)

Native Resolution and Projection Systems

Native cell resolution of "rap-30m" is approximately 30m x 30m in WGS84 geographic coordinate system (longitude, latitude). Native cell resolution of "rap-10m" is 10m x 10m in the local (projected) WGS84 Universal Transverse Mercator (UTM) system.

For "rap-10m" requests spanning multiple UTM zones, either pass a SpatRaster object as x or specify template argument. In lieu of a user-specified grid system for multi-zone requests, a default CONUS Albers Equal Area projection ("EPSG:5070") with 10 m resolution will be used. See rap_projection() for options and details.

Value

a SpatRaster containing the requested product layers by year. If sds=TRUE a SpatRasterDataset where each SpatRaster contains only one product (possibly with multiple years)

References

See citation("rapr") for all references related to Rangeland Analysis Platform products.

See Also

rap_projection()

Examples

library(rapr)    # access RAP products
library(terra)   # spatial data handling

p <- buffer(terra::vect(
  data.frame(x = -105.97133, y = 32.73437),
  geom = c("x", "y"),
  crs = "OGC:CRS84"
), width = 1000)

rap <- get_rap(
  p,
  product = "vegetation-biomass",
  years = 2020:2024,
  verbose = FALSE
)

plot(rap, type = "continuous")

rap10m <- get_rap(
  p,
  product = "pft",
  source = "rap-10m",
  years = c(2020, 2024),
  sds = TRUE,
  verbose = FALSE
)

plot(
  rap10m$pft_2020,
  type = "continuous",
  range = c(0, 100),
  sub = "Year: 2020"
)

plot(
  rap10m$pft_2024,
  type = "continuous",
  range = c(0, 100),
  sub = "Year: 2024"
)

Description

Retrieves remotely sensed production or cover estimates from the Rangeland Analysis Platform (RAP) using the tabular data API endpoints. This function supports querying one or more spatial features (points, lines, or polygons) provided as a terra SpatVector object, or any spatial object that can be converted with terra::vect(). See Details for the products available.

get_rap_production16day_table() is deprecated, please use get_rap_table(product="production16day") instead.

Usage

get_rap_table(
  aoi,
  years = NULL,
  product,
  version = "V3",
  mask = TRUE,
  nodata_flag = NA_real_
)

get_rap_production16day_table(
  aoi,
  years = NULL,
  mask = TRUE,
  nodata_flag = NA_real_,
  ...
)

Arguments

Details

For each feature - year combination, a separate request is made to the RAP API, and results are returned as a combined data.frame. In the special case of (years=NULL) default, all available years are returned in a single query.

For more information on the API and data products, see the RAP API documentation: https://rangelands.app/support/71-api-documentation

Products Overview

You can query several Landsat derived biomass, cover, and meteorological products from 1986 to present:

• "cover" – yearly fractional cover, including:

  • "AFG" (Annual Forb and Grass cover)

  • "PFG" (Perennial Forb and Grass cover)

  • "SHR" (Shrub cover)

  • "TRE" (Tree cover)

  • "LTR" (Litter cover)

  • "BGR" (Bare Ground cover)

• "coverMeteorology" – the same data provided by "cover" above, plus:

  • "annualTemp" (Annual average temperature in degrees Fahrenheit)

  • "annualPrecip" (Annual total precipitation in inches)

• "production" – annual production, including:

  • "AFG" (Annual Forb and Grass production)

  • "PFG" (Perennial Forb and Grass production)

  • "HER" (Herbaceous production)

• "production16day" – 16-day production, including:

  • "date" (production estimate date)

  • "doy" (production estimate Julian day of year)

  • "AFG" (Annual Forb and Grass production)

  • "PFG" (Perennial Forb and Grass production)

  • "HER" (Herbaceous production)

Value

A data.frame with requested time-series data by year or 16-day production period. In addition to the columns described in Details above, all products include columns for "year" (production estimate year) and "feature" (feature ID, row number from aoi). Units are % cover for fractional cover and lbs / acre for production.

Examples

aoi <- terra::vect(data.frame(x = -119.72330, y = 36.92204),
                   geom = c('x', 'y'),
                   crs = "EPSG:4326")

# all years (years=NULL) fractional cover data
res <- get_rap_table(aoi, product="cover")
str(res)

# specific year fractional cover and meteorological data 
res <- get_rap_table(aoi, years = 1992, product="coverMeteorology")
str(res)

# multiple specific years above-ground production (annual)
res <- get_rap_table(aoi, years = 1993:2003, product="production")
str(res)

# 1 kilometer buffer around point, above-ground production (16 days) in 2004
res <- get_rap_table(terra::buffer(aoi, 1000), years = 2004, product="production16day")
str(res)

Description

This function provides several "standard" projected Coordinate Reference Systems that are suitable for representing Rangeland Analysis Platform products across the contiguous (lower 48) United States at the specified resolution (in meters).

Usage

rap_projection(x, res)

Arguments

Details

Currently there are three pre-calculated grid systems that have their extent designed to align at 1, 5, 10, 30, 100, and 300 meter resolutions.

"CONUS_AEA" is the default template used with get_rap(source="rap-10m") when data spanning multiple UTM zones are requested, unless user specifies their own template via SpatRaster object as x or template argument.

Grid Specifications

• "CONUS_AEA": Albers Equal Area Conic projection for CONUS extent.

  • xmin = -2356300

  • ymax = 3172500

  • xmax = 2264000

  • ymin = 270000

  • crs = "EPSG:5070"

• ⁠"CONUS_EQUI7⁠: Equi7Grid projection for CONUS + Hawaii extent.

  • xmin = 599500

  • ymax = 4967500

  • xmax = 10737100

  • ymin = 1913500

  • crs = "EPSG:27705"

• "CONUS_IGH": Interrupted Goode Homolosine projection for CONUS extent.

  • xmin = -13390500

  • ymax = 5836700

  • xmax = -8268600

  • ymin = 2480600

  • crs = "+proj=igh"

Value

An empty SpatRaster object with a standard extent (xmin,ymax,xmax,ymin), resolution and projected Coordinate Reference System.

See Also

get_rap()

Examples

rap_projection("CONUS_AEA", 10)

rap_projection("CONUS_IGH", 100)