Add band mappings for alos palsar

get_alos_palsar_imagery added to get_stac_data

alos palsar mask function added

test added for get_alos_palsar_imagery

bandmapping data

export mask function

update band mapping to include linci

docs update

add all potential bands to band mapping

update namespace

Document band mapping, regenerate data

NAMESPACE

@@ -3,10 +3,12 @@
 S3method("[",rsi_band_mapping)
 S3method("[[",rsi_band_mapping)
 S3method(print,rsi_band_mapping)
+export(alos_palsar_mask_function)
 export(calculate_indices)
 export(default_query_function)
 export(filter_bands)
 export(filter_platforms)
+export(get_alos_palsar_imagery)
 export(get_dem)
 export(get_landsat_imagery)
 export(get_naip_imagery)

R/data.R

@@ -25,6 +25,16 @@
 #' @template band_mappings
 "landsat_band_mapping"
 
+#' ALOS PALSAR band mapping
+#'
+#' This object is a named list of character vectors, with names corresponding to
+#' Landsat band names and values corresponding to band names in
+#' `spectral_indices`.
+#'
+#' @template band_mappings
+"alos_palsar_band_mapping"
+
+
 #' Landsat band mapping
 #'
 #' This object is structured slightly differently from other band mapping

R/get_stac_data.R

@@ -69,13 +69,20 @@
 #' expected values.
 #'
 #' @section Sentinel-1 Data:
-#' The `get_sentinel1_data()` function is designed to download Sentinel-1 data
+#' The `get_sentinel1_imagery()` function is designed to download Sentinel-1 data
 #' from the Microsoft Planetary Computer STAC API. Both the GRD and RTC
 #' Sentinel-1 collections are supported. To download RTC data,
 #' set `collection` to `sentinel-1-rtc`, and supply your subscription key
 #' as an environment variable named `rsi_pc_key` (through, e.g., `Sys.setenv()`
 #' or your `.Renviron` file).
 #'
+#' @section AlOS PALSAR Data:
+#' The `get_alos_palsar_imagery()` function is designed to download ALOS PALSAR
+#' annual mosaic data from the Microsoft Planetary Computer STAC API. Data are
+#' returned as a digital number (which is appropriate for some applications
+#' and indices). To convert to backscatter (decibels) use the following formula:
+#' `10 * log10(dn) - 83.0` where dn is the radar band in digital number.
+#'
 #' @param aoi An sf(c) object outlining the area of interest to get imagery for.
 #' Will be used to get the bounding box used for calculating metrics and the
 #' output data's CRS.
@@ -607,6 +614,51 @@ get_naip_imagery <- function(aoi,
   do.call(get_stac_data, args)
 }
 
+#' @rdname get_stac_data
+#' @export
+get_alos_palsar_imagery <- function(aoi,
+                                    start_date,
+                                    end_date,
+                                    ...,
+                                    pixel_x_size = 10,
+                                    pixel_y_size = 10,
+                                    asset_names = rsi::alos_palsar_band_mapping$planetary_computer_v1,
+                                    stac_source = attr(asset_names, "stac_source"),
+                                    collection = attr(asset_names, "collection_name"),
+                                    query_function = attr(asset_names, "query_function"),
+                                    sign_function = attr(asset_names, "sign_function"),
+                                    rescale_bands = FALSE,
+                                    item_filter_function = NULL,
+                                    mask_band = attr(asset_names, "mask_band"),
+                                    mask_function = attr(asset_names, "mask_function"),
+                                    output_filename = paste0(proceduralnames::make_english_names(1), ".tif"),
+                                    composite_function = "median",
+                                    limit = 999,
+                                    gdalwarp_options = c(
+                                      "-r", "bilinear",
+                                      "-multi",
+                                      "-overwrite",
+                                      "-co", "COMPRESS=DEFLATE",
+                                      "-co", "PREDICTOR=2",
+                                      "-co", "NUM_THREADS=ALL_CPUS"
+                                    ),
+                                    gdal_config_options = c(
+                                      VSI_CACHE = "TRUE",
+                                      GDAL_CACHEMAX = "30%",
+                                      VSI_CACHE_SIZE = "10000000",
+                                      GDAL_HTTP_MULTIPLEX = "YES",
+                                      GDAL_INGESTED_BYTES_AT_OPEN = "32000",
+                                      GDAL_DISABLE_READDIR_ON_OPEN = "EMPTY_DIR",
+                                      GDAL_HTTP_VERSION = "2",
+                                      GDAL_HTTP_MERGE_CONSECUTIVE_RANGES = "YES",
+                                      GDAL_NUM_THREADS = "ALL_CPUS"
+                                    )) {
+  args <- mget(names(formals()))
+  args$`...` <- NULL
+  args <- c(args, rlang::list2(...))
+  do.call(get_stac_data, args)
+}
+
 #' @rdname get_stac_data
 #' @export
 get_dem <- function(aoi,

R/mask_functions.R

@@ -74,3 +74,40 @@ landsat_mask_function <- function(raster, include = c("land", "water", "both"))
 
   terra::`%in%`(raster, classes)
 }
+
+
+#' Create an ALOS PALSAR mask raster from the mask band
+#'
+#' @param raster The mask band of an ALOS PALSAR image
+#' @param include Include pixels that represent land, water, or both? Passing
+#' `c("land", "water")` is identical to passing `"both"`.
+#'
+#' @returns A boolean raster to be used to mask an ALOS PALSAR image
+#'
+#' @examplesIf interactive()
+#' aoi <- sf::st_point(c(-74.912131, 44.080410))
+#' aoi <- sf::st_set_crs(sf::st_sfc(aoi), 4326)
+#' aoi <- sf::st_buffer(sf::st_transform(aoi, 5070), 100)
+#'
+#' palsar_image <- get_alos_palsar_imagery(
+#'   aoi,
+#'   start_date = "2021-01-01",
+#'   end_date = "2021-12-31",
+#'   mask_function = alos_palsar_mask_function
+#' )
+#'
+#' @export
+alos_palsar_mask_function <- function(
+    raster,
+    include = c("land", "water", "both")) {
+  if (missing(include)) include <- include[[1]]
+  include <- rlang::arg_match(include, multiple = TRUE)
+  # includes no data (0), layover (100) and shadow (150)
+  # https://docs.digitalearthafrica.org/en/latest/sandbox/notebooks/Datasets/ALOS_PALSAR_Annual_Mosaic.html
+  classes <- c(0, 100, 150)
+
+  if (any(c("land", "both") %in% include)) classes <- c(classes, 255)
+  if (any(c("water", "both") %in% include)) classes <- c(classes, 50)
+
+  terra::`%in%`(raster, classes)
+}

data-raw/band_mappings.R

@@ -100,6 +100,28 @@ sentinel1_band_mapping <- list(
 
 usethis::use_data(sentinel1_band_mapping, overwrite = TRUE)
 
+alos_palsar_band_mapping <- list(
+  planetary_computer_v1 = structure(
+    c(
+      "HH" = "HH",
+      "HV" = "HV",
+      "VV" = "VV",
+      "VH" = "VH",
+      "linci" = "linci"
+    ),
+    mask_band = "mask",
+    mask_function = alos_palsar_mask_function,
+    stac_source = "https://planetarycomputer.microsoft.com/api/stac/v1/",
+    collection_name = "alos-palsar-mosaic",
+    query_function = default_query_function,
+    sign_function = sign_planetary_computer,
+    class = "rsi_band"
+  )
+)
+
+usethis::use_data(alos_palsar_band_mapping, overwrite = TRUE)
+
+
 pc_dem_mapping <- function(assets, collection_name) {
   structure(
     assets,

tests/testthat/test-get_stac_data.R

@@ -320,3 +320,21 @@ test_that("get_naip_imagery() is stable", {
   )
   expect_no_error(terra::rast(out))
 })
+
+test_that("get_alos_palsar_imagery() is stable", {
+  skip_on_cran()
+  skip_if_offline()
+  aoi <- sf::st_point(c(-74.912131, 44.080410))
+  aoi <- sf::st_set_crs(sf::st_sfc(aoi), 4326)
+  aoi <- sf::st_buffer(sf::st_transform(aoi, 3857), 100)
+
+  expect_no_error(
+    out <- get_alos_palsar_imagery(
+      aoi,
+      "2021-01-01",
+      "2021-12-31",
+      output_filename = tempfile(fileext = ".tif")
+    )
+  )
+  expect_no_error(terra::rast(out))
+})