Package 'rGEDI'

Description

The rGEDI package provides functions for i) downloading, ii) visualizing, iii) clipping, iv) gridding, iv) simulating and v) exporting GEDI data.

Note

See more details about GEDI data in https://gedi.umd.edu/dataproducts/products/.

Author(s)

Carlos A. Silva, Caio Hamamura, Ruben Valbuena, Steve Hancock, Adrian Cardil, Eben N. Broadbent, Danilo R. A. de Almeida, Celso H. L. Silva Junior and Carine Klauberg

See Also

For comprehensive examples refer to https://github.com/carlos-alberto-silva/rGEDI/blob/master/README.md

Description

Add an Earth Engine image to a Leaflet map

Usage

addEEImage(
  map,
  image,
  bands = NULL,
  min = 0,
  max = 1,
  palette = NULL,
  group = NULL,
  ...
)

Arguments

Value

A Leaflet widget.

Description

Aggregate a GEDI Level 3 raster

Usage

aggregateLevel3(x, fact, fun = mean, ...)

Arguments

Value

A terra::SpatRaster.

Description

Aggregate a GEDI Level 4B raster

Usage

aggregateLevel4B(x, fact, fun = mean, ...)

Arguments

Value

A terra::SpatRaster.

Description

Earth Engine terrain aspect

Usage

aspect(x)

Arguments

Value

An Earth Engine image.

Description

Train a regression forest in Earth Engine

Usage

build_ee_forest(training, response, predictors, trees = 500L, seed = 1L)

Arguments

Value

A trained Earth Engine classifier configured for regression.

Description

clip() provides one clipping interface for open GEDI HDF5 products, extracted footprint tables, and GEDI Level 3 or Level 4B rasters. It follows the workflow used by ICESat2VegR while retaining rGEDI's coordinate order.

Usage

clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level1b,numeric'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level1b,SpatExtent'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level1b,ANY'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level2a,numeric'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level2a,SpatExtent'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level2a,ANY'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level2b,numeric'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level2b,SpatExtent'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level2b,ANY'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level4a,numeric'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level4a,SpatExtent'
clip(x, clip_obj, ...)

## S4 method for signature 'gedi.level4a,ANY'
clip(x, clip_obj, ...)

## S4 method for signature 'data.frame,numeric'
clip(x, clip_obj, ...)

## S4 method for signature 'data.frame,SpatExtent'
clip(x, clip_obj, ...)

## S4 method for signature 'data.frame,ANY'
clip(x, clip_obj, ...)

## S4 method for signature 'SpatRaster,ANY'
clip(x, clip_obj, ...)

Arguments

Details

Extracted tables are recognized from standard GEDI coordinates: longitude_bin0/latitude_bin0, lon_lowestmode/lat_lowestmode, or longitude/latitude. When the corresponding longitude_lastbin and latitude_lastbin fields exist, both waveform endpoints must fall inside a numeric extent.

This function masks graphics::clip(). Use graphics::clip() explicitly when changing a base graphics clipping region.

Value

The return type follows x. Open Level 1B, 2A, 2B, and 4A HDF5 inputs return clipped open GEDI objects; footprint tables return a data.table::data.table; and Level 3/4B rasters return a terra::SpatRaster. Geometry clipping with split_by returns a named list of HDF5-backed GEDI objects, one per polygon ID.

Examples

footprints <- data.frame(
  shot_number = 1:3,
  lon_lowestmode = c(-44.13, -44.12, -44.10),
  lat_lowestmode = c(-13.74, -13.73, -13.70)
)
clip(footprints, c(-44.14, -44.11, -13.75, -13.72))

Description

This function clips GEDI Level1B data (geolocated waveforms) within a given bounding coordinates

Usage

clipLevel1B(level1b, xmin, xmax, ymin, ymax, output)

Arguments

Value

Returns a list of S4 objects of class gedi.level1b containing clipped GEDI Level1B data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi01-b-002

Examples

## Not run: 
# Specifying the path to GEDI level1B data (zip file)
outdir <- tempdir()

level1B_fp_zip <- system.file("extdata",
  "GEDI01_B_2019108080338_O01964_T05337_02_003_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level1B data
level1Bpath <- unzip(level1B_fp_zip, exdir = outdir)

# Reading GEDI level1B data (h5 file)
level1b <- readLevel1B(level1Bpath = level1Bpath)

# Bounding rectangle coordinates
xmin <- -44.13
xmax <- -44.12
ymin <- -13.74
ymax <- -13.73

# Specifying output file and path
output <- file.path(outdir, "GEDI01_B_2019108080338_O01964_T05337_02_003_01_clip")

# Clipping GEDI Level1B data by extent boundary box
level1b_clip <- clipLevel1B(level1b, xmin, xmax, ymin, ymax, output)

close(level1b)
close(level1b_clip)

## End(Not run)

Description

This function clips GEDI level1B extracted geolocation (getLevel1BGeo()) data a within given bounding coordinates

Usage

clipLevel1BGeo(level1BGeo, xmin, xmax, ymin, ymax)

Arguments

Value

Returns an S4 object of class data.table::data.table.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi01-b-002

Examples

# Specifying the path to GEDI level1B data (zip file)
outdir <- tempdir()
level1B_fp_zip <- system.file("extdata",
  "GEDI01_B_2019108080338_O01964_T05337_02_003_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level1B data
level1Bpath <- unzip(level1B_fp_zip, exdir = outdir)

# Reading GEDI level1B data (h5 file)
level1b <- readLevel1B(level1Bpath = level1Bpath)

# Extracting GEDI Full Waveform Geolocations
level1bGeo <- getLevel1BGeo(level1b)

# Bounding rectangle coordinates
xmin <- -44.15036
xmax <- -44.10066
ymin <- -13.75831
ymax <- -13.71244

# Clipping GEDI Full Waveform Geolocations by boundary box extent
level1bGeo_clip <- clipLevel1BGeo(level1bGeo, xmin, xmax, ymin, ymax)

if (interactive() && requireNamespace("leaflet", quietly = TRUE)) {
  library(leaflet)
  leaflet() %>%
    addCircleMarkers(level1bGeo_clip$longitude_bin0,
      level1bGeo_clip$latitude_bin0,
      radius = 1,
      opacity = 1,
      color = "red"
    ) %>%
    addScaleBar(options = list(imperial = FALSE)) %>%
    addProviderTiles(providers$Esri.WorldImagery)
}

close(level1b)

Description

This function clips level1BGeo extracted geolocation (level1BGeo) data within a given geometry

Usage

clipLevel1BGeoGeometry(level1BGeo, polygon, split_by = "id")

Arguments

Value

Returns an S4 object of class data.table::data.table containing the clipped GEDI level1B extracted geolocations.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi01-b-002

Examples

# Specifying the path to GEDI level1B data (zip file)
outdir <- tempdir()
level1B_fp_zip <- system.file("extdata",
  "GEDI01_B_2019108080338_O01964_T05337_02_003_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level1B data
level1Bpath <- unzip(level1B_fp_zip, exdir = outdir)

# Reading GEDI level1B data (h5 file)
level1b <- readLevel1B(level1Bpath = level1Bpath)

# Extracting GEDI Full Waveform Geolocations
level1BGeo <- getLevel1BGeo(level1b, beams = "BEAM0001")

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Clipping GEDI Full Waveform Geolocations by Geometry
level1BGeo_clip <- clipLevel1BGeoGeometry(level1BGeo, polygon, split_by = "id")

if (interactive() && requireNamespace("leaflet", quietly = TRUE)) {
  library(leaflet)
  leaflet() %>%
    addCircleMarkers(level1BGeo_clip$longitude_bin0,
      level1BGeo_clip$latitude_bin0,
      radius = 1,
      opacity = 1,
      color = "red"
    ) %>%
    addScaleBar(options = list(imperial = FALSE)) %>%
    addPolygons(
      data = polygon, weight = 1, col = "white",
      opacity = 1, fillOpacity = 0
    ) %>%
    addProviderTiles(providers$Esri.WorldImagery)
}

close(level1b)

Description

This function clips GEDI Level1B (geolocated waveforms) data within a given bounding geometry

Usage

clipLevel1BGeometry(level1b, polygon, output = "", split_by = NULL)

Arguments

Value

Returns a list of S4 object of class gedi.level1b containing clipped GEDI Level1B data.

Examples

## Not run: 
outdir <- tempdir()

# Specifying the path to GEDI level1B data (zip file)
level1B_fp_zip <- system.file("extdata",
  "GEDI01_B_2019108080338_O01964_T05337_02_003_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level1B data
level1Bpath <- unzip(level1B_fp_zip, exdir = outdir)

# Reading GEDI level1B data (h5 file)
level1b <- readLevel1B(level1Bpath = level1Bpath)

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Spepecifing output file and path
output <- file.path(outdir, "GEDI01_B_2019108080338_O01964_T05337_02_003_01_clip")

# clipping GEDI Level1B data by extent boundary box
level1b_clip <- clipLevel1BGeometry(level1b,
  polygon = polygon,
  output = output,
  split_by = "id"
)

close(level1b)
lapply(level1b_clip, close)

## End(Not run)

Description

This function clips GEDI Level2A data within a given bounding coordinates

Usage

clipLevel2A(level2a, xmin, xmax, ymin, ymax, output)

Arguments

Value

Returns a list of S4 objects of class "gedi.level2a" containing clipped GEDI Level2A data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-a-002

Examples

## Not run: 
outdir <- tempdir()

# Specifying the path to GEDI level2A data (zip file)
level2A_fp_zip <- system.file("extdata",
  "GEDI02_A_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Apath <- unzip(level2A_fp_zip, exdir = outdir)

# Reading GEDI level2A data (h5 file)
level2a <- readLevel2A(level2Apath = level2Apath)

# Bounding rectangle coordinates
xmin <- -44.13
xmax <- -44.12
ymin <- -13.74
ymax <- -13.73

print(level2a)

# Specifying output file and path
output <- file.path(outdir, "GEDI02_A_2019108080338_O01964_T05337_02_001_01_clip.h5")

# Clipping GEDI Level2A data by boundary box extent
level2a_clip <- clipLevel2A(level2a, xmin, xmax, ymin, ymax, output)

close(level2a)
close(level2a_clip)

## End(Not run)

Description

This function clips GEDI Level2A data within a given geometry

Usage

clipLevel2AGeometry(level2a, polygon, output = "", split_by = NULL)

Arguments

Value

Returns a list of S4 object of class "gedi.level2a" containing clipped GEDI Level2A data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-a-002

Examples

## Not run: 
outdir <- tempdir()

# Specifying the path to GEDI level2A data (zip file)
level2A_fp_zip <- system.file("extdata",
  "GEDI02_A_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Apath <- unzip(level2A_fp_zip, exdir = outdir)

# Reading GEDI level2A data (h5 file)
level2a <- readLevel2A(level2Apath = level2Apath)

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Specifying output file and path
output <- file.path(outdir, "GEDI02_A_2019108080338_O01964_T05337_02_001_01_clip")

# Clipping GEDI Level2A data by geometry
level2a_clip <- clipLevel2AGeometry(level2a,
  polygon = polygon,
  output = output,
  split_by = "id"
)
close(level2a)
lapply(level2a_clip, close)

## End(Not run)

Description

This function clips GEDI Level2A extracted Elevation and Height Metrics (Level2AM) within a given bounding coordinates

Usage

clipLevel2AM(level2AM, xmin, xmax, ymin, ymax)

Arguments

Value

Returns an S4 object of class data.table::data.table containing the clipped elevation and relative heights metrics.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-a-002

Examples

# Specifying the path to GEDI level2A data (zip file)
outdir <- tempdir()
level2A_fp_zip <- system.file("extdata",
  "GEDI02_A_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Apath <- unzip(level2A_fp_zip, exdir = outdir)

# Reading GEDI level2A data (h5 file)
level2a <- readLevel2A(level2Apath = level2Apath)

# Extracting GEDI Elevation and Height Metrics
level2AM <- getLevel2AM(level2a, beams = "BEAM0001")

# Bounding rectangle coordinates
xmin <- -44.15036
xmax <- -44.10066
ymin <- -13.75831
ymax <- -13.71244

# Clipping GEDI data by boundary box extent
level2AM_clip <- clipLevel2AM(level2AM, xmin, xmax, ymin, ymax)

close(level2a)

Description

This function clips GEDI Level2A extracted Elevation and Height Metrics (Level2AM) within a given bounding coordinates

Usage

clipLevel2AMGeometry(level2AM, polygon, split_by = "id")

Arguments

Value

Returns an S4 object of class data.table::data.table containing the clipped elevation and relative heights metrics.

Examples

# Specifying the path to GEDI level2A data (zip file)
outdir <- tempdir()
level2A_fp_zip <- system.file("extdata",
  "GEDI02_A_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Apath <- unzip(level2A_fp_zip, exdir = outdir)

# Reading GEDI level2A data (h5 file)
level2a <- readLevel2A(level2Apath = level2Apath)

# Extracting GEDI Elevation and Height Metrics
level2AM <- getLevel2AM(level2a, beams = "BEAM0001")

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Clipping GEDI data by Geometry
level2AM_clip <- clipLevel2AMGeometry(level2AM, polygon, split_by = "id")

hasLeaflet <- require(leaflet)

if (hasLeaflet) {
  leaflet() %>%
    addCircleMarkers(level2AM_clip$lat_lowestmode,
      level2AM_clip$lon_lowestmode,
      radius = 1,
      opacity = 1,
      color = "red"
    ) %>%
    addScaleBar(options = list(imperial = FALSE)) %>%
    addPolygons(
      data = polygon, weight = 1, col = "white",
      opacity = 1, fillOpacity = 0
    ) %>%
    addProviderTiles(providers$Esri.WorldImagery)
}

close(level2a)

Description

This function extracts GEDI Level1B data a within given bounding coordinates

Usage

clipLevel2B(level2b, xmin, xmax, ymin, ymax, output = "")

Arguments

Value

Returns a list of S4 object of class "gedi.level2b" containing clipped GEDI Level2B data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi01-b-002

Examples

## Not run: 
outdir <- tempdir()

# Specifying the path to GEDI level2B data (zip file)
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Bounding rectangle coordinates
xmin <- -44.13
xmax <- -44.12
ymin <- -13.74
ymax <- -13.73

# Specifying output file and path
output <- file.path(outdir, "GEDI02_B_2019108080338_O01964_T05337_02_001_01_clip")

# Clipping GEDI data by extent boundary box
level2b_clip <- clipLevel2B(level2b, xmin, xmax, ymin, ymax)

close(level2b)
close(level2b_clip)

## End(Not run)

Description

This function extracts GEDI Level1B data within a given geometry

Usage

clipLevel2BGeometry(level2b, polygon, output = "", split_by = NULL)

Arguments

Value

Returns a list of S4 objects of class "gedi.level2b" containing clipped GEDI Level2B data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi01-b-002

Examples

## Not run: 
outdir <- tempdir()

# Specifying the path to GEDI level2B data (zip file)
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Specifying output file and path
output <- file.path(outdir, "GEDI02_B_2019108080338_O01964_T05337_02_001_01_clip")

# Clipping GEDI data by extent boundary box
level2b_clip <- clipLevel2BGeometry(level2b,
  polygon = polygon,
  output = output,
  split_by = "id"
)

close(level2b)
lapply(level2b_clip, close)

## End(Not run)

Description

This function clips GEDI level2B derived Plant Area Index profile a within given bounding coordinates

Usage

clipLevel2BPAIProfile(level2BPAIProfile, xmin, xmax, ymin, ymax)

Arguments

Value

Returns an S4 object of class data.table::data.table containing the Plant Area Index profile data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# Specifying the path to GEDI level2B data (zip file)
outdir <- tempdir()
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Extracting GEDI Plant Area Index profile
level2BPAIProfile <- getLevel2BPAIProfile(level2b)

# Bounding rectangle coordinates
xmin <- -44.15036
xmax <- -44.10066
ymin <- -13.75831
ymax <- -13.71244

# Clipping GEDI Plant Area Index profile by extent boundary box
level2b_clip <- clipLevel2BPAIProfile(level2BPAIProfile, xmin, xmax, ymin, ymax)

close(level2b)

Description

This function clips GEDI level2B derived Plant Area Index profile within a given geometry

Usage

clipLevel2BPAIProfileGeometry(level2BPAIProfile, polygon, split_by = NULL)

Arguments

Value

Returns an S4 object of class data.table::data.table containing the Plant Area Index profile data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# Specifying the path to GEDI level2B data (zip file)
outdir <- tempdir()
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Extracting GEDI Plant Area Index profile
level2BPAIProfile <- getLevel2BPAIProfile(level2b)

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Clipping GEDI Plant Area Index profile by geometry
level2b_clip_geometry <- clipLevel2BPAIProfileGeometry(
  level2BPAIProfile,
  polygon,
  split_by = "id"
)

close(level2b)

Description

This function clips GEDI level2B derived Plant Area Volume Density profile within a given bounding coordinates

Usage

clipLevel2BPAVDProfile(level2BPAVDProfile, xmin, xmax, ymin, ymax)

Arguments

Value

Returns an S4 object of class data.table::data.table containing the Plant Area Volume Density profile data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# specify the path to GEDI level2B data (zip file)
outdir <- tempdir()
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Extracting GEDI Plant Area Volume Density profile
level2BPAVDProfile <- getLevel2BPAVDProfile(level2b)

# Bounding rectangle coordinates
xmin <- -44.15036
xmax <- -44.10066
ymin <- -13.75831
ymax <- -13.71244

# Clipping GEDI Plant Area Volume Density profile by boundary box extent
level2BPAVDProfile_clip <- clipLevel2BPAVDProfile(level2BPAVDProfile, xmin, xmax, ymin, ymax)

close(level2b)

Description

This function clips GEDI level2B derived Plant Area Index profile within a given geometry

Usage

clipLevel2BPAVDProfileGeometry(level2BPAVDProfile, polygon, split_by = NULL)

Arguments

Value

Returns an S4 object of class data.table::data.table containing the Plant Area Volume Density profile data.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# Specifying the path to GEDI level2B data (zip file)
outdir <- tempdir()
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Extracting GEDI Plant Area Volume Density profile
level2BPAVDProfile <- getLevel2BPAVDProfile(level2b)

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Clipping GEDI Plant Area Volume Density profile by geometry
level2BPAVDProfile_clip <- clipLevel2BPAVDProfileGeometry(
  level2BPAVDProfile,
  polygon,
  split_by = "id"
)

close(level2b)

Description

This function clips GEDI level2B derived Canopy Cover and Vertical Profile metrics a within given bounding coordinates

Usage

clipLevel2BVPM(level2BVPM, xmin, xmax, ymin, ymax)

Arguments

Value

Returns an S4 object of class data.table::data.table containing the Canopy Cover and Vertical Profile metrics.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# Specifying the path to GEDI level2B data (zip file)
outdir <- tempdir()
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Extracting canopy cover and vertical profile metrics
beam <- grep("^BEAM", (level2b@h5)$ls(recursive = FALSE)$name,
             value = TRUE)[1]
level2BVPM <- getLevel2BVPM(level2b, beams = beam)

# Bounding rectangle coordinates
xmin <- -44.15036
xmax <- -44.10066
ymin <- -13.75831
ymax <- -13.71244

# Clipping level2BVPM by extent boundary box
level2b_clip <- clipLevel2BVPM(level2BVPM, xmin, xmax, ymin, ymax)

hasLeaflet <- require(leaflet)

if (hasLeaflet) {
  leaflet() %>%
    addCircleMarkers(level2b_clip$longitude_bin0,
      level2b_clip$latitude_bin0,
      radius = 1,
      opacity = 1,
      color = "red"
    ) %>%
    addScaleBar(options = list(imperial = FALSE)) %>%
    addProviderTiles(providers$Esri.WorldImagery)
}

close(level2b)

Description

This function clips GEDI level2B derived Canopy Cover and Vertical Profile metrics within a given geometry

Usage

clipLevel2BVPMGeometry(level2BVPM, polygon, split_by = NULL)

Arguments

Value

Returns an S4 object of class data.table::data.table containing the Canopy Cover and Vertical Profile metrics.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# Specifying the path to GEDI level2B data (zip file)
outdir <- tempdir()
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Extracting canopy cover and vertical profile metrics
beam <- grep("^BEAM", (level2b@h5)$ls(recursive = FALSE)$name,
             value = TRUE)[1]
level2BVPM <- getLevel2BVPM(level2b, beams = beam)

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Clipping level2BVPM by geometry
level2b_clip_geometry <- clipLevel2BVPMGeometry(level2BVPM, polygon, split_by = "id")

hasLeaflet <- require(leaflet)

if (hasLeaflet) {
  leaflet() %>%
    addCircleMarkers(level2b_clip_geometry$longitude_bin0,
      level2b_clip_geometry$latitude_bin0,
      radius = 1,
      opacity = 1,
      color = "red"
    ) %>%
    addScaleBar(options = list(imperial = FALSE)) %>%
    addPolygons(
      data = polygon, weight = 1, col = "white",
      opacity = 1, fillOpacity = 0
    ) %>%
    addProviderTiles(providers$Esri.WorldImagery)
}

close(level2b)

Description

Clip a GEDI Level 3 raster

Usage

clipLevel3(x, y, filename = "", overwrite = FALSE)

Arguments

Value

A terra::SpatRaster.

Description

Clip GEDI Level 4A data by an extent

Usage

clipLevel4A(level4A, xmin, xmax, ymin, ymax, output = "")

Arguments

Value

A clipped gedi.level4a object for HDF5 input, or a data.table::data.table for table input.

Description

Clip GEDI Level 4A data by polygons

Usage

clipLevel4AGeometry(level4A, polygon, split_by = NULL, output = "")

Arguments

Value

A clipped gedi.level4a object (or a named list when split_by is used) for HDF5 input, or a data.table::data.table for table input.

Description

Clip a GEDI Level 4B raster

Usage

clipLevel4B(x, y, filename = "", overwrite = FALSE)

Arguments

Value

A terra::SpatRaster.

Safely closes the gedi.level1b

Description

Closing files will avoid locking HDF5 GEDI files.

Closing files will avoid locking HDF5 GEDI files.

Closing files will avoid locking HDF5 GEDI files.

Usage

## S4 method for signature 'gedi.level1b'
close(con, ...)

## S4 method for signature 'gedi.level2a'
close(con, ...)

## S4 method for signature 'gedi.level2b'
close(con, ...)

## S4 method for signature 'gedi.level4a'
close(con, ...)

Arguments

Description

Close a cloud HDF5 connection

Usage

## S3 method for class 'gedi.cloud_h5'
close(con, ...)

Arguments

Value

Invisibly returns NULL.

Description

Uses an existing bearer token, environment credentials, or .netrc file.

Usage

earthdata_login(persist = TRUE, netrc = Sys.getenv("NETRC", unset = ""))

Arguments

Value

Invisibly returns TRUE after successful authentication.

Description

Requests short-lived AWS credentials from Earthaccess and exports them for GDAL/terra. Direct S3 access to GEDI is available from AWS us-west-2.

Usage

earthdata_s3_credentials(daac = "ORNL")

Arguments

Value

Invisibly returns the credential list.

Description

Build an AlphaEarth and terrain predictor stack

Usage

ee_build_AlphaEarth_embedding_terrain_stack(
  geom,
  start_year,
  end_year,
  add_lonlat = TRUE
)

Arguments

Value

An Earth Engine image.

Description

Build an HLS and terrain predictor stack in Earth Engine

Usage

ee_build_hls_s1c_terrain_stack(
  x,
  start_date,
  end_date,
  cloud_max = 20,
  buffer_m = 30
)

Arguments

Value

An Earth Engine image.

Description

Check an Earth Engine task

Usage

ee_check_task_status(task, quiet = TRUE)

Arguments

Value

Task status list.

Description

Creates a Google Earth Engine batch export task for a GeoTIFF in Google Drive. This is useful for images that exceed the direct download limit.

Usage

ee_image_to_drive(
  image,
  description = "rGEDI_export",
  folder = "EE_Exports",
  file_name_prefix = description,
  region,
  scale = 30,
  crs = "EPSG:4326",
  max_pixels = 1e+13,
  start = TRUE,
  ...
)

Arguments

Value

An Earth Engine batch task. Use ee_check_task_status() to monitor it.

Description

Initialize Google Earth Engine

Usage

ee_initialize(
  project = Sys.getenv("EE_PROJECT", unset = ""),
  authenticate = TRUE,
  quiet = FALSE
)

Arguments

Value

Invisibly returns the Python Earth Engine module.

Description

Convert an Earth Engine rectangle to sf

Usage

ee_rect_to_sf(aoi)

Arguments

Value

An sf polygon.

Description

Convert an extent to an Earth Engine geometry

Usage

ext_to_ee(x)

Arguments

Value

An Earth Engine geometry.

Description

Extract Earth Engine image values at GEDI footprints

Usage

extractEE(stack, geom, scale = 30, chunk_size = 1000L)

extractGEDIAncillary(stack, geom, scale = 30, chunk_size = 1000L)

Arguments

Value

A data.table::data.table.

Description

Extract GEDI Level 3 raster values

Usage

extractLevel3(x, y, ...)

Arguments

Value

A data frame.

Description

Extract GEDI Level 4B raster values

Usage

extractLevel4B(x, y, ...)

Arguments

Value

A data frame.

Description

Model fit metrics

Usage

fit_metrics(observed, predicted, plotstat = FALSE, unit = "", ...)

Arguments

Value

A data frame of accuracy statistics.

Description

Fit a GEDI statistical or random-forest model

Usage

fit_model(
  x,
  y,
  method = c("randomForest", "lm"),
  test = c("none", "split", "kfold", "loocv", "bootstrap"),
  k = 5L,
  test_size = 0.3,
  iterations = 100L,
  seed = NULL,
  ...
)

Arguments

Value

An object of class gedi_model.

Description

Class for GEDI level1B Full Waveform

Slots

dt

Object of class data.table from data.table package containing the extracted GEDI full-waveform elevation and amplitude.

Description

Class for GEDI level1B

Slots

h5

A local H5File or a cloud-backed GEDI HDF5 connection containing geolocated waveforms.

See Also

H5File in the hdf5r package and https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi01-b-002

Description

Class for GEDI level2A

Slots

h5

A local H5File or cloud-backed GEDI HDF5 connection containing ground elevation, canopy top height, and relative heights (RH).

See Also

H5File in the hdf5r package and https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-a-002

Description

Class for GEDI level2B

Slots

h5

A local H5File or cloud-backed GEDI HDF5 connection containing canopy cover, PAI, PAVD, and FHD.

See Also

H5File in the hdf5r package and https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Description

Class for GEDI Level 4A footprint biomass data

Slots

h5

An open local or cloud-backed HDF5 connection containing a GEDI04_A granule.

See Also

https://daac.ornl.gov/GEDI/guides/GEDI_L4A_AGB_Density_V3.html

Description

Download GEDI data from LP DAAC Data Pool. Users will need to enter their Earth Explore login Information for downloading the data.

Usage

gediDownload(
  filepath,
  outdir = NULL,
  overwrite = FALSE,
  buffer_size = 512,
  timeout = 10,
  netrc = Sys.getenv("NETRC", unset = "")
)

downloadGEDI(
  filepath,
  outdir = NULL,
  overwrite = FALSE,
  buffer_size = 512,
  timeout = 10,
  netrc = Sys.getenv("NETRC", unset = "")
)

Arguments

Value

The normalized paths of the downloaded files, invisibly. On failure the function stops with an error.

References

Credits to Cole Krehbiel. Code adapted from https://git.earthdata.nasa.gov/projects/LPDUR/repos/daac_data_download_r/browse/DAACDataDownload.R

Examples

## Not run: 
# Set path to GEDI data
# herein we will only download xml metedata
filepath=c(paste0(
                 "https://e4ftl01.cr.usgs.gov/GEDI/GEDI02_B.001",
                 "/2019.04.18/GEDI02_B_2019108032534_O01961_T03911_02_001_01.h5.xml"
                 ),
          paste0("https://e4ftl01.cr.usgs.gov/GEDI/GEDI02_B.001",
                 "/2019.04.18/GEDI02_B_2019108045815_O01962_T01066_02_001_01.h5.xml"
                )
         )

# Set dir to download files to
outdir=tempdir()

# Create .netrc file
netrc = file.path(outdir, ".netrc")
netrc_conn <- file(netrc)

writeLines(c("machine urs.earthdata.nasa.gov",
            sprintf("login %s", Sys.getenv("NASA_USER")),
            sprintf("password %s", Sys.getenv("NASA_PASSWORD"))
), netrc_conn)

close(netrc_conn)

#' Downloading GEDI data
gediDownload(filepath,outdir)

## End(Not run)

Description

Open a GEDI product in Google Earth Engine

Usage

gediEE(
  product = names(.gedi_ee_catalog),
  start_date = NULL,
  end_date = NULL,
  aoi = NULL,
  quality = TRUE,
  max_granules = 200L
)

Arguments

Value

An Earth Engine image, image collection, or feature collection.

Description

Find GEDI granules through NASA CMR

Usage

gedifinder(
  product,
  ul_lat = NULL,
  ul_lon = NULL,
  lr_lat = NULL,
  lr_lon = NULL,
  version = NULL,
  daterange = NULL,
  access = c("https", "s3", "opendap", "all"),
  cloud_hosted = TRUE,
  return = c("url", "table"),
  page_size = 2000L,
  cloud_computing = FALSE,
  persist = TRUE,
  orbit = NULL
)

Arguments

Value

A character vector or data.table::data.table.

See Also

https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html

Description

Compute metrics from GEDI or simulated full waveforms

Usage

gediWFMetrics(
  input,
  outRoot = NULL,
  rhRes = 5,
  ground = TRUE,
  rhoG = 0.4,
  rhoC = 0.57,
  ground_method = c("auto", "truth", "lowest_peak", "quantile"),
  ...
)

Arguments

Value

A data.table::data.table with waveform metrics.

Description

This portable implementation follows the core gediRat algorithm: Gaussian footprint weighting, optional return-density normalization, vertical binning, pulse convolution, separation of LAS class 2 ground returns, and unit-integral normalization. Vectorized binning replaces the original point loop while avoiding its native GSL/GDAL build stack.

Usage

gediWFSimulator(
  input,
  output = tempfile(fileext = ".h5"),
  ground = TRUE,
  ascii = FALSE,
  waveID = NULL,
  coords = NULL,
  listCoord = NULL,
  gridBound = NULL,
  gridStep = 30,
  pSigma = -1,
  pFWHM = 15,
  fSigma = 5.5,
  res = 0.15,
  decimate = 1,
  maxBins = 1024L,
  countOnly = FALSE,
  method = c("count", "intensity", "fraction"),
  normalize = TRUE,
  density_res = 1,
  intensity_threshold = 6e-04,
  noise = 0,
  keepOld = FALSE,
  seed = NULL,
  ...
)

Arguments

Value

A gedi.level1b object, or a waveform table when ascii=TRUE.

References

Hancock et al. (2019) doi:10.1029/2018EA000506

Description

GEDI polygon-stratified sampling specification

Usage

geomSampling(size, geom, split_id = NULL, lon = NULL, lat = NULL)

Arguments

Description

Return an Earth Engine catalog ID

Usage

get_catalog_id(x)

Arguments

Value

A character catalog ID.

Description

Standardizes footprint coordinates, acquisition order, and beam identifiers from any open point-level GEDI product or an extracted footprint table. The result can be plotted directly or passed to plot_gedi_orbit_animation().

Usage

getGEDITrack(
  x,
  lon = NULL,
  lat = NULL,
  time = NULL,
  track = NULL,
  beams = NULL,
  every = 1L,
  segment_gaps = TRUE
)

Arguments

Value

A data.table::data.table with longitude, latitude, sequence, track, and available time and shot identifiers.

Examples

shots <- data.frame(
  lon_lowestmode = seq(-44.2, -44.1, length.out = 10),
  lat_lowestmode = seq(-13.8, -13.7, length.out = 10),
  delta_time = seq_len(10), beam = "BEAM0000"
)
getGEDITrack(shots, every = 2)

Description

This function extracts Pulse Full Waveform Geolocations from GEDI gedi.level1b data

Usage

getLevel1BGeo(
  level1b,
  select = c("elevation_bin0", "elevation_lastbin"),
  beams = NULL
)

Arguments

Details

Additional fields to be extracted from GEDI level 1B:

• all_samples_sum Sum of all values within the 10 km range window.

• beam Beam number Number.

• channel Channel number.

• master_frac Master time, fractional part.

• master_int Master time, integer part.

• noise_mean_corrected Noise mean.

• noise_stddev_corrected Corrected noise standard deviation.

• nsemean_even Noise mean of the beam's detector channel from even sub-converter.

• nsemean_odd Noise mean of the beam's odd sub-converter.

• rx_energy Integrated energy in receive (RX) waveform after subtracting the noise mean.

• rx_offset Time interval from first stored sample to first downloaded RX sample.

• rx_open Time interval from time 0 to first stored RX sample.

• rx_sample_count The number of sample intervals (elements) in each RX waveform.

• rx_sample_start_index The index in the rxwaveform dataset of the first element of each RX waveform starting at 1.

• selection_stretchers_x Commanded number of samples added to the algorithm section on the left.

• selection_stretchers_y Commanded number of samples added to the algorithm section on the right.

• shot_number Unique shot identifier.

• stale_return_flag Indicates that a "stale" cue point from the coarse search algorithm is being used.

• th_left_used Count values for the left threshold used in fine search where two consecutive points at or above this value indicate pulse detection.

• tx_egamplitude Amplitude of the extended Gaussian fit to the transmit (TX) waveform.

• tx_egamplitude_error Error on tx_egamplitude.

• tx_egbias Bias of the extended Gaussian fit to the TX waveform.

• tx_egbias_error Error on tx_egbias.

• tx_egflag Extended Gaussian fit status flag.

• tx_eggamma Gamma value of the extended Gaussian fit to the TX waveform.

• tx_eggamma_error Error on tx_eggamma.

• tx_egsigma Sigma of the extended Gaussian fit to the TX waveform.

• tx_egsigma_error Error on tx_egsigma.

• tx_gloc Location (mean) of the Gaussian fit to the TX waveform.

• tx_gloc_error Error on tx_gloc.

• tx_pulseflag Set to 1 if a pulse is detected in the TX waveform.

• tx_sample_count The number of sample intervals (elements) in each transmit waveform.

• tx_sample_start_index The index in the rxwaveform dataset of the first element of each RX waveform starting at 1.

• altitude_instrument Height of the instrument diffractive optical element (DOE) above the WGS84 ellipsoid.

• altitude_instrument_error Error on altitude_instrument.

• bounce_time_offset_bin0 The difference between the TX time and the time at the start of the RX window.

• bounce_time_offset_bin0_error Error on bounce_time_offset_bin0.

• bounce_time_offset_lastbin The difference between the TX time and the time at the end of the RX window.

• bounce_time_offset_lastbin_error Error on bounce_time_offset_lastbin.

• degrade Greater than zero if the shot occurs during a degrade period, zero otherwise.

• delta_time Transmit time of the shot, measured in seconds since 2018-01-01.

• digital_elevation_model Digital elevation model height above the WGS84 ellipsoid.

• elevation_bin0 Height of the start of the RX window, relative to the WGS-84 ellipsoid.

• elevation_bin0_error Error on elevation_bin0.

• elevation_lastbin Height of the end of the RX window, relative to the WGS-84 ellipsoid.

• elevation_lastbin_error Error on elevation_lastbin.

• latitude_bin0 Latitude of the start of the RX window.

• latitude_bin0_error Error on latitude_bin0.

• latitude_lastbin Latitude of the end of the RX window.

• latitude_lastbin_error Error on latitude_lastbin.

• latitude_instrument Latitude of the instrument diffractive optical element (DOE) at laser transmit time.

• latitude_instrument_error Error on latitude_instrument.

• local_beam_azimuth Azimuth of the unit pointing vector for the laser in the local East, North, Up (ENU) frame.

• local_beam_azimuth_error Error on local_beam_azimuth.

• local_beam_elevation Elevation of the unit pointing vector for the laser in the local ENU frame.

• local_beam_elevation_error Error on local_beam_elevation.

• longitude_bin0 Longitude of the start of the RX window.

• longitude_bin0_error Error on longitude_bin0.

• longitude_lastbin Longitude of the end of the RX window.

• longitude_lastbin_error Error on longitude_lastbin.

• longitude_instrument Longitude of the instrument diffractive optical element (DOE) at laser transmit time.

• longitude_instrument_error Error on longitude_instrument.

• mean_sea_surface Mean sea surface height above the WGS84 ellipsoid, includes the geoid .

• neutat_delay_derivative_bin0 Change in neutral atmospheric delay per height change for the start of the RX window.

• neutat_delay_derivative_lastbin Change in neutral atmospheric delay per height change for the end of the RX window.

• neutat_delay_total_bin0 Total neutral atmosphere delay correction (wet+dry) from the TX pulse to the start of the RX window.

• neutat_delay_total_lastbin Total neutral atmosphere delay correction (wet+dry) from the TX pulse to the end of the RX window.

• range_bias_correction The range bias applied to the range measurement.

• shot_number Unique shot identifier Number.

• solar_azimuth The azimuth of the sun position vector.

• solar_elevation The elevation of the sun position vector.

• surface_type Flags describing which surface types.

• dynamic_atmosphere_correction Dynamic Atmospheric Correction (DAC) includes inverted barometer (IB) effect.

• geoid Geoid height above WGS-84 reference ellipsoid.

• tide_earth Solid Earth tides.

• tide_load Load Tide - Local displacement due to Ocean Loading.

• tide_ocean Ocean Tides including diurnal and semi-diurnal, and longerperiod tides.

• tide_ocean_pole Oceanic surface rotational deformation due to polar motion.

• tide_pole Solid Earth Pole Tide. Rotational deformation due to polar motion.

Value

Returns an S4 object of class data.table::data.table containing the GEDI Full Waveform Geolocations

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi01-b-002

Examples

# specify the path to GEDI level1B data (zip file)
outdir = tempdir()
level1B_fp_zip <- system.file("extdata",
                  "GEDI01_B_2019108080338_O01964_T05337_02_003_01_sub.zip",
                  package="rGEDI")

# Unzipping GEDI level1B data
level1Bpath <- unzip(level1B_fp_zip,exdir = outdir)

# Reading GEDI level1B data (h5 file)
level1b<-readLevel1B(level1Bpath=level1Bpath)

# Extracting GEDI level1B geolocations
level1bGeo<-getLevel1BGeo(level1b,select=c("elevation_bin0", "elevation_lastbin"))
head(level1bGeo)

close(level1b)

Description

This function extracts the full waveform of a given pulse from GEDI Level1B data.

Usage

getLevel1BWF(level1b, shot_number)

Arguments

Details

Shot numbers can be extracted using readLevel1B function.

Value

Returns an S4 object of class "gedi.fullwaveform".

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi01-b-002

Examples

# Specifying the path to GEDI level1B data (zip file)
outdir = tempdir()
level1B_fp_zip <- system.file("extdata",
                  "GEDI01_B_2019108080338_O01964_T05337_02_003_01_sub.zip",
                  package="rGEDI")

# Unzipping GEDI level1B data
level1Bpath <- unzip(level1B_fp_zip,exdir = outdir)

# Reading GEDI level1B data (h5 file)
level1b<-readLevel1B(level1Bpath=level1Bpath)

# Extracting GEDI full waveform for a giving shotnumber
wf <- getLevel1BWF(level1b, shot_number="19640521100108408")

# Plotting GEDI Full waveform
oldpar<-par()
par(mfrow = c(1,2), cex.axis = 1.5)
plot(wf, relative=FALSE, polygon=TRUE, type="l", lwd=2, col="forestgreen",
xlab="Waveform Amplitude", ylab="Elevation (m)")

plot(wf, relative=TRUE, polygon=TRUE, type="l", lwd=2, col="forestgreen",
xlab="Waveform Amplitude (%)", ylab="Elevation (m)")

par(oldpar)
close(level1b)

Description

This function extracts Elevation and Relative Height (RH) metrics from GEDI Level2A data.

Usage

getLevel2AM(level2a, beams = NULL, include_rh = TRUE)

Arguments

Details

Characteristics. Flag indicating likely invalid waveform (1=valid, 0=invalid).

• beam Beam identifier

• shot_number Shot number

• degrade_flag Flag indicating degraded state of pointing and/or positioning information

• quality_flag Flag simplifying selection of most useful data

• delta_time Transmit time of the shot since Jan 1 00:00 2018

• sensitivity Maxmimum canopy cover that can be penetrated

• solar_elevation Solar elevation

• lat_lowestmode Latitude of center of lowest mode

• lon_lowestmode Longitude of center of lowest mode

• elev_highestreturn Elevation of highest detected return relative to reference ellipsoid Meters

• elev_lowestmode Elevation of center of lowest mode relative to reference ellipsoid

• rh Relative height metrics at 1% interval

Value

Returns an S4 object of class data.table::data.table containing the elevation and relative heights metrics.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-a-002

Examples

# Specifying the path to GEDI level2A data (zip file)
outdir = tempdir()
level2A_fp_zip <- system.file("extdata",
                  "GEDI02_A_2019108080338_O01964_T05337_02_001_01_sub.zip",
                  package="rGEDI")

# Unzipping GEDI level2A data
level2Apath <- unzip(level2A_fp_zip,exdir = outdir)

# Reading GEDI level2A data (h5 file)
level2a<-readLevel2A(level2Apath=level2Apath)

# Extracting GEDI Elevation and Height Metrics
level2AM<-getLevel2AM(level2a)
head(level2AM)

close(level2a)

Description

This function extracts the Plant Area Index (PAI) Profile from GEDI Level2B data.

Usage

getLevel2BPAIProfile(level2b, beams = NULL)

Arguments

Details

Characteristics. Flag indicating likely invalid waveform (1=valid, 0=invalid).

• beam Beam identifier

• shot_number Shot number

• algorithmrun_flag The L2B algorithm is run if this flag is set to 1 indicating data have sufficient waveform fidelity for L2B to run

• l2b_quality_flag L2B quality flag

• delta_time Transmit time of the shot since Jan 1 00:00 2018

• lat_lowestmode Latitude of center of lowest mode

• lon_lowestmode Longitude of center of lowest mode

• elev_highestreturn Elevation of highest detected return relative to reference ellipsoid

• elev_lowestmode Elevation of center of lowest mode relative to reference ellipsoid

• height_lastbin Height of the last bin of the pgap_theta_z, relative to the ground

• pai_z Plant Area Index profile

Value

Returns an S4 object of class data.table::data.table containing the elevation and relative heights.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# Specifying the path to GEDI level2B data (zip file)
outdir = tempdir()
level2B_fp_zip <- system.file("extdata",
                  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
                  package="rGEDI")

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip,exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b<-readLevel2B(level2Bpath=level2Bpath)

# Extracting GEDI Plant Area Index (PAI) Profile (GEDI Level2B)
level2BPAIProfile<-getLevel2BPAIProfile(level2b)
head(level2BPAIProfile)

close(level2b)

Description

This function extracts the Plant Area Volume Density (PAVD) Profile from GEDI Level2B data.

Usage

getLevel2BPAVDProfile(level2b, beams = NULL)

Arguments

Details

Characteristics. Flag indicating likely invalid waveform (1=valid, 0=invalid).

• beam Beam identifier

• shot_number Shot number

• algorithmrun_flag The L2B algorithm is run if this flag is set to 1 indicating data have sufficient waveform fidelity for L2B to run

• l2b_quality_flag L2B quality flag

• delta_time Transmit time of the shot since Jan 1 00:00 2018

• lat_lowestmode Latitude of center of lowest mode

• lon_lowestmode Longitude of center of lowest mode

• elev_highestreturn Elevation of highest detected return relative to reference ellipsoid

• elev_lowestmode Elevation of center of lowest mode relative to reference ellipsoid

• height_lastbin Height of the last bin of the pgap_theta_z, relative to the ground

• pavd_z Plant Area Volume Density profile

Value

Returns an S4 object of class data.table::data.table containing the Plant Area Volume Density Index.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# Specifying the path to GEDI level2B data (zip file)
outdir = tempdir()
level2B_fp_zip <- system.file("extdata",
                  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
                  package="rGEDI")

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip,exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b<-readLevel2B(level2Bpath=level2Bpath)

# Extracting GEDI Plant Area Volume Density (PAVD) Index
level2BPAVDProfile<-getLevel2BPAVDProfile(level2b)
head(level2BPAVDProfile)

close(level2b)

Description

This function extracts information from GEDI Level2B data: Total Plant Area Index, Foliage Height Diversity, Foliage Clumping Index, Total Gap Probability (theta), and Total canopy cover.

Usage

getLevel2BVPM(
  level2b,
  cols = c("beam", "shot_number", "algorithmrun_flag", "l2b_quality_flag", "delta_time",
    "sensitivity", "solar_elevation", "latitude_lastbin", "latitude_bin0",
    "longitude_bin0", "longitude_lastbin", "elev_highestreturn", "elev_lowestmode",
    "rh100", "pai", "fhd_normal", "omega", "pgap_theta", "cover"),
  beams = NULL
)

Arguments

Details

These are the biophysical variables and additional information extracted by default:

• beam Beam identifier

• shot_number Shot number

• algorithmrun_flag The L2B algorithm is run if this flag is set to 1 indicating data have sufficient waveform fidelity for L2B to run

• l2b_quality_flag L2B quality flag

• delta_time Transmit time of the shot since Jan 1 00:00 2018

• sensitivity Maxmimum canopy cover that can be penetrated

• solar_elevation Solar elevation

• latitude_lastbin Latitude of last bin of the pgap_theta_z, interpolated from L1B waveform coordinate

• latitude_bin0 Latitude of first bin of the pgap_theta_z, interpolated from L1B waveform coordinate

• elev_highestreturn Elevation of highest detected return relative to reference ellipsoid

• elev_lowestmode Elevation of center of lowest mode relative to reference ellipsoid

• rh100 RH100 slice

• pai Total Plant Area Index

• fhd_normal Foliage Height Diversity

• omega Foliage Clumping Index

• pgap_theta Total Gap Probability (theta)

• cover Total canopy cover

Every other columns in the GEDI2B product are also available, you can specify each column by using the cols parameter.

Value

Returns an S4 object of class data.table::data.table containing the Vegetation Profile Biophysical Variables.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# Specifying the path to GEDI level2B data (zip file)
outdir = tempdir()
level2B_fp_zip <- system.file("extdata",
                  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
                  package="rGEDI")

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip,exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b<-readLevel2B(level2Bpath=level2Bpath)

# Extracting GEDI Vegetation Profile Biophysical Variables
level2BVPM<-getLevel2BVPM(level2b, cols=c("beam", "shot_number"))
head(level2BVPM)

close(level2b)

Description

Extract GEDI Level 4A footprint metrics

Usage

getLevel4A(
  level4a,
  cols = .level4a_default_columns,
  quality = FALSE,
  beams = NULL
)

Arguments

Value

A data.table::data.table with one row per footprint.

Description

Get an Earth Engine image tile URL

Usage

getTileUrl(image, vis = list())

Arguments

Value

Character tile URL.

Description

Earth Engine gray-level co-occurrence textures

Usage

glcmTexture(x, size = 1L, kernel = NULL, average = TRUE)

Arguments

Value

An Earth Engine image.

Description

GEDI grid-stratified sampling specification

Usage

gridSampling(size, grid_size, lon = NULL, lat = NULL)

Arguments

Description

This function computes a series of user defined descriptive statistics within each grid cell for GEDI derived Elevation and Height Metrics (Level2A)

Usage

gridStatsLevel2AM(level2AM, func, res)

Arguments

Value

Return a stars raster layer(s) of selected GEDI Elevation and Height Metric(s)

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-a-002

Examples

## Not run: 
# specify the path to GEDI level2A data (zip file)
outdir <- tempdir()
level2A_fp_zip <- system.file("extdata",
  "GEDI02_A_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Apath <- unzip(level2A_fp_zip, exdir = outdir)

# Reading GEDI level2A data (h5 file)
level2a <- readLevel2A(level2Apath = level2Apath)

# Get GEDI derived Elevation and Height Metrics
level2AM <- getLevel2AM(level2a)
head(level2AM)

#' Define your own function
mySetOfMetrics <- function(x) {
  metrics <- list(
    min = min(x), # Min of z
    max = max(x), # Max of z
    mean = mean(x), # Mean of z
    sd = sd(x) # Sd of z
  )
  return(metrics)
}

#' Computing a serie of GEDI metrics
ZTstats <- gridStatsLevel2AM(
  level2AM = level2AM,
  func = mySetOfMetrics(elev_highestreturn),
  res = 0.005
)
if (interactive()) plot(ZTstats)

if (interactive()) {
  # Computing the maximum of RH100 only
  maxRH100 <- gridStatsLevel2AM(level2AM, mySetOfMetrics(rh100), res = 0.0005)
  plot(maxRH100)

  # Computing the mean of ZG only
  ZGmean <- gridStatsLevel2AM(level2AM, mean(elev_lowestmode), res = 0.005)
  plot(ZGmean)
}

close(level2a)

## End(Not run)

Description

This function computes a series of user defined descriptive statistics within each grid cell for GEDI derived Canopy Cover and Vertical Profile Metrics (Level2B)

Usage

gridStatsLevel2BVPM(level2BVPM, func, res)

Arguments

Value

Returns a stars raster layer(s) of selected GEDI Canopy Cover and Vertical Profile Metric(s)

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

## Not run: 
# specify the path to GEDI level2B data (zip file)
outdir <- tempdir()
level2B_fp_zip <- system.file("extdata",
  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip, exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b <- readLevel2B(level2Bpath = level2Bpath)

# Get GEDI derived Canopy Cover and Vertical Profile Metrics
level2BVPM <- getLevel2BVPM(level2b)
head(level2BVPM)

#' Define your own function
mySetOfMetrics <- function(x) {
  metrics <- list(
    min = min(x), # Min of z
    max = max(x), # Max of z
    mean = mean(x), # Mean of z
    sd = sd(x) # Sd of z
  )
  return(metrics)
}

#' Computing a serie of statistics of GEDI derived canopy cover
cover_stats <- gridStatsLevel2BVPM(
  level2BVPM = level2BVPM,
  func = mySetOfMetrics(cover),
  res = 0.005
)
plot(cover_stats)

#' Computing the max of the Total Plant Area Index only
pai_max <- gridStatsLevel2BVPM(level2BVPM = level2BVPM, func = max(pai), res = 0.005)
plot(pai_max)

#' Computing the Foliage Height Diversity Index only
fhd_mean <- gridStatsLevel2BVPM(level2BVPM = level2BVPM, func = mean(fhd_normal), res = 0.005)
plot(fhd_mean)

close(level2b)

## End(Not run)

Description

Grid GEDI Level 4A footprint metrics

Usage

gridStatsLevel4A(level4A, metric = "agbd", fun = mean, res = 0.01, ...)

Arguments

Value

A terra::SpatRaster.

Description

Apply an Earth Engine model to a predictor image

Usage

map_create(model, stack, aoi = NULL, name = "prediction")

Arguments

Value

An Earth Engine image.

Description

Download an Earth Engine image

Usage

map_download(
  image,
  filename,
  region,
  scale = 30,
  crs = "EPSG:4326",
  overwrite = FALSE
)

Arguments

Value

Invisibly returns filename.

Description

Display Earth Engine layers in Leaflet

Usage

map_view(layers, vis = list(), aoi = NULL)

Arguments

Value

A Leaflet widget.

Description

Mosaic GEDI Level 3 rasters

Usage

mosaicLevel3(x, fun = "mean", filename = "", overwrite = FALSE)

Arguments

Value

A terra::SpatRaster.

Description

Mosaic GEDI Level 4B rasters

Usage

mosaicLevel4B(x, fun = "mean", filename = "", overwrite = FALSE)

Arguments

Value

A terra::SpatRaster.

Description

Raster products are opened with GDAL through terra::rast(). HDF5 cloud granules are opened lazily with Python earthaccess and h5py.

Usage

openGEDI(x, product = NULL, stream = TRUE, cache_dir = tempdir())

Arguments

Value

A SpatRaster, gedi.cloud_h5, or local GEDI object.

Description

Creates an interactive 3D HTML animation or an animated GIF from GEDI footprint coordinates. The presentation follows the ICESat2VegR orbit animation, with a rotating Earth, a NASA ISS illustration carrying GEDI, and a red near-infrared laser and ground track. ISS motion follows the time-ordered geolocation of the most complete beam extracted from the supplied HDF5 object.

Usage

plot_gedi_orbit_animation(
  x,
  lon = NULL,
  lat = NULL,
  time = NULL,
  track = NULL,
  output_file = tempfile("rGEDI-orbit-", fileext = ".html"),
  title = "GEDI orbit animation",
  duration = 18,
  launch = interactive(),
  track_speed = 2,
  earth_rotation_speed = 2,
  beams = NULL,
  every = 1L
)

Arguments

Value

The normalized path to the HTML file, invisibly.

Examples

orbit <- data.frame(
  longitude = seq(-60, -45, length.out = 30),
  latitude = seq(-8, 5, length.out = 30),
  delta_time = seq_len(30), beam = "BEAM0101"
)
html <- plot_gedi_orbit_animation(
  orbit, output_file = tempfile(fileext = ".html")
)
file.exists(html)

Description

For gedi.fullwaveform: will plot the full waveform

Usage

## S4 method for signature 'gedi.fullwaveform,missing'
plot(x, relative = FALSE, polygon = FALSE, ...)

Arguments

Value

No return value

Examples

# Specifying the path to GEDI level1B data (zip file)
outdir <- tempdir()
level1B_fp_zip <- system.file("extdata",
  "GEDI01_B_2019108080338_O01964_T05337_02_003_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level1B data
level1Bpath <- unzip(level1B_fp_zip, exdir = outdir)

# Reading GEDI level1B data (h5 file)
level1b <- readLevel1B(level1Bpath = level1Bpath)

# Extracting GEDI Full-Waveform
wf <- getLevel1BWF(level1b, shot_number = "19640521100108408")

# Plotting GEDI Full-waveform
oldpar <- par()
par(mfrow = c(1, 2), cex.axis = 1.5)
plot(wf,
  relative = FALSE, polygon = TRUE, type = "l", lwd = 2, col = "forestgreen",
  xlab = "", ylab = "Elevation (m)"
)

rGEDI::plot(wf,
  relative = TRUE, polygon = TRUE, type = "l", lwd = 2, col = "forestgreen",
  xlab = "Waveform Amplitude (%)", ylab = "Elevation (m)"
)

par(oldpar)
close(level1b)

Description

Plot GEDI variable selection results

Usage

## S3 method for class 'gedi_var_selection'
plot(x, which = c("importance", "rfe"), ...)

Arguments

Value

The object, invisibly.

Description

Plot GEDI Level 3 metrics

Usage

plotLevel3(x, ...)

Arguments

Value

Invisibly returns the raster.

Description

Plot GEDI Level 4A footprint biomass

Usage

plotLevel4A(level4A, metric = "agbd", ...)

Arguments

Value

Invisibly returns level4A.

Description

Plot GEDI Level 4B metrics

Usage

plotLevel4B(x, ...)

Arguments

Value

Invisibly returns the raster.

Description

This functions plots Plant Area Index (PAI) Profile (GEDI level2B)

Usage

plotPAIProfile(level2BPAIProfile, beam = "BEAM0101", elev = TRUE)

Arguments

Details

list of GEDI beams. See the output of getLevel2BPAIProfile() function.

• BEAM0000

• BEAM0001

• BEAM0010

• BEAM0011

• BEAM0101

• BEAM0110

• BEAM1000

• BEAM1011

Value

Returns a ggplot object. See ggplot2::ggplot package.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# specify the path to GEDI level2B data (zip file)
outdir = tempdir()
level2B_fp_zip <- system.file("extdata",
                  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
                  package="rGEDI")

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip,exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b<-readLevel2B(level2Bpath=level2Bpath)

# Get Plant Area Volume Density profile
level2BPAIProfile<-getLevel2BPAIProfile(level2b)

# Plot Level2B PAI Profile
gprofile<-plotPAIProfile(level2BPAIProfile, beam="BEAM0101", elev=TRUE)



close(level2b)

Description

This functions plots Plant Area Volume Density profile (GEDI level2B)

Usage

plotPAVDProfile(level2BPAVDProfile, beam = "BEAM0101", elev = TRUE)

Arguments

Details

list of GEDI beams. See the output of getLevel2BPAVDProfile() function.

• BEAM0000

• BEAM0001

• BEAM0010

• BEAM0011

• BEAM0101

• BEAM0110

• BEAM1000

• BEAM1011

Value

Returns a ggplot object. See ggplot2::ggplot package.

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# specify the path to GEDI level2B data (zip file)
outdir = tempdir()
level2B_fp_zip <- system.file("extdata",
                  "GEDI02_B_2019108080338_O01964_T05337_02_001_01_sub.zip",
                  package="rGEDI")

# Unzipping GEDI level2A data
level2Bpath <- unzip(level2B_fp_zip,exdir = outdir)

# Reading GEDI level2B data (h5 file)
level2b<-readLevel2B(level2Bpath=level2Bpath)

# Get Plant Area Volume Density profile
level2BPAVDProfile<-getLevel2BPAVDProfile(level2b)

# Plot Level2B PAVD Profile
gprofile<-plotPAVDProfile(level2BPAVDProfile, beam="BEAM0101", elev=TRUE)


close(level2b)

Description

Plots the waveform with overlaid RH metrics

Usage

plotWFMetrics(level1b, level2a, shot_number, rh=c(25, 50, 75),...)

Arguments

Value

Nothing

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# specify the path to GEDI level1B and Level2A data (zip file)
outdir <- tempdir()
level1B_fp_zip <- system.file("extdata",
  "GEDI01_B_2019108080338_O01964_T05337_02_003_01_sub.zip",
  package = "rGEDI"
)

level2A_fp_zip <- system.file("extdata",
  "GEDI02_A_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level1B data
level1Bpath <- unzip(level1B_fp_zip, exdir = outdir)
level2Apath <- unzip(level2A_fp_zip, exdir = outdir)

# Reading GEDI level1B and Level2A data (h5 file)
level1b <- readLevel1B(level1Bpath = level1Bpath)
level2a <- readLevel2A(level2Apath = level2Apath)

shot_number <- "19640521100108408"

plotWFMetrics(level1b, level2a, shot_number, rh = c(25, 50, 75, 90))

close(level1b)
close(level2a)

Description

Computes a Series of Statistics from GEDI derived Elevation and Height Metrics (Level2A) within a given area defined or not by a polygon

Usage

polyStatsLevel2AM(level2AM, func, id=NULL)

Arguments

Value

Returns an S4 object of class data.table::data.table Containing Statistics of GEDI level2A defined metrics

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-a-002

Examples

# Specifying the path to GEDI level2A data (zip file)
outdir <- tempdir()
level2A_fp_zip <- system.file("extdata",
  "GEDI02_A_2019108080338_O01964_T05337_02_001_01_sub.zip",
  package = "rGEDI"
)

# Unzipping GEDI level2A data
level2Apath <- unzip(level2A_fp_zip, exdir = outdir)

# Reading GEDI level2A data (h5 file)
level2a <- readLevel2A(level2Apath = level2Apath)

# Specifying the path to shapefile
polygon_filepath <- system.file("extdata", "stands_cerrado.shp", package = "rGEDI")

# Reading shapefile as sf object
library(sf)
polygon <- sf::st_read(polygon_filepath)

# Extracting GEDI Eleveation and Relative Metrics (level2A)
level2AM <- getLevel2AM(level2a)
head(level2AM)

# Clipping GEDI data by geometry
level2AM_clip <- clipLevel2AMGeometry(level2AM, polygon, split_by = "id")

#' Define your own function
mySetOfMetrics <- function(x) {
  metrics <- list(
    min = min(x), # Min of x
    max = max(x), # Max of x
    mean = mean(x), # Mean of x
    sd = sd(x) # Sd of x
  )
  return(metrics)
}

# Computing the maximum of RH100
RH100max <- polyStatsLevel2AM(level2AM_clip, func = max(rh100))

# Computing the maximum of RH100 stratified by polygon
RH100max_poly <- polyStatsLevel2AM(level2AM_clip, func = max(rh100), id = "id")

# Computing a serie statistics for GEDI metrics stratified by polygon
RH100metrics <- polyStatsLevel2AM(level2AM_clip,
  func = mySetOfMetrics(rh100),
  id = "id"
)

head(RH100metrics)

close(level2a)

Description

Computes a Series of Statistics of GEDI derived Canopy Cover and Vertical Profile metrics within a given area defined or not by a polygon

Usage

polyStatsLevel2BVPM(level2BVPM, func, id=NULL)

Arguments

Value

Returns an S4 object of class data.table::data.table Containing Statistics of GEDI level2BVPM defined metrics

See Also

https://www.earthdata.nasa.gov/data/catalog/lpcloud-gedi02-b-002

Examples

# A small extracted Level 2B table
level2BVPM <- data.table::data.table(
  pai = c(1.1, 1.8, 2.2, 0.9, 1.5, 2.4),
  cover = c(0.31, 0.44, 0.52, 0.27, 0.39, 0.58),
  poly_id = rep(c("stand_1", "stand_2"), each = 3)
)
head(level2BVPM)

# Define your own function
mySetOfMetrics <- function(x) {
  metrics <- list(
    min = min(x), # Min of x
    max = max(x), # Max of x
    mean = mean(x), # Mean of x
    sd = sd(x) # Sd of x
  )
  return(metrics)
}

# Computing the max of the Total Plant Area Index
pai_max <- polyStatsLevel2BVPM(level2BVPM, func = max(pai), id = NULL)
pai_max

# Computing the max of the Total Plant Area Index stratified by polygon
pai_max_poly <- polyStatsLevel2BVPM(level2BVPM, func = max(pai), id = "poly_id")
head(pai_max_poly)

# Computing the serie of statistics of canopy cover stratified by polygon
cover_metrics <- polyStatsLevel2BVPM(level2BVPM,
  func = mySetOfMetrics(cover),
  id = "poly_id"
)
head(cover_metrics)

Description

Polygon summaries of GEDI Level 3 metrics

Usage

polyStatsLevel3(x, y, fun = mean, na.rm = TRUE, ...)

Arguments

Value

A data frame.

Description

Polygon statistics for GEDI Level 4A footprints

Usage

polyStatsLevel4A(level4A, polygon, metric = "agbd", fun = mean, id = NULL, ...)

Arguments

Value

A data table with one row per polygon.

Description

Polygon summaries of GEDI Level 4B metrics

Usage