ee_extract: Extract values from EE Images or ImageCollections objects

In r-spatial/rgee: R Bindings for Calling the 'Earth Engine' API

Extract values from EE Images or ImageCollections objects

Description

Extract values from an ee$Image based on the locations of a geometry object. Users can utilize ee$Geometry$*, ee$Feature, ee$FeatureCollection, sf or sfc object for spatial filter. This function emulates the functionality of the existing extract method.

Usage

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 given in meters of the Image projection to work in. By default 1000.
sf	Logical. Should the function return an sf object?
via	Character. Method for exporting the image. Three methods are available: "getInfo", "drive", "gcs".
container	Character. Name of the folder ('drive') or bucket ('gcs') to export the image 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.

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.

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).

Examples

## Not run: 
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
)

## End(Not run)

r-spatial/rgee documentation built on July 4, 2024, 9:33 a.m.