Package {ICESat2VegR}

ICESat2VegR: NASA ICESat-2 data for land & vegetation

Description

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

Author(s)

Maintainer: Carlos Alberto Silva c.silva@ufl.edu [copyright holder]

Authors:

• Carlos Alberto Silva c.silva@ufl.edu [copyright holder]

• Caio Hamamura caiohamamura@gmail.com [copyright holder]

• Cesar Alvites c.alvitesdiaz@ufl.edu [contributor]

• Alexander J. Gaskins alexandergaskins@ufl.edu [contributor]

Other contributors:

• Sunil Arya (Author of the bundled ANN library (src/)) [contributor, copyright holder]

• David Mount (Author of the bundled ANN library (src/)) [contributor, copyright holder]

• University of Maryland (Copyright holder of the bundled ANN library (src/)) [copyright holder]

• Chuck Gantz (Author of the lat/long to UTM conversion algorithm used in R/utmTools.R) [contributor]

• Cole Krehbiel (Author of the NASA data download routine adapted in R/ATLAS_dataDownload.R) [contributor]

See Also

Useful links:

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

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

Add an EE raster layer to a leaflet map (single tile source)

Description

Add an EE raster layer to a leaflet map (single tile source)

Usage

.add_ee_image_layer(
  map,
  x,
  bands,
  aoi = NULL,
  group = NULL,
  min_value = 0,
  max_value = 1,
  palette = c("#00441B", "#1B7837", "#A6DBA0", "#E7E1EF", "#762A83"),
  is_class = FALSE,
  scale_to_int = TRUE,
  int_factor = 1000L
)

Add a tiled EE raster layer to a leaflet map (large AOIs)

Description

Add a tiled EE raster layer to a leaflet map (large AOIs)

Usage

.add_ee_image_tiled(
  map,
  x,
  bands,
  aoi,
  group = NULL,
  min_value = 0,
  max_value = 1,
  palette = c("#00441B", "#1B7837", "#A6DBA0", "#E7E1EF", "#762A83"),
  is_class = FALSE,
  scale_to_int = TRUE,
  int_factor = 1000L,
  nx = NULL,
  ny = NULL
)

Add vector overlays (sf/terra) to a leaflet map with optional categorical legend

Description

Add vector overlays (sf/terra) to a leaflet map with optional categorical legend

Usage

.add_vector_overlay(
  map,
  vect,
  group = "overlay",
  border_color = "#FF3B3B",
  border_weight = 2,
  fill = FALSE,
  fill_color = "#FF3B3B",
  fill_opacity = 0.2,
  color_field = NULL,
  palette = NULL,
  legend_title = NULL
)

Arguments

Value

Leaflet map.

Convert R geometry objects to an Earth Engine geometry

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", "clip_geom.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)

Attach per-group opacity sliders (client-side)

Description

Attach per-group opacity sliders (client-side)

Usage

.attach_opacity_control(m, position = "topright")

Arguments

Value

Leaflet map with interactive opacity controls.

Normalize and validate a Google Cloud project ID for Earth Engine

Description

This is an internal helper used by tryInitializeEarthEngine(). It accepts explicit project IDs, numeric project numbers, or pulls from the environment variable EE_PROJECT. It:

Usage

.ee_normalize_project(project, quiet = FALSE)

Arguments

Details

• Accepts accidental "projects/<id>" strings and strips the prefix.

• Allows numeric project numbers as valid.

• Rejects IDs with underscores (suggesting replacement with hyphens).

• Enforces basic format rules for project IDs.

Value

A normalized project ID string.

Compute percentiles for a band within an AOI (server-side reduce)

Description

Compute percentiles for a band within an AOI (server-side reduce)

Usage

.ee_percentiles(
  img,
  band,
  aoi,
  probs = c(2, 98),
  scale = NULL,
  maxPixels = 1e+08
)

Arguments

Value

Numeric vector of percentiles.

Check if Google Earth Engine is initialized

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)

Convert an EE Task status to an R list

Description

Convert an EE Task status to an R list

Usage

.ee_status_to_list(task)

Arguments

Value

A named list with task fields (e.g., state, description, destination_uris).

Extract a sortable timestamp from a googledrive resource row

Description

Extract a sortable timestamp from a googledrive resource row

Usage

.gd_get_time(drive_resource_row)

Order googledrive results by recency

Description

Order googledrive results by recency

Usage

.gd_order_by_time(drib)

Safe list extractor

Description

Safe list extractor

Usage

.lst_get(x, key, default = NULL)

Ensure a required namespace is available

Description

Ensure a required namespace is available

Usage

.must_have(pkg)

Arguments

LAS Public Header Description

Description

Internal function that returns the ASPRS LAS public header structure.

Usage

.publicHeaderDescription()

Value

A data.frame describing the LAS public header fields.

Register an internal tile-layer prefix per group

Description

Register an internal tile-layer prefix per group

Usage

.register_group_prefix(m, group, prefix)

Arguments

Value

Map with attribute updated.

Internal confusion matrix accuracy

Description

Internal helper to compute overall PCC, producer's accuracy and kappa from a confusion matrix. Adapted conceptually from rfUtilities::accuracy.

Usage

.rfAccuracy(cmat)

Arguments

Value

A list with:

• PCC - overall percent correctly classified.

• kappa - Cohen's kappa coefficient.

• producers.accuracy - vector of producer's accuracy per class.

Internal scaling of Random Forest importance values

Description

Internal helper for scaling permutation-based randomForest importance values. Supports the mir and 'se“ scaling options.

Usage

.rfImpScale(x, scaling = c("mir", "se"), sort = FALSE)

Arguments

Details

The scaled importance measures are calculated as:

\mathrm{mir}_j = \frac{i_j}{\max(i)}

\mathrm{se}_j = \frac{i_j / \mathrm{SE}_j}{\sum_k (i_k / \mathrm{SE}_k)}

Value

A data.frame with:

• parameter - variable name

• importance - scaled importance value

Write fixed-length character string

Description

Write fixed-length character string

Usage

.write_char_fixed(value, con, n)

Write 8-byte floating-point value

Description

Write 8-byte floating-point value

Usage

.write_f8(value, con)

Write signed 1-byte integer

Description

Write signed 1-byte integer

Usage

.write_i1(value, con)

Write signed 4-byte integer

Description

Write signed 4-byte integer

Usage

.write_i4(value, con)

Write fixed-length raw vector

Description

Write fixed-length raw vector

Usage

.write_raw_fixed(value, con, n)

Write unsigned 1-byte integer

Description

Write unsigned 1-byte integer

Usage

.write_u1(value, con)

Write unsigned 2-byte integer

Description

Write unsigned 2-byte integer

Usage

.write_u2(value, con)

Write unsigned 4-byte integer

Description

Write unsigned 4-byte integer

Usage

.write_u4(value, con)

ANNIndex Class

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/

Statistics of ATL03 and ATL08 labeled photons at the segment level

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Export Merged ICESat-2 ATL03/ATL08 Photon Data to LAS Files

Description

Converts the merged ATL03/ATL08 photon dataset generated by ATL03_ATL08_photons_attributes_dt_join() into one or more LAS files. The output preserves ATL03 photon geolocation and elevation information together with ATL08 photon classifications and normalized heights, enabling the resulting point cloud to be visualized and analyzed in standard LiDAR software.

Usage

ATL03_ATL08_photons_attributes_dt_LAS(
  atl03_atl08_dt,
  output,
  normalized = TRUE
)

Arguments

Details

This function converts the output of ATL03_ATL08_photons_attributes_dt_join() to LAS format using the package internal dt_to_las() and writeLAS() functions.

The input table must contain photon longitude, photon latitude, ATL03 photon height, ATL08 normalized photon height, and ATL08 photon classification.

If normalized = TRUE, the ph_h column is used as the LAS Z coordinate. If normalized = FALSE, the raw ATL03 h_ph column is used as the LAS Z coordinate.

Photon classes are written to the LAS Classification field using classed_pc_flag + 1.

Because LAS files require projected coordinates, the longitude and latitude values are split by UTM zone and projected to the corresponding UTM CRS before writing. One LAS file is created per UTM zone. The internal UTM-zone assignment follows helper routines based on the latitude/longitude to UTM conversion algorithms developed by Chuck Gantz.

Value

Invisibly returns a character vector with the written LAS file paths.

References

Gantz, C. Latitude/Longitude to UTM Conversion Algorithms. https://www.gpsy.com/gpsinfo/geotoutm/

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
outdir <- tempdir()

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

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_photons_attributes_dt_LAS(
  atl03_atl08_dt,
  output = file.path(outdir, "output.las"),
  normalized = TRUE
)

close(atl03_h5)
close(atl08_h5)

}

Clip joined ATL03 and ATL08 photons by bounding extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
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)

}

Clip Joined ATL03 and ATL08 by Geometry

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Statistics of ATL03 and ATL08 photon attributes

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

}

Join ATL03 and ATL08 photons attributes

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Statistics of ATL03 and ATL08 joined photons attributes within a given area

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

}

Fit and estimate ground elevation for photons or arbitrary distances from the track beginning

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Normalize photon heights relative to estimated ground elevation

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Clip joined ATL03/ATL08 segment attributes by bounding extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Clip joined ATL03/ATL08 segment attributes by geometry

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Compute canopy cover from ATL03/ATL08 classified photons

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Compute segments id for a given segment length

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Clip ICESat-2 ATL03 HDF5 Data Using a Bounding Extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

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

}

Clip ICESat-2 ATL03 HDF5 Data Using Geometry-Based Boundaries

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

# 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"
)
clip_obj <- terra::vect(vect_path)

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

close(atl03_h5)

}

ATL03 photon attributes

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
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)


}

Export ICESat-2 ATL03 Photon Data to LAS Files

Description

Converts ATL03 photon-level data extracted with ATL03_photons_attributes_dt() into one or more LAS files.

Usage

ATL03_photons_attributes_dt_LAS(atl03_dt, output)

Arguments

Details

LAS files require projected coordinates. This function uses internal helper functions to identify the appropriate UTM zone for each photon, reproject the original ICESat-2 geographic coordinates, and write one LAS file per UTM zone using the package internal LAS writer. The internal UTM-zone assignment follows helper routines based on the latitude/longitude to UTM conversion algorithms developed by Chuck Gantz.

Value

Invisibly returns a character vector with the written LAS file paths.

References

Gantz, C. Latitude/Longitude to UTM Conversion Algorithms. https://www.gpsy.com/gpsinfo/geotoutm/

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
atl03_path <- system.file("extdata",
  "atl03_clip.h5",
  package = "ICESat2VegR"
)

atl03_h5 <- ATL03_read(atl03_path = atl03_path)

atl03_dt <- ATL03_photons_attributes_dt(atl03_h5, beam = "gt1r")

outdir <- tempdir()

ATL03_photons_attributes_dt_LAS(
  atl03_dt,
  file.path(outdir, "atl03_photons.las")
)

close(atl03_h5)

}

Clip ATL03 photons by bounding extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
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)

}

Clip ATL03 photons by Coordinates

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Read ICESat-2 ATL03 data

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Read ICESat-2 ATL03 data from a local HDF5 file

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.

Read ICESat-2 ATL03 data from a single cloud granule

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.

ATL03 geolocation segment metadata

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
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)

}

Clip ICESat-2 ATL08 HDF5 Data Using a Bounding Extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

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

}

Clips ICESat-2 ATL08 data

Description

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

Clips an ICESat-2 ATL08 HDF5 file using one or more geometry-based clipping regions provided as a terra::SpatVector. Each feature (row) in clip_obj defines a separate clipping boundary. For every geometry, a new clipped ATL08 HDF5 file is created with the beam-level datasets spatially filtered to include only segments within the clipping region.

The resulting output filenames are automatically suffixed with the value of the attribute specified in split_by, enabling batch generation of multiple clipped ATL08 files from a single input.

Metadata, ancillary groups, and orbit information are preserved unchanged in every output file.

Usage

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

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

Arguments

Details

Only the beam-level groups (e.g., gt1l, 'gt2r“, ...) are spatially filtered. All metadata, orbit information, and ancillary ATL08 groups are preserved without modification.

The function:

1. Computes polygon-based masks for each beam-segment pair.

2. Removes all ATL08 segment datasets outside the clipping geometry.

3. Writes each clipped subset into its own ATL08 HDF5 file.

4. Returns the loaded results as S4 objects.

This is the geometry-based companion to bounding-box clipping functions in the package.

Value

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

A list of clipped S4 objects of class icesat2.atl08_h5, one for each geometry in clip_obj.

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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"
)

clip_obj <- terra::vect(vect_path)

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

close(atl08_h5)
}
if (requireNamespace("hdf5r", quietly = TRUE)) {

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

# Read ATL08 file
ATL08_h5 <- ATL08_read(ATL08_path)

# Base output name (actual filenames will append split_by values)
output <- tempfile(fileext = ".h5")

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

# Clip ATL08 using polygon geometries
ATL08_clipped_list <- ATL08_h5_clipGeometry(
  ATL08_h5,
  output,
  clip_obj,
  split_by = "id"
)

close(ATL08_h5)

}

ATL08 computed photons attributes

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Export ICESat-2 ATL08 photon attributes to LAS files

Description

Converts ICESat-2 ATL08 photon-level data stored as a data.table to one or more LAS files.

Usage

ATL08_photons_attributes_dt_LAS(atl08_dt, output)

Arguments

Details

This function is designed for ATL08 photon-level data, including classified photon attributes such as photon height, classification flag, and photon segment ID. The input must contain longitude, latitude, and photon height information. Because LAS files require projected coordinates, the input longitude and latitude values are automatically split by UTM zone and reprojected before writing the LAS file. The internal UTM-zone assignment follows helper routines based on the latitude/longitude to UTM conversion algorithms developed by Chuck Gantz.

Value

Invisibly returns a character vector with the written LAS file paths.

References

Gantz, C. Latitude/Longitude to UTM Conversion Algorithms. https://www.gpsy.com/gpsinfo/geotoutm/

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
atl03_path <- system.file("extdata", "atl03_clip.h5", package = "ICESat2VegR")
atl08_path <- system.file("extdata", "atl08_clip.h5", package = "ICESat2VegR")

atl03_h5 <- ATL03_read(atl03_path = atl03_path)
atl08_h5 <- ATL08_read(atl08_path = atl08_path)

# ATL08 photon attributes alone have no geolocation; join with ATL03 first
atl03_atl08_dt <- ATL03_ATL08_photons_attributes_dt_join(atl03_h5, atl08_h5)
atl08_photons <- data.table::data.table(
  longitude = atl03_atl08_dt$lon_ph,
  latitude  = atl03_atl08_dt$lat_ph,
  ph_h      = atl03_atl08_dt$ph_h
)

ATL08_photons_attributes_dt_LAS(
  atl08_dt = atl08_photons,
  output = tempfile(fileext = ".las")
)

close(atl03_h5)
close(atl08_h5)

}

Read ICESat-2 ATL08 data

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Read ICESat-2 ATL08 data from a local HDF5 file

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Read ICESat-2 ATL08 data from a single granule in the cloud

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.

Read ICESat-2 ATL08 data from multiple granules

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.

ATL08 Terrain and Canopy Attributes

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Export ICESat-2 ATL08 Segment Data to LAS Files

Description

Converts ATL08 segment-level vegetation attributes extracted with ATL08_seg_attributes_dt() into one or more LAS files.

Usage

ATL08_seg_attributes_dt_LAS(atl08_dt, output)

Arguments

Details

This function exports ATL08 segment-level observations as LAS point clouds using longitude, latitude, and canopy height h_canopy.

Because LAS files require projected coordinates, the input geographic coordinates are automatically reprojected to the appropriate UTM coordinate reference system before export. If the data span multiple UTM zones, one LAS file is generated for each zone.

The internal UTM-zone assignment follows helper routines based on the latitude/longitude to UTM conversion algorithms developed by Chuck Gantz.

Value

Invisibly returns a character vector with the written LAS file paths.

References

Gantz, C. Latitude/Longitude to UTM Conversion Algorithms. https://www.gpsy.com/gpsinfo/geotoutm/

See Also

ATL08_seg_attributes_dt, dt_to_las

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
atl08_path <- system.file("extdata",
  "atl08_clip.h5",
  package = "ICESat2VegR"
)

atl08_h5 <- ATL08_read(atl08_path = atl08_path)

atl08_dt <- ATL08_seg_attributes_dt(atl08_h5)

outputLas <- tempfile(fileext = ".las")

ATL08_seg_attributes_dt_LAS(
  atl08_dt,
  outputLas
)

close(atl08_h5)

}

Clip ATL08 terrain and canopy attributes by bounding extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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
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)

}

Clip ATL08 Terrain and Canopy Attributes by Geometry

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

}

Statistics of ATL08 terrain and canopy attributes at grid level

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}
}

Statistics of ATL08 Terrain and Canopy Attributes by Geometry

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Rasterize ATL08 canopy attributes from h5 files at large scale

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

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 <- file.path(tempdir(), "gridstat_out")
dir.create(outdir)
out_root <- file.path(outdir, "h_canopy")

ATL08_seg_attributes_h5_gridStat(
  atl08_dir        = dirname(atl08_path),
  metrics          = c("h_canopy"),
  out_root         = out_root,
  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()
unlink(outdir, recursive = TRUE)
close(atl08_h5)

}

Download ICESat-2 ATL03/ATL08 data

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)

ICESat-2 ATL03 and ATL08 data finder for either direct download or cloud computing

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)

List of datatypes supported by the GDALDataset R6 class

Description

List of datatypes supported by the GDALDataset R6 class

Usage

GDALDataType

R6 Class GDALDataset wrapping

Description

Wrapping class for GDALDataset C++ API exporting GetRasterBand, GetRasterXSize, GetRasterYSize

Methods

Public methods

• GDALDataset$new()

• GDALDataset$GetRasterBand()

• GDALDataset$GetRasterXSize()

• GDALDataset$GetRasterYSize()

• GDALDataset$Close()

• GDALDataset$clone()

GDALDataset$new()

Create a new raster file based on specified data. It will output a *.tif file.

Usage

GDALDataset$new(ds)

Arguments

Returns

An object from GDALDataset R6 class.

GDALDataset$GetRasterBand()

Function to retrieve the GDALRasterBand R6 Object.

Usage

GDALDataset$GetRasterBand(x)

Arguments

Returns

An object of GDALRasterBand R6 class.

GDALDataset$GetRasterXSize()

Get the width for the raster

Usage

GDALDataset$GetRasterXSize()

Returns

An integer indicating the raster width

GDALDataset$GetRasterYSize()

Get the height for the raster

Usage

GDALDataset$GetRasterYSize()

Returns

An integer indicating the raster height

GDALDataset$Close()

Closes the GDALDataset

Usage

GDALDataset$Close()

Returns

An integer indicating the raster width

GDALDataset$clone()

The objects of this class are cloneable with this method.

Usage

GDALDataset$clone(deep = FALSE)

Arguments

Open GDAL raster

Description

Function to open GDAL Dataset

Usage

GDALOpen(filename, readonly = TRUE)

Arguments

Value

An R6 object of GDALDataset class.

Examples

# Create a small raster to open
ds_path <- tempfile(fileext = ".tif")
ds <- createDataset(
  raster_path = ds_path,
  nbands = 1,
  datatype = GDALDataType$GDT_Int32,
  projstring = "EPSG:4326",
  ul_lat = -15, ul_lon = -45, lr_lat = -25, lr_lon = -35,
  res = c(0.01, -0.01),
  nodata = -1
)
ds$Close()

# Reopen the raster read-only
ds2 <- GDALOpen(ds_path)
ds2$Close()

R6 Class GDALRasterBand wrapping

Description

Wrapping class for GDALRasterBand C++ API exporting GetBlockXSize, GetBlockYSize, ReadBlock, WriteBlock for better IO speed.

Methods

Public methods

• GDALRasterBand$new()

• GDALRasterBand$ReadBlock()

• GDALRasterBand$WriteBlock()

• GDALRasterBand$GetBlockXSize()

• GDALRasterBand$GetBlockYSize()

• GDALRasterBand$GetXSize()

• GDALRasterBand$CalculateStatistics()

• GDALRasterBand$GetYSize()

• GDALRasterBand$GetNoDataValue()

• GDALRasterBand$GetRasterDataType()

• GDALRasterBand$clone()

GDALRasterBand$new()

Creates a new GDALRasterBand

Usage

GDALRasterBand$new(band)

Arguments

Returns

An object of GDALRasterBand R6 class

GDALRasterBand$ReadBlock()

Efficiently reads a raster block

Usage

GDALRasterBand$ReadBlock(iXBlock, iYBlock)

Arguments

Details

The returned Vector will be single dimensional with the length BLOCKXSIZE \times BLOCKYSIZE . If you use matrix(, ncol=BLOCKXSIZE) the matrix returned will actually be transposed. You should either transpose it or you can calculate the indices using y \cdot xsize + x

Returns

RawVector for GDALDataType$GDT_Byte, IntegerVector for int types and NumericVector for floating point types.

GDALRasterBand$WriteBlock()

Efficiently writes a raster block

Usage

GDALRasterBand$WriteBlock(iXBlock, iYBlock, buffer)

Arguments

Details

The returned Vector will be single dimensional with the length BLOCKXSIZE \times BLOCKYSIZE . If you use matrix(, ncol=BLOCKXSIZE) the matrix returned will actually be transposed. You should either transpose it or you can calculate the indices using y \cdot xsize + x .

Returns

Nothing

GDALRasterBand$GetBlockXSize()

Get the block width

Usage

GDALRasterBand$GetBlockXSize()

Returns

An integer indicating block width

GDALRasterBand$GetBlockYSize()

Get the block height

Usage

GDALRasterBand$GetBlockYSize()

Returns

An integer indicating block height

GDALRasterBand$GetXSize()

Get the band width

Usage

GDALRasterBand$GetXSize()

Returns

An integer indicating band width

GDALRasterBand$CalculateStatistics()

Calculate statistics for the GDALRasterBand

Usage

GDALRasterBand$CalculateStatistics()

Returns

nothing

GDALRasterBand$GetYSize()

Get the band height

Usage

GDALRasterBand$GetYSize()

Returns

An integer indicating band height

GDALRasterBand$GetNoDataValue()

Get band no data value

Usage

GDALRasterBand$GetNoDataValue()

Returns

Numeric indicating no data value

GDALRasterBand$GetRasterDataType()

Get band datatype

Usage

GDALRasterBand$GetRasterDataType()

Returns

Numeric indicating the datatype

GDALRasterBand$clone()

The objects of this class are cloneable with this method.

Usage

GDALRasterBand$clone(deep = FALSE)

Arguments

Note

This constructor must not be called at all, this is automatically called from GDALDataset$GetRasterBand function.

The class representing the h5 file opened from the cloud for cloud computing

Description

Besides representing h5 files, it is also used to represent groups opened with ⁠[[]]⁠.

The variants ⁠_cloud⁠ and ⁠_local⁠ allows all the other functions to use generic calls using the same interface, with each class implementation is provided accordingly.

The regular usage does not require the user to work with those classes as most other provided functions will actually give access to the most common necessities for working with ICESat-2 data.

Public fields

Methods

Public methods

• ICESat2.h5_cloud$new()

• ICESat2.h5_cloud$ls()

• ICESat2.h5_cloud$ls_groups()

• ICESat2.h5_cloud$ls_attrs()

• ICESat2.h5_cloud$dt_datasets()

• ICESat2.h5_cloud$exists()

• ICESat2.h5_cloud$attr()

• ICESat2.h5_cloud$close_all()

• ICESat2.h5_cloud$print()

• ICESat2.h5_cloud$clone()

ICESat2.h5_cloud$new()

Direct initialization should not be used, it is handled by ATL0X_read()

Usage

ICESat2.h5_cloud$new(h5)

Arguments

Returns

The class object

ICESat2.h5_cloud$ls()

Lists the groups and datasets that are within current group

Usage

ICESat2.h5_cloud$ls()

Returns

List the groups and datasets within the current path

ICESat2.h5_cloud$ls_groups()

Lists all grouops recursively

Usage

ICESat2.h5_cloud$ls_groups(recursive = FALSE)

Arguments

Returns

The character representing

ICESat2.h5_cloud$ls_attrs()

Lists the available attributes

Usage

ICESat2.h5_cloud$ls_attrs()

Returns

character vector of attributes available

ICESat2.h5_cloud$dt_datasets()

Get datasets as data.table with columns (name, dataset.dims, rank)

Usage

ICESat2.h5_cloud$dt_datasets(recursive = FALSE)

Arguments

Returns

A data.table::data.table with the columns (name, dataset.dims, rank)

ICESat2.h5_cloud$exists()

Checks if a supplied group/dataset exist within the H5

Usage

ICESat2.h5_cloud$exists(path)

Arguments

Returns

logical TRUE or FALSE if it exists or not

ICESat2.h5_cloud$attr()

Read an attribute from h5

Usage

ICESat2.h5_cloud$attr(attribute)

Arguments

ICESat2.h5_cloud$close_all()

Safely closes the h5 file pointer

Usage

ICESat2.h5_cloud$close_all()

Returns

Nothing, just closes the file

ICESat2.h5_cloud$print()

Prints the data in a friendly manner

Usage

ICESat2.h5_cloud$print(...)

Arguments

Returns

Outputs information about object

ICESat2.h5_cloud$clone()

The objects of this class are cloneable with this method.

Usage

ICESat2.h5_cloud$clone(deep = FALSE)

Arguments

The class representing the h5 file opened from local files

Description

The variants ⁠_cloud⁠ and ⁠_local⁠ allows all the other functions to use generic calls using the same interface, with each class implementation is provided accordingly.

The regular usage does not require the user to work with those classes as most other provided functions will actually give access to the most common necessities for working with ICESat-2 data.

Public fields

Methods

Public methods

• ICESat2.h5_local$new()

• ICESat2.h5_local$ls()

• ICESat2.h5_local$ls_groups()

• ICESat2.h5_local$ls_attrs()

• ICESat2.h5_local$dt_datasets()

• ICESat2.h5_local$exists()

• ICESat2.h5_local$attr()

• ICESat2.h5_local$close_all()

• ICESat2.h5_local$print()

• ICESat2.h5_local$clone()

ICESat2.h5_local$new()

Direct initialization should not be used, it is handled by ATL0X_read()

Usage

ICESat2.h5_local$new(h5)

Arguments

Returns

The class object

ICESat2.h5_local$ls()

Lists the groups and datasets that are within current group

Usage

ICESat2.h5_local$ls()

Returns

List the groups and datasets within the current path

ICESat2.h5_local$ls_groups()

Lists all grouops recursively

Usage

ICESat2.h5_local$ls_groups(recursive = FALSE)

Arguments

Returns

The character representing

ICESat2.h5_local$ls_attrs()

Lists the available attributes

Usage

ICESat2.h5_local$ls_attrs()

Returns

character vector of attributes available

ICESat2.h5_local$dt_datasets()

Get datasets as data.table with columns (name, dataset.dims, rank)

Usage

ICESat2.h5_local$dt_datasets(recursive = FALSE)

Arguments

Returns

A data.table::data.table with the columns (name, dataset.dims, rank)

ICESat2.h5_local$exists()

Checks if a supplied group/dataset exist within the H5

Usage

ICESat2.h5_local$exists(path)

Arguments

Returns

logical TRUE or FALSE if it exists or not

ICESat2.h5_local$attr()

Read an attribute from h5

Usage

ICESat2.h5_local$attr(attribute)

Arguments

ICESat2.h5_local$close_all()

Safely closes the h5 file pointer

Usage

ICESat2.h5_local$close_all(silent = TRUE)

Arguments

Returns

Nothing, just closes the file

ICESat2.h5_local$print()

Prints the data in a friendly manner

Usage

ICESat2.h5_local$print(...)

Arguments

Returns

Outputs information about object

ICESat2.h5_local$clone()

The objects of this class are cloneable with this method.

Usage

ICESat2.h5_local$clone(deep = FALSE)

Arguments

Class representing dataset opened from the cloud using h5py

Description

This class should not be instanced by the user, instead it is automatically handled when the user opens a dataset using ⁠[[]]⁠ operator from a h5 file.

Public fields

Methods

Public methods

• ICESat2.h5ds_cloud$new()

• ICESat2.h5ds_cloud$get_type()

• ICESat2.h5ds_cloud$get_fill_value()

• ICESat2.h5ds_cloud$get_creation_property_list()

• ICESat2.h5ds_cloud$clone()

ICESat2.h5ds_cloud$new()

Constructor using a dataset pointer

Usage

ICESat2.h5ds_cloud$new(ds)

Arguments

ICESat2.h5ds_cloud$get_type()

Get the type of data for this dataset

Usage

ICESat2.h5ds_cloud$get_type()

ICESat2.h5ds_cloud$get_fill_value()

Get the fill_value used by the dataset

Usage

ICESat2.h5ds_cloud$get_fill_value()

ICESat2.h5ds_cloud$get_creation_property_list()

Get creation property list for the dataset (plist)

Usage

ICESat2.h5ds_cloud$get_creation_property_list()

ICESat2.h5ds_cloud$clone()

The objects of this class are cloneable with this method.

Usage

ICESat2.h5ds_cloud$clone(deep = FALSE)

Arguments

Class representing dataset opened from locally using hdf5r

Description

This class should not be instanced by the user, instead it is automatically handled when the user opens a dataset using ⁠[[]]⁠ operator from a h5 file.

Public fields

Methods

Public methods

• ICESat2.h5ds_local$new()

• ICESat2.h5ds_local$get_type()

• ICESat2.h5ds_local$get_fill_value()

• ICESat2.h5ds_local$get_creation_property_list()

• ICESat2.h5ds_local$clone()

ICESat2.h5ds_local$new()

Constructor using a dataset pointer

Usage

ICESat2.h5ds_local$new(ds)

Arguments

ICESat2.h5ds_local$get_type()

Get the type of data for this dataset

Usage

ICESat2.h5ds_local$get_type()

ICESat2.h5ds_local$get_fill_value()

Get the fill_value used by the dataset

Usage

ICESat2.h5ds_local$get_fill_value()

ICESat2.h5ds_local$get_creation_property_list()

Get creation property list for the dataset (plist)

Usage

ICESat2.h5ds_local$get_creation_property_list()

ICESat2.h5ds_local$clone()

The objects of this class are cloneable with this method.

Usage

ICESat2.h5ds_local$clone(deep = FALSE)

Arguments

Configure Python environment for ICESat2VegR cloud features

Description

This function sets up a robust, persistent Python environment for the cloud-related features of ICESat2VegR, including:

Usage

ICESat2VegR_configure(
  envname = "icesat2-env",
  py_ver = "3.10",
  prefer_conda = TRUE,
  force_conda_forge = TRUE,
  allow_session_installs = TRUE,
  manage_aiobotocore = TRUE,
  auto_restart = TRUE,
  verbose = TRUE,
  quick_probe = c("h5py", "earthaccess", "ee")
)

Arguments

Details

• Downloading ICESat-2 data via earthaccess

• Interfacing with Google Earth Engine via earthengine-api

• Handling S3 access via boto3/botocore

The function:

• Detects whether Python is already initialized in the R session.

• Performs a fast "quick probe" to see if required modules are present (h5py, earthaccess, ee by default).

• If everything is already available, it returns immediately.

• Otherwise, it:

  • Ensures Miniconda is installed (if prefer_conda = TRUE).

  • Creates or reuses a conda environment (default: "icesat2-env").

  • Installs required Python modules using conda-forge (and pip fallback).

  • Optionally tries in-session installs if Python is already initialized.

  • Optionally resolves common aiobotocore/botocore conflicts.

  • Optionally restarts the R session in RStudio to bind the new env.

Typical usage is simply:

  ICESat2VegR_configure()

You usually only need to run this:

• Once per machine, or

• After major Python / Miniconda changes, or

• If the package reports missing Python modules.

Value

Logical TRUE on success, FALSE otherwise.

Checked/installed Python modules

The function checks for the following import names and installs the corresponding packages when missing:

Examples

## Not run: 
  # Basic configuration using defaults
  ICESat2VegR_configure()

  # Use existing conda env named "icesat2"
  ICESat2VegR_configure(envname = "icesat2")

## End(Not run)

Subset Granules

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.

GDALRasterBand [[]]= 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

Extract Granules

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)

GDALDataset [[]] accessor

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.

GDALRasterBand [[]] getter

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

Add an Earth Engine Image to a leaflet map

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)

Compute terrain aspect (degrees) from a DEM image

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)

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

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

Extract the ICESat-2 timestamp from an ATL filename

Description

Extracts a 14-digit timestamp (YYYYMMDDHHMMSS) from an ICESat-2 ATL granule filename or path. Many ATL03/ATL08 filenames include a timestamp segment such as ATL03_20200101000000_...; this helper retrieves that substring.

Usage

atl_extract_timestamp(file_path)

Arguments

Value

A character vector of the same length as file_path, where each element is either the extracted 14-digit timestamp (YYYYMMDDHHMMSS) or, if no match is found, the original string (due to the use of sub()).

Convert an R randomForest model to a Google Earth Engine randomForest classifier

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

Stop with an informative message if 'hdf5r' is not installed

Description

hdf5r is an optional (Suggests) dependency used only for reading and writing local HDF5 (.h5) files.

Usage

check_hdf5r()

Value

Nothing, called for the side effect of stopping if missing

Clip ICESat-2 ATL03/ATL08 data ( h5, attributes, or ATL03-ATL08 join) by box or geometry

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

Clip ATL03 photons by Coordinates

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Clip ATL03 photons by bounding extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
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
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)
}

Clip ATL03 photons by bounding extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
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
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)
}

Clip ICESat-2 ATL03 HDF5 Data Using Geometry-Based Boundaries

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

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

}

Clip ICESat-2 ATL03 HDF5 Data Using a Bounding Extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

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


}

Clip ICESat-2 ATL03 HDF5 Data Using a Bounding Extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

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

}

Clip Joined ATL03 and ATL08 by Geometry

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
}

Clip joined ATL03 and ATL08 photons by bounding extent

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

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
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)
}

Clip joined ATL03 and ATL08 photons by bounding extent

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

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)
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)

}

Clip ATL08 Terrain and Canopy Attributes by Geometry

Description

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

Usage

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

Arguments

Value

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

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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)

}

Clip ATL08 terrain and canopy attributes by bounding extent

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

## S4 method for signature 'icesat2.atl08_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 an S4 object of class icesat2.atl08_dt containing the clipped ATL08 terrain and canopy attributes.

Clip ATL08 terrain and canopy attributes by bounding extent

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

## S4 method for signature 'icesat2.atl08_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.atl08_dt containing the clipped ATL08 terrain and canopy attributes.

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
# 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
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)

}

Clips ICESat-2 ATL08 data

Description

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

Usage

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

Arguments

Value

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

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {

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

}

Clip ICESat-2 ATL08 HDF5 Data Using a Bounding Extent

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

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

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

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


}

Clip ICESat-2 ATL08 HDF5 Data Using a Bounding Extent

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

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

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

if (requireNamespace("hdf5r", quietly = TRUE)) {

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


}

Safely closes the ICESat2.h5 base classes

Description

Closing files will avoid locking HDF5 ATL03 files.

Closing files will avoid locking HDF5 files.

Usage

## S4 method for signature 'icesat2.h5'
close(con, ...)

## S4 method for signature 'icesat2.predict_h5'
close(con, ...)

Arguments

Method to close GDALDataset

Description

Closing ensures the data is actually flushed (saved) to the dataset also it releases the lock from the file.

Usage

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

Arguments

Closes the HDF5 file pointer to release resources

Description

Closes the HDF5 file pointer to release resources

Usage

## S3 method for class 'icesat2.predict_h5'
close(con, ...)

Arguments

Value

Nothing, just closes the HDF5 file pointer

Creates a new GDALDataset

Description

Create a new raster file based on specified data. It will output a *.tif file.

Usage

createDataset(
  raster_path,
  nbands,
  datatype,
  projstring,
  lr_lat,
  ul_lat,
  ul_lon,
  lr_lon,
  res,
  nodata,
  co = c("TILED=YES", "BLOCKXSIZE=512", "BLOCKYSIZE=512", "COMPRESSION=LZW")
)

Arguments

Value

An object from GDALDataset R6 class.

Examples

# Parameters
raster_path <- tempfile(fileext = ".tif")
ul_lat <- -15
ul_lon <- -45
lr_lat <- -25
lr_lon <- -35
res <- c(0.01, -0.01)
datatype <- GDALDataType$GDT_Int32
nbands <- 1
projstring <- "EPSG:4326"
nodata <- -1
co <- c("TILED=YES", "BLOCKXSIZE=512", "BLOCKYSIZE=512", "COMPRESSION=LZW")

# Create a new raster dataset
ds <- createDataset(
  raster_path = raster_path,
  nbands = nbands,
  datatype = datatype,
  projstring = projstring,
  lr_lat = lr_lat,
  ul_lat = ul_lat,
  ul_lon = ul_lon,
  lr_lon = lr_lon,
  res = res,
  nodata = nodata,
  co = co
)

# Get the GDALRasterBand for ds
band <- ds[[1]]

# Set some dummy values
band[[0, 0]] <- 1:(512 * 512)

ds$Close()

Convert ICESat-2 ATL03 and ATL08 data.table objects to LAS files

Description

Converts ICESat-2 ATL03 or ATL08 point data stored as a data.table with longitude, latitude, and height values into one or more LAS files.

Usage

dt_to_las(dt, output)

Arguments

Details

The input data must contain at least three columns representing longitude, latitude, and height. The function renames the first three columns to X, Y, and Z internally. The original X and Y values are assumed to be longitude and latitude in EPSG:4326.

Because LAS files should store projected coordinates, the function identifies the appropriate UTM zone for each point, splits the dataset by UTM zone, projects each subset to the corresponding UTM coordinate system, and writes one LAS file per UTM zone.

Value

Invisibly returns a character vector with the written LAS file paths.

Examples

library(data.table)

dt <- data.table(
  lon = runif(1000, -52.5, -52.4),
  lat = runif(1000, -15.9, -15.8),
  h = runif(1000, 0, 35)
)

dt_to_las(dt, tempfile(fileext = ".las"))

The pointer to the earthaccess python reticulate module

Description

The pointer to the earthaccess python reticulate module

Usage

earthaccess

Get or Create a .netrc File for NASA Earthdata Login

Description

Creates (if necessary) and configures a .netrc file containing credentials for NASA Earthdata Login (<urs.earthdata.nasa.gov>). This file is required for authenticated downloads from Earthdata services (e.g., via earthaccess, curl, wget, or other clients).

Usage

earthdata_login(output_dir = tempdir())

Arguments

Details

The function will:

• Use an existing .netrc file if valid credentials are already present

• Otherwise prompt the user securely for credentials

• Or read credentials from environment variables:

  • EARTHDATA_USERNAME

  • EARTHDATA_PASSWORD

• Set the NETRC environment variable for the active Python session

Credentials are written in standard .netrc format:

machine urs.earthdata.nasa.gov
  login <username>
  password <password>

If credentials are not found in environment variables and the package getPass is available, the user is prompted securely. Otherwise, an error is thrown.

The function also updates the NETRC environment variable inside the active Python session via reticulate, ensuring compatibility with Python libraries such as earthaccess.

Value

Character string. The normalized path to the .netrc file being used.

See Also

NASA Earthdata Login

The pointer to the earth-engine-api python reticulate module

Description

The pointer to the earth-engine-api python reticulate module

Usage

ee

See Also

https://developers.google.com/earth-engine/apidocs

Stack Alpha Earth embedding and terrain ancillary layers

Description

Creates a Google Earth Engine image stack that combines:

• Annual satellite embeddings from GOOGLE/SATELLITE_EMBEDDING/V1/ANNUAL (AlphaEarth).

• Terrain derivatives (elevation, slope, aspect) from USGS 3DEP or NASADEM as fallbacks.

• Optional longitude/latitude bands from ee$Image$pixelLonLat().

The embedding collection is filtered to the specified year range and AOI, reduced using a pixel-wise median, and clipped to the AOI. Terrain data are reprojected to a target scale (default 30 m).

Geographic coverage limitation: The primary terrain sources (USGS 3DEP 1 m and 10 m) cover only the contiguous United States, Alaska, and Hawaii. For areas outside the US, the function falls back to NASADEM, which provides global coverage but at coarser resolution (~30 m). For best terrain accuracy, this function is recommended for use within the United States.

Authentication: This function requires an active Google Earth Engine session. Authenticate using ICESat2VegR::ee_initialize() before calling this function.

Usage

ee_build_AlphaEarth_embedding_terrain_stack(
  geom,
  start_year,
  end_year,
  mask_outside = TRUE,
  terrain_scale = 30,
  multiply_slope_aspect_by10 = TRUE,
  add_lonlat = TRUE
)

Arguments

Details

The terrain source is chosen in the following order:

1. USGS 3DEP 1 m (USGS/3DEP/1m), if available for the AOI.

2. USGS 3DEP 10 m (USGS/3DEP/10m).

3. NASADEM (NASA/NASADEM_HGT/001) as a global fallback.

All terrain layers are clipped to the AOI and reprojected to EPSG:4326 with the requested terrain_scale.

Value

A Python ee$Image object containing:

• The median annual AlphaEarth embedding bands.

• elevation, slope, and aspect bands.

• Optional lon and lat bands.

Examples

## Not run: 
  # Requires Google Earth Engine authentication
  # Note: USGS 3DEP terrain data covers the United States only.
  # Outside the US, NASADEM is used as a global fallback.
  Sys.setenv(EE_PROJECT = "your-ee-project-id")
  ICESat2VegR::ee_initialize()

  library(sf)
  aoi <- st_as_sfc(st_bbox(c(
    xmin = -82.4, xmax = -82.2,
    ymin =  29.6, ymax =  29.8
  ), crs = 4326))

  ee_geom <- ICESat2VegR::.as_ee_geom(aoi)

  # Build the embedding + terrain stack for 2025
  predictors <- ee_build_AlphaEarth_embedding_terrain_stack(
    geom       = ee_geom,
    start_year = 2025,
    end_year   = 2025
  )

  # Visualize RGB embedding bands using leaflet
  predictors_rgb <- predictors$select(c("A00", "A20", "A40"))

  centroid_lon <- mean(terra::ext(terra::vect(aoi))[c(1, 2)])
  centroid_lat <- mean(terra::ext(terra::vect(aoi))[c(3, 4)])

  leaflet::leaflet() |>
    ICESat2VegR::addEEImage(
      predictors_rgb,
      bands = c("A00", "A20", "A40"),
      group = "RGB Embedding",
      min   = -0.2,
      max   =  0.2
    ) |>
    leaflet::setView(
      lng  = centroid_lon,
      lat  = centroid_lat,
      zoom = 15
    ) |>
    leaflet::addLayersControl(
      overlayGroups = "RGB Embedding",
      options = leaflet::layersControlOptions(collapsed = FALSE)
    )

## End(Not run)

Build HLS, Sentinel-1C and terrain ancillary stack in Earth Engine

Description

Constructs a multi-source ancillary stack in Google Earth Engine composed of:

1. Optical features from the Harmonized Landsat and Sentinel-2 (HLS) product, including spectral bands, vegetation indices, and spectral unmixing fractions.

2. C-band SAR backscatter and radar-based indices from Sentinel-1C GRD.

3. Terrain variables (elevation, slope, aspect) from a NASA DEM.

4. Neighborhood statistics (mean, min, max, stdDev) computed over a 3x3 kernel for HLS and terrain bands.

5. GLCM texture metrics computed from scaled HLS reflectance bands.

The final stack contains 244 bands covering spectral, radar, terrain, neighborhood, and texture features.

Authentication: This function requires an active Google Earth Engine session. Authenticate using ICESat2VegR::ee_initialize() before calling this function.

Usage

ee_build_hls_s1c_terrain_stack(
  x,
  start_date,
  end_date,
  cloud_max = 10,
  buffer_m = 30,
  hls_collection_id = c("NASA/HLS/HLSS30/v002", "NASA/HLS/HLSL30/v002")
)

Arguments

Details

The HLS collection is selected automatically from hls_collection_id by trying each ID in order and using the first one that contains scenes for the specified AOI and date range. By default, Sentinel-2 HLS (NASA/HLS/HLSS30/v002) is tried first, followed by Landsat HLS (NASA/HLS/HLSL30/v002).

Cloud masks are applied using the Fmask band before computing the median mosaic. Sentinel-1C is filtered by VV/VH polarization and IW instrument mode, sorted by acquisition time, and reduced using ee$Reducer$firstNonNull().

Neighborhood statistics (mean, min, max, stdDev) are computed over a fixed 3x3 kernel for HLS and terrain bands. GLCM texture metrics are computed from scaled (x10000) HLS reflectance bands using a window size of 3.

Value

Returns an ee$Image object containing 244 bands:

• HLS reflectance bands and vegetation indices (blue, green, red, nir, swir1, swir2, ndvi, kndvi, evi, savi, msavi, f_soil, f_veg, f_water, sri, ndwi, gci, wdrvi, gvmi, cvi, cmr).

• Sentinel-1C SAR bands and radar indices (vv, vh, rvi, copol, copol2, copol3).

• Terrain bands (elevation, slope, aspect).

• Neighborhood statistics (mean, min, max, stdDev) for HLS and terrain bands.

• GLCM texture metrics for HLS reflectance bands.

Examples

## Not run: 
  # Requires Google Earth Engine authentication
  Sys.setenv(EE_PROJECT = "your-ee-project-id")
  ICESat2VegR::ee_initialize()

  library(sf)
  library(terra)

  # AOI in Ocala National Forest, Florida
  aoi <- st_as_sfc(st_bbox(c(
    xmin = -81.8, xmax = -81.6,
    ymin =  29.1, ymax =  29.3
  ), crs = 4326))

  # Build the full ancillary stack (244 bands)
  stack <- ee_build_hls_s1c_terrain_stack(
    x          = aoi,
    start_date = "2024-03-01",
    end_date   = "2024-06-01",
    cloud_max  = 10
  )

  # Check available bands
  names(stack)

  # Compute AOI centroid for map view
  centroid_lon <- mean(terra::ext(terra::vect(aoi))[c(1, 2)])
  centroid_lat <- mean(terra::ext(terra::vect(aoi))[c(3, 4)])

  # Visualize true color RGB
  leaflet::leaflet() |>
    leaflet::addProviderTiles("Esri.WorldImagery") |>
    ICESat2VegR::addEEImage(
      stack$select(c("red", "green", "blue")),
      bands = c("red", "green", "blue"),
      group = "True Color",
      min   = 0,
      max   = 0.3
    ) |>
    leaflet::addControl(
      html     = "<b>True Color</b><br>red / green / blue",
      position = "bottomleft"
    ) |>
    leaflet::setView(lng = centroid_lon, lat = centroid_lat, zoom = 11) |>
    leaflet::addLayersControl(
      overlayGroups = "True Color",
      options = leaflet::layersControlOptions(collapsed = FALSE)
    )

  # Visualize false color (nir, red, green)
  leaflet::leaflet() |>
    leaflet::addProviderTiles("Esri.WorldImagery") |>
    ICESat2VegR::addEEImage(
      stack$select(c("nir", "red", "green")),
      bands = c("nir", "red", "green"),
      group = "False Color",
      min   = 0,
      max   = 0.3
    ) |>
    leaflet::addControl(
      html     = "<b>False Color</b><br>nir / red / green",
      position = "bottomleft"
    ) |>
    leaflet::setView(lng = centroid_lon, lat = centroid_lat, zoom = 11) |>
    leaflet::addLayersControl(
      overlayGroups = "False Color",
      options = leaflet::layersControlOptions(collapsed = FALSE)
    )

  # Visualize NDVI
  leaflet::leaflet() |>
    leaflet::addProviderTiles("Esri.WorldImagery") |>
    ICESat2VegR::addEEImage(
      stack$select("ndvi"),
      bands = "ndvi",
      group = "NDVI",
      min   = 0,
      max   = 0.8
    ) |>
    leaflet::addControl(
      html     = "<b>NDVI</b>",
      position = "bottomleft"
    ) |>
    leaflet::setView(lng = centroid_lon, lat = centroid_lat, zoom = 11) |>
    leaflet::addLayersControl(
      overlayGroups = "NDVI",
      options = leaflet::layersControlOptions(collapsed = FALSE)
    )

  # Force Landsat HLS only
  stack_landsat <- ee_build_hls_s1c_terrain_stack(
    x                 = aoi,
    start_date        = "2024-03-01",
    end_date          = "2024-06-01",
    hls_collection_id = "NASA/HLS/HLSL30/v002"
  )
  names(stack_landsat)

## End(Not run)

One-shot task status check

Description

One-shot task status check

Usage

ee_check_task_status(task, quiet = TRUE)

Arguments

Value

The task status (list).

Find, wait, and download the most recent Drive file with a given prefix

Description

After a Drive export task is COMPLETED, this utility queries Google Drive for files whose names contain file_name_prefix, waits until results are indexed, and downloads the most recent match to dsn.

Usage

ee_drive_fetch_completed(
  task,
  dsn,
  file_name_prefix,
  overwrite = TRUE,
  poll_drive_secs = 10,
  max_wait_secs = Inf,
  verbose = TRUE
)

Arguments

Value

If terra is available, a SpatRaster; otherwise the dsn path.

Alias of ee_drive_fetch_completed()

Description

Alias of ee_drive_fetch_completed()

Usage

ee_drive_to_local(
  task,
  dsn,
  file_name_prefix,
  overwrite = TRUE,
  poll_drive_secs = 10,
  max_wait_secs = Inf,
  verbose = TRUE
)

Arguments

Value

See ee_drive_fetch_completed().

Find, wait, and download the most recent GCS object with a given prefix

Description

After a GCS export task is COMPLETED, this utility lists objects in the target bucket with names starting with file_name_prefix, waits for availability, and downloads the largest (by size) to dsn.

Usage

ee_gcs_fetch_completed(
  task,
  dsn,
  file_name_prefix,
  bucket = NULL,
  overwrite = TRUE,
  poll_secs = 10,
  max_wait_secs = Inf,
  verbose = TRUE
)

Arguments

Value

If terra is available, a SpatRaster; otherwise the dsn path.

Alias of ee_gcs_fetch_completed()

Description

Alias of ee_gcs_fetch_completed()

Usage

ee_gcs_to_local(
  task,
  dsn,
  file_name_prefix,
  bucket = NULL,
  overwrite = TRUE,
  poll_secs = 10,
  max_wait_secs = Inf,
  verbose = TRUE
)

Arguments

Value

See ee_gcs_fetch_completed().

Create an unstarted Asset export task for an EE image

Description

Thin wrapper over ee$batch$Export$image$toAsset(). Optionally deletes an existing asset when overwrite=TRUE (requires appropriate perms).

Usage

ee_image_to_asset(
  image,
  description = "myExportImageTask",
  assetId = NULL,
  overwrite = FALSE,
  pyramidingPolicy = NULL,
  dimensions = NULL,
  region = NULL,
  scale = NULL,
  crs = NULL,
  crsTransform = NULL,
  maxPixels = 1e+10
)

Arguments

Value

An unstarted EE Task (Python object).

Create an unstarted Drive export task for an EE image

Description

Thin wrapper over ee$batch$Export$image$toDrive() that supports optional time-based prefixes. Returns an unstarted task.

Usage

ee_image_to_drive(
  image,
  description = "myExportImageTask",
  folder = "EE_Exports",
  fileNamePrefix = NULL,
  timePrefix = FALSE,
  dimensions = NULL,
  region = NULL,
  scale = NULL,
  crs = NULL,
  crsTransform = NULL,
  maxPixels = 1e+10,
  shardSize = NULL,
  fileDimensions = NULL,
  skipEmptyTiles = NULL,
  fileFormat = "GeoTIFF",
  formatOptions = NULL
)

Arguments

Value

An unstarted EE Task (Python object).

Create an unstarted Cloud Storage export task for an EE image

Description

Thin wrapper over ee$batch$Export$image$toCloudStorage().

Usage

ee_image_to_gcs(
  image,
  description = "myExportImageTask",
  bucket = NULL,
  fileNamePrefix = NULL,
  timePrefix = FALSE,
  dimensions = NULL,
  region = NULL,
  scale = NULL,
  crs = NULL,
  crsTransform = NULL,
  maxPixels = 1e+10,
  shardSize = NULL,
  fileDimensions = NULL,
  skipEmptyTiles = NULL,
  fileFormat = "GeoTIFF",
  formatOptions = NULL
)

Arguments

Value

An unstarted EE Task (Python object).

Initializes the Google Earth Engine API Initialize Earth Engine for this R session

Description

Initializes the Google Earth Engine API Initialize Earth Engine for this R session

Usage

ee_initialize(
  project = Sys.getenv("EE_PROJECT", unset = NA),
  service_account = NULL,
  keyfile = NULL,
  quiet = FALSE,
  force_auth = FALSE
)

Arguments

Value

TRUE on success; FALSE otherwise (invisibly).

Lightweight task monitor (poll-only)

Description

Polls the task state at fixed intervals until the task leaves READY/RUNNING, or until max_attempts is reached.

Usage

ee_monitoring(task, task_time = 5, quiet = FALSE, max_attempts = Inf)

Arguments

Value

The final task status as a list.

Creates an ⁠Earth Engine⁠ server number

Description

Creates an ⁠Earth Engine⁠ server number

Usage

ee_number(x)

Arguments

Value

The Earth Engine number

See Also

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

Convert an EE Rectangle to an sf polygon (EPSG:4326)

Description

Convert an EE Rectangle to an sf polygon (EPSG:4326)

Usage

ee_rect_to_sf(aoi)

Arguments

Value

An sf polygon with CRS EPSG:4326.

Start an EE Task if not already running

Description

Start an EE Task if not already running

Usage

ee_task_start_safe(task)

Arguments

Value

Invisibly returns task. Messages current state.

Convert a terra extent or spatial object to an Earth Engine Rectangle

Description

Converts a terra::ext, terra::SpatVector, or terra::SpatRaster into a Google Earth Engine geometry of type ee$Geometry$Rectangle. The resulting rectangle is always expressed in geographic coordinates (EPSG:4326), regardless of the input object's projection.

This function is mainly used internally to standardize spatial inputs before Earth Engine requests (e.g., filtering, clipping, or exporting data).

Usage

ext_to_ee(x)

Arguments

Value

A Python object representing ee$Geometry$Rectangle, suitable for use with Earth Engine Python API functions accessed via reticulate.

Examples

## Not run: 
library(terra)

# Create an extent over Gainesville, FL
bb <- ext(c(-82.4, -82.2, 29.6, 29.8))

# Convert to EE geometry
aoi <- ext_to_ee(bb)

## End(Not run)

Given a geometry with point samples and images from Earth Engine retrieve the point geometry with values for the images

Description

Given a geometry with point samples and images from Earth Engine retrieve the point geometry with values for the images

Usage

extract(stack, geom, scale)

Arguments

Value

An ee.FeatureCollection with the properties extracted from the stack of images from ee.

Fit a leaflet map to an EE Rectangle AOI

Description

Fit a leaflet map to an EE Rectangle AOI

Usage

fit_map_to_aoi(m, aoi)

Arguments

Value

The input leaflet map with bounds set to the AOI.

Model fit metrics

Description

Computes RMSE (absolute and relative), MAE (absolute and relative), bias (absolute and relative), Pearson correlation (r), and adjusted R^2 from a linear fit between predicted and observed values. Optionally draws a 1:1 plot with the regression line.

Usage

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

Arguments

Value

A data.frame with rows for rmse, rmseR (%), mae, maeR (%), bias, biasR (%), r, and adj_r2.

Examples

observed  <- c(178, 33, 60, 80, 104, 204, 146)
predicted <- c(184, 28.5, 55, 85, 105, 210, 155)
fit_metrics(observed, predicted,
            plotstat = TRUE, legend = "topleft", unit = "Mg/ha",
            xlab = "Observed AGBD (Mg/ha)", ylab = "Predicted AGBD (Mg/ha)", pch = 16)

Fit a Random Forest with optional resampling, tuning, and progress bars

Description

fit_model() trains a Random Forest regression model and optionally evaluates it via LOOCV, K-fold CV, a train/test split, or bootstrap OOB estimation. It can also tune core RF hyperparameters and shows progress bars for long-running loops.

Usage

fit_model(
  x,
  y,
  rf_args = list(ntree = 500, mtry = NULL, nodesize = 5, sampsize = NULL),
  test = list(method = "none", k = 5, test_size = 0.3, seed = NULL, folds = NULL,
    iterations = 200, correction = FALSE),
  tune = list(enable = FALSE, search = "grid", grid = NULL, n_random = 20, seed = NULL),
  verbose = TRUE,
  list_test_models = TRUE
)

Arguments

Details

Tuning minimizes OOB MSE for each candidate configuration on the current training subset and then refits the model using the best settings. When test$method = "bootstrap" and correction = TRUE, the .632 corrected RMSE is reported while keeping other OOB statistics unchanged.

Value

A list with:

method

rf

rf_args

Final RF arguments used for the full-data fit (after tuning).

tune_table

(data.frame or NULL) tuning results sorted by OOB MSE.

test

Echo of test configuration (with resolved values).

model

randomForest object fit on the full dataset (or train subset for split).

fitted_full

Numeric vector of in-sample predictions from the full-data fit.

stats_train

data.frame of training statistics (RMSE, Bias, %RMSE, %Bias, r, r2).

stats_test

(data.frame or NULL) test-set or OOF statistics depending on method.

loocv_pred

(numeric) LOOCV predictions (for method = "loocv").

cv_pred

(numeric) K-fold OOF predictions (for method = "k-fold").

train_index,test_index

(integer) indices for method = "split".

pred_train,pred_test

(numeric) predictions for train/test in split.

oob_pred

(numeric) OOB mean prediction per observation in bootstrap.

models_test

(list or NULL) models fitted per resample/fold/iteration when list_test_models=TRUE.

Workflow

1. Optionally tune RF hyperparameters on the current training subset (or on full data when test$method = "none").

2. Always fit a model on the full dataset (model and fitted_full).

3. If a testing method is requested, refit on resampled training folds and compute out-of-fold predictions to summarize generalization performance.

Progress Bars

Uses utils::txtProgressBar(); disable with verbose = FALSE. The internal helper is lightweight and has no external dependencies.

See Also

randomForest::randomForest(), stats::lm(), stats::cor()

Examples

set.seed(42)
n <- 200
x <- data.frame(NDVI = runif(n, 0.2, 0.9),
                EVI  = runif(n, 0.1, 0.8),
                NBR  = runif(n, -0.5, 0.9),
                SLP  = runif(n, 0, 30))
y <- with(x, 5 + 20*NDVI + 10*EVI^1.5 - 0.05*SLP + rnorm(n, 0, 2))

# Full-data fit (no resampling)
fit_none <- fit_model(x, y, rf_args = list(ntree = 400, mtry = 2))
fit_none$stats_train

# LOOCV

fit_loocv <- fit_model(x, y, test = list(method = "loocv"))
fit_loocv$stats_test

# 5-fold CV
fit_k_fold <- fit_model(x, y, test = list(method = "k-fold", k = 5, seed = 42))
fit_k_fold$stats_test

# Train/Test split
fit_split <- fit_model(x, y, test = list(method = "split", test_size = 0.25, seed = 42))
fit_split$stats_test

# Bootstrap (with tuning and .632 correction)
ntree <- 400
iterations <- 300

fit_boot <- fit_model(
  x, y,
  rf_args = list(ntree = ntree),
  test    = list(method = "bootstrap", iterations = iterations, correction = TRUE),
  tune    = list(enable = TRUE, search = "random", n_random = 12)
)

# K-fold CV with saved models
fit_k <- fit_model(x, y, test = list(method = "k-fold", k = 5, seed = 42), list_test_models = TRUE)
length(fit_k$models_test)  # one model per fold

Calculate raster values based on a formula

Description

Calculate raster values based on a formula

Usage

formulaCalculate(formula, data, updateBand)

Arguments

Value

Nothing, it just updates the band of interest.

Examples

# Parameters
raster_path <- file.path(tempdir(), "output.tif")
ul_lat <- -15
ul_lon <- -45
lr_lat <- -25
lr_lon <- -35
res <- c(0.01, -0.01)
datatype <- GDALDataType$GDT_Int32
nbands <- 2
projstring <- "EPSG:4326"
nodata <- -1
co <- c("TILED=YES", "BLOCKXSIZE=512", "BLOCKYSIZE=512", "COMPRESSION=LZW")

# Create a new raster dataset
ds <- createDataset(
  raster_path = raster_path,
  nbands = nbands,
  datatype = datatype,
  projstring = projstring,
  lr_lat = lr_lat,
  ul_lat = ul_lat,
  ul_lon = ul_lon,
  lr_lon = lr_lon,
  res = res,
  nodata = nodata,
  co = co
)

# Get the GDALRasterBand for ds
band <- ds[[1]]

# The updateBand can be the same
# using a different one just for testing
updateBand <- ds[[2]]

# Set some dummy values
band[[0, 0]] <- 1:(512 * 512)

# Calculate the double - 10
formulaCalculate(
  formula = ~ x * 2 - 10,
  data = list(x = band),
  updateBand = updateBand
)

ds$Close()

Get observations sampled within polygon features

Description

Get observations sampled within polygon features

Usage

geomSampling(size, geom, split_id = NULL, chainSampling = NULL)

Arguments

Value

A icesat2_sampling_method-class object for use in sample.

See Also

sample, randomSampling

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
atl08_path <- system.file("extdata", "atl08_clip.h5", package = "ICESat2VegR")
atl08_h5   <- ATL08_read(atl08_path = atl08_path)
atl08_dt   <- ATL08_seg_attributes_dt(atl08_h5)

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

# Sample 2 observations per polygon feature
set.seed(1)
sampled <- ICESat2VegR::sample(
  atl08_dt,
  method = geomSampling(size = 2, geom = polygon, split_id = "id")
)
head(sampled)

close(atl08_h5)
}

Retrieve Google Earth Engine's tile url for an Image or ImageCollection

Description

Retrieve Google Earth Engine's tile url for an Image or ImageCollection

Usage

getTileUrl(img)

Arguments

Value

The url for the tile service.

Retrieve the Google Earth Engine image catalog id

Description

Retrieve the Google Earth Engine image catalog id

Usage

get_catalog_id(id)

Arguments

Value

The catalog id to open within Google Earth Engine.

Maps to ee.Image.glcmTexture

Description

Computes texture metrics from the Gray Level Co-occurrence Matrix around each pixel of every band. The GLCM is a tabulation of how often different combinations of pixel brightness values (grey levels) occur in an image. It counts the number of times a pixel of value X lies next to a pixel of value Y, in a particular direction and distance. and then derives statistics from this tabulation.

Usage

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

Arguments

Details

This implementation computes the 14 GLCM metrics proposed by Haralick, and 4 additional metrics from Conners. Inputs are required to be integer valued.

The output consists of 18 bands per input band if directional averaging is on and 18 bands per directional pair in the kernel, if not:

1. ASM: f1, Angular Second Moment; measures the number of repeated pairs

2. CONTRAST: f2, Contrast; measures the local contrast of an image

3. CORR: f3, Correlation; measures the correlation between pairs of pixels

4. VAR: f4, Variance; measures how spread out the distribution of gray-levels is

5. IDM: f5, Inverse Difference Moment; measures the homogeneity

6. SAVG: f6, Sum Average

7. SVAR: f7, Sum Variance

8. SENT: f8, Sum Entropy

9. ENT: f9, Entropy. Measures the randomness of a gray-level distribution

10. DVAR: f10, Difference variance

11. DENT: f11, Difference entropy

12. IMCORR1: f12, Information Measure of Corr. 1

13. IMCORR2: f13, Information Measure of Corr. 2

14. MAXCORR: f14, Max Corr. Coefficient. (not computed)

15. DISS: Dissimilarity

16. INERTIA: Inertia

17. SHADE: Cluster Shade

18. PROM: Cluster prominence

Value

Another Earth Engine image with bands described on details section.

See Also

More information can be found in the two papers: Haralick et. al, 'Textural Features for Image Classification', http://doi.org/10.1109/TSMC.1973.4309314 and Conners, et al, Segmentation of a high-resolution urban scene using texture operators', http://doi.org/10.1016/0734-189X(84)90197-X.

https://developers.google.com/earth-engine/apidocs/ee-image-glcmtexture

Get samples stratified by grid cells of specified size

Description

Get samples stratified by grid cells of specified size

Usage

gridSampling(size, grid_size, chainSampling = NULL)

Arguments

Value

A icesat2_sampling_method-class object for use in sample.

See Also

sample, randomSampling

Examples

if (requireNamespace("hdf5r", quietly = TRUE)) {
atl08_path <- system.file("extdata", "atl08_clip.h5", package = "ICESat2VegR")
atl08_h5   <- ATL08_read(atl08_path = atl08_path)
atl08_dt   <- ATL08_seg_attributes_dt(atl08_h5)

# Sample 2 observations per 0.01 degree grid cell
set.seed(1)
sampled <- ICESat2VegR::sample(
  atl08_dt,
  method = gridSampling(size = 2, grid_size = 0.01)
)
head(sampled)

# Chain grid sampling with random sampling within each cell
set.seed(1)
sampled_chain <- ICESat2VegR::sample(
  atl08_dt,
  method = gridSampling(
    size          = 2,
    grid_size     = 0.01,
    chainSampling = randomSampling(2)
  )
)
head(sampled_chain)

close(atl08_h5)
}

Class that represent custom segments created from ATL03 and ATL08 joined data

Description

Class that represent custom segments created from ATL03 and ATL08 joined data

Details

This class is actually just a wrap around the data.table, but it indicates the output from ATL03_ATL08_segment_create(), which means the dataset will contain the needed structure for computing value for the computing the stats with ATL03_ATL08_compute_seg_attributes_dt_segStat()

Class for ATL03 attributes

Description

Class for ATL03 attributes

See Also

data.table in the data.table package and https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Class for ICESat-2 ATL03

Description

Class for ICESat-2 ATL03

Slots

h5

Object of class H5File from hdf5r package containing the ICESat-2 Global Geolocated Photon Data (ATL03)

See Also

H5File in the hdf5r package and https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Class for ATL03 segment attributes

Description

Class for ATL03 segment attributes

See Also

data.table in the data.table package and https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Class for joined ATL03 and ATL08 attributes

Description

Class for joined ATL03 and ATL08 attributes

See Also

data.table in the data.table package and https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL03_ATBD_r006.pdf

Class for ATL08 attributes

Description

Class for ATL08 attributes

See Also

data.table in the data.table package and https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Class for ICESat-2 ATL08

Description

Class for ICESat-2 ATL08

Slots

h5

Object of class H5File from hdf5r package containing the ICESat-2 Land and Vegetation Along-Track Products (ATL08)

See Also

H5File in the hdf5r package and https://icesat-2.gsfc.nasa.gov/sites/default/files/page_files/ICESat2_ATL08_ATBD_r006.pdf

Base class for all ICESat2VegR package's H5 files for generic functions that can be run on any H5

Description

Base class for all ICESat2VegR package's H5 files for generic functions that can be run on any H5

HDF5 prediction class

Description

This is a generic prediction class for HDF5 files to make type checking and method matching with S4 methods.

Class for sampling methods to be passed on for the sample function

Description

Class for sampling methods to be passed on for the sample function

Returns the number of images in an ImageCollection

Description

Returns the number of images in an ImageCollection

Usage

## S4 method for signature 'ee.imagecollection.ImageCollection'
length(x)

Arguments

Value

The number of images in the ImageCollection

Create a prediction map in Google Earth Engine using a fitted Random Forest model

Description

Applies a fitted Random Forest model (from R's randomForest package) to a Google Earth Engine image stack and returns an ee$Image containing the predicted values. The model is converted to a GEE Classifier via build_ee_forest, which serializes the R forest through the ICESat2VegR C++ module and constructs an EE estimator using ee$Classifier$decisionTreeEnsemble().

Authentication: This function requires an active Google Earth Engine session. Authenticate using ICESat2VegR::ee_initialize() before calling this function.

Usage

map_create(
  model,
  stack,
  aoi = NULL,
  reducer = c("mosaic", "median"),
  mode = c("auto", "classifier"),
  to_float = TRUE
)

Arguments

Details

The function works for both:

• ee$Image: predictors already merged into one raster.

• ee$ImageCollection: predictions computed for each image and reduced using mosaic or median.

The output band is always named prediction_layer. Properties from a zero-pixel placeholder image are copied to preserve band metadata.

The predictor variable names used to train the model must exactly match the band names in stack. Use names(stack) to verify the available bands before training the model.

Value