lsat_export_ts: Export reflectance time-series from the Landsat record using...

In logan-berner/lsatTS: An R package to facilitate retrieval, cleaning, cross-calibration, and phenological modeling of Landsat time-series data

Export reflectance time-series from the Landsat record using rgee

Description

This function exports surface reflectance time series for a set of point-coordinates from the whole Landsat Collection 2 record using the Google Earth Engine (GEE). The resulting time-series can then be processed using the remainder of the LandsatTS workflow.

For polygon geometries consider using lsat_get_pixel_centers() to generate pixel center coordinates for all pixels within a given polygon first.

Please note: Unlike other functions in this package, this function does NOT return the time-series as an object, instead it returns a list of GEE tasks issued for the export. The actual time-series are exported as CSV objects via GEE to the user's Google Drive. This way of exporting allows for a more efficient scheduling, larger exports, and does not require the R session to continue to run in the background while the requests are processed on the GEE.

The progress of the exports can be monitored using the list of tasks returned in combination with ee_monitoring() from the rgee package, or simply by using the task overview in the GEE web code-editor (https://code.earthengine.google.com).

Usage

lsat_export_ts(
  pixel_coords_sf,
  sample_id_from = "sample_id",
  chunks_from = NULL,
  this_chunk_only = NULL,
  max_chunk_size = 250,
  drive_export_dir = "lsatTS_export",
  file_prefix = "lsatTS_export",
  start_doy = 152,
  end_doy = 243,
  start_date = "1984-01-01",
  end_date = "today",
  buffer_dist = 0,
  scale = 30,
  mask_value = 0
)

Arguments

pixel_coords_sf	Simple feature object of point coordinates for the sample.
sample_id_from	The column name that specifies the unique sample identifier in pixel_coords_sf (defaults to "sample_id" as generated by lsat_get_pixel_centers).
chunks_from	Column name in pixel_coords_sf to divide the exports into chunks. Over-rides chunk division by size (see max_chunk_size).
this_chunk_only	Name of a specific chunk to be exported. Useful for re-exporting a single chunk should the export fail for some reason.
max_chunk_size	Maximum number of sample coordinates to be exported in each chunk. Defaults to 250.
drive_export_dir	Folder on the user's Google Drive to export the records to. Defaults to "lsatTS_export".
file_prefix	Optional file_prefix for the exported files.
start_doy	Optional first day of year to extract for. Defaults to 152.
end_doy	Optional last day of year to extract for. Defaults to 243.
start_date	Optional extraction start date (as string, format YYYY-MM-DD). Defaults to "1984-01-01".
end_date	Optional extraction end date (as string, format YYYY-MM-DD). Defaults to today's date.
buffer_dist	Buffer distance around sample coordinates. Wrapper for lsat_get_pixel_centers() to find all Landsat pixel centers around each point in pixel_coords_sf within the specified buffer distance (square)). Can be slow if the number of points is large. Defaults to 0 m.
scale	scale for extraction. Defaults to 30 m nominal Landsat pixel size.
mask_value	Optional masking value for global surface water mask. Defaults to 0.

Value

List of initiated rgee tasks.

Author(s)

Jakob J. Assmann and Richard Massey

Examples

# Only run example if "rgee" is installed
if (requireNamespace("rgee", quietly = TRUE)) { 

# Using sf, dplyr and rgee
library(sf)
library(dplyr)
library(rgee)

# Initialize GEE
ee_Initialize()

# Generate test points
test_points_sf <- st_sfc(st_point(c(-149.6026, 68.62574)),
                         st_point(c(-149.6003, 68.62524)),
                         st_point(c(-75.78057, 78.87038)),
                         st_point(c(-75.77098, 78.87256)),
                         st_point(c(-20.56182, 74.47670)),
                         st_point(c(-20.55376, 74.47749)), crs = 4326) %>%
  st_sf() %>%
  mutate(sample_id = c("toolik_1",
                      "toolik_2",
                      "ellesmere_1",
                      "ellesmere_1",
                      "zackenberg_1",
                      "zackenberg_2"),
         region = c("toolik", "toolik",
                    "ellesmere", "ellesmere",
                    "zackenberg", "zackenberg"))

# Export time-series using lsat_export_ts()
task_list <- lsat_export_ts(test_points_sf)

# Export time-series using with a chunk size of 2
task_list <- lsat_export_ts(test_points_sf, max_chunk_size = 2)

# Export time-series in chunks by column
task_list <- lsat_export_ts(test_points_sf, chunks_from = "region")

# Closing bracket for the "rgee" check   
}

logan-berner/lsatTS documentation built on Oct. 21, 2024, 12:23 a.m.