Package 'ICESat2VegR'

Description

Tools to download, read, process, model, and visualize ICESat-2 ATL03/ATL08 for land and vegetation applications.

Author(s)

Maintainer: Caio Hamamura [email protected] [copyright holder]

Authors:

• Caio Hamamura [email protected] [copyright holder]

• Carlos Alberto Silva [email protected] [copyright holder]

See Also

Useful links:

• https://github.com/carlos-alberto-silva/ICESat2VegR

• Report bugs at https://github.com/carlos-alberto-silva/ICESat2VegR/issues

Description

.as_ee_geom() converts a variety of R geometry representations (including sf, sfc, terra objects, bounding boxes, WKT/GeoJSON, and even existing Earth Engine python objects) into a Python ee$Geometry suitable for use in Earth Engine workflows.

This helper is designed to be flexible and permissive: it accepts most common spatial formats used in R and normalizes them into a standard Earth Engine geometry. When a buffer distance is supplied, the geometry is optionally buffered in meters on the Earth Engine side.

Usage

.as_ee_geom(geom, xcol = "lon", ycol = "lat", crs = 4326, buffer_m = NULL)

Arguments

Details

For sf/sfc and data.frame inputs, geometries are first transformed to EPSG:4326 and written to a temporary GeoJSON file, which is then read and wrapped into an ee$FeatureCollection(... )$geometry(). For terra::SpatVector and terra::SpatExtent inputs, conversion proceeds via terra::writeVector() / terra::as.polygons() and an EE rectangle geometry, respectively.

Existing Earth Engine python objects are returned as-is, except that ee$Feature and ee$FeatureCollection objects are coerced to their underlying geometry via ⁠$geometry()⁠.

Value

A Python ee$Geometry object (or compatible geometry-like EE object) suitable for use in Earth Engine operations.

Examples

## Not run: 
  ee <- reticulate::import("ee", delay_load = FALSE)

  # 1) From sf polygon
  library(sf)
  poly <- st_as_sfc(st_bbox(c(
    xmin = -82.4, xmax = -82.2,
    ymin =  29.6, ymax =  29.8
  ), crs = 4326))

  ee_geom1 <- .as_ee_geom(poly)


  # 2) From terra::SpatVector
  library(terra)
  v <- vect(system.file("extdata", "all_boundary.shp", package = "ICESat2VegR"))
  ee_geom2 <- .as_ee_geom(v, buffer_m = 30)


  # 3) From numeric extent (xmin, ymin, xmax, ymax)
  bbox_vec <- c(-82.4, 29.6, -82.2, 29.8)
  ee_geom3 <- .as_ee_geom(bbox_vec)


  # 4) From data.frame of points
  df <- data.frame(
    lon = c(-82.3, -82.25),
    lat = c(29.65, 29.7)
  )
  ee_geom4 <- .as_ee_geom(df, buffer_m = 1000)

## End(Not run)

Description

.ee_ping() verifies that the Earth Engine Python API is initialized and responsive. It attempts to evaluate a trivial Earth Engine expression (ee$Image$constant(1)$getInfo()) and returns invisibly if successful. If the call fails, an error is raised with a hint to authenticate and initialize Earth Engine.

Usage

.ee_ping(ee)

Arguments

Value

Invisibly returns TRUE if Earth Engine is initialized and responsive. Otherwise, an error is thrown indicating that Earth Engine must be authenticated and initialized.

Examples

## Not run: 
  library(reticulate)
  ee <- import("ee", delay_load = FALSE)

  # Will error if EE is not authenticated/initialized
  .ee_ping(ee)

## End(Not run)

Description

This method subsets the granules slot of an icesat2.granules_cloud object.

Usage

## S4 method for signature 'icesat2.granules_cloud,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

Arguments

Value

An object of class icesat2.granule_cloud.

Description

This method extracts a single element from the granules slot of an icesat2.granules_cloud object.

Usage

## S4 method for signature 'icesat2.granules_cloud,ANY,ANY'
x[[i, j, ...]]

Arguments

Value

An object of class icesat2.granule_cloud.

Examples

## Not run: 
lower_left_lon <- -83.26
lower_left_lat <- 31.95
upper_right_lon <- -83.11
upper_right_lat <- 32.46

daterange <- c("2019-04-12", "2019-05-03")

ATL08_granules_cloud <- ATLAS_dataFinder(
  short_name = "ATL08",
  lower_left_lon,
  lower_left_lat,
  upper_right_lon,
  upper_right_lat,
  version = "007",
  daterange = daterange,
  persist = TRUE,
  cloud_computing = TRUE
)

ATL08_h5_cloud <- ATL08_read(ATL08_granules_cloud[1])

ATL08_h5_cloud[['gt1l']]
close(ATL08_h5_cloud)

## End(Not run)

Description

This function gives access to the GDALRasterBand using [[i]], where i is the band index to return.

Usage

## S3 method for class 'GDALDataset'
x[[slice]]

Arguments

Value

An object of GDALRasterBand R6 class.

Description

This function gives access to the GDALRasterBand using [[i]], where i is the band index to return.

Usage

## S3 method for class 'GDALRasterBand'
x[[blockX, blockY]]

Arguments

Value

Nothing, this is a setter

Description

This function gives access to the GDALRasterBand using [[i]], where i is the band index to return.

Usage

## S3 replacement method for class 'GDALRasterBand'
x[[blockX, blockY]] <- value

Arguments

Value

Nothing, this is a setter

Description

Add an Earth Engine Image to a leaflet map

Usage

addEEImage(
  map,
  img,
  bands = NULL,
  min_value = 0,
  max_value = 1,
  palette = c("#d55e00", "#cc79a7", "#f0e442", "#0072b2", "#009e73"),
  group = NULL,
  aoi = NULL,
  ...
)

Arguments

Value

The input leaflet map with the EE image layer added.

Examples

## Not run: 
# Initialize Earth Engine (use your own project id)
Sys.setenv(EE_PROJECT = "your-ee-project-id")
ee_initialize()

# Harmonized Landsat-Sentinel (HLS) surface reflectance collection
collection_id <- "NASA/HLS/HLSL30/v002"
ee_collection <- ee$ImageCollection(collection_id)

# Mask cloud, cloud-shadow and adjacent-cloud pixels (Fmask bits 1-3)
cloudMask <- 2^1 + 2^2 + 2^3
hlsMask <- function(image) {
  image$updateMask(!(image[["Fmask"]] & cloudMask))
}

# Cloud-free median composite over two summer seasons
image <- c(
  ee_collection$filterDate("2020-04-01", "2020-07-31")$map(hlsMask),
  ee_collection$filterDate("2021-04-01", "2021-07-31")$map(hlsMask)
)$filter("CLOUD_COVERAGE < 30")$median()

# Show the RGB composite (bands 3-2-1) on an interactive map
if (require("leaflet")) {
  leaflet() %>%
    addEEImage(
      image,
      bands = c(3, 2, 1),
      min_value = 0.001,
      max_value = 0.2
    ) %>%
    setView(lng = -82.2345, lat = 29.6552, zoom = 10)
}

## End(Not run)

Description

This class uses Approximate Neareast Neighbor Index for finding points that are within a specified range.

Public fields

Methods

Public methods

• ANNIndex$new()

• ANNIndex$searchFixedRadius()

ANNIndex$new()

Creates a new instance of the ANNIndex class.

Usage

ANNIndex$new(x, y)

Arguments

ANNIndex$searchFixedRadius()

Given a x, y point get the indexes that are within a specified radius.

Usage

ANNIndex$searchFixedRadius(x, y, radius)

Arguments

See Also

Mount, D. M.; Arya, S. ANN: A Library for Approximate Nearest Neighbor Searching, available in https://www.cs.umd.edu/~mount/ANN/

Description

Computes the terrain aspect in degrees for each pixel of an Earth Engine ee$Image representing a digital elevation model (DEM).

Aspect describes the downslope direction of the steepest gradient and is expressed in degrees clockwise from north. The computation is performed using Earth Engine's built-in ee$Terrain$aspect() function. As with slope, Earth Engine uses the 4-connected neighborhood, so missing values may occur near image edges.

Usage

aspect(x)

Arguments

Value

An ee$Image with one band named aspect containing aspect values in degrees clockwise from north.

Examples

## Not run: 
  ee <- reticulate::import("ee")
  dem <- ee$Image("NASA/NASADEM_HGT/001")
  asp <- aspect(dem)

## End(Not run)

Description

Calculates the angle formed by the 2D vector [x, y]

Usage

atan2.ee.ee_number.Number(x, e2)

Arguments

Value

An ee$Number representing the angle in radians

See Also

https://developers.google.com/earth-engine/apidocs/ee-number-atan2

Description

Computes a series of statistics from ATL03 and ATL08 labeled photons within a given segment length.

Usage

ATL03_ATL08_compute_seg_attributes_dt_segStat(
  atl03_atl08_seg_dt,
  list_expr,
  ph_class = c(0, 1, 2, 3),
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  quality_ph = NULL,
  night_flag = NULL
)

Arguments

Value

Returns an S4 object of class icesat2.atl08_dt Containing Statistics of ATL03 and ATL08 labeled photons

Examples

# Specifying ATL03 and ATL08 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL03 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL03 and ATL08 labeled photons
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)

# Computing the max canopy height at 30 m segments
atl03_atl08_dt_seg <- ATL03_ATL08_segment_create(atl03_atl08_dt, segment_length = 30)

max_canopy <- ATL03_ATL08_compute_seg_attributes_dt_segStat(atl03_atl08_dt_seg,
  list_expr = max(ph_h),
  ph_class = c(2, 3),
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  quality_ph = 0,
  night_flag = 0
)

head(max_canopy)

# Computing a series of canopy height statistics from customized list expressions
canopy_metrics <- ATL03_ATL08_compute_seg_attributes_dt_segStat(atl03_atl08_dt_seg,
  list_expr = list(
    max_ph_elevation = max(h_ph),
    h_canopy = quantile(ph_h, 0.98),
    n_canopy = sum(classed_pc_flag == 2),
    n_top_canopy = sum(classed_pc_flag == 3)
  ),
  ph_class = c(2, 3),
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  quality_ph = 0,
  night_flag = 0 # there are no night photons in this dataset
)

head(canopy_metrics)

close(atl03_h5)
close(atl08_h5)

Description

Clips joined ATL03 and ATL08 photon attributes within a given bounding extent, defined by a single clip_obj argument. The clipping extent can be provided as:

• (i) a numeric bounding box, or

• (ii) a spatial extent object.

Usage

ATL03_ATL08_photons_attributes_dt_clipBox(atl03_atl08_dt, clip_obj)

Arguments

Details

When clip_obj is a SpatExtent, the package terra must be installed. If not found, the function stops with an informative message.

Value

Returns an S4 object of class icesat2.atl03atl08_dt containing a subset of the joined ATL03 and ATL08 photon attributes restricted to the clipping extent.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Examples

# Specifying the path to ATL03 and ATL08 files
atl03_path <- system.file("extdata", "atl03_clip.h5",
                          package = "ICESat2VegR")

atl08_path <- system.file("extdata", "atl08_clip.h5",
                          package = "ICESat2VegR")

# Reading ATL03 and ATL08 data (h5 files)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Joining ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)
head(atl03_atl08_dt)

# 1) Using a numeric bounding box: xmin ymin xmax ymax
bbox <- c(-106.571, 41.531, -106.569, 41.540)

atl03_atl08_dt_clip <- ATL03_ATL08_photons_attributes_dt_clipBox(
  atl03_atl08_dt = atl03_atl08_dt,
  clip_obj = bbox
)
head(atl03_atl08_dt_clip)

# 2) Using a SpatExtent (example)
# library(terra)
# ext <- terra::ext(-106.57, -106.569, 41.531, 41.540)
# atl03_atl08_dt_clip_ext <- ATL03_ATL08_photons_attributes_dt_clipBox(
#   atl03_atl08_dt = atl03_atl08_dt,
#   clip_obj = ext
# )

close(atl03_h5)
close(atl08_h5)

Description

This function clips joined ATL03 and ATL08 photon attributes within a given geometry.

Usage

ATL03_ATL08_photons_attributes_dt_clipGeometry(
  atl03_atl08_dt,
  clip_obj,
  split_by = NULL
)

Arguments

Value

Returns an S4 object of class icesat2.atl03atl08_dt containing the clipped ATL08 attributes.

Examples

# Specifying the path to ATL03 and ATL08 files
atl03_path <- system.file("extdata", "atl03_clip.h5", package = "ICESat2VegR")
atl08_path <- system.file("extdata", "atl08_clip.h5", package = "ICESat2VegR")

# Reading ATL03 and ATL08 data (h5 files)
atl03_h5 <- ATL03_read(atl03_path)
atl08_h5 <- ATL08_read(atl08_path)

# Joining ATL03 and ATL08 photon attributes
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)
head(atl03_atl08_dt)

# Specifying the path to the shapefile
clip_obj_filepath <- system.file("extdata", "clip_geom.shp", package = "ICESat2VegR")

# Reading shapefile as a SpatVector object
clip_obj <- terra::vect(clip_obj_filepath)

# Clipping ATL08 terrain attributes by geometry
atl03_atl08_dt_clip <- ATL03_ATL08_photons_attributes_dt_clipGeometry(
  atl03_atl08_dt,
  clip_obj,
  split_by = "id"
)
head(atl03_atl08_dt_clip)

close(atl03_h5)
close(atl08_h5)

Description

This function computes a series of user defined descriptive statistics within each given grid cell for ATL03 and ATL08 photon attributes

Usage

ATL03_ATL08_photons_attributes_dt_gridStat(
  atl03_atl08_dt,
  func,
  res = 0.5,
  ph_class = c(2, 3),
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  quality_ph = 0,
  night_flag = 1
)

Arguments

Value

Return a SpatRast raster layer(s) of selected ATL03 and ATL08 photon attribute(s)

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# ATL08 file path
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)
# Reading ATL03 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# # Extracting ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)

# Computing the mean of ph_h attribute at 0.0002 degree grid cell
mean_ph_h <- ATL03_ATL08_photons_attributes_dt_gridStat(atl03_atl08_dt,
  func = mean(ph_h),
  res = 0.0002
)

plot(mean_ph_h)

# 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 a series of ph_h stats at 0.0002 degree grid cell from customized function
ph_h_metrics <- ATL03_ATL08_photons_attributes_dt_gridStat(atl03_atl08_dt,
  func = mySetOfMetrics(ph_h), res = 0.0002
)

plot(ph_h_metrics)

close(atl03_h5)
close(atl08_h5)

Description

This function joins ATL03 and ATL08 computed photons attributes

Usage

ATL03_ATL08_photons_attributes_dt_join(
  atl03_h5,
  atl08_h5,
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r")
)

Arguments

Details

These are the photons attributes extracted by default:

• ph_segment_id: Georeferenced segment id (20-m) associated with each photon.

• lon_ph: Longitude of each received photon. Computed from the ECEF Cartesian coordinates of the bounce point.

• lat_ph: Latitude of each received photon. Computed from the ECEF Cartesian coordinates of the bounce point.

• h_ph: Height of each received photon, relative to the WGS-84 ellipsoid including the geophysical corrections noted in section 6.0. Please note that neither the geoid, ocean tide nor the dynamic atmospheric corrections (DAC) are applied to the ellipsoidal heights.

• quality_ph: Indicates the quality of the associated photon. 0=nominal, 1=possible_afterpulse, 2=possible_impulse_response_effect, 3=possible_tep. Use this flag in conjunction with signal_conf_ph to identify those photons that are likely noise or likely signal.

• solar_elevation: Elevation of the sun above the horizon at the photon bounce point.

• dist_ph_along: Along-track distance of the photon from the beginning of the segment.

• dist_ph_across: Across-track distance of the photon from the center of the segment.

• night_flag: Flag indicating the data were acquired in night conditions: 0=day, 1=night. Night flag is set when solar elevation is below 0.0 degrees.

• classed_pc_indx: Indices of photons tracking back to ATL03 that surface finding software identified and used within the creation of the data products.

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

• ph_h: Height of photon above interpolated ground surface.

• d_flag: Flag indicating whether DRAGANN labeled the photon as noise or signal.

• delta_time: Mid-segment GPS time in seconds past an epoch. The epoch is provided in the metadata at the file level.

• orbit_number: Orbit number identifier to identify data from different orbits.

• beam: Beam identifier.

• strong_beam: Logical indicating if the beam is a strong beam.

Value

Returns an S4 object of class icesat2.atl03atl08_dt containing the ATL08 computed photons attributes.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Examples

# Specifying the path to ATL03 file
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL03 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# # Extracting ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)
head(atl03_atl08_dt)

close(atl03_h5)
close(atl08_h5)

Description

Converts ATL03/ATL08 classified photon cloud to LAS

Usage

ATL03_ATL08_photons_attributes_dt_LAS(
  atl03_atl08_dt,
  output,
  normalized = TRUE
)

Arguments

Value

Nothing, it just saves outputs as LAS file in disk

Examples

outdir <- tempdir()

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# ATL08 file path
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL03 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)

if (require("lidR")) {
  ATL03_ATL08_photons_attributes_dt_LAS(
    atl03_atl08_dt,
    output = file.path(outdir, "output.laz"),
    normalized = TRUE
  )
}

close(atl03_h5)
close(atl08_h5)

Description

Computes a series of statistics ATL03 and ATL08 joined photons attributes within area defined by a polygon

Usage

ATL03_ATL08_photons_attributes_dt_polyStat(
  atl03_atl08_dt,
  func,
  poly_id = NULL
)

Arguments

Value

Returns an S4 object of class icesat2.atl08_dt Containing Statistics of ATL08 classified canopy photons

Examples

# Specifying the path to ATL03 and ATL08 files
# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# ATL08 file path
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL03 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)
head(atl03_atl08_dt)

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

# Reading shapefile as sf object
polygon <- terra::vect(polygon_filepath)

# Clipping ATL08 terrain attributes by Geometry
atl03_atl08_dt_clip <- ATL03_ATL08_photons_attributes_dt_clipGeometry(atl03_atl08_dt,
  polygon, split_by = "id")

# Computing the maximum ph_h by polygon id
max_ph_h <- ATL03_ATL08_photons_attributes_dt_polyStat(atl03_atl08_dt_clip,
  func = max(ph_h), poly_id = "poly_id")
head(max_ph_h)

# 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 a series of ph_h statistics from customized function
ph_h_metrics <- ATL03_ATL08_photons_attributes_dt_polyStat(
  atl03_atl08_dt_clip,
  func = mySetOfMetrics(ph_h),
  poly_id = "poly_id"
)

head(ph_h_metrics)

close(atl03_h5)
close(atl08_h5)

Description

Function to estimate ground elevation using smoothing and interpolation functions. Ground photons (classed_pc_flag == 1) are first aggregated within a smoothing window, then an interpolation function is applied to estimate the ground elevation at each photon location or at arbitrary distances along the track.

Usage

ATL03_ATL08_photons_seg_dt_fitground(
  atl03_atl08_seg_dt,
  smoothing_window = NA,
  smoothing_func = median,
  interpolation_func = NA,
  xout_parameter_name = "xout",
  ...
)

Arguments

Details

The function for calculating the ground will first pass a smoothing window with smoothing_window size, applying the smoothing_func to aggregate the ground photons (classed_pc_flag == 1).

Then it will use an interpolation function between those aggregated photons to estimate a smooth ground surface.

The smoothing_func signature will depend on the function used. It is assumed that the first two arguments are vectors of x (independent variable) and y (the values to be aggregated). The remaining arguments are passed through ....

The interpolation functions need a third parameter which is the x vector to predict at. Functions from the stats base package such as stats::approx() and stats::spline() name this argument xout, so you can use:

ATL03_ATL08_photons_seg_dt_fitground(
  atl03_atl08_seg_dt,
  interpolation_func = approx,
  xout_parameter_name = "xout"
)

to predict at every photon location along the track. Other functions may name the prediction parameter differently — for example, signal::pchip() uses xi instead of xout. The pchip algorithm (as implemented in the signal package) is the algorithm used by the ATL08 ATBD.

The smoothing_window can be left NA, which will use the ATBD adaptive algorithm for calculating the window size:

$Sspan = \lceil 5 + 46 \times (1 - e^{-a \times length}) \rceil$, where length is the number of photons within the segment.

$a \approx 21 \times 10^{-6}$

$window\_size = \frac{2}{3} \times Sspan$

This is not the same algorithm as used in ATL08 but is an adapted version that uses the ATL08 pre-classification.

Value

When xout_parameter_name is not NA, returns a named list with two numeric vectors:

x

Distance along track (dist_ph_along) for each photon, in meters.

y

Interpolated ground elevation (h_ph) at each photon location, in meters. Values are NA for photons outside the smoothed ground range (controlled by the rule argument of the interpolation function).

When xout_parameter_name = NA, returns the raw output of interpolation_func directly — for example, a callable function when interpolation_func = approxfun, which can then be evaluated at arbitrary distances along the track.

Examples

# Specifying the path to ATL03 and ATL08 files
atl03_path <- system.file("extdata", "atl03_clip.h5", package = "ICESat2VegR")
atl08_path <- system.file("extdata", "atl08_clip.h5", package = "ICESat2VegR")

# Reading ATL03 and ATL08 data (h5 files)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)

# Converting to seg_dt class (required input for fitground)
atl03_atl08_seg_dt <- ATL03_ATL08_segment_create(
  atl03_atl08_dt,
  segment_length = 30
)

# Example 1: ATBD adaptive smoothing window + linear interpolation
# at each photon location along the track.
# Returns a list with $x (dist_ph_along) and $y (ground elevation in meters).
# NAs appear at photon locations outside the smoothed ground range.
ground_approx <- ATL03_ATL08_photons_seg_dt_fitground(
  atl03_atl08_seg_dt,
  interpolation_func = approx,
  xout_parameter_name = "xout"
)
head(ground_approx$x) # photon distances along track (meters)
head(ground_approx$y) # interpolated ground elevations (meters)

# Example 2: Return an interpolation function (approxfun) for
# querying ground elevation at arbitrary distances along the track.
# xout_parameter_name = NA skips prediction at photon locations
# and returns the interpolation function directly.
ground_fun <- ATL03_ATL08_photons_seg_dt_fitground(
  atl03_atl08_seg_dt,
  interpolation_func = approxfun,
  xout_parameter_name = NA
)
# Query ground elevation at custom distances along track (meters)
ground_fun(c(100, 200, 300))

# Example 3: Fixed 5 m smoothing window using mean instead of median
ground_mean <- ATL03_ATL08_photons_seg_dt_fitground(
  atl03_atl08_seg_dt,
  smoothing_window = 5,
  smoothing_func = mean,
  interpolation_func = approx,
  xout_parameter_name = "xout"
)
head(ground_mean$y)

close(atl03_h5)
close(atl08_h5)

Description

Normalizes ATL03 and ATL08 photon heights (ph_h) by subtracting the estimated ground elevation at each photon location. Ground elevation is estimated internally using ATL03_ATL08_photons_seg_dt_fitground. The function updates the ph_h column in place and returns the modified atl03_atl08_seg_dt object.

Usage

ATL03_ATL08_photons_seg_dt_height_normalize(
  atl03_atl08_seg_dt,
  smoothing_window = NA,
  smoothing_func = median,
  interpolation_func = NA,
  xout_parameter_name = "xout",
  ...
)

Arguments

Details

This function is a wrapper around ATL03_ATL08_photons_seg_dt_fitground. It first estimates the ground elevation at every photon location using the smoothing and interpolation approach described in that function, then subtracts the estimated ground elevation from the raw photon height (h_ph) to produce height above ground level.

For full details on the smoothing window, smoothing function, and interpolation function behaviour, see ATL03_ATL08_photons_seg_dt_fitground.

Value

Returns the input atl03_atl08_seg_dt object with the ph_h column updated in place to contain height above ground level (AGL) in meters, computed as h_ph - ground_elevation. Values are NA for photons outside the interpolated ground range. Note: as this function uses data.table assignment by reference, the original input object is also modified.

Examples

# Specifying the path to ATL03 and ATL08 files
atl03_path <- system.file("extdata", "atl03_clip.h5", package = "ICESat2VegR")
atl08_path <- system.file("extdata", "atl08_clip.h5", package = "ICESat2VegR")

# Reading ATL03 and ATL08 data (h5 files)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)

# Converting to seg_dt class (required input)
atl03_atl08_seg_dt <- ATL03_ATL08_segment_create(
  atl03_atl08_dt,
  segment_length = 30
)

# Example 1: Normalize photon heights using default ATBD smoothing window
atl03_atl08_seg_dt_norm <- ATL03_ATL08_photons_seg_dt_height_normalize(
  atl03_atl08_seg_dt,
  interpolation_func = approx,
  xout_parameter_name = "xout"
)
head(atl03_atl08_seg_dt_norm)

# Example 2: Fixed 5 m smoothing window using mean aggregation
# Recreate seg_dt since ph_h was modified in place by the previous call
atl03_atl08_seg_dt <- ATL03_ATL08_segment_create(
  atl03_atl08_dt,
  segment_length = 30
)
atl03_atl08_seg_dt_norm2 <- ATL03_ATL08_photons_seg_dt_height_normalize(
  atl03_atl08_seg_dt,
  smoothing_window = 5,
  smoothing_func = mean,
  interpolation_func = approx,
  xout_parameter_name = "xout"
)
head(atl03_atl08_seg_dt_norm2)

close(atl03_h5)
close(atl08_h5)

Description

Clips an icesat2.atl08_dt object to a given spatial extent. Only rows whose longitude and latitude fall inside the specified bounding extent are retained. This is the bounding-box counterpart to geometry-based clipping via ATL03_ATL08_seg_attributes_dt_clipGeometry.

Usage

ATL03_ATL08_seg_attributes_dt_clipBox(atl03_atl08_dt, clip_obj)

Arguments

Details

The function:

1. Validates that the input has longitude and latitude columns.

2. Converts clip_obj to numeric bounds xmin, ymin, xmax, ymax.

3. Drops rows with missing coordinates.

4. Returns a subset of atl03_atl08_dt where longitude and latitude fall inside the bounding box.

Value

An object of the same class as atl03_atl08_dt, containing only segments whose longitude and latitude fall inside the bounding extent.

Examples

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL08 segment attributes
atl08_seg_dt <- ATL08_seg_attributes_dt(atl08_h5)
head(atl08_seg_dt)

# Example 1: Clip using a numeric bounding box (xmin, ymin, xmax, ymax)
bbox <- c(-106.571, 41.532, -106.570, 41.537)
atl08_seg_clip <- ATL03_ATL08_seg_attributes_dt_clipBox(
  atl08_seg_dt,
  clip_obj = bbox
)
head(atl08_seg_clip)
nrow(atl08_seg_clip)

# Example 2: Clip using a terra SpatExtent object
library(terra)
ext_obj <- terra::ext(bbox)
atl08_seg_clip2 <- ATL03_ATL08_seg_attributes_dt_clipBox(
  atl08_seg_dt,
  clip_obj = ext_obj
)
head(atl08_seg_clip2)
nrow(atl08_seg_clip2)

close(atl08_h5)

Description

Clips an icesat2.atl08_dt or icesat2.atl03_atl08_seg_dt object to the features inside a polygon. Accepts terra::SpatVector or sf/sfc polygons. Performs a fast bounding box pre-clip, then a precise intersection in the polygon CRS.

Usage

ATL03_ATL08_seg_attributes_dt_clipGeometry(
  atl03_atl08_dt,
  clip_obj,
  split_by = NULL
)

Arguments

Details

The function performs clipping in two steps for efficiency:

1. A fast bounding box pre-clip using ATL03_ATL08_seg_attributes_dt_clipBox to reduce the number of points before the precise intersection.

2. A precise point-in-polygon intersection using terra::intersect(), reprojecting the points to the polygon CRS if needed.

Value

An object of the same class as atl03_atl08_dt containing only segments that fall inside the polygon. If split_by is provided, an additional poly_id column is added identifying which polygon feature each segment belongs to.

Examples

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL08 segment attributes
atl08_seg_dt <- ATL08_seg_attributes_dt(atl08_h5)
head(atl08_seg_dt)

# Reading polygon from shapefile
polygon_filepath <- system.file("extdata",
  "clip_geom.shp",
  package = "ICESat2VegR"
)
polygon <- terra::vect(polygon_filepath)

# Example 1: Clip by polygon geometry
atl08_seg_clip_geom <- ATL03_ATL08_seg_attributes_dt_clipGeometry(
  atl08_seg_dt,
  clip_obj = polygon
)
head(atl08_seg_clip_geom)
nrow(atl08_seg_clip_geom)

# Example 2: Clip by polygon geometry and add polygon id column
atl08_seg_clip_geom2 <- ATL03_ATL08_seg_attributes_dt_clipGeometry(
  atl08_seg_dt,
  clip_obj = polygon,
  split_by = "id"
)
head(atl08_seg_clip_geom2)
nrow(atl08_seg_clip_geom2)

close(atl08_h5)

Description

Computes canopy cover metrics from ATL03 and ATL08 classified photons within each segment. Cover is calculated using the ratio of ground to vegetation photons, optionally weighted by a reflectance ratio. The function adds three new columns (cover, n_g, n_v) to the input object and returns it.

Usage

ATL03_ATL08_seg_cover_dt_compute(atl03_atl08_dt, reflectance_ratio = 1)

Arguments

Details

Cover is calculated with the formula:

$cover = \frac{1}{1 + \frac{\rho_v \cdot N_g}{\rho_g \cdot N_v}}$

where $N_g$ is the number of ground photons (classed_pc_flag == 1) and $N_v$ is the number of vegetation photons (classed_pc_flag > 1) within each segment.

Value

Returns the input object with three additional columns:

cover

Numeric. Canopy cover fraction per segment (0-1).

n_g

Integer. Number of ground photons per segment (classed_pc_flag == 1).

n_v

Integer. Number of vegetation photons per segment (classed_pc_flag > 1).

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Examples

# Specifying the path to ATL03 and ATL08 files
atl03_path <- system.file("extdata", "atl03_clip.h5", package = "ICESat2VegR")
atl08_path <- system.file("extdata", "atl08_clip.h5", package = "ICESat2VegR")

# Reading ATL03 and ATL08 data (h5 files)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)

# Converting to seg_dt class (required input)
atl03_atl08_seg_dt <- ATL03_ATL08_segment_create(
  atl03_atl08_dt,
  segment_length = 30
)

# Computing canopy cover metrics per segment
cover <- ATL03_ATL08_seg_cover_dt_compute(atl03_atl08_seg_dt)
head(cover[, c("segment_id", "cover", "n_g", "n_v")])

# Computing cover with a custom reflectance ratio (rho_v/rho_g = 1.5)
cover2 <- ATL03_ATL08_seg_cover_dt_compute(
  atl03_atl08_seg_dt,
  reflectance_ratio = 1.5
)
head(cover2[, c("segment_id", "cover", "n_g", "n_v")])

close(atl03_h5)
close(atl08_h5)

Description

This function reads the ICESat-2 Land and Vegetation Along-Track Products (ATL08) as h5 file.

Usage

ATL03_ATL08_segment_create(
  atl03_atl08_dt,
  segment_length,
  centroid = "mean",
  output = NA,
  overwrite = FALSE
)

Arguments

Details

The centroid will be computed using either the photons centroid or the approximate segment centroid.

• "mean": calculated using the average coordinates from all photons within the segment. This approach will better represent the mean statistics location.

• "mid-point": the minimum and maximum coordinates will be averaged to calculate a midpoint within the segment. This will give a better representation of the segment true mid-point

Value

Returns an S4 object of class icesat2.atl03atl08_dt containing ICESat-2 ATL08 data.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Examples

# Specifying the path to ICESat-2 ATL03 and ATL08 data
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ICESat-2 ATL08 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)

atl03_atl08_dt_seg <- ATL03_ATL08_segment_create(atl03_atl08_dt,
  segment_length = 30,
  centroid = "mean",
  output = NA,
  overwrite = FALSE
)

head(atl03_atl08_dt_seg)

close(atl03_h5)
close(atl08_h5)

Description

Clips an ICESat-2 ATL03 HDF5 file to a specified spatial extent. Only geolocated photon and segment datasets within the ATL03 beam groups are clipped; all metadata, orbit information, and ancillary groups are preserved unchanged. This function provides bounding-box-based clipping, complementing geometry-based clipping workflows.

Usage

ATL03_h5_clipBox(
  atl03,
  output,
  clip_obj,
  beam = c("gt1r", "gt2r", "gt3r", "gt1l", "gt2l", "gt3l"),
  additional_groups = c("orbit_info")
)

Arguments

Details

The function performs spatial subsetting at the photon and segment level. Internally, it:

1. Copies file- and group-level attributes.

2. Extracts beam-level datasets and evaluates segment-level and photon-level masks using the supplied bounding box.

3. Applies these masks to all datasets whose dimensions correspond to segments or photons.

4. Recomputes dependent indexing datasets (e.g., ph_index_beg) to maintain ATL03 structural integrity.

5. Writes the clipped data into a new, valid ATL03 HDF5 file.

This function preserves the full ATL03 metadata, ancillary information, and file structure while trimming the spatial domain to the user-specified bounding extent.

Value

An S4 object of class icesat2.atl03_h5 representing the clipped ATL03 HDF5 file saved at the output location.

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Read ATL03 data (HDF5)
atl03_h5 <- ATL03_read(atl03_path)

# Bounding rectangle coordinates (ul_lat, ul_lon, lr_lat, lr_lon)
xmin <- -106.5723
xmax <- -106.5693
ymin <- 41.533
ymax <- 41.537

bbox <- c(ymax, xmin, ymin, xmax)

# Clip ATL03 using the bounding extent
output <- tempfile(fileext = ".h5")
atl03_clip <- ATL03_h5_clipBox(
  atl03_h5,
  output = output,
  clip_obj = bbox
)

close(atl03_h5)

Description

Clips an ICESat-2 ATL03 HDF5 file using one or more geometry-based clipping objects provided as a terra::SpatVector. Each geometry in vect defines an individual clipping region. The function iteratively clips the ATL03 data for each region and writes a separate output HDF5 file for every geometry. The name of each output file is automatically appended with the value of the attribute specified in split_by.

Only datasets within the ATL03 beam groups are spatially clipped; metadata and ancillary non-beam groups remain unchanged in the resulting files.

Usage

ATL03_h5_clipGeometry(
  atl03,
  output,
  clip_obj,
  split_by = NULL,
  beam = c("gt1r", "gt2r", "gt3r", "gt1l", "gt2l", "gt3l"),
  additional_groups = c("orbit_info")
)

Arguments

Value

Returns a list of clipped S4 objects of class icesat2.atl03_h5, one for each clipping geometry contained in vect.

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Read ATL03 file
atl03_h5 <- ATL03_read(atl03_path)

# Output base filename
output <- tempfile(fileext = ".h5")

# Load clipping geometries
vect_path <- system.file("extdata", "clip_geom.shp",
  package = "ICESat2VegR"
)
vect <- terra::vect(vect_path)

# Clip ATL03 data using polygon geometries
atl03_clipped_list <- ATL03_h5_clipGeometry(
  atl03_h5,
  output,
  vect,
  split_by = "id"
)

close(atl03_h5)

Description

Extract photon-level attributes from ICESat-2 ATL03 data.

Usage

ATL03_photons_attributes_dt(
  atl03_h5,
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  attributes = c("quality_ph", "dist_ph_along")
)

Arguments

Details

The returned data.table always includes the following columns:

• beam: Beam ID (e.g., "gt2l").

• strong_beam: Logical indicating whether the beam is classified as strong for that orbit.

• lon_ph: Longitude of each received photon, computed from ECEF Cartesian coordinates of the bounce point (degrees_east).

• lat_ph: Latitude of each received photon, computed from ECEF Cartesian coordinates of the bounce point (degrees_north).

• h_ph: Height of each received photon, relative to the WGS-84 ellipsoid, including the geophysical corrections described in the ATL03 ATBD. (Geoid, ocean tide, and dynamic atmosphere corrections are not applied.)

• solar_elevation: Solar elevation interpolated from segment-level geolocation/solar_elevation to photon level.

Additional photon-level attributes can be requested using the attributes argument. These must correspond to names defined in ATL03.photon.map. Available optional attributes currently include:

• delta_time: Photon transmit time in seconds since 2018-01-01 (ATLAS SDP epoch).

• dist_ph_across: Across-track distance of the photon projected to the reference ellipsoid (meters).

• pce_mframe_cnt: Major frame counter (part of photon ID).

• ph_id_channel: Channel number assigned to the photon event.

• ph_id_count: Photon event counter (part of photon ID).

• ph_id_pulse: Laser pulse counter (part of photon ID).

• quality_ph: Photon quality flag indicating nominal, saturation, or noise conditions.

• signal_class_ph: Experimental photon classification flag based on photon weights.

• signal_conf_ph: Signal confidence level per surface type (5 x N array in original product).

• weight_ph: Relative photon weight (0-65535), proportional to photon density.

If a requested attribute is not present in a given beam, the corresponding column is filled with NA.

Value

An S4 object of class data.table::data.table (with class icesat2.atl03_dt prepended) containing photon-level ATL03 attributes.

See Also

https://nsidc.org/sites/default/files/documents/technical-reference/icesat2_atl03_data_dict_v007.pdf

Examples

atl03_path <- system.file(
  "extdata", "atl03_clip.h5",
  package = "ICESat2VegR"
)

atl03_h5 <- ATL03_read(atl03_path)

atl03_photons_dt <- ATL03_photons_attributes_dt(
 atl03_h5,
 beam = c("gt1r"),
 attributes = c("quality_ph", "dist_ph_along", "ph_id_count")
)
head(atl03_photons_dt)

close(atl03_h5)

Description

Clips ATL03 photon attributes within a given bounding extent, defined by a single clip_obj argument. The clipping extent can be provided as:

• (i) a numeric bounding box, or

• (ii) a spatial extent object.

Usage

ATL03_photons_attributes_dt_clipBox(atl03_photons_dt, clip_obj)

Arguments

Details

When clip_obj is a SpatExtent, the package terra must be installed. If not found, the function stops with an informative message.

Value

Returns a subset of the original icesat2.atl03_dt object containing only photons within the bounding box.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Examples

atl03_path <- system.file("extdata", "atl03_clip.h5",
                          package = "ICESat2VegR")

atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl03_photons_dt <- ATL03_photons_attributes_dt(atl03_h5 = atl03_h5)

# 1) Using a numeric bbox: xmin ymin xmax ymax
bbox <- c(-106.57, 41.53, -106.5698, 41.54)
atl03_clip_bbox <- ATL03_photons_attributes_dt_clipBox(
  atl03_photons_dt = atl03_photons_dt,
  clip_obj = bbox
)

# 2) Using a SpatExtent
# library(terra)
# ext <- terra::ext(-106.57, -106.5698, 41.53, 41.54)
# atl03_clip_ext <- ATL03_photons_attributes_dt_clipBox(
#   atl03_photons_dt = atl03_photons_dt,
#   clip_obj = ext
# )

close(atl03_h5)

Description

This function clips ATL03 photon attributes within given bounding coordinates.

Usage

ATL03_photons_attributes_dt_clipGeometry(
  atl03_photons_dt,
  clip_obj,
  split_by = "id"
)

Arguments

Value

Returns an S4 object of class icesat2.atl03_dt containing the ATL03 photon attributes.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL03 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)

# Extracting ATL03 photon attributes
atl03_photons_dt <- ATL03_photons_attributes_dt(atl03_h5 = atl03_h5)

# Specifying the path to shapefile
clip_obj_filepath <-
  system.file(
    "extdata",
    "clip_geom.shp",
    package = "ICESat2VegR"
  )

# Reading shapefile as sf object
clip_obj <- terra::vect(clip_obj_filepath)

# Clipping ATL03 photon attributes by Geometry
atl03_photons_dt_clip <-
  ATL03_photons_attributes_dt_clipGeometry(atl03_photons_dt, clip_obj, split_by = "id")

head(atl03_photons_dt_clip)

close(atl03_h5)

Description

Converts ATL03 photon cloud to LAS

Usage

ATL03_photons_attributes_dt_LAS(atl03_dt, output)

Arguments

Details

As the las format expects a metric coordinate reference system (CRS) we use helper functions to define UTM zones to which the original ICESat-2 data will be converted.

Writing LAS/LAZ files requires the lidR package; if it is not installed the function stops with an informative message.

The function credits go to Chuck Gantz- [email protected].

Value

Nothing, it just saves outputs as LAS file in disk

See Also

https://oceancolor.gsfc.nasa.gov/docs/ocssw/LatLong-UTMconversion_8cpp_source.html

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL03 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)

# Extracting ATL03 photons and heights
atl03_dt <- ATL03_photons_attributes_dt(atl03_h5, beam = "gt1r")

# Writing to LAS/LAZ requires the 'lidR' package
if (requireNamespace("lidR", quietly = TRUE)) {
  outdir <- tempdir()
  ATL03_photons_attributes_dt_LAS(
    atl03_dt,
    file.path(outdir, "output.laz")
  )
}

close(atl03_h5)

Description

This function reads the ICESat-2 Global Geolocated Photons Product (ATL03) from an HDF5 (.h5) file.

Usage

ATL03_read(atl03_path)

Arguments

Value

An S4 object of class icesat2.atl03_dt containing ICESat-2 ATL03 data.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r007.pdf

Examples

# Specify the path to an ATL03 file
atl03_path <- system.file(
  "extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Read ICESat-2 ATL03 data (HDF5 file)
ATL03 <- ATL03_read(atl03_path = atl03_path)
close(ATL03)

Description

Method for reading ICESat-2 ATL03 data from a local HDF5 (.h5) file.

Usage

## S4 method for signature 'character'
ATL03_read(atl03_path)

Arguments

Value

An S4 object of class icesat2.atl03_h5 containing ICESat-2 ATL03 data.

Description

Method for reading ICESat-2 ATL03 data from a cloud-based granule.

Usage

## S4 method for signature 'icesat2.granule_cloud'
ATL03_read(atl03_path)

Arguments

Value

An S4 object of class icesat2.atl03_h5 containing ICESat-2 ATL03 data.

Description

Extract geolocation segment-level metadata from ICESat-2 ATL03 data. Each row in the output corresponds to a single 20m geolocation segment along track, not to individual photons.

In addition to variables from the ATL03 geolocation group, this function derives a segment-level reference photon height (h_ph) using the reference photon index and the photon-height array in the heights group.

Usage

ATL03_seg_metadata_dt(
  atl03_h5,
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  attributes = c("h_ph", "altitude_sc", "bounce_time_offset", "delta_time",
    "full_sat_fract", "near_sat_fract", "neutat_delay_derivative", "neutat_delay_total",
    "neutat_ht", "ph_index_beg", "pitch", "podppd_flag", "range_bias_corr",
    "ref_azimuth", "ref_elev", "reference_photon_index", "roll", "segment_dist_x",
    "segment_id", "segment_length", "segment_ph_cnt", "sigma_across", "sigma_along",
    "sigma_h", "sigma_lat", "sigma_lon", "solar_azimuth", "solar_elevation", "surf_type",
    "tx_pulse_energy", "tx_pulse_skew_est", 
     "tx_pulse_width_lower",
    "tx_pulse_width_upper", "yaw")
)

Arguments

Details

The following variables may be requested via 'attributes“:

• h_ph: Height of the reference photon above the WGS84 ellipsoid for each geolocation segment. This is derived from geolocation/ph_index_beg, geolocation/reference_photon_index, and heights/h_ph.

• altitude_sc: Height of the spacecraft above the WGS84 ellipsoid.

• beta_angle: Acute angle between Sun vector and orbit plane

• bounce_time_offset: Difference between the transmit time and the ground-bounce time of the reference photon.

• delta_time: Transmit time of the reference photon, measured in seconds from 'atlas_sdp_gps_epoch“.

• full_sat_fract: Fraction of pulses within the segment that are fully saturated.

• near_sat_fract: Fraction of pulses within the segment that are nearly saturated.

• neutat_delay_derivative: Change in neutral atmospheric delay per unit height change.

• neutat_delay_total: Total neutral atmosphere delay correction (wet + dry).

• neutat_ht: Reference height of the neutral atmosphere range correction.

• ph_index_beg: 1-based index of the first photon in this segment within the photon-rate data.

• pitch: Spacecraft pitch (degrees), 3-2-1 Euler sequence.

• podppd_flag: Composite flag describing the quality of input geolocation products for the segment.

• range_bias_corr: Estimated range bias from geolocation analysis.

• ref_azimuth: Azimuth (radians) of the unit pointing vector for the reference photon in the local ENU frame.

• ref_elev: Elevation (radians) of the unit pointing vector for the reference photon in the local ENU frame.

• reference_photon_index: Index of the reference photon within the photon set for a segment.

• reference_photon_lat: Latitude of the reference photon.

• reference_photon_lon: Longitude of the reference photon.

• roll: Spacecraft roll (degrees), 3-2-1 Euler sequence.

• segment_dist_x: Along-track distance from the equator crossing to the start of the 20 m geolocation segment.

• segment_id: 7-digit along-track geolocation segment identifier.

• segment_length: Along-track length of the geolocation segment (typically 20 m).

• segment_ph_cnt: Number of photons in the segment.

• sigma_across: Estimated Cartesian across-track uncertainty (1-sigma) for the reference photon.

• sigma_along: Estimated Cartesian along-track uncertainty (1-sigma) for the reference photon.

• sigma_h: Estimated height uncertainty (1-sigma) for the reference photon bounce point.

• sigma_lat: Estimated geodetic latitude uncertainty (1-sigma) for the reference photon.

• sigma_lon: Estimated geodetic longitude uncertainty (1-sigma) for the reference photon.

• solar_azimuth: Azimuth (degrees east) of the sun position vector from the reference photon bounce point in the local ENU frame.

• solar_elevation: Elevation (degrees) of the sun position vector from the reference photon bounce point in the local ENU frame.

• surf_type: Flags describing which surface types the segment is associated with (land, ocean, sea ice, land ice, inland water).

• tx_pulse_energy: Average transmit pulse energy per beam.

• tx_pulse_skew_est: Difference between the averages of the lower and upper threshold crossing times, estimating transmit pulse skew.

• tx_pulse_width_lower: Average distance between lower threshold crossing times measured by the Start Pulse Detector.

• tx_pulse_width_upper: Average distance between upper threshold crossing times measured by the Start Pulse Detector.

• velocity_sc: Spacecraft velocity components (east component, north component, up component) an observer on the ground would measure. While values are common to all beams, this parameter is naturally produced as part of geolocation.

• yaw: Spacecraft yaw (degrees), 3-2-1 Euler sequence.

Value

A data.table::data.table with one row per ATL03 geolocation segment, with class icesat2.atl03_seg_dt prepended. Columns include:

• beam - beam ID (e.g., gt2l).

• strong_beam - logical flag indicating whether the beam is classified as strong for the orbit.

• selected geolocation fields (see below).

• a derived h_ph column: height of the reference photon for each segment (one value per segment).

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Examples

atl03_path <- system.file(
  "extdata", "atl03_clip.h5",
  package = "ICESat2VegR"
)

atl03_h5 <- ATL03_read(atl03_path)

# Extract ATL03 geolocation segment metadata
atl03_segment_dt <- ATL03_seg_metadata_dt(atl03_h5)

head(atl03_segment_dt)
close(atl03_h5)

Description

Clips an ICESat-2 ATL08 HDF5 file to a specified spatial extent. Only segment-level datasets within the ATL08 beam groups are clipped; all metadata, orbit information, and ancillary groups are preserved unchanged. This function is the bounding-box-based counterpart to geometry-based clipping functions.

Usage

ATL08_h5_clipBox(
  atl08,
  output,
  clip_obj,
  beam = c("gt1r", "gt2r", "gt3r", "gt1l", "gt2l", "gt3l"),
  additional_groups = c("orbit_info")
)

Arguments

Details

The function performs the following steps:

1. Copies file-level attributes and all requested non-beam groups.

2. Clips beam-level datasets based on latitude/longitude coordinates and the supplied spatial extent.

3. Reconstructs dependent indexing datasets (e.g., photon index ranges) when necessary to maintain valid ATL08 structure.

The resulting HDF5 file remains fully compliant with the ATL08 product structure, but contains only data within the specified bounding extent.

Value

An S4 object of class icesat2.atl08_h5 representing the clipped ATL08 HDF5 file.

Examples

# ATL08 file path
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Read ATL08 data
atl08_h5 <- ATL08_read(atl08_path)

# Bounding rectangle coordinates (ul_lat, ul_lon, lr_lat, lr_lon)
ul_lon <- -106.5723
lr_lon <- -106.5693
lr_lat <- 41.533
ul_lat <- 41.537

# Clip ATL08 data using the bounding extent
atl08_clip <- ATL08_h5_clipBox(
  atl08_h5,
  output = tempfile(fileext = ".h5"),
  clip_obj = c(ul_lat, ul_lon, lr_lat, lr_lon)
)

close(atl08_h5)
close(atl08_clip)

Description

This function clips ATL08 HDF5 file within beam groups, but keeps metada and ancillary data the same.

Usage

ATL08_h5_clipGeometry(
  atl08,
  output,
  clip_obj,
  split_by = "id",
  beam = c("gt1r", "gt2r", "gt3r", "gt1l", "gt2l", "gt3l"),
  additional_groups = c("orbit_info")
)

Arguments

Value

Returns a list of clipped S4 object of class icesat2.atl08_h5

Examples

# ATL08 file path
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

output <- tempfile(fileext = ".h5")

vect_path <- system.file("extdata",
  "clip_geom.shp",
  package = "ICESat2VegR"
)

vect <- terra::vect(vect_path)

# Clipping ATL08 photons by boundary box extent
atl08_photons_dt_clip <- ATL08_h5_clipGeometry(
  atl08_h5,
  output,
  vect,
  split_by = "id"
)

close(atl08_h5)

Description

This function extracts computed photons attributes from ICESat-2 ATL08 data

Usage

ATL08_photons_attributes_dt(
  atl08_h5,
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  photon_attributes = c("ph_segment_id", "classed_pc_indx", "classed_pc_flag", "ph_h",
    "d_flag", "delta_time")
)

Arguments

Details

These are the photons attributes extracted by default:

• ph_segment_id: Georeferenced bin number (20-m) associated with each photon

• classed_pc_indx: Indices of photons tracking back to ATL03 that surface finding software identified and used within the creation of the data products.

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

• ph_h: Height of photon above interpolated ground surface

• d_flag: Flag indicating whether DRAGANN labeled the photon as noise or signal

• delta_time: Mid-segment GPS time in seconds past an epoch. The epoch is provided in the metadata at the file level

Value

Returns an S4 object of class data.table::data.table containing the ATL08 computed photons attributes.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Examples

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path)

# Extracting ATL08 classified photons and heights
atl08_photons <- ATL08_photons_attributes_dt(atl08_h5 = atl08_h5)

head(atl08_photons)
close(atl08_h5)

Description

This function reads the ICESat-2 Land and Vegetation Along-Track Products (ATL08) as h5 file.

Usage

ATL08_photons_attributes_dt_LAS(atl08_path)

Arguments

Value

Returns an S4 object of class icesat2.atl08_dt containing ICESat-2 ATL08 data.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Examples

# ATL08 file path
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ICESat-2 ATL08 data (h5 file)
atl08 <- ATL08_read(atl08_path = atl08_path)

close(atl08)

Description

Read the ICESat-2 Land and Vegetation Along-Track Product (ATL08) from an HDF5 (.h5) file.

Usage

ATL08_read(atl08_path)

Arguments

Value

An S4 object of class icesat2.atl08_h5 containing ICESat-2 ATL08 data.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r007.pdf

Examples

# Specify the path to an example ATL08 file
atl08_path <- system.file(
  "extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Read ICESat-2 ATL08 data (HDF5 file)
atl08 <- ATL08_read(atl08_path = atl08_path)
close(atl08)

Description

Read the ICESat-2 Land and Vegetation Along-Track Product (ATL08) from a local HDF5 (.h5) file.

Usage

## S4 method for signature 'character'
ATL08_read(atl08_path)

Arguments

Value

An S4 object of class icesat2.atl08_h5 containing ICESat-2 ATL08 data.

Examples

# Specify the path to an example ATL08 file
atl08_path <- system.file(
  "extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Read ICESat-2 ATL08 data (HDF5 file)
atl08 <- ATL08_read(atl08_path = atl08_path)
close(atl08)

Description

Read the ICESat-2 Land and Vegetation Along-Track Product (ATL08) from a single granule accessible in the cloud.

Usage

## S4 method for signature 'icesat2.granule_cloud'
ATL08_read(atl08_path)

Arguments

Value

An S4 object of class icesat2.atl08_h5 containing ICESat-2 ATL08 data.

Description

This method stops execution when multiple granules are provided, because the package currently supports only one granule at a time.

Usage

## S4 method for signature 'icesat2.granules_cloud'
ATL08_read(atl08_path)

Arguments

Value

This method always stops with an error indicating that only one granule at a time is supported.

Description

This function extracts terrain and canopy attributes by segments from ICESat-2 ATL08 data

Usage

ATL08_seg_attributes_dt(
  atl08_h5,
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  attributes = c("delta_time", "h_canopy", "canopy_openness", "h_te_mean",
    "terrain_slope")
)

Arguments

Details

Segment-level attributes

• segment_id_beg

• segment_id_end

• delta_time

• delta_time_beg

• delta_time_end

• latitude_20m

• longitude_20m

• rgt

• n_seg_ph

• ph_ndx_beg

• segment_landcover

• segment_snowcover

• segment_watermask

• surf_type

• urban_flag

• night_flag

• permafrost_alt

• permafrost_prob

• cloud_flag_atm

• cloud_fold_flag

• column_od_asr

• brightness_flag

• layer_flag

• msw_flag

• psf_flag

• sat_flag

• asr

• atlas_pa

• beam_azimuth

• beam_coelev

• solar_azimuth

• solar_elevation

• snr

• dem_flag

• dem_removal_flag

• dem_h

• h_dif_ref

• last_seg_extend

• sigma_h

• sigma_along

• sigma_across

• sigma_topo

• sigma_atlas_land

ATL08 Canopy attributes

• can_noise

• can_quality_score

• canopy_h_metrics_abs

• canopy_openness

• h_canopy

• canopy_rh_conf

• h_median_canopy_abs

• h_min_canopy

• h_mean_canopy_abs

• h_median_canopy

• h_canopy_abs

• toc_roughness

• h_min_canopy_abs

• h_dif_canopy

• h_canopy_quad

• h_canopy_20m

• n_ca_photons

• photon_rate_can

• 'photon_rate_can_nr“

• centroid_height

• canopy_h_metrics_abs

• h_mean_canopy

• subset_can_flag

• canopy_h_metrics

• n_toc_photons

• h_max_canopy_abs

• h_canopy_uncertainty

• canopy_openness

• h_max_canopy

• segment_cover

ATL08 Terrain attributes

• h_te_best_fit

• h_te_best_fit_20m

• h_te_interp

• h_te_max

• h_te_mean

• h_te_median

• h_te_mode

• h_te_rh25

• h_te_skew

• h_te_std

• h_te_uncertainty

• n_te_photons

• photon_rate_te

• subset_te_flag

• terrain_slope

• te_quality

Value

Returns an S4 object of class icesat2.atl08_dt containing the ATL08-derived terrain and canopy attributes by segments.

See Also

https://nsidc.org/sites/default/files/documents/technical-reference/icesat2_atl08_atbd_v007.pdf

Examples

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL08-derived terrain and canopy attributes
atl08_seg_att_dt <- ATL08_seg_attributes_dt(atl08_h5 = atl08_h5)
head(atl08_seg_att_dt)

close(atl08_h5)

Description

Clips ATL08 terrain and canopy segment attributes within a given bounding extent, defined by a single clip_obj argument. The clipping extent can be provided as:

• (i) a numeric bounding box, or

• (ii) a spatial extent object.

Usage

ATL08_seg_attributes_dt_clipBox(atl08_seg_att_dt, clip_obj)

Arguments

Details

When clip_obj is a SpatExtent, the package terra must be installed. If not found, the function stops with an informative message.

Value

Returns an S4 object of class icesat2.atl08_dt containing the clipped ATL08 terrain and canopy attributes.

Examples

# Specifying the path to the ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path)

# Extracting ATL08-derived segment attributes
atl08_seg_att_dt <- ATL08_seg_attributes_dt(atl08_h5 = atl08_h5)

# 1) Using a numeric bounding box: xmin ymin xmax ymax
bbox <- c(-103.7604, 59.4672, -103.7600, 59.4680)

atl08_seg_att_dt_clip <- ATL08_seg_attributes_dt_clipBox(
  atl08_seg_att_dt = atl08_seg_att_dt,
  clip_obj = bbox
)

# 2) Using a SpatExtent
# library(terra)
# ext <- terra::ext(-103.7604, -103.7600, 59.4672, 59.4680)
# atl08_seg_att_dt_clip_ext <- ATL08_seg_attributes_dt_clipBox(
#   atl08_seg_att_dt = atl08_seg_att_dt,
#   clip_obj = ext
# )

close(atl08_h5)

Description

This function clips ATL08 Terrain and Canopy Attributes within a given geometry

Usage

ATL08_seg_attributes_dt_clipGeometry(
  atl08_seg_att_dt,
  clip_obj,
  split_by = NULL
)

Arguments

Value

Returns an S4 object of class icesat2.atl08_dt containing the clipped ATL08 Terrain and Canopy Attributes.

Examples

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL08-derived terrain and canopy attributes
atl08_seg_att_dt <- ATL08_seg_attributes_dt(atl08_h5 = atl08_h5)

clip_obj_path <- system.file("extdata",
  "clip_geom.shp",
  package = "ICESat2VegR"
)

if (require(terra)) {
  polygon <- terra::vect(clip_obj_path)

  head(atl08_seg_att_dt)
  # Clipping ATL08 Terrain and Canopy Attributes by Geometry
  atl08_seg_att_dt_clip <- ATL08_seg_attributes_dt_clipGeometry(
   atl08_seg_att_dt,
   polygon,
   split_by = "id"
  )

  hasLeaflet <- require(leaflet)

  if (hasLeaflet) {
    leaflet() %>%
      addCircleMarkers(atl08_seg_att_dt_clip$longitude,
        atl08_seg_att_dt_clip$latitude,
        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,
        options = providerTileOptions(minZoom = 3, maxZoom = 17)
      )
  }
}
close(atl08_h5)

Description

Computes a series of user-defined descriptive statistics within each grid cell for ATL08 terrain and canopy attributes.

Usage

ATL08_seg_attributes_dt_gridStat(atl08_seg_att_dt, func, res = 0.5)

Arguments

Value

Returns a SpatRaster object containing one layer per computed statistic of the selected ATL08 terrain and canopy attribute(s).

Examples

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL08-derived terrain and canopy attributes
atl08_seg_att_dt <- ATL08_seg_attributes_dt(atl08_h5 = atl08_h5)

# Computing mean h_canopy at 0.0001 degree grid cell
library(terra)
mean_h_canopy <- ATL08_seg_attributes_dt_gridStat(
  atl08_seg_att_dt,
  func = mean(h_canopy),
  res = 0.0001
)
terra::plot(mean_h_canopy)

# Define a custom set of metrics
mySetOfMetrics <- function(x) {
  metrics <- list(
    min = min(x, na.rm = TRUE),
    max = max(x, na.rm = TRUE),
    mean = mean(x, na.rm = TRUE),
    sd = sd(x, na.rm = TRUE)
  )
  return(metrics)
}

# Computing h_canopy statistics at 0.05 degree grid cell
h_canopy_metrics <- ATL08_seg_attributes_dt_gridStat(
  atl08_seg_att_dt,
  func = mySetOfMetrics(h_canopy),
  res = 0.05
)
terra::plot(h_canopy_metrics)

close(atl08_h5)

Description

Converts ATL08 segments to LAS

Usage

ATL08_seg_attributes_dt_LAS(atl08_dt, output)

Arguments

Details

As the las format expects a metric coordinate reference system (CRS) we use helper functions to define UTM zones to which the original ICESat-2 data will be converted.

The function credits go to Chuck Gantz- [email protected].

Value

Nothing, it just saves outputs as LAS file in disk

See Also

https://oceancolor.gsfc.nasa.gov/docs/ocssw/LatLong-UTMconversion_8cpp_source.html

Examples

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# # Extracting ATL03 and ATL08 photons and heights
atl08_dt <- ATL08_seg_attributes_dt(atl08_h5)

outputLaz <- tempfile(fileext = ".laz")
ATL08_seg_attributes_dt_LAS(
  atl08_dt,
  outputLaz
)

close(atl08_h5)

Description

Computes a series of statistics of ATL08 terrain and canopy attributes within area defined by a polygon

Usage

ATL08_seg_attributes_dt_polyStat(atl08_seg_att_dt, func, poly_id = NULL)

Arguments

Value

Returns an S4 object of class icesat2.atl08_dt Containing Statistics of ATL08 terrain and canopy attributes

Examples

# Specifying the path to ATL08 file
atl08_path <- system.file(
  "extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Extracting ATL08 terrain and canopy attributes
atl08_seg_att_dt <- ATL08_seg_attributes_dt(atl08_h5 = atl08_h5)

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

# Reading shapefile as sf object
polygon <- terra::vect(polygon_filepath)

# Clipping ATL08 terrain and canopy attributes by Geometry
atl08_seg_att_dt_clip <- ATL08_seg_attributes_dt_clipGeometry(
  atl08_seg_att_dt,
  polygon,
  split_by = "id"
)

# Computing the max h_canopy by polygon id
max_h_canopy <- ATL08_seg_attributes_dt_polyStat(
  atl08_seg_att_dt_clip,
  func = max(h_canopy),
  poly_id = "poly_id"
)
head(max_h_canopy)

# 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 a series of canopy statistics from customized function
h_canopy_metrics <- ATL08_seg_attributes_dt_polyStat(
  atl08_seg_att_dt_clip,
  func = mySetOfMetrics(h_canopy),
  poly_id = "poly_id"
)

head(h_canopy_metrics)

close(atl08_h5)

Description

This function will read multiple ATL08 H5 files and create a stack of raster layers: count, and 1st, 2nd, 3rd and 4th moments (count, m1, m2, m3 and m4) for each metric selected, from which we can calculate statistics such as Mean, SD, Skewness and Kurtosis.

Usage

ATL08_seg_attributes_h5_gridStat(
  atl08_dir,
  metrics = c("h_canopy", "canopy_rh_conf", "h_median_canopy_abs", "h_min_canopy",
    "h_mean_canopy_abs", "h_median_canopy", "h_canopy_abs", "toc_roughness",
    "h_min_canopy_abs", "h_dif_canopy", "h_canopy_quad", "h_canopy_20m", "n_ca_photons",
    "photon_rate_can", "centroid_height", "canopy_h_metrics_abs", "h_mean_canopy",
    "subset_can_flag", "canopy_h_metrics", "n_toc_photons", "h_max_canopy_abs",
    "h_canopy_uncertainty", "canopy_openness", "h_max_canopy", "segment_cover"),
  beam = c("gt1l", "gt1r", "gt2l", "gt2r", "gt3l", "gt3r"),
  out_root,
  clip_obj,
  res,
  creation_options = def_co,
  agg_function = default_agg_function,
  agg_join = default_agg_join,
  finalizer = default_finalizer
)

Arguments

Details

This function will create five different aggregate statistics (n, mean, variance, min, max). One can calculate mean and standard deviation with the following formulas according to Terriberry (2007).

The agg_function is a formula which return a data.table with the aggregate function to perform over the data. The default is:

~data.table(
    n = length(x),
    mean = mean(x,na.rm = TRUE),
    var = var(x) * (length(x) - 1),
    min = min(x, na.rm=T),
    max = max(x, na.rm=T)
  )

The agg_join is a function to merge two data.table aggregates from the agg_function. Since the h5 files will be aggregated one by one, the statistics from the different h5 files should have a function to merge them. The default function is:

function(x1, x2) {
    combined = data.table()
    x1$n[is.na(x1$n)] = 0
    x1$mean[is.na(x1$mean)] = 0
    x1$variance[is.na(x1$variance)] = 0
    x1$max[is.na(x1$max)] = -Inf
    x1$min[is.na(x1$min)] = Inf

    combined$n = x1$n + x2$n

    delta = x2$mean - x1$mean
    delta2 = delta * delta

    combined$mean = (x1$n * x1$mean + x2$n * x2$mean) / combined$n
    combined$variance = x1$variance + x2$variance +
      delta2 * x1$n * x2$n / combined$n

    combined$min = pmin(x1$min, x2$min, na.rm=F)
    combined$max = pmax(x1$max, x2$max, na.rm=F)
    return(combined)
}

The finalizer is a list of formulas to generate the final rasters based on the intermediate statistics from the previous functions. The default finalizer will calculate the sd, skewness and kurtosis based on the variance, M3, M4 and n values. It is defined as:

list(
  sd = ~sqrt(variance/(n - 1)),
)

Value

Nothing. It outputs multiple raster tif files to the out_root specified path.

References

Terriberry, Timothy B. (2007), Computing Higher-Order Moments Online, archived from the original on 23 April 2014, retrieved 5 May 2008

Examples

library(data.table)

# Specifying the path to ATL08 file
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL08 data (h5 file)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Bounding rectangle as numeric bbox: c(xmin, ymin, xmax, ymax)
clip_obj <- c(
  xmin = -106.5708541870117188,
  ymin =  41.5314979553222656,
  xmax = -106.5699081420898438,
  ymax =  41.5386848449707031
)

res <- 100 # meters
lat_to_met_factor <- 1 / 110540
lon_to_met_factor <- 1 / 111320
xres <- lon_to_met_factor * res
yres <- lat_to_met_factor * res

agg_function <- ~ data.table(
  min = min(x),
  max = max(x),
  sum = sum(x),
  n = length(x)
)

agg_join <- function(agg1, agg2) {
  agg1[is.na(agg1)] <- 0
  data.table(
    min = pmin(agg1$min, agg2$min),
    max = pmax(agg1$max, agg2$max),
    sum = agg1$sum + agg2$sum,
    n = agg1$n + agg2$n
  )
}

finalizer <- list(
  mean  = "sum/n",
  range = "max-min"
)

outdir <- tempdir()

# ATL08_seg_attributes_h5_gridStat(
#   atl08_dir        = dirname(atl08_path),
#   metrics          = c("h_canopy"),
#   out_root         = outdir,
#   beam             = c("gt1l","gt1r","gt2l","gt2r","gt3l","gt3r"),
#   clip_obj         = clip_obj,
#   res              = c(xres, -yres),
#   creation_options = c(
#     "COMPRESS=DEFLATE",
#     "BIGTIFF=IF_SAFER",
#     "TILED=YES",
#     "BLOCKXSIZE=512",
#     "BLOCKYSIZE=512"
#   ),
#   agg_function     = agg_function,
#   agg_join         = agg_join,
#   finalizer        = finalizer
# )

gc()
file.remove(list.files(outdir, "*.tif"))
close(atl08_h5)

Description

Download ICESat-2 ATL03 and ATL08 data from the LP DAAC / NSIDC endpoints. Handles connection drops by resuming partial files and retrying with exponential backoff. Authentication is handled via a .netrc file: if it does not exist, the user is prompted for Earthdata Login credentials. If authentication fails (e.g., wrong username/password), the user is informed and can choose to re-enter credentials or cancel.

Usage

ATLAS_dataDownload(
  url,
  outdir = NULL,
  overwrite = FALSE,
  buffer_size = 512,
  timeout = 10,
  retries = 3,
  backoff = 2,
  quiet = FALSE
)

Arguments

Value

(invisibly) a data.frame with columns:

• file: file name

• dest: full destination path

• status: one of ok, failed, skipped

• attempts: number of attempts used

• error: error message (if any)

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: 
urls <- c(
  "https://example.com/path/to/ATL03_001.h5",
  "https://example.com/path/to/ATL08_001.h5"
)
status <- ATLAS_dataDownload(urls,
                             outdir        = "data",
                             retries       = 5,
                             backoff       = 2)
subset(status, status == "failed")

## End(Not run)

Description

This function finds the exact granule(s) that contain ICESat-2 ATLAS data for a given region of interest and date range

Usage

ATLAS_dataFinder(
  short_name,
  lower_left_lon,
  lower_left_lat,
  upper_right_lon,
  upper_right_lat,
  version = "006",
  daterange = NULL,
  persist = TRUE,
  cloud_hosted = TRUE,
  cloud_computing = FALSE
)

Arguments

Value

Return either a vector object pointing out the path to ICESat-2 ATLAS data found within the boundary box coordinates provided for data download or a vector object containing the granules hosted on the cloud for cloud computing directly.

See Also

bbox: Defined by the upper left and lower right corner coordinates, in lat,lon ordering, for the bounding box of the area of interest (e.g. lower_left_lon,lower_left_lat,upper_right_lon,upper_right_lat)

This function relies on the existing CMR tool: https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html

Examples

# ICESat-2 data finder is a web service provided by NASA
# usually the request takes more than 5 seconds

# Specifying bounding box coordinates
lower_left_lon <- -96.0
lower_left_lat <- 40.0
upper_right_lon <- -96.5
upper_right_lat <- 40.5

# Specifying the date range
daterange <- c("2022-05-01", "2022-05-02")

# Extracting the path to ICESat-2 ATLAS data for the specified boundary box coordinates
# for data download

# Shouldn't be tested because it relies on a web service which might be down

## Not run: 
ATLAS02b_list <- ATLAS_dataFinder(
  short_name = "ATL08",
  lower_left_lon,
  lower_left_lat,
  upper_right_lon,
  upper_right_lat,
  version = "007",
  daterange = daterange
)

## End(Not run)

Description

Given a fitted randomForest::randomForest object, this function serializes the forest using the internal Rcpp module icesat2_module and constructs a corresponding Google Earth Engine random forest classifier via ee$Classifier$decisionTreeEnsemble(rf_strings).

This implementation always returns an ee$Classifier and does not use ee$Regressor.

Usage

build_ee_forest(rf)

Arguments

Value

An Earth Engine ee$Classifier object created with ee$Classifier$decisionTreeEnsemble() that can be used with ee$Image$classify().

Description

Unified clipping interface for ICESat-2 ATL03/ATL08 data. The generic clip() dispatches on the class of x and internally calls appropriate ⁠_clipBox()⁠ or ⁠_clipGeometry()⁠ helpers.

Depending on the product you are working with you can access its specific clipping methods:

ATL03_h5:

• ATL03_h5_clipBox()

• ATL03_h5_clipGeometry()

ATL08_h5:

• ATL08_h5_clipBox()

• ATL08_h5_clipGeometry()

ATL08_seg_attributes_dt:

• ATL08_seg_attributes_dt_clipBox()

• ATL08_seg_attributes_dt_clipGeometry()

ATL03_ATL08_photons_attributes_dt_join:

• ATL03_ATL08_photons_attributes_dt_clipBox()

• ATL03_ATL08_photons_attributes_dt_clipGeometry()

Usage

clip(x, clip_obj, ...)

Arguments

Description

This function clips ATL03 photon attributes within given bounding coordinates.

Usage

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

Arguments

Value

Returns an S4 object of class icesat2.atl03_dt containing the ATL03 photon attributes.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL03 data (h5 file)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)

# Extracting ATL03 photon attributes
atl03_photons_dt <- ATL03_photons_attributes_dt(atl03_h5 = atl03_h5)

# Specifying the path to shapefile
clip_obj_filepath <-
  system.file(
    "extdata",
    "clip_geom.shp",
    package = "ICESat2VegR"
  )

# Reading shapefile as sf object
clip_obj <- terra::vect(clip_obj_filepath)

# Clipping ATL03 photon attributes by Geometry
atl03_photons_dt_clip <-
  ATL03_photons_attributes_dt_clipGeometry(atl03_photons_dt, clip_obj, split_by = "id")

head(atl03_photons_dt_clip)

close(atl03_h5)

Description

Clips ATL03 photon attributes within a given bounding extent, defined by a single clip_obj argument. The clipping extent can be provided as:

• (i) a numeric bounding box, or

• (ii) a spatial extent object.

Usage

## S4 method for signature 'icesat2.atl03_dt,numeric'
clip(x, clip_obj, ...)

Arguments

Details

When clip_obj is a SpatExtent, the package terra must be installed. If not found, the function stops with an informative message.

Value

Returns a subset of the original icesat2.atl03_dt object containing only photons within the bounding box.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Examples

atl03_path <- system.file("extdata", "atl03_clip.h5",
  package = "ICESat2VegR"
)

atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl03_photons_dt <- ATL03_photons_attributes_dt(atl03_h5 = atl03_h5)

# 1) Using a numeric bbox: xmin ymin xmax ymax
bbox <- c(-106.57, 41.53, -106.5698, 41.54)
atl03_clip_bbox <- ATL03_photons_attributes_dt_clipBox(
  atl03_photons_dt = atl03_photons_dt,
  clip_obj = bbox
)

# 2) Using a SpatExtent
# library(terra)
# ext <- terra::ext(-106.57, -106.5698, 41.53, 41.54)
# atl03_clip_ext <- ATL03_photons_attributes_dt_clipBox(
#   atl03_photons_dt = atl03_photons_dt,
#   clip_obj = ext
# )

close(atl03_h5)

Description

Clips ATL03 photon attributes within a given bounding extent, defined by a single clip_obj argument. The clipping extent can be provided as:

• (i) a numeric bounding box, or

• (ii) a spatial extent object.

Usage

## S4 method for signature 'icesat2.atl03_dt,SpatExtent'
clip(x, clip_obj, ...)

Arguments

Details

When clip_obj is a SpatExtent, the package terra must be installed. If not found, the function stops with an informative message.

Value

Returns a subset of the original icesat2.atl03_dt object containing only photons within the bounding box.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Examples

atl03_path <- system.file("extdata", "atl03_clip.h5",
  package = "ICESat2VegR"
)

atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl03_photons_dt <- ATL03_photons_attributes_dt(atl03_h5 = atl03_h5)

# 1) Using a numeric bbox: xmin ymin xmax ymax
bbox <- c(-106.57, 41.53, -106.5698, 41.54)
atl03_clip_bbox <- ATL03_photons_attributes_dt_clipBox(
  atl03_photons_dt = atl03_photons_dt,
  clip_obj = bbox
)

# 2) Using a SpatExtent
# library(terra)
# ext <- terra::ext(-106.57, -106.5698, 41.53, 41.54)
# atl03_clip_ext <- ATL03_photons_attributes_dt_clipBox(
#   atl03_photons_dt = atl03_photons_dt,
#   clip_obj = ext
# )

close(atl03_h5)

Description

Clips an ICESat-2 ATL03 HDF5 file using one or more geometry-based clipping objects provided as a terra::SpatVector. Each geometry in vect defines an individual clipping region. The function iteratively clips the ATL03 data for each region and writes a separate output HDF5 file for every geometry. The name of each output file is automatically appended with the value of the attribute specified in split_by.

Only datasets within the ATL03 beam groups are spatially clipped; metadata and ancillary non-beam groups remain unchanged in the resulting files.

Usage

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

Arguments

Value

Returns a list of clipped S4 objects of class icesat2.atl03_h5, one for each clipping geometry contained in vect.

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Read ATL03 file
atl03_h5 <- ATL03_read(atl03_path)

# Output base filename
output <- tempfile(fileext = ".h5")

# Load clipping geometries
vect_path <- system.file("extdata", "clip_geom.shp",
  package = "ICESat2VegR"
)
vect <- terra::vect(vect_path)

# Clip ATL03 data using polygon geometries
atl03_clipped_list <- ATL03_h5_clipGeometry(
  atl03_h5,
  output,
  vect,
  split_by = "id"
)

close(atl03_h5)

Description

Clips an ICESat-2 ATL03 HDF5 file to a specified spatial extent. Only geolocated photon and segment datasets within the ATL03 beam groups are clipped; all metadata, orbit information, and ancillary groups are preserved unchanged. This function provides bounding-box-based clipping, complementing geometry-based clipping workflows.

Usage

## S4 method for signature 'icesat2.atl03_h5,numeric'
clip(x, clip_obj, ...)

Arguments

Details

The function performs spatial subsetting at the photon and segment level. Internally, it:

1. Copies file- and group-level attributes.

2. Extracts beam-level datasets and evaluates segment-level and photon-level masks using the supplied bounding box.

3. Applies these masks to all datasets whose dimensions correspond to segments or photons.

4. Recomputes dependent indexing datasets (e.g., ph_index_beg) to maintain ATL03 structural integrity.

5. Writes the clipped data into a new, valid ATL03 HDF5 file.

This function preserves the full ATL03 metadata, ancillary information, and file structure while trimming the spatial domain to the user-specified bounding extent.

Value

An S4 object of class icesat2.atl03_h5 representing the clipped ATL03 HDF5 file saved at the output location.

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Read ATL03 data (HDF5)
atl03_h5 <- ATL03_read(atl03_path)

# Bounding rectangle coordinates (ul_lat, ul_lon, lr_lat, lr_lon)
xmin <- -106.5723
xmax <- -106.5693
ymin <- 41.533
ymax <- 41.537

bbox <- c(ymax, xmin, ymin, xmax)

# Clip ATL03 using the bounding extent
output <- tempfile(fileext = ".h5")
atl03_clip <- ATL03_h5_clipBox(
  atl03_h5,
  output = output,
  clip_obj = bbox
)

close(atl03_h5)

Description

Clips an ICESat-2 ATL03 HDF5 file to a specified spatial extent. Only geolocated photon and segment datasets within the ATL03 beam groups are clipped; all metadata, orbit information, and ancillary groups are preserved unchanged. This function provides bounding-box-based clipping, complementing geometry-based clipping workflows.

Usage

## S4 method for signature 'icesat2.atl03_h5,SpatExtent'
clip(x, clip_obj, ...)

Arguments

Details

The function performs spatial subsetting at the photon and segment level. Internally, it:

1. Copies file- and group-level attributes.

2. Extracts beam-level datasets and evaluates segment-level and photon-level masks using the supplied bounding box.

3. Applies these masks to all datasets whose dimensions correspond to segments or photons.

4. Recomputes dependent indexing datasets (e.g., ph_index_beg) to maintain ATL03 structural integrity.

5. Writes the clipped data into a new, valid ATL03 HDF5 file.

This function preserves the full ATL03 metadata, ancillary information, and file structure while trimming the spatial domain to the user-specified bounding extent.

Value

An S4 object of class icesat2.atl03_h5 representing the clipped ATL03 HDF5 file saved at the output location.

Examples

# ATL03 file path
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

# Read ATL03 data (HDF5)
atl03_h5 <- ATL03_read(atl03_path)

# Bounding rectangle coordinates (ul_lat, ul_lon, lr_lat, lr_lon)
xmin <- -106.5723
xmax <- -106.5693
ymin <- 41.533
ymax <- 41.537

bbox <- c(ymax, xmin, ymin, xmax)

# Clip ATL03 using the bounding extent
output <- tempfile(fileext = ".h5")
atl03_clip <- ATL03_h5_clipBox(
  atl03_h5,
  output = output,
  clip_obj = bbox
)

close(atl03_h5)

Description

This function clips joined ATL03 and ATL08 photon attributes within a given geometry.

Usage

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

Arguments

Value

Returns an S4 object of class icesat2.atl03atl08_dt containing the clipped ATL08 attributes.

Examples

# Specifying the path to ATL03 and ATL08 files
atl03_path <- system.file("extdata", "atl03_clip.h5", package = "ICESat2VegR")
atl08_path <- system.file("extdata", "atl08_clip.h5", package = "ICESat2VegR")

# Reading ATL03 and ATL08 data (h5 files)
atl03_h5 <- ATL03_read(atl03_path)
atl08_h5 <- ATL08_read(atl08_path)

# Joining ATL03 and ATL08 photon attributes
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)
head(atl03_atl08_dt)

# Specifying the path to the shapefile
clip_obj_filepath <- system.file("extdata", "clip_geom.shp", package = "ICESat2VegR")

# Reading shapefile as a SpatVector object
clip_obj <- terra::vect(clip_obj_filepath)

# Clipping ATL08 terrain attributes by geometry
atl03_atl08_dt_clip <- ATL03_ATL08_photons_attributes_dt_clipGeometry(
  atl03_atl08_dt,
  clip_obj,
  split_by = "id"
)
head(atl03_atl08_dt_clip)

close(atl03_h5)
close(atl08_h5)

Description

Clips joined ATL03 and ATL08 photon attributes within a given bounding extent, defined by a single clip_obj argument. The clipping extent can be provided as:

• (i) a numeric bounding box, or

• (ii) a spatial extent object.

Usage

## S4 method for signature 'icesat2.atl03atl08_dt,numeric'
clip(x, clip_obj, ...)

Arguments

Details

When clip_obj is a SpatExtent, the package terra must be installed. If not found, the function stops with an informative message.

Value

Returns an S4 object of class icesat2.atl03atl08_dt containing a subset of the joined ATL03 and ATL08 photon attributes restricted to the clipping extent.

See Also

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Examples

# Specifying the path to ATL03 and ATL08 files
atl03_path <- system.file("extdata", "atl03_clip.h5",
  package = "ICESat2VegR"
)

atl08_path <- system.file("extdata", "atl08_clip.h5",
  package = "ICESat2VegR"
)

# Reading ATL03 and ATL08 data (h5 files)
atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# Joining ATL03 and ATL08 photons and heights
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)
head(atl03_atl08_dt)

# 1) Using a numeric bounding box: xmin ymin xmax ymax
bbox <- c(-103.7604, 59.4672, -103.7600, 59.4680)

atl03_atl08_dt_clip <- ATL03_ATL08_photons_attributes_dt_clipBox(
  atl03_atl08_dt = atl03_atl08_dt,
  clip_obj = bbox
)
head(atl03_atl08_dt_clip)

# 2) Using a SpatExtent (example)
# library(terra)
# ext <- terra::ext(-103.7604, -103.7600, 59.4672, 59.4680)
# atl03_atl08_dt_clip_ext <- ATL03_ATL08_photons_attributes_dt_clipBox(
#   atl03_atl08_dt = atl03_atl08_dt,
#   clip_obj = ext
# )

close(atl03_h5)
close(atl08_h5)

Description

Clips joined ATL03 and ATL08 photon attributes within a given bounding extent, defined by a single clip_obj argument. The clipping extent can be provided as:

• (i) a numeric bounding box, or

• (ii) a spatial extent object.

Usage

## S4 method for signature 'icesat2.atl03atl08_dt,SpatExtent'
clip(x, clip_obj, ...)

Arguments