rgee (version 1.0.7)

ee_as_sf: Convert an Earth Engine table in a sf object

Description

Convert an Earth Engine table in a sf object

Usage

ee_as_sf(
  x,
  dsn,
  overwrite = TRUE,
  via = "getInfo",
  container = "rgee_backup",
  crs = NULL,
  maxFeatures = 5000,
  selectors = NULL,
  lazy = FALSE,
  public = TRUE,
  add_metadata = TRUE,
  timePrefix = TRUE,
  quiet = FALSE
)

Arguments

x

Earth Engine table (ee$FeatureCollection) to be converted in a sf object.

dsn

Character. Output filename; in case dsn is missing a shapefile will be created in the tmp() directory.

overwrite

Logical. Delete data source dsn before attempting to write?.

via

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

container

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

crs

Integer or character. coordinate reference system for the EE table. If is NULL, ee_as_sf will take the CRS of the first element.

maxFeatures

Numeric. The maximum allowed number of features to export (ignore if via is not set as "getInfo"). The task will fail if the exported region covers more features. Defaults to 5000.

selectors

The list of properties to include in the output, as a list of strings or a comma-separated string. By default, all properties are included.

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.

public

Logical. If TRUE, a public link to the image will be created.

add_metadata

Add metadata to the sf object. See details.

timePrefix

Logical. Add current date and time (Sys.time()) as a prefix to files to export. This parameter helps to avoid exported files with the same name. By default TRUE.

quiet

logical. Suppress info message.

Value

An sf object.

Details

ee_as_sf supports the download of ee$Geometry, ee$Feature, and ee$FeatureCollection by three different options: "getInfo" (which make an REST call to retrieve the data), "drive" (which use Google Drive) and "gcs" (which use Google Cloud Storage). The advantage of use "getInfo" is a direct and faster download. However, there is a limitation of 5000 features by request which makes it not recommendable for large FeatureCollections. Instead of "getInfo", the options: "drive" and "gcs" are suitable for large FeatureCollections since the use of an intermediate container. They work as follow:

• 1. A task will be started (i.e. ee$batch$Task$start()) to move the EE Table from Earth Engine to the intermediate container specified in argument via.

• 2. If the argument lazy is TRUE, the task will not be monitored. This is useful to lunch several tasks at the same time and call them later using ee_utils_future_value or future::value. At the end of this step, the EE Table will be stored on the path specified in the argument dsn.

• 3. Finally if the argument add_metadata is TRUE, a list with the following elements will be added to the sf object.

  • if via is "drive":

    • ee_id: Name of the Earth Engine task.

    • drive_name: Name of the Table in Google Drive.

    • drive_id: Id of the Table in Google Drive.

    • drive_download_link: Download link to the table.

  • if via is "gcs":

    • ee_id: Name of the Earth Engine task.

    • gcs_name: Name of the Table in Google Cloud Storage.

    • gcs_bucket: Name of the bucket.

    • gcs_fileFormat: Format of the table.

    • gcs_public_link: Download link to the table.

    • gcs_URI: gs:// link to the table.

  Run attr(sf, "metadata") to get the list.

For getting more information about exporting data from Earth Engine, take a look at the Google Earth Engine Guide - Export data.

Examples

# NOT RUN {
library(rgee)

ee_Initialize(drive = TRUE, gcs = TRUE)

# Region of interest
roi <- ee$Geometry$Polygon(list(
  c(-122.275, 37.891),
  c(-122.275, 37.868),
  c(-122.240, 37.868),
  c(-122.240, 37.891)
))

# TIGER: US Census Blocks Dataset
blocks <- ee$FeatureCollection("TIGER/2010/Blocks")
subset <- blocks$filterBounds(roi)
sf_subset <- ee_as_sf(x = subset)
plot(sf_subset)

# Create Random points in Earth Engine
region <- ee$Geometry$Rectangle(-119.224, 34.669, -99.536, 50.064)
ee_help(ee$FeatureCollection$randomPoints)
ee_randomPoints <- ee$FeatureCollection$randomPoints(region, 100)

# Download via GetInfo
sf_randomPoints <- ee_as_sf(ee_randomPoints)
plot(sf_randomPoints)

# Download via drive
sf_randomPoints_drive <- ee_as_sf(
  x = ee_randomPoints,
  via = 'drive'
)

# Download via GCS
# sf_randomPoints_gcs <- ee_as_sf(
#   x = subset,
#   via = 'gcs',
#   container = 'rgee_dev' #GCS bucket name
# )
# }