Extract values from EE Images or ImageCollections objects

Source: R/ee_extract.R

Extract values from an ee$Image at the locations of a geometry object. Users can use ee$Geometry$*, ee$Feature, ee$FeatureCollection, sf or sfc object to filter spatially. This function mimicking how extract currently works.

ee_extract(
  x,
  y,
  fun = ee$Reducer$mean(),
  scale = NULL,
  sf = FALSE,
  via = "getInfo",
  container = "rgee_backup",
  lazy = FALSE,
  quiet = FALSE,
  ...
)

Arguments

x

ee$Image.
y

ee$Geometry$*, ee$Feature, ee$FeatureCollection, sfc or sf objects.
fun

ee$Reducer object. Function to summarize the values. The function must take a single numeric value as an argument and return a single value. See details.
scale

A nominal scale in meters of the Image projection to work in. By default 1000.
sf

Logical. Should return an sf object?
via

Character. Method to export the image. Three method are implemented: "getInfo", "drive", "gcs".
container

Character. Name of the folder ('drive') or bucket ('gcs') to be exported into (ignore if via is not defined as "drive" or "gcs").
lazy

Logical. If TRUE, a future::sequential object is created to evaluate the task in the future. Ignore if via is set as "getInfo". See details.
quiet

Logical. Suppress info message.
...

ee$Image$reduceRegions additional parameters. See ee_help(ee$Image$reduceRegions) for more details.

Value

A data.frame or an sf object depending on the sf argument. Column names are extracted from band names. Use ee$Image$rename to rename the bands of an ee$Image. See ee_help(ee$Image$rename).

Details

The reducer functions that return one value are:

  • allNonZero: Returns a Reducer that returns 1 if all of its inputs are non-zero, 0 otherwise.

  • anyNonZero: Returns a Reducer that returns 1 if any of its inputs are non-zero, 0 otherwise.

  • bitwiseAnd: Returns a Reducer that computes the bitwise-and summation of its inputs.

  • bitwiseOr: Returns a Reducer that computes the bitwise-or summation of its inputs.

  • count: Returns a Reducer that computes the number of non-null inputs.

  • first: Returns a Reducer that returns the first of its inputs.

  • firstNonNull: Returns a Reducer that returns the first of its non-null inputs.

  • kurtosis: Returns a Reducer that Computes the kurtosis of its inputs.

  • last: Returns a Reducer that returns the last of its inputs.

  • lastNonNull: Returns a Reducer that returns the last of its non-null inputs.

  • max: Creates a reducer that outputs the maximum value of its (first) input. If numInputs is greater than one, also outputs the corresponding values of the additional inputs.

  • mean: Returns a Reducer that computes the (weighted) arithmetic mean of its inputs.

  • median: Create a reducer that will compute the median of the inputs. For small numbers of inputs (up to maxRaw) the median will be computed directly; for larger numbers of inputs the median will be derived from a histogram.

  • min: Creates a reducer that outputs the minimum value of its (first) input. If numInputs is greater than one, also outputs additional inputs.

  • mode: Create a reducer that will compute the mode of the inputs. For small numbers of inputs (up to maxRaw) the mode will be computed directly; for larger numbers of inputs the mode will be derived from a histogram.

  • product: Returns a Reducer that computes the product of its inputs.

  • sampleStdDev: Returns a Reducer that computes the sample standard deviation of its inputs.

  • sampleVariance: Returns a Reducer that computes the sample variance of its inputs.

  • stdDev: Returns a Reducer that computes the standard deviation of its inputs.

  • sum: Returns a Reducer that computes the (weighted) sum of its inputs.

  • variance: Returns a Reducer that computes the variance of its inputs.

Examples

if (FALSE) {
library(rgee)
library(sf)

ee_Initialize(gcs = TRUE, drive = TRUE)

# Define a Image or ImageCollection: Terraclimate
terraclimate <- ee$ImageCollection("IDAHO_EPSCOR/TERRACLIMATE") %>%
 ee$ImageCollection$filterDate("2001-01-01", "2002-01-01") %>%
ee$ImageCollection$map(
   function(x) {
     date <- ee$Date(x$get("system:time_start"))$format('YYYY_MM_dd')
     name <- ee$String$cat("Terraclimate_pp_", date)
     x$select("pr")$rename(name)
   }
 )

# Define a geometry
nc <- st_read(
 dsn = system.file("shape/nc.shp", package = "sf"),
 stringsAsFactors = FALSE,
 quiet = TRUE
)


#Extract values - getInfo
ee_nc_rain <- ee_extract(
 x = terraclimate,
 y = nc["NAME"],
 scale = 250,
 fun = ee$Reducer$mean(),
 sf = TRUE
)

# Extract values - drive (lazy = TRUE)
ee_nc_rain <- ee_extract(
 x = terraclimate,
 y = nc["NAME"],
 scale = 250,
 fun = ee$Reducer$mean(),
 via = "drive",
 lazy = TRUE,
 sf = TRUE
)
ee_nc_rain <- ee_nc_rain %>% ee_utils_future_value()

# Extract values - gcs (lazy = FALSE)
ee_nc_rain <- ee_extract(
 x = terraclimate,
 y = nc["NAME"],
 scale = 250,
 fun = ee$Reducer$mean(),
 via = "gcs",
 container = "rgee_dev",
 sf = TRUE
)

# Spatial plot
plot(
 ee_nc_rain["X200101_Terraclimate_pp_2001_01_01"],
 main = "2001 Jan Precipitation - Terraclimate",
 reset = FALSE
)
}