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.
The usage of the IceSat2R package requires a geospatial setup as specified in the sf or terra README.md files.
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,
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)
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:
- up to maximum 100 concurrent users
- 1 CPU
- 1 to 2 GB of memory
- up to six hours of session time per user session, or up to one cpu-hour for more computationally intensive sessions
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.
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')
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 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 Number | Ground track Designation | Beam Strength |
|---|---|---|
| 1 | gt3r | Strong |
| 2 | gt3l | Weak |
| 3 | gt2r | Strong |
| 4 | gt2l | Weak |
| 5 | gt1r | Strong |
| 6 | gt1l | Weak |
| ATLAS Spot Number | Ground track Designation | Beam Strength |
|---|---|---|
| 1 | gt3r | Weak |
| 2 | gt3l | Strong |
| 3 | gt2r | Weak |
| 4 | gt2l | Strong |
| 5 | gt1r | Weak |
| 6 | gt1l | Strong |
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 = {2024},
doi = 10.32614/CRAN.package.IceSat2R,
note = {R package version 1.0.6},
url = {https://CRAN.R-project.org/package=IceSat2R},
}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.
This project received financial support from the
