R: Assets functions

assets_functions {rstac}

R Documentation

Assets functions

Description

These functions provide support to work with doc_items and doc_item item objects.

assets_download(): Downloads the assets provided by the STAC API.
assets_url(): 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(): 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(): Rename each asset using a named list or a function.

Usage

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

## S3 method for class 'doc_item'
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  use_gdal = FALSE,
  create_json = FALSE,
  download_fn = NULL
)

## S3 method for class 'doc_items'
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  use_gdal = FALSE,
  download_fn = NULL,
  create_json = TRUE,
  items_max = Inf,
  progress = TRUE
)

## Default S3 method:
assets_download(
  items,
  asset_names = NULL,
  output_dir = getwd(),
  overwrite = FALSE,
  ...,
  use_gdal = FALSE,
  create_json = FALSE,
  download_fn = NULL
)

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

## S3 method for class 'doc_item'
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

## S3 method for class 'doc_items'
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

## Default S3 method:
assets_url(items, asset_names = NULL, append_gdalvsi = FALSE)

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

## S3 method for class 'doc_item'
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

## S3 method for class 'doc_items'
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

## Default S3 method:
assets_select(items, ..., asset_names = NULL, select_fn = NULL)

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

## S3 method for class 'doc_item'
assets_rename(items, mapper = NULL, ...)

## S3 method for class 'doc_items'
assets_rename(items, mapper = NULL, ...)

## Default S3 method:
assets_rename(items, mapper = NULL, ...)

has_assets(items)

## S3 method for class 'doc_item'
has_assets(items)

## S3 method for class 'doc_items'
has_assets(items)

## Default S3 method:
has_assets(items)

asset_key()

asset_eo_bands(field)

asset_raster_bands(field)

Arguments

`items`	a `doc_item` or `doc_items` 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.
`use_gdal`	a `logical` indicating if the file should be downloaded by GDAL instead httr package.
`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.
`create_json`	a `logical` indicating if a JSON file with item metadata (`doc_item` or `doc_items`) 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 (`doc_item` or `doc_items`). 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 (`doc_item` or `doc_items`). 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.

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. assets_select() uses non-standard evaluation to evaluate its expressions. That means users must escape any variable or call to be able to use them in the expressions. The escape is done by using double-curly-braces, i.e., {{variable}}.

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.

Value

assets_download(): returns the same input object item (doc_item or doc_items) where href properties point to the download assets.
assets_url(): returns a character vector with all assets href of an item (doc_item or doc_items).
assets_select(): returns the same input object item (doc_item or doc_items) with the selected assets.
assets_rename(): returns the same input object item (doc_items or doc_item) with the assets renamed.

Examples

## Not run: 
 # assets_download function
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   stac_search(collections = "CB4-16D-2",
               datetime = "2019-06-01/2019-08-01") %>%
   stac_search() %>%
   get_request() %>%
   assets_download(asset_names = "thumbnail", output_dir = tempdir())

## End(Not run)

## Not run: 
 # assets_url function
 stac_item <- stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2", 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()

## End(Not run)

## Not run: 
 # assets_select function
 stac_item <- stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2", 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")

## End(Not run)

## Not run: 
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)

## End(Not run)

[Package rstac version 1.0.1 Index]