R client library for STAC (rstac)

Description

Provides functions to access, search and download spacetime earth observation data via SpatioTemporal Asset Catalog (STAC). This package supports the version 1.0.0 (and older) of the STAC specification (https://github.com/radiantearth/stac-spec). For further details see Simoes et al. (2021) doi:10.1109/IGARSS47720.2021.9553518.

The rstac functions

The rstac package provides two categories of functions: API endpoints and data access and organization.

STAC API endpoints functions

• stac(): implements STAC ⁠/stac⁠ endpoint for version 0.8.1 or below, and / for versions 0.9.0 or higher.

• conformance(): implements ⁠/conformance⁠ endpoint.

• collections(): implements ⁠/collections⁠ and /collections/{collectionId} endpoints.

• items(): implements /collections/{collectionId}/items and /collections/{collectionId}/items/{featureId} endpoints.

• queryables(): implements ⁠/queryables⁠ and /collections/{collectionId}/queryables endpoints.

• stac_search(): implements STAC ⁠/stac/search⁠ endpoint for version 0.8.1 or below, and ⁠/search⁠ endpoint for versions 0.9.0 or higher.

• ext_filter(): implements ⁠/filter⁠ CQL2 endpoint.

Data access and organization functions

• get_request(): makes HTTP GET requests to STAC web service.

• post_request(): makes HTTP POST requests to STAC web service.

• items_matched(): returns how many items matched the search criteria.

• items_fetch(): fetches all matched items from service.

• items_filter(): selects items according to some criteria.

• items_as_sf(): converts items to a sf object.

• items_fields(): help explore fields inside items.

• items_compact(): removes all items with empty assets.

• items_reap(): extracts contents from items.

• items_length(): informs how many items are fetched locally.

• items_sign(): appends tokens to assets' URL and turn them accessible.

• assets_select(): select assets in items.

• assets_rename(): rename assets in items.

• assets_url(): extract all URL to assets in items.

• assets_download(): download assets in batch.

Data types

The package implements the following S3 classes: doc_items, doc_item, doc_catalog, doc_collections and doc_collection. These classes are regular lists representing the corresponding JSON STAC objects.

Author(s)

Maintainer: Felipe Carvalho lipecaso@gmail.com

Authors:

• Rolf Simoes rolfsimoes@gmail.com

• Brazil Data Cube Team brazildatacube@inpe.br

Other contributors:

• National Institute for Space Research (INPE) [copyright holder]

See Also

Useful links:

• https://brazil-data-cube.github.io/rstac/

• Report bugs at https://github.com/brazil-data-cube/rstac/issues

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

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.

See Also

stac_search(), items(), get_request()

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)

Endpoint functions

Description

The collections function implements the WFS3 ⁠/collections⁠ and /collections/{collectionId} endpoints.

Each endpoint retrieves specific STAC objects:

• ⁠/collections⁠: Returns a list of STAC Collections published in the STAC service

• /collections/{collectionId}: Returns a single STAC Collection object

Usage

collections(q, collection_id = NULL, limit = NULL)

Arguments

Value

A rstac_query object with the subclass collections for ⁠/collections/⁠ endpoint, or a collection_id subclass for /collections/{collection_id} endpoint, containing all search field parameters to be provided to STAC API web service.

See Also

get_request(), post_request(), items()

Examples

## Not run: 
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   collections() %>%
   get_request()

 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   collections(collection_id = "CB4-16D-2") %>%
   get_request()

## End(Not run)

Collections functions

Description

These functions provide support to work with doc_collectionsobjects.

• collections_length(): shows how many items there are in the doc_items object.

• collections_matched(): shows how many items matched the search criteria.

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

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

Usage

collections_next(collections, ...)

collections_matched(collections, matched_field)

collections_length(collections)

collections_fetch(collections, ..., progress = TRUE, matched_field = NULL)

Arguments

Details

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

• collections_fetch() and collections_next(): ellipsis is used to pass additional httr options to GET method, such as add_headers or set_cookies.

Value

• collections_length(): an integer value.

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

• collections_fetch(): a doc_items with all matched items.

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

Examples

## Not run: 
# doc_items object
stac("https://cmr.earthdata.nasa.gov/stac/LPCLOUD") |>
  collections() |>
  get_request() |>
  collections_fetch()

## End(Not run)

doc_conformance endpoint

Description

The conformance endpoint provides the capabilities of the service. This endpoint is accessible from the provider's catalog (⁠/conformance⁠).

Usage

conformance(q)

Arguments

Value

A rstac_query object with the subclass conformance for ⁠/conformance⁠ endpoint.

See Also

get_request(), stac(), collections()

Examples

## Not run: 
stac("https://planetarycomputer.microsoft.com/api/stac/v1") %>%
  conformance() %>% get_request()

## End(Not run)

CQL2 helper function

Description

These are helper functions to easy construction CQL2 expressions. These functions are not meant to be used in expressions and they must be escaped using ⁠{{⁠ to be evaluated before request.

Usage

cql2_bbox_as_geojson(bbox)

cql2_date(x)

cql2_timestamp(x)

cql2_interval(start = "..", end = "..")

Arguments

Details

• cql2_bbox_as_geojson(): used to convert bounding box (bbox) to a GeoJSON object to be used as argument of CQL2 spatial operators.

• cql2_date(), cql2_timestamp(), and cql2_interval(): create temporal literal values to be passed into CQL2 expressions.

Value

• cql2_bbox_as_geojson(): GeoJSON object.

• cql2_date(), cql2_timestamp(), and cql2_interval(): internal rstac expressions representing temporal values.

Examples

## Not run: 
bbox <- c(-122.2751, 47.5469, -121.9613, 47.7458)

cql2_json(
    collection == "landsat-c2-l2" &&
      t_intersects(datetime, {{
        cql2_interval("2020-12-01", "2020-12-31")
      }}) &&
      s_intersects(geometry, {{
        cql2_bbox_as_geojson(bbox)
      }})
  )

## End(Not run)

Filter extension

Description

ext_filter() implements Common Query Language (CQL2) filter extension on rstac. This extension expands the filter capabilities providing a query language to construct more complex expressions. CQL2 is an OGC standard and defines how filters can be constructed. It supports predicates for standard data types like strings, numbers, and boolean as well as for spatial geometries (point, lines, polygons) and temporal data (instants and intervals).

cql2_json() and cql2_text() are helper functions that can be used to show how expressions are converted into CQL2 standard, either JSON or TEXT formats.

rstac translates R expressions to CQL2, allowing users to express their filter criteria using R language. For more details on how to create CQL2 expressions in rstac. See the details section.

Usage

ext_filter(q, expr, lang = NULL, crs = NULL)

cql2_json(expr)

cql2_text(expr)

Arguments

Details

To allow users to express filter criteria in R language, rstac takes advantage of the abstract syntax tree (AST) to translate R expressions to CQL2 expressions. The following topics describe the correspondences between rstac expressions and CQL2 operators.

Non-standard evaluation

• ext_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}}.

Standard comparison operators

• ==, >=, <=, >, <, and != operators correspond to =, >=, <=, >, <, and ⁠<>⁠ in CQL2, respectively.

• function is_null(a) and !is_null(a) corresponds to ⁠a IS NULL⁠ and ⁠a IS NOT NULL⁠ CQL2 operators, respectively.

Advanced comparison operators

• a %like% b corresponds to CQL2 ⁠a LIKE b⁠, a and b strings values.

• between(a, b, c) corresponds to CQL2 ⁠a BETWEEN b AND c⁠, where b and c integer values.

• a %in% b corresponds to CQL2 ⁠a IN (b)⁠, where b should be a list of values of the same type as a.

Spatial operators

• functions s_intersects(a, b), s_touches(a, b), s_within(a, b), s_overlaps(a, b), s_crosses(a, b), and s_contains(a, b) corresponds to CQL2 S_INTERSECTS(a, b), S_TOUCHES(a, b), S_WITHIN(a, b), S_OVERLAPS(a, b), S_CROSSES(a, b), and S_CONTAINS(a, b) operators, respectively. Here, a and b should be geometry objects. rstac accepts sf, sfc, sfg, list (representing GeoJSON objects), or character (representing either GeoJSON or WKT).

• NOTE: All of the above spatial object types, except for the character, representing a WKT, may lose precision due to numeric truncation when R converts numbers to JSON text. WKT strings are sent "as is" to the service. Therefore, the only way for users to retain precision on spatial objects is to represent them as a WKT string. However, user can control numeric precision using the options(stac_digits = ...). The default value is 15 digits.

Temporal operators

• functions date(a), timestamp(a), and interval(a, b) corresponds to CQL2 DATE(a), TIMESTAMP(a), and INTERVAL(a, b) operators, respectively. These functions create literal temporal values. The first two define an instant type, and the third an interval type.

• functions t_after(a, b), t_before(a, b), t_contains(a, b), t_disjoint(a, b), t_during(a, b), t_equals(a, b), t_finishedby(a, b), t_finishes(a, b), t_intersects(a, b), t_meets(a, b), t_meet(a, b), t_metby(a, b), t_overlappedby(a, b), t_overlaps(a, b), t_startedby(a, b), and t_starts(a, b) corresponds to CQL2 T_AFTER(a, b), T_BEFORE(a, b), T_CONTAINS(a, b), T_DISJOINT(a, b), T_DURING(a, b), T_EQUALS(a, b), T_FINISHEDBY(a, b), T_FINISHES(a, b), T_INTERSECTS(a, b), T_MEETS(a, b), T_MEET(a, b), T_METBY(a, b), T_OVERLAPPEDBY(a, b), T_OVERLAPS(a, b), T_STARTEDBY(a, b), and T_STARTS(a, b) operators, respectively. Here, a and b are temporal values (instant or interval, depending on function).

Array Operators

• R unnamed lists (or vectors of size > 1) are translated to arrays by rstac. list() and c() functions always create array values in CQL2 context, no matter the number of its arguments.

• functions a_equals(a, b), a_contains(a, b), a_containedby(a, b), and a_overlaps(a, b) corresponds to CQL2 A_EQUALS(a, b), A_CONTAINS(a, b), A_CONTAINEDBY(a, b), and A_OVERLAPS(a, b) operators, respectively. Here, a and b should be arrays.

Value

A rstac_query object with the subclass ext_filter containing all request parameters to be passed to get_request() or post_request() function.

Note

The specification states that double-quoted identifiers should be interpreted as properties. However, the R language does not distinguish double quote from single quote strings. The right way to represent double quoted properties in R is to use the escape character (⁠), for example ⁠"date"'.

See Also

ext_query(), stac_search(), post_request(), before_request(), after_response(), content_response()

Examples

## Not run: 
# Standard comparison operators in rstac:
# Creating a stac search query
req <- stac("https://planetarycomputer.microsoft.com/api/stac/v1") %>%
  stac_search(limit = 5)

# Equal operator '=' with collection property
req %>% ext_filter(collection == "sentinel-2-l2a") %>% post_request()

# Not equal operator '!=' with collection property
req %>% ext_filter(collection != "sentinel-2-l2a") %>% post_request()

# Less than or equal operator '<=' with datetime property
req %>% ext_filter(datetime <= "1986-01-01") %>% post_request()

# Greater than or equal '>=' with AND operator
req %>% ext_filter(collection == "sentinel-2-l2a"   &&
                   `s2:vegetation_percentage` >= 50 &&
                   `eo:cloud_cover` <= 10) %>% post_request()
# Advanced comparison operators
# 'LIKE' operator
req %>% ext_filter(collection %like% "modis%") %>% post_request()

# 'IN' operator
req %>% ext_filter(
  collection %in% c("landsat-c2-l2", "sentinel-2-l2a") &&
    datetime > "2019-01-01" &&
    datetime < "2019-06-01") %>%
  post_request()

# Spatial operator
# Lets create a polygon with list
polygon <- list(
  type = "Polygon",
  coordinates = list(
    matrix(c(-62.34499836, -8.57414572,
             -62.18858174, -8.57414572,
             -62.18858174, -8.15351185,
             -62.34499836, -8.15351185,
             -62.34499836, -8.57414572),
           ncol = 2, byrow = TRUE)
  )
)
# 'S_INTERSECTS' spatial operator with polygon and geometry property
req %>% ext_filter(collection == "sentinel-2-l2a" &&
                   s_intersects(geometry, {{polygon}})) %>% post_request()

# 'S_CONTAINS' spatial operator with point and geometry property
point <- list(type = "Point", coordinates = c(-62.45792211, -8.61158488))
req %>% ext_filter(collection == "landsat-c2-l2" &&
                   s_contains(geometry, {{point}})) %>% post_request()

# 'S_CROSSES' spatial operator with linestring and geometry property
linestring <- list(
  type = "LineString",
  coordinates = matrix(
         c(-62.55735320, -8.43329465, -62.21791603, -8.36815014),
         ncol = 2, byrow = TRUE
  )
)
req %>% ext_filter(collection == "landsat-c2-l2" &&
                   s_crosses(geometry, {{linestring}})) %>% post_request()

# Temporal operator
# 'T_INTERSECTS' temporal operator with datetime property
req %>% ext_filter(
  collection == "landsat-c2-l2" &&
    t_intersects(datetime, interval("1985-07-16T05:32:00Z",
                                    "1985-07-24T16:50:35Z"))) %>%
 post_request()

# 'T_DURING' temporal operator with datetime property
req %>%
 ext_filter(collection == "landsat-c2-l2" &&
            t_during(datetime,
            interval("2022-07-16T05:32:00Z", ".."))) %>%
 post_request()

# 'T_BEFORE' temporal operator with datetime property
req %>%
 ext_filter(collection == "landsat-c2-l2" &&
            t_before(datetime, timestamp("2022-07-16T05:32:00Z"))) %>%
 post_request()

# 'T_AFTER' temporal operator with datetime property
req %>%
 ext_filter(collection == "landsat-c2-l2" &&
            t_after(datetime, timestamp("2022-07-16T05:32:00Z"))) %>%
  post_request()

# Shows how CQL2 expression (TEXT format)
cql2_text(collection == "landsat-c2-l2" &&
  s_crosses(geometry, {{linestring}}))

# Shows how CQL2 expression (JSON format)
cql2_json(collection == "landsat-c2-l2" &&
            t_after(datetime, timestamp("2022-07-16T05:32:00Z")))

## End(Not run)

Query extension

Description

The ext_query() is the exported function of the STAC API query extension. It can be used after a call to stac_search() function. It allows that additional fields and operators other than those defined in stac_search() function be used to make a complex filter.

The function accepts multiple filter criteria. Each filter entry is an expression formed by ⁠<field> <operator> <value>⁠, where ⁠<field>⁠ refers to a valid item property. Supported ⁠<fields>⁠ depends on STAC API service implementation. The users must rely on the service providers' documentation to know which properties can be used by this extension.

The ext_query() function allows the following ⁠<operators>⁠

• == corresponds to 'eq'

• != corresponds to 'neq'

• < corresponds to 'lt'

• <= corresponds to 'lte'

• > corresponds to 'gt'

• >= corresponds to 'gte'

• ⁠\%startsWith\%⁠ corresponds to 'startsWith' and implements a string prefix search operator.

• ⁠\%endsWith\%⁠ corresponds to 'endsWith' and implements a string suffix search operator.

• ⁠\%contains\%⁠: corresponds to 'contains' and implements a string infix search operator.

• ⁠\%in\%⁠: corresponds to '⁠in⁠' and implements a vector search operator.

Besides this function, the following S3 generic methods were implemented to get things done for this extension:

• The before_request() for subclass ext_query

• The after_response() for subclass ext_query

See source file ext_query.R for an example of how to implement new extensions.

Usage

ext_query(q, ...)

Arguments

Value

A rstac_query object with the subclass ext_query containing all request parameters to be passed to post_request() function.

See Also

ext_filter(), stac_search(), post_request(), before_request(), after_response(), content_response()

Examples

## Not run: 
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   stac_search(collections = "CB4-16D-2") %>%
   ext_query("bdc:tile" %in% "007004") %>%
   post_request()

## End(Not run)

Extension development functions

Description

Currently, there are five STAC documents defined in STAC spec:

• doc_catalog

• doc_collection

• doc_collections

• doc_item

• doc_items

Each document class is associated with STAC API endpoints. As soon as new STAC documents are proposed in the specification, new classes can be created in the rstac package.

Let version parameter NULL to detect version automatically.

Basically, there are two types of extensions in STAC specification:

1. STAC documents extensions: these extensions can be defined in different elements of the document specification.

2. STAC API extensions: these extensions are associated with the interaction between the client and server through API and may add new elements in the STAC documents or just filter the elements to be returned in the documents.

Here, we will focus on the second type of extension.

To let rstac package perform some behavior according to an STAC API extension we need define some functions. These functions can be implemented in three environments:

1. In rstac package by including new functions make a GitHub pull request on rstac repository (https://github.com/brazil-data-cube/rstac)

2. In a new package by using rstac as dependent package

3. In a script that loads rstac into the environment

All these places may impose specific requirements, however the core logic to implement an extension is the same.

These functions are intended for those who want to implement new STAC API extensions. An extension must define a subclass name and implement all the following S3 generic methods for that subclass:

• before_request(): allows handling query parameters before submit them to the HTTP server, usually sets up the query endpoint;

• after_request(): allows to check and parse document received by the HTTP server;

These methods will work 'behind the scenes' when a rstac_query object representing a user query are passed to a request function (e.g. get_request() or post_request()). The calling order is:

1. begin of get_request() or post_request()

2. if STAC API version is not defined, try detect it

3. call before_request()

4. send HTTP request

5. receive HTTP response

6. after_response()

7. end of get_request() or post_request()

Besides that, the extension must expose a function to receive user parameters and return a rstac_query object with a subclass associated with the above S3 methods. This function must accept as its first parameter a rstac_query object representing the actual query. To keep the command flow consistency, the function needs to check the subclass of the input query. After that, it must set new or changes the input query parameters according to the user input and, finally, return the new query as a rstac_query object.

You can see examples on how to implement an STAC API extension by looking at stac.R, collections.R, items.R, stac_search.R, and ext_query.R source files. These files implement core STAC API endpoints, as well as the query API extension.

There are also some utility functions described in Functions section bellow that can help the extension development.

Usage

before_request(q)

after_response(q, res)

parse_params(q, params)

content_response(res, status_codes, content_types, key_message)

check_query_verb(q, verbs, msg = NULL)

check_query(x, classes = NULL)

subclass(x)

set_query_endpoint(q, endpoint, params = NULL)

rstac_query(version = NULL, base_url, params = list(), subclass)

Arguments

Value

A rstac_query object for before_request() and after_response() functions.

The content_response() function returns a list data structure representing the JSON file received in HTTP response

The rstac_query() function returns a STACQuery object with subclass defined by subclass parameter.

Functions

• content_response(): The content_response function checks if the request's response is in accordance with the allowed status codes and content-types. It returns the parsed content response.

• check_query_verb(): The check_query_verb() function allows you to define which HTTP verbs are allowed. It is useful for establishing which verbs will be supported by an extension.

• check_query(): The check_query() function specifies which type of query object (rstac_query) is expected in the function extension.

• subclass(): The subclass() function returns a character representing the subclass name of rstac_query objects.

• set_query_endpoint(): The set_query_endpoint() function defines the endpoint of a query. If params parameter is passed, each value must be an entry of params field of the given query. The corresponding param value will be used as value replacement of ⁠%s⁠ occurrences in the endpoint string. After the replacement, all params in this list will be removed.

• rstac_query(): The rstac_query() function is a constructor of rstac_query objects. Every extension must implement a subclass of rstac_query to represent its queries. This is done by informing to the subclass parameter the extension's subclass name.

  The params parameter is a named list where user parameters must be stored. It is important to know if previous query parameters needs to be keeped in the new query. If so, it is recommended do use utils::modifyList() function to merge the old and new query parameters.

  If the version parameter is NULL, rstac will detect STAC API version automatically.

  In general, if you are implementing a new subclass, the parameters version and url will be the same as the previous query. The params parameter will be merged with previous query. And subclass is the extension's subclass name.

See Also

ext_query()

STAC API request functions

Description

The get_request is function that makes HTTP GET requests to STAC web services, retrieves, and parse the data.

The post_request is function that makes HTTP POST requests to STAC web services, retrieves, and parse the data.

Usage

get_request(q, ...)

post_request(q, ..., encode = c("json", "multipart", "form"))

Arguments

Value

Either a doc_catalog, doc_collection, doc_collections, doc_items or doc_item object depending on the subclass and search fields parameters of q argument.

See Also

stac() stac_search() collections() items()

Examples

## Not run: 
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  get_request()

 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2") %>%
  post_request()

## End(Not run)

Endpoint functions

Description

The items function implements WFS3 /collections/{collectionId}/items, and /collections/{collectionId}/items/{featureId} endpoints.

Each endpoint retrieves specific STAC objects:

• /collections/{collectionId}/items: Returns a STAC Items collection (GeoJSON)

• /collections/{collectionId}/items/{itemId}: Returns a STAC Item (GeoJSON Feature)

The endpoint /collections/{collectionId}/items accepts the same filters parameters of stac_search() function.

Usage

items(q, feature_id = NULL, datetime = NULL, bbox = NULL, limit = NULL)

Arguments

Value

A rstac_query object with the subclass items for /collections/{collection_id}/items endpoint, or a item_id subclass for /collections/{collection_id}/items/{feature_id} endpoint, containing all search field parameters to be provided to STAC API web service.

See Also

get_request(), post_request(), collections()

Examples

## Not run: 
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   collections("CB4-16D-2") %>%
   items(bbox = c(-47.02148, -17.35063, -42.53906, -12.98314)) %>%
   get_request()

 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   collections("CB4-16D-2") %>%
   items("CB4-16D_V2_000002_20230509") %>%
   get_request()

## End(Not run)

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

items_matched(items, matched_field = NULL)

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

items_fetch(items, ...)

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

items_next(items, ...)

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

items_datetime(items)

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

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

items_bbox(items)

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

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

items_assets(items)

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

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

## Default S3 method:
items_assets(items)

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

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

items_compact(items)

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

items_reap(items, field, pick_fn = identity)

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

## S3 method for class 'doc_items'
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 'doc_item'
items_fields(items, field = NULL)

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

items_sign(items, sign_fn)

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

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

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

items_as_sf(items, ..., crs = 4326)

## S3 method for class 'doc_item'
items_as_sf(items, ..., crs = 4326)

## S3 method for class 'doc_items'
items_as_sf(items, ..., crs = 4326)

items_as_sfc(items, crs = 4326)

## S3 method for class 'doc_item'
items_as_sfc(items, crs = 4326)

## S3 method for class 'doc_items'
items_as_sfc(items, crs = 4326)

items_as_tibble(items)

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

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

items_intersects(items, geom, ..., crs = 4326)

## S3 method for class 'doc_item'
items_intersects(items, geom, ..., crs = 4326)

## S3 method for class 'doc_items'
items_intersects(items, geom, ..., crs = 4326)

items_properties(items)

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

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

items_select(items, selection)

## S3 method for class 'doc_items'
items_select(items, selection)

Arguments

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.

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.

Examples

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

## End(Not run)

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


## End(Not run)

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

## End(Not run)

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


## End(Not run)

Signature in hrefs provided by the STAC from the Brazil Data Cube project.

Description

These functions provide support to access assets from Brazil Data Cube.

• items_sign_bdc(): A simplified function to sign assets' URL from Brazil Data Cube to be able to access the data.

• sign_bdc(): Creates a signing function to be used by items_sign(). This function sign all the assets' URL.

To sign the hrefs with your token you need to store it in an environment variable in BDC_ACCESS_KEYor use acess_token parameter.

Usage

items_sign_bdc(items, access_token = NULL, ...)

sign_bdc(access_token = NULL, ...)

Arguments

Value

a function that signs each item assets.

• items_sign_bdc(): items with signed assets URLs.

• sign_bdc(): a function to to be passed to items_sign().

Examples

## Not run: 
 # doc_items object
 stac_obj <- stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   stac_search(collections = "CB4-16D-2",
               datetime = "2019-06-01/2019-08-01") %>%
   stac_search() %>%
   get_request()

 # the new way to authenticate:
 stac_obj <- stac_obj %>%
   items_sign_bdc("<your-access-token>")

 # this is the old way of authentication (still works):
 # stac_obj %>%
 #   items_sign(sign_fn = sign_bdc(access_token = "<your-access-token>"))

## End(Not run)

Signs URL to access assets from Microsoft's Planetary Computer.

Description

These functions provide support to access assets from Planetary Computer.

• items_sign_planetary_computer(): A simplified function to sign assets' URL from Microsoft Planetary Computer to be able to access the data.

• sign_planetary_computer(): Creates a signing function to be used by items_sign(). This function sign all the assets' URL.

Usage

items_sign_planetary_computer(items, subscription_key = NULL, ...)

sign_planetary_computer(..., headers = NULL, token_url = NULL)

Arguments

Value

• items_sign_planetary_computer(): items with signed assets URLs.

• sign_planetary_computer(): a function to to be passed to items_sign().

Examples

## Not run: 
 # doc_items object
 stac_obj <- stac("https://planetarycomputer.microsoft.com/api/stac/v1/") %>%
  stac_search(collections = "sentinel-2-l2a",
              bbox = c(-47.02148, -17.35063, -42.53906, -12.98314)) %>%
  get_request()

 # the new way to authenticate:
 stac_obj <- stac_obj %>%
   items_sign_planetary_computer()

 # this is the old way of authentication (still works):
 # stac_obj <- stac_obj %>%
 #   items_sign(sign_fn = sign_planetary_computer())

 # example of access to collections that require authentication
 stac_obj <- stac("https://planetarycomputer.microsoft.com/api/stac/v1") %>%
   stac_search(collections = c("sentinel-1-rtc"),
               bbox = c(-64.8597, -10.4919, -64.79272527, -10.4473),
               datetime = "2019-01-01/2019-01-28") %>%
   post_request()

 # the new way to authenticate:
 # stac_obj <- stac_obj %>%
 #   items_sign_planetary_computer("<subscription-key>")

 # this is the old way of authentication (still works):
 # stac_obj <- stac_obj %>%
 #   items_sign(
 #     sign_fn = sign_planetary_computer(
 #       headers = c("Ocp-Apim-Subscription-Key" = <your-mpc-token>)
 #     )
 #   )

## End(Not run)

Plot preview images

Description

This is a helper function to plot preview assets (e.g. quicklook, thumbnail, rendered_preview). Currently, only png and jpeg formats are supported.

Usage

preview_plot(url)

Arguments

Value

A rastergrob grob from package grid.

Printing functions

Description

The print function covers all objects in the rstac package:

• stac(): returns a doc_catalog document from ⁠/stac⁠ (v0.8.0) or / (v0.9.0 or v1.0.0) endpoint.

• stac_search(): returns a doc_items document from ⁠/stac/search⁠ (v0.8.0) or ⁠/search⁠ (v0.9.0 or v1.0.0) endpoint containing all Items that match the provided search predicates.

• collections(): implements the ⁠/collections⁠ and /collections/{collectionId} endpoints. The former returns a doc_collections document that lists all collections published by the server, and the later returns a single doc_collection document that describes a unique collection.

• items(): retrieves a doc_items document from /collections/{collectionId}/items endpoint and a doc_item document from /collections/{collectionId}/items/{itemId} endpoints.

The rstac package objects visualization is based on markdown, a lightweight markup language. You can paste the output into any markdown editor for a better visualization.

Call print() function to print the rstac's objects. You can determine how many items will be printed using n parameter.

Usage

## S3 method for class 'rstac_query'
print(x, ...)

## S3 method for class 'doc_catalog'
print(x, ...)

## S3 method for class 'doc_collections'
print(x, n = 10, ...)

## S3 method for class 'doc_collection'
print(x, ...)

## S3 method for class 'doc_items'
print(x, n = 10, ..., tail = FALSE)

## S3 method for class 'doc_item'
print(x, ...)

## S3 method for class 'doc_queryables'
print(x, n = 10, ...)

## S3 method for class 'doc_conformance'
print(x, n = 10, ...)

## S3 method for class 'doc_link'
print(x, ...)

## S3 method for class 'doc_links'
print(x, n = 10, ...)

Arguments

See Also

stac() stac_search() collections() items()

Examples

## Not run: 
 # doc_items object
 stac_item_collection <-
   stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   stac_search(collections = "CB4-16D-2",
          bbox = c(-47.02148, -17.35063, -42.53906, -12.98314),
          limit = 15) %>%
   get_request()

 print(stac_item_collection, n = 10)

 # doc_collections object
 stac_collection <-
     stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
     collections() %>%
     get_request()

 print(stac_collection, n = 5)

 # rstac_query object
 obj_rstac <- stac("https://brazildatacube.dpi.inpe.br/stac/")

 print(obj_rstac)

## End(Not run)

Endpoint functions

Description

The queryables endpoint allows the user to discover which properties can be used in the filter extension. This endpoint can be accessed from the catalog (⁠/queryables⁠) or from a collection (⁠/collections/{collection_id}/queryables⁠).

Usage

queryables(q)

Arguments

Value

A rstac_query object with the subclass queryables for ⁠/queryables⁠ endpoint.

See Also

ext_filter(), conformance(), collections()

Examples

## Not run: 
# Catalog's queryables
stac("https://planetarycomputer.microsoft.com/api/stac/v1") %>%
  queryables() %>% get_request()

# Collection's queryables
stac("https://planetarycomputer.microsoft.com/api/stac/v1") %>%
  collections(collection_id = "sentinel-2-l2a") %>%
  queryables() %>%
  get_request()

## End(Not run)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

magrittr

%>%

Endpoint functions

Description

The stac function implements ⁠/stac⁠ API endpoint (>=0.8.0), and / for versions 0.9.0 or higher. It prepares search field parameters to be provided to a STAC API web service. This endpoint should return a STAC Catalog document containing all published data catalogs.

Usage

stac(base_url, force_version = NULL)

Arguments

Value

A rstac_query object with the subclass stac containing all request parameters to be provided to API service.

See Also

stac_search(), collections(), items(), get_request(), post_request()

Examples

## Not run: 
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
   get_request()

## End(Not run)

Utility functions

Description

These function retrieves information about either rstac queries (rstac_query objects) or rstac documents (rstac_doc objects).

Usage

stac_version(x, ...)

stac_type(x)

Arguments

Value

The stac_version() function returns a character STAC API version.

Endpoint functions

Description

(This document is based on STAC specification documentation https://github.com/radiantearth/stac-spec/ and reproduces some of its parts)

The stac_search function implements ⁠/stac/search⁠ API endpoint (v0.8.1) and ⁠/search⁠ (v0.9.0 or v1.0.0). It prepares query parameters used in the search API request, a stac object with all filter parameters to be provided to get_request or post_request functions. The GeoJSON content returned by these requests is a doc_items object, a regular R list representing a STAC Item Collection document.

Usage

stac_search(
  q,
  collections = NULL,
  ids = NULL,
  bbox = NULL,
  datetime = NULL,
  intersects = NULL,
  limit = NULL
)

Arguments

Value

A rstac_query object with the subclass search containing all search field parameters to be provided to STAC API web service.

See Also

stac(), ext_query(), get_request(), post_request()

Examples

## Not run: 
 # GET request
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2", limit = 10,
         datetime = "2017-08-01/2018-03-01") %>%
  get_request()

 # POST request
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2",
         bbox = c(-47.02148, -17.35063, -42.53906, -12.98314)) %>%
  post_request()

## End(Not run)

Static functions

Description

These functions provide support to work with static catalogs.

• stac_read(): open a STAC document from an URL.

• read_items(): opens (statically) all items referred in links key entry of a given collection document (doc_collection).

• links(): extracts and filters the links of any STAC document.

• link_open(): opens (statically) the document referenced by the link. This function can resolve any relative URL.

Usage

read_stac(url, ...)

read_items(collection, ..., limit = 100, page = 1, progress = TRUE)

read_collections(catalog, ..., limit = 100, page = 1, progress = TRUE)

links(x, ...)

link_open(link, base_url = NULL)

Arguments

Details

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

• stac_read(): ellipsis is used to pass any additional parameters to read_json function.

• links(): ellipsis is used to pass logical expressions to be evaluated against a doc_link item as a filter criteria. See examples.

Value

• links(): a doc_links object containing a list of link entries.

• link_open(): a recognizable rstac document.

Examples

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

 link <- links(x, rel == "items")
 link_open(link[[1]])

## End(Not run)

## Not run: 
 wv_url <- paste0(
   "https://s3.eu-central-1.wasabisys.com",
   "/stac/openlandmap/wv_mcd19a2v061.seasconv/collection.json"
 )
 wv <- read_stac(wv_url)
 stac_type(wv)  # Collection

 # reads the second page of 5 links
 wv_items <- read_items(wv, limit = 5, page = 2)

 # lists all links of the collection document that are not items
 links(wv, rel != "item")

 # lists all links of the items document
 links(wv_items)

## End(Not run)