Skip to contents

Assets functions

Source: R/assets-funs.R
assets_functions.Rd

These functions provide support to work with STACItemCollection and STACItem item objects.

  • assets_download(): Downloads the assets provided by the STAC API.

  • assets_url(): [Experimental] Returns a character vector with each asset href. For the URL, you can add the GDAL library drivers for the following schemes: HTTP/HTTPS files, S3 (AWS S3) and GS (Google Cloud Storage).

  • assets_select(): [Experimental] Selects the assets of each item by its name (asset_names parameter), by expressions (... parameter), or by a selection function (select_fn parameter). Note: This function can produce items with empty assets. In this case, users can use the items_compact() function to remove items with no assets.

  • assets_rename(): [Experimental] Rename each asset using a named list or a function.

Usage

assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  download_fn = NULL,
  fn = deprecated()
)

# S3 method for STACItem
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  create_json = FALSE,
  download_fn = NULL,
  fn = deprecated()
)

# S3 method for STACItemCollection
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  download_fn = NULL,
  create_json = TRUE,
  items_max = Inf,
  progress = TRUE,
  fn = deprecated()
)

# S3 method for default
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  create_json = FALSE,
  download_fn = NULL,
  fn = deprecated()
)

assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

# S3 method for STACItem
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

# S3 method for STACItemCollection
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

# S3 method for default
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

assets_select(items, ..., asset_names = NULL, select_fn = NULL)

# S3 method for STACItem
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

# S3 method for STACItemCollection
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

# S3 method for default
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

assets_rename(items, mapper = NULL, ...)

# S3 method for STACItem
assets_rename(items, mapper = NULL, ...)

# S3 method for STACItemCollection
assets_rename(items, mapper = NULL, ...)

# S3 method for default
assets_rename(items, mapper = NULL, ...)

has_assets(items)

# S3 method for STACItem
has_assets(items)

# S3 method for STACItemCollection
has_assets(items)

# S3 method for default
has_assets(items)

asset_key()

asset_eo_bands(field)

asset_raster_bands(field)

Arguments

items

a STACItem or STACItemCollection object representing the result of /stac/search, /collections/{collectionId}/items or /collections/{collectionId}/items/{itemId} endpoints.

asset_names

a character vector with the names of the assets to be selected.

output_dir

a character directory in which the assets will be saved. Default is the working directory (getwd())

overwrite

a logical if TRUE will replace the existing file, if FALSE, a warning message is shown.

...

additional arguments. See details.

download_fn

a function to handle download of assets for each item to be downloaded. Using this function, you can change the hrefs for each asset, as well as the way download is done.

fn

[Deprecated] use download_fn parameter instead.

create_json

a logical indicating if a JSON file with item metadata (STACItem or STACItemCollection) must be created in the output directory.

items_max

a numeric corresponding to how many items will be downloaded.

progress

a logical indicating if a progress bar must be shown or not. Defaults to TRUE.

append_gdalvsi

a logical value. If true, gdal drivers are included in the URL of each asset. The following schemes are supported: HTTP/HTTPS files, S3 (AWS S3) and GS (Google Cloud Storage).

select_fn

a function to select assets an item (STACItem or STACItemCollection). This function receives as parameter the asset element and, optionally, the asset name. Asset elements contain metadata describing spatial-temporal objects. Users can provide a function to select assets based on this metadata by returning a logical value where TRUE selects the asset, and FALSE discards it.

mapper

either a named list or a function to rename assets of an item (STACItem or STACItemCollection). In the case of a named list, use <old name> = <new name> to rename the assets. The function can be used to rename the assets by returning a character string using the metadata contained in the asset object.

field

a character with the name of the asset field to return.

Value

  • assets_download(): returns the same input object item (STACItem or STACItemCollection) where href properties point to the download assets.

  • assets_url(): returns a character vector with all assets href of an item (STACItem or STACItemCollection).

  • assets_select(): returns the same input object item (STACItem or STACItemCollection) with the selected assets.

  • assets_rename(): returns the same input object item (STACItemCollection or STACItem) with the assets renamed.

Details

Ellipsis argument (...) appears in different assets functions and has distinct purposes:

  • assets_download(): ellipsis is used to pass additional httr options to GET or POST methods, such as add_headers or set_cookies.

  • assets_select(): ellipsis is used to pass expressions that will be evaluated against each asset metadata. Expressions must be evaluated as a logical value where TRUE selects the asset and FALSE discards it. Multiple expressions are combine with AND operator. Expressions can use asset helper functions (i.e. asset_key(), asset_eo_bands(), and asset_raster_bands()). Multiple expressions are combined with AND operator.

    WARNING: Errors in the evaluation of expressions are considered as FALSE.

  • assets_rename(): ellipsis is used to pass named parameters to be processed in the same way as the named list in mapper argument.

See also

stac_search(), items(), get_request()

Examples

if (FALSE) {
 # assets_download function
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   stac_search(collections = "CB4_64_16D_STK-1",
               datetime = "2019-06-01/2019-08-01") %>%
   stac_search() %>%
   get_request() %>%
   assets_download(asset_names = "thumbnail", output_dir = tempdir())
}

if (FALSE) {
 # assets_url function
 stac_item <- stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4_64_16D_STK-1", limit = 100,
         datetime = "2017-08-01/2018-03-01",
         bbox = c(-48.206,-14.195,-45.067,-12.272)) %>%
  get_request() %>% items_fetch(progress = FALSE)

 stac_item %>% assets_url()
}

if (FALSE) {
 # assets_select function
 stac_item <- stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4_64_16D_STK-1", limit = 100,
         datetime = "2017-08-01/2018-03-01",
         bbox = c(-48.206,-14.195,-45.067,-12.272)) %>%
  get_request() %>% items_fetch(progress = FALSE)

 stac_item %>% assets_select(asset_names = "NDVI")
}

if (FALSE) {
items <- stac("https://planetarycomputer.microsoft.com/api/stac/v1") %>%
  stac_search(collections = c("landsat-8-c2-l2", "sentinel-2-l2a"),
              bbox = c(xmin = -64.85976089, ymin = -10.49199395,
                       xmax = -64.79272527, ymax =-10.44736091),
              datetime = "2019-01-01/2019-06-28",
              limit = 50) %>%
  post_request()

# Selects assets by name
items <- assets_select(items,
                       asset_names = c("B02", "B03", "SR_B1", "SR_B2"))
# Renames the landsat assets
items <- assets_rename(items,
                       SR_B1 = "blue",
                       SR_B2 = "green",
                       B02   = "blue",
                       B03   = "green")
# Get the assets url's
assets_url(items)
}