Learn R Programming

IceSat2R

Programmatic connection to the OpenAltimetry EARTHDATA API to download and process the following ICESat-2 Altimeter Data,

  • 'ATL03' (Global Geolocated Photon Data)
  • 'ATL06' (Land Ice Height)
  • 'ATL07' (Sea Ice Height)
  • 'ATL08' (Land and Vegetation Height)
  • 'ATL10' (Sea Ice Freeboard)
  • 'ATL12' (Ocean Surface Height)
  • 'ATL13' (Inland Water Surface Height)

The user has the option to download the data by selecting a bounding box from a 1- or 5-degree grid globally utilizing a shiny application. The Documentation, the two package Vignettes (first, second) and the blog post explain the functionality in detail.

The ICESat-2 mission collects altimetry data of the Earth's surface. The sole instrument on ICESat-2 is the Advanced Topographic Laser Altimeter System (ATLAS) instrument that measures ice sheet elevation change and sea ice thickness, while also generating an estimate of global vegetation biomass.

ICESat-2 continues the important observations of

  • ice-sheet elevation change
  • sea-ice freeboard, and
  • vegetation canopy height

begun by ICESat in 2003.

System Requirements

The usage of the IceSat2R package requires a geospatial setup as specified in the sf or terra README.md files.

How the IceSat2R package can be used?

The IceSat2R package includes the code, documentation, and examples so that,

  • A user can select an area of interest (AOI) either programmatically or interactively
  • If the Reference Ground Track (RGT) is not known, the user has the option to utilize either
    • one of the "overall_mission_orbits()" or "time_specific_orbits()" to compute the RGT(s) for a pre-specified global area or for a time period, or
    • one of the "vsi_nominal_orbits_wkt()" or "vsi_time_specific_orbits_wkt()" to compute the RGT(s) for a specific AOI
  • Once the RGT is computed it can be verified with the "getTracks()" function of the OpenAltimetry EARTHDATA Web API
  • Finally the user can utilize one of the "get_atlas_data()" or "get_level3a_data()" functions to retrieve the data for specific product(s), Date(s) and Beam(s)

This work-flow is illustrated also in the following diagram,

Shiny application to select an area of interest (AOI) from a 1- or 5-degree global grid

The OpenAltimetry EARTHDATA API restricts the requests to a 1x1 or 5x5 degree spatial bounding box, unless the "sampling" parameter is set to TRUE. The shiny application of the IceSat2R package allows the user to create a spatial grid of an AOI, preferably a 1- or 5-degree grid so that the selection can be within limits. An alternative would be to create a grid of smaller grid cells than required (for instance a 4-degree grid) and then to select multiple grid cells,

Example Use Case-1: 3-Dimensional Line Plot by combining ICESat-2 and Copernicus DEM (Digital Elevation Model) Data

The following 3-dimensional interactive line plot (which appears in the 'IceSat-2_Atlas_products' Vignette) shows,

  • in blue color the elevation based on the DEM compared to the two ICESat-2 beams ('gt1r' and 'gt2l'), as these are separated by a 3-km distance
  • in orange color the land-ice-height measurements of the summer period (separately for 'gt1r' and 'gt2l')
  • in green color the land-ice-height measurements of the winter period (separately for 'gt1r' and 'gt2l')

Example Use Case-2: Multi-Plot displaying the Ice, Land, Canopy and Copernicus DEM (30-meter) of each beam separately for a specific ICESat-2 Track and area of interest (Himalayas mountain range)

Binder

The user of the IceSat2R R package can reproduce the examples of the documentation using the available binder Rstudio image. Once launched the cloud instance will take a few minutes to be ready. You can read more about binder on the web. In short, binder allows to make "your code immediately reproducible by anyone, anywhere". Limitations:

Docker Image

Docker images of the IceSat2R package are available to download from my dockerhub account. The images come with Rstudio and the R-development version (latest) installed. The whole process was tested on Ubuntu 18.04. To pull & run the image do the following,


docker pull mlampros/icesat2r:rstudiodev

docker run -d --name rstudio_dev -e USER=rstudio -e PASSWORD=give_here_your_password --rm -p 8787:8787 mlampros/icesat2r:rstudiodev

The user can also bind a home directory / folder to the image to use its files by specifying the -v command,


docker run -d --name rstudio_dev -e USER=rstudio -e PASSWORD=give_here_your_password --rm -p 8787:8787 -v /home/YOUR_DIR:/home/rstudio/YOUR_DIR mlampros/icesat2r:rstudiodev

The USER defaults to rstudio but you have to give your PASSWORD of preference (see https://rocker-project.org/ for more information).

Open your web-browser and depending where the docker image was build / run give,

1st. Option on your personal computer,

http://0.0.0.0:8787 

2nd. Option on a cloud instance,

http://Public DNS:8787

to access the Rstudio console in order to give your username and password.

Installation:

To install the package from CRAN use,

install.packages("IceSat2R")

and to download the latest version of the package from Github,

remotes::install_github('mlampros/IceSat2R')

R package tests:

To execute the package tests (all or a specific file) use the following code snippet:


# first download the latest version of the package

url_pkg = 'https://github.com/mlampros/IceSat2R/archive/refs/heads/master.zip'
temp_pkg_file = tempfile(fileext = '.zip')
print(temp_pkg_file)

options(timeout = 600)
downl_f = IceSat2R::download_file(url = url_pkg,
                                  destfile = temp_pkg_file,
                                  download_method = 'curl',
                                  verbose = TRUE)

dir_pkg_save = dirname(temp_pkg_file)
utils::unzip(zipfile = temp_pkg_file, exdir = dir_pkg_save, junkpaths = FALSE)

# build and install the latest version of the package

require(glue)

setwd(dir_pkg_save)
system('R CMD build --compact-vignettes="gs+qpdf" --resave-data IceSat2R-master')
gz_file = which(gregexpr(pattern = "^IceSat2R+_+[0-9]+.+[0-9]+.+[0-9]+.tar.gz", text = list.files()) != -1)
system(glue::glue("R CMD INSTALL {list.files()[gz_file]}"))

# load the package

require(IceSat2R)

# run all tests

testthat::test_local(path = file.path(dirname(temp_pkg_file), 'IceSat2R-master'),
                     reporter = testthat::default_reporter())

# run a specific test file from the 'testthat' directory of the package 
# https://github.com/mlampros/IceSat2R/tree/master/tests/testthat

test_specific_file = file.path(dirname(temp_pkg_file), 
                               'IceSat2R-master', 
                               'tests', 
                               'testthat', 
                               'test-mission_orbits.R')

Sys.setenv(NOT_CRAN = "true")       # run all tests (including the ones skipped on CRAN)
testthat::test_file(path = test_specific_file, reporter = testthat::default_reporter())
Sys.unsetenv("NOT_CRAN")            # unset the previously modified environment variable

The previous code snippet allows a user to test if the package works as expected in any Operating System.

The Beam Pattern

The ATLAS beam pattern on the ground changes depending on the orientation of the ICESat-2 observatory. The pattern on top (of the following Figure) corresponds to traveling in the forward (+x) orientation, while the pattern on the bottom corresponds to traveling in the backward (-x) orientation. The numbers indicate the corresponding ATLAS beam, while the L/R mapping are used on the ATL03 and higher-level data products. The two strong beams with the TEP are ATLAS beams 1 and 3 (Fig.8, Neumann et al., 2019, https://doi.org/10.1016/j.rse.2019.111325)

Using a table to map the strong and weak beams (Reference: sliderule-python documentation)

ATLAS Spot NumberGround track DesignationBeam Strength
1gt3rStrong
2gt3lWeak
3gt2rStrong
4gt2lWeak
5gt1rStrong
6gt1lWeak
ATLAS Spot NumberGround track DesignationBeam Strength
1gt3rWeak
2gt3lStrong
3gt2rWeak
4gt2lStrong
5gt1rWeak
6gt1lStrong

Citation:

If you use the code of this repository in your paper or research please cite both IceSat2R and the original articles (see CITATION) https://CRAN.R-project.org/package=IceSat2R:

@Manual{,
  title = {{IceSat2R}: ICESat-2 Altimeter Data using R},
  author = {Lampros Mouselimis},
  year = {2025},
  doi = 10.32614/CRAN.package.IceSat2R,
  note = {R package version 1.0.7},
  url = {https://CRAN.R-project.org/package=IceSat2R},
}

Code of Conduct

Please note that the IceSat2R project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Acknowledgment

This project received financial support from the

Copy Link

Version

Install

install.packages('IceSat2R')

Monthly Downloads

334

Version

1.0.7

License

GPL-3

Issues

Pull Requests

Stars

Forks

Maintainer

Lampros Mouselimis

Last Published

February 15th, 2025

Functions in IceSat2R (1.0.7)

inner_elapsed_time

inner function of 'compute_elapsed_time'
revisit_time_RGTs

Revisit Time Reference Ground Tracks and Dates
latest_orbits

Extraction of the url from the Technical Specification Website
select_aoi_global_grid

R6 Class to Select an Area of Interest (AOI) from a Global Grid
get_level3a_data

Get IceSat-2 ATLAS 'Level-3A' data for a time interval (up to 1 year)
switch_abb

Convert an abbreviated month name to a numeric value
overall_mission_orbits

Overall Mission Orbits
ne_10m_glaciated_areas

Natural Earth 10m Glaciated Areas (1:10 million scale)
leaflet_base_map

a leaflet base map
switch_full

Convert a full month name to a numeric value
vsi_kml_from_zip

Utilizing Virtual File Systems (vsi) to extract the .kml from the .zip file
vsi_time_specific_orbits_wkt

Utilizing Virtual File Systems (vsi) and Well Known Text (WKT) to access the 'time specific orbits'
vsi_nominal_orbits_wkt

Utilizing Virtual File Systems (vsi) and Well Known Text (WKT) to access the 'nominal orbits'
time_specific_orbits

Time Specific Orbits
verify_RGTs

Verification of the Reference Ground Tracks (RGTs)
get_atlas_data

Get ICESat-2 ATLAS data for a specific Date
available_RGTs

Reference Ground Tracks (RGTs)
get_URL_data

Get the data based on the API URL
available_nominal_orbits

Nominal mission orbits
IceSat2R

The "IceSat2R" package
download_file

Customized function to download files
getTracks

Get the ICESAT-2 Tracks
degrees_to_global_grid

Create a global grid based on degrees
compute_elapsed_time

elapsed time in hours & minutes & seconds
RGT_cycle_14

Reference Ground Tracks (RGTs) for IceSat-2 Cycle 14