items_functions: Items functions

items_groupR Documentation

Items functions

Description

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 class 'STACItem'
items_length(items)

## S3 method for class 'STACItemCollection'
items_length(items)

## Default S3 method:
items_length(items)

items_matched(items, matched_field = NULL)

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

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

## Default S3 method:
items_matched(items, matched_field = NULL)

items_fetch(items, ...)

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

items_next(items, ...)

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

items_datetime(items)

## S3 method for class 'STACItem'
items_datetime(items)

## S3 method for class 'STACItemCollection'
items_datetime(items)

## Default S3 method:
items_datetime(items)

items_bbox(items)

## S3 method for class 'STACItem'
items_bbox(items)

## S3 method for class 'STACItemCollection'
items_bbox(items)

## Default S3 method:
items_bbox(items)

items_assets(items, simplify = deprecated())

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

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

## Default S3 method:
items_assets(items, simplify = deprecated())

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

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

items_compact(items)

## S3 method for class 'STACItemCollection'
items_compact(items)

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

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

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

## Default S3 method:
items_reap(items, field, ..., pick_fn = identity)

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

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

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

## Default S3 method:
items_fields(items, field = NULL, ...)

items_sign(items, sign_fn)

## S3 method for class 'STACItem'
items_sign(items, sign_fn)

## S3 method for class 'STACItemCollection'
items_sign(items, sign_fn)

## Default S3 method:
items_sign(items, sign_fn)

items_as_sf(items)

## S3 method for class 'STACItem'
items_as_sf(items)

## S3 method for class '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.

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.

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.

Examples

## Not run: 
 x <- stac("https://brazildatacube.dpi.inpe.br/stac") %>%
     stac_search(collections = "CB4-16D-2") %>%
     stac_search(limit = 500) %>%
     get_request()

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

## End(Not run)

## Not run: 
# Defining BDC token
Sys.setenv("BDC_ACCESS_KEY" = "token-123")

# STACItem 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())


## End(Not run)

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

## End(Not run)

## Not run: 
# STACItemCollection 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(field = c("properties", "datetime"))

## End(Not run)


rstac documentation built on Oct. 18, 2023, 1:15 a.m.