items_functions: Items functions

Description

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

items_length(): shows how many items there are in the doc_items 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 doc_items and doc_item objects.
items_bbox(): retrieves the bbox field of a doc_items or a doc_item object.
item_assets(): returns the assets name from doc_items and doc_item objects.
items_filter(): selects only items that match some criteria (see details section).
items_reap(): traverses all items in a doc_items object and extracts values based on the specified field path. It is useful for retrieving nested elements from STAC items.
items_fields(): lists field names inside an item.
items_sign(): allow access assets by preparing its url.
items_as_sf(): convert items to sf object.
items_as_sfc(): convert items to sfc object.
items_intersects(): indicates which items intersects a given geometry.
items_properties(): lists properties names inside an item.

Usage

items_length(items)
# S3 method for doc_items
items_length(items)
items_matched(items, matched_field = NULL)
# S3 method for doc_items
items_matched(items, matched_field = NULL)
items_fetch(items, ...)
# S3 method for doc_items
items_fetch(items, ..., progress = TRUE, matched_field = NULL)
items_next(items, ...)
# S3 method for doc_items
items_next(items, ...)
items_datetime(items)
# S3 method for doc_item
items_datetime(items)
# S3 method for doc_items
items_datetime(items)
items_bbox(items)
# S3 method for doc_item
items_bbox(items)
# S3 method for doc_items
items_bbox(items)
items_assets(items)
# S3 method for doc_item
items_assets(items)
# S3 method for doc_items
items_assets(items)
# S3 method for default
items_assets(items)
items_filter(items, ..., filter_fn = NULL)
# S3 method for doc_items
items_filter(items, ..., filter_fn = NULL)
items_compact(items)
# S3 method for doc_items
items_compact(items)
items_reap(items, field, pick_fn = identity)
# S3 method for doc_item
items_reap(items, field, pick_fn = identity)
# S3 method for doc_items
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 doc_item
items_fields(items, field = NULL)
# S3 method for doc_items
items_fields(items, field = NULL)
items_sign(items, sign_fn)
# S3 method for doc_item
items_sign(items, sign_fn)
# S3 method for doc_items
items_sign(items, sign_fn)
# S3 method for default
items_sign(items, sign_fn)
items_as_sf(items, ..., crs = 4326)
# S3 method for doc_item
items_as_sf(items, ..., crs = 4326)
# S3 method for doc_items
items_as_sf(items, ..., crs = 4326)
items_as_sfc(items, crs = 4326)
# S3 method for doc_item
items_as_sfc(items, crs = 4326)
# S3 method for doc_items
items_as_sfc(items, crs = 4326)
items_as_tibble(items)
# S3 method for doc_item
items_as_tibble(items)
# S3 method for doc_items
items_as_tibble(items)
items_intersects(items, geom, ..., crs = 4326)
# S3 method for doc_item
items_intersects(items, geom, ..., crs = 4326)
# S3 method for doc_items
items_intersects(items, geom, ..., crs = 4326)
items_properties(items)
# S3 method for doc_item
items_properties(items)
# S3 method for doc_items
items_properties(items)
items_select(items, selection)
# S3 method for doc_items
items_select(items, selection)

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 doc_items 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 all items.
items_filter(): a doc_items object.
items_reap(): a vector if the supplied field is atomic, otherwise or a list.
items_fields(): a character vector.
items_sign(): a doc_items object with signed assets url.
items_as_sf(): a sf object.
items_as_sfc(): a sfc object.
items_as_tibble(): a tibble object.
items_intersects(): a logical vector.
items_properties(): returns a character value with all properties of all items.
items_select(): select features from an items object.

Arguments

items: a doc_items object.
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").
...: additional arguments. See details.
progress: a logical indicating if a progress bar must be shown or not. Defaults to TRUE.
filter_fn: a function that receives an item that should evaluate a logical value.
field: A character vector specifying the path to the field from which to extract subfield values. For example, c("assets", "*") will traverse all assets from each item.
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.
crs: a character representing the geometry projection.
geom: a sf or sfc object.
selection: an integer vector containing the indices of the items to select.

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_filter(): ellipsis is used to pass logical expressions to be evaluated against a doc_item field as filter criteria. Expressions must be evaluated as a logical value where TRUE selects the item and FALSE discards it. Multiple expressions are combine with AND operator. items_filter() 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: 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

Run this code

if (FALSE) {
 x <- stac("https://brazildatacube.dpi.inpe.br/stac") %>%
     stac_search(collections = "CB4-16D-2") %>%
     stac_search(datetime = "2020-01-01/2021-01-01", 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")

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

}

if (FALSE) {
# doc_items object
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_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) {
# doc_items object
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 %>% items_reap(c("properties", "datetime"))

# Extract all asset URLs from each item
stac_item %>% items_reap(c("assets", "*"), \(x) x$href)

stac_item %>% items_as_sf()

stac_item %>% items_as_tibble()

stac_item %>% items_select(c(1, 4, 10, 20))

}

Run the code above in your browser using DataLab