Skip to contents

Items functions

Source: R/deprec-funs.R, R/items-funs.R
items_functions.Rd

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

  • items_length(): shows how many items there are in the STACItemCollection object.

  • items_matched(): shows how many items matched the search criteria. It supports search:metadata (v0.8.0), context (v0.9.0), and numberMatched (OGC WFS3 core spec).

  • items_fetch(): request all STAC Items through pagination.

  • items_next(): fetches a new page from STAC service.

  • items_datetime(): retrieves the datetime field in properties from STACItemCollection and STACItem objects.

  • items_bbox(): retrieves the bbox field of a STACItemCollection or a STACItem object.

  • item_assets(): returns the assets name from STACItemCollection and STACItem objects.

  • items_filter(): selects only items that match some criteria (see details section).

  • items_reap(): extract key values by traversing all items in a STACItemCollection object.

  • items_fields(): lists field names inside an item.

  • items_group(): [Deprecated] organizes items as elements of a list using some criteria.

  • items_sign(): allow access assets by preparing its url.

  • items_as_sf(): [Experimental] convert items to sf object.

Usage

items_group(items, ..., field = NULL, index = NULL)

items_length(items)

# S3 method for STACItem
items_length(items)

# S3 method for STACItemCollection
items_length(items)

# S3 method for default
items_length(items)

items_matched(items, matched_field = NULL)

# S3 method for STACItem
items_matched(items, matched_field = NULL)

# S3 method for STACItemCollection
items_matched(items, matched_field = NULL)

# S3 method for default
items_matched(items, matched_field = NULL)

items_fetch(items, ...)

# S3 method for STACItemCollection
items_fetch(items, ..., progress = TRUE, matched_field = NULL)

items_next(items, ...)

# S3 method for STACItemCollection
items_next(items, ...)

items_datetime(items)

# S3 method for STACItem
items_datetime(items)

# S3 method for STACItemCollection
items_datetime(items)

# S3 method for default
items_datetime(items)

items_bbox(items)

# S3 method for STACItem
items_bbox(items)

# S3 method for STACItemCollection
items_bbox(items)

# S3 method for default
items_bbox(items)

items_assets(items, simplify = deprecated())

# S3 method for STACItem
items_assets(items, simplify = deprecated())

# S3 method for STACItemCollection
items_assets(items, simplify = deprecated())

# S3 method for default
items_assets(items, simplify = deprecated())

items_filter(items, ..., filter_fn = NULL)

# S3 method for STACItemCollection
items_filter(items, ..., filter_fn = NULL)

items_compact(items)

# S3 method for STACItemCollection
items_compact(items)

items_reap(items, field, ..., pick_fn = identity)

# S3 method for STACItem
items_reap(items, field, ..., pick_fn = identity)

# S3 method for STACItemCollection
items_reap(items, field, ..., pick_fn = identity)

# S3 method for default
items_reap(items, field, ..., pick_fn = identity)

items_fields(items, field = NULL, ...)

# S3 method for STACItem
items_fields(items, field = NULL, ...)

# S3 method for STACItemCollection
items_fields(items, field = NULL, ...)

# S3 method for default
items_fields(items, field = NULL, ...)

items_sign(items, sign_fn)

# S3 method for STACItem
items_sign(items, sign_fn)

# S3 method for STACItemCollection
items_sign(items, sign_fn)

# S3 method for default
items_sign(items, sign_fn)

items_as_sf(items)

# S3 method for STACItem
items_as_sf(items)

# S3 method for STACItemCollection
items_as_sf(items)

Arguments

items

a STACItemCollection object.

...

additional arguments. See details.

field

a character with the names of the field to get the subfields values.

index

an atomic vector with values as the group index.

matched_field

a character vector with the path where the number of items returned in the named list is located starting from the initial node of the list. For example, if the information is in a position items$meta$found of the object, it must be passed as the following parameter c("meta", "found").

progress

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

simplify

[Deprecated] no side-effect

filter_fn

a function that receives an item that should evaluate a logical value.

pick_fn

a function used to pick elements from items addressed by field parameter.

sign_fn

a function that receives an item as a parameter and returns an item signed.

Value

  • items_length(): an integer value.

  • items_matched(): returns an integer value if the STAC web server does support this extension. Otherwise returns NULL.

  • items_fetch(): a STACItemCollection with all matched items.

  • items_next(): fetches a new page from STAC service.

  • items_datetime(): a list of all items' datetime.

  • items_bbox(): returns a list with all items' bounding boxes.

  • item_assets(): Returns a character value with all assets names of the all items.

  • items_filter(): a STACItemCollection object.

  • items_reap(): a vector if the supplied field is atomic, otherwise or a list.

  • items_fields(): a character vector.

  • items_group(): a list of STACItemCollection objects.

  • items_sign(): a STACItemCollection object with signed assets url.

  • items_as_sf(): a sf object.

Details

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

  • items_matched() and items_assets(): ellipsis is not used.

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

  • items_fields(): ellipsis parameter is deprecated in version 0.9.2 of rstac. Please, use field parameter instead.

  • items_filter(): ellipsis is used to pass logical expressions to be evaluated against a STACItem field as filter criteria.

    WARNING: the evaluation of filter expressions changed in rstac 0.9.2. Older versions of rstac used properties field to evaluate filter expressions. Below, there is an example of how to write expressions in new rstac version:

    # expression in older version
items_filter(stac_obj, `eo:cloud_cover` < 10)
# now expressions must refer to properties explicitly
items_filter(stac_obj, properties$`eo:cloud_cover` < 10)
items_filter(stac_obj, properties[["eo:cloud_cover"]] < 10)

  • items_sign(): in the near future, ellipsis will be used to append key-value pairs to the url query string of an asset.

items_sign() has sign_fn parameter that must be a function that receives as argument an item and returns a signed item. rstac provides sign_bdc() and sign_planetary_computer() functions to access Brazil Data Cube products and Microsoft Planetary Computer catalogs, respectively.

Examples

if (FALSE) {
 x <- stac("https://brazildatacube.dpi.inpe.br/stac") %>%
     stac_search(collections = "CB4_64_16D_STK-1") %>%
     stac_search(limit = 500) %>%
     get_request()

 x %>% items_length()
 x %>% items_matched()
 x %>% items_datetime()
 x %>% items_bbox()
 x %>% items_fetch()
}

if (FALSE) {
# Defining BDC token
Sys.setenv("BDC_ACCESS_KEY" = "token-123")

# STACItem object
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_sign(sign_fn = sign_bdc())

}

if (FALSE) {
# STACItemCollection object
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_filter(properties$`eo:cloud_cover` < 10)

# Example with AWS STAC
stac("https://earth-search.aws.element84.com/v0") %>%
  stac_search(collections = "sentinel-s2-l2a-cogs",
              bbox = c(-48.206, -14.195, -45.067, -12.272),
              datetime = "2018-06-01/2018-06-30",
              limit = 500) %>%
  post_request() %>%
  items_filter(filter_fn = function(x) {x$properties$`eo:cloud_cover` < 10})
}

if (FALSE) {
# STACItemCollection object
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 %>% items_reap(field = c("properties", "datetime"))
}