Create data cubes from image collections

Description

Creates a data cube based on spatial and temporal restrictions on a collection available in repositories such as AWS, Brazil Data Cube (BDC), and Digital Earth Africa (DEA) using information provided by STAC endpoints. Users can also create data cubes from local files.

A data cube does not contain actual data; it points to the files where the required data is archived. Other functions (e.g. 'sits_classify') use that information to retrieve and process data.

Currently, users can create data cube from the following sources:

• "BDC": Brazil Data Cube (BDC), see also https://brazil-data-cube.github.io/applications/stac.html

• "WTSS": Web Time Series Service from BDC, see also https://brazil-data-cube.github.io/applications/wtss.html

• "DEAFRICA": Digital Earth Africa, see also https://www.digitalearthafrica.org/

• "AWS": Amazon Web Services (AWS), see also https://earth-search.aws.element84.com/v0/

• "USGS":USGS LANDSAT collection

• "SATVEG": Defines a cube to use the SATVEG web service, see also https://www.satveg.cnptia.embrapa.br/satveg/login.html

For all cubes, users need to provide information on:

• collection: Collections are the highest level of aggregation on big data repositories. Use 'sits_list_collections()' to see which collections are supported by 'sits'

• spatial extent: The spatial extent of the data cube can be defined in two ways: (a) a region of interest('bbox') in WGS 84 coordinates; (b) a set of tiles defined according the collection tiling system.

• temporal extent: The start and end date of the cube

Optional parameters include:

• data_dir: Directory where data is installed (required for data sets stored in local disks)

• bands: Bands used to build the cube

Usage

sits_cube(source, ..., collection, data_dir = NULL)

## S3 method for class 'wtss_cube'
sits_cube(source = "WTSS", ..., collection, data_dir = NULL, url = NULL)

## S3 method for class 'stac_cube'
sits_cube(
  source,
  collection,
  data_dir = NULL,
  ...,
  bands = NULL,
  tiles = NULL,
  roi = NULL,
  start_date = NULL,
  end_date = NULL,
  name = NULL
)

## S3 method for class 'local_cube'
sits_cube(
  source,
  collection,
  data_dir,
  ...,
  bands = NULL,
  start_date = NULL,
  end_date = NULL,
  parse_info,
  delim = "_",
  name = NULL,
  origin = NULL,
  multicores = 2,
  progress = TRUE
)

## S3 method for class 'satveg_cube'
sits_cube(source = "SATVEG", collection = "TERRA", data_dir = NULL, ...)

Arguments

Details

The roi parameter allows a selection of an area of interest. Either using a named vector ("lon_min", "lat_min", "lon_max", "lat_max") with values in WGS 84, a sfc or sf object from sf package in WGS84 projection. GeoJSON geometries (RFC 7946) and shapefiles should be converted to sf objects before being used to define a region of interest. This parameter does not crop a region, but only selects the images that intersect with it.

Value

The description of a data cube

Note

In AWS, there are two types of collections: open data and requester-pays. Currently, 'sits' supports collection "SENTINEL-S2-L2A" (requester-pays) and "SENTINEL-S2-L2A-COGS" (open data). There is no need to provide AWS credentials to access open data collections. For requester-pays data, users need to provide their access codes as environment variables, as follows: Sys.setenv( AWS_ACCESS_KEY_ID = <your_access_key>, AWS_SECRET_ACCESS_KEY = <your_secret_access_key> )

Sentinel-2/2A level 2A files in AWS are organized by sensor resolution. The AWS bands in 10m resolution are "B02", "B03", "B04", and "B08". The 20m bands are "B05", "B06", "B07", B8A", "B8A", "B11", and "B12". Bands "B01" and "B09" are available at 60m resolution.

For DEAFRICA, sits currently works with collection 'S2_L2A' (open data). This collection is the same as AWS collection "SENTINEL-S2-L2A-COGS", and is located in Africa (Capetown) for faster access to African users. No payment for access is required.

For USGS, sits currently works with collection 'landsat-c2l2-sr', which corresponds to Landsat Collection 2 Level-2 surface reflectance data, covering datasets from Landsat-4 to Landsat-8. This collection is open data.

All BDC collections have been regularized. BDC users need to provide their credentials using environment variables. To create your credentials, please see "https://brazildatacube.dpi.inpe.br/portal/explore". There is no cost for accessing data in the BDC. After obtaining the BDC access key, please include it as an environment variable, as follows: Sys.setenv( BDC_ACCESS_KEY = <your_bdc_access_key> )

To create a cube from local files, the user needs to inform:

• source: Provider from where the data has been downloaded (e.g, "BDC", "AWS)

• collection:Collection from which the data has been extracted

• data_dir: Local directory where the files are stored

• parse_info: Parsing information for files (see below)

• delim: Delimiter for parsing files (see below)

To create a cube from local files, all image files should have the same spatial resolution and projection. Files can belong to different tiles of a spatial reference system. Each file should contain a single image band for a single date. File names must include tile, date and band information. For example: "CBERS-4_022024_B13_2018-02-02.tif" and "cube_20LKP_B02_2018-07-18.jp2" are accepted names. The user has to provide parsing information to allow 'sits' to extract the tile, the band and the date. In the examples above, the parsing info is c("X1", "X2", "tile", "band", "date") and the delimiter is "_".

The SATVEG service is run by Embrapa Agricultural Informatics Centre provides access to time series from the MODIS sensor. There are three collections: "terra" (from the TERRA satellite), "aqua" (from the AQUA satellite) and "comb" (combination of both satellites).

WTSS is a web service for providing individual time series from BDC. Users specify a list of spatio-temporal positions and a collection where they want to extract the data.

References

'rstac' package (https://github.com/brazil-data-cube/rstac)

Examples

## Not run: 

# --- Access to the Brazil Data Cube
# Provide your BDC credentials as environment variables
bdc_access_key <- Sys.getenv("BDC_ACCESS_KEY")
if (nchar(bdc_access_key) == 0)
       stop("No BDC_ACCESS_KEY defined in environment.")

# create a raster cube file based on the information in the BDC
cbers_tile <- sits_cube(
    source = "BDC",
    collection = "CB4_64_16D_STK-1",
    bands = c("NDVI", "EVI"),
    tiles = "022024",
    start_date = "2018-09-01",
    end_date = "2019-08-28"
)

# --- Create a WTSS cube from BDC cubes
# Provide your BDC credentials as environment variables
bdc_access_key <- Sys.getenv("BDC_ACCESS_KEY")
if (nchar(bdc_access_key) == 0)
       stop("No BDC_ACCESS_KEY defined in environment.")

cube_wtss <- sits_cube(source = "WTSS",
                       collection = "MOD13Q1-6")

# --- Access to Digital Earth Africa
# create a raster cube file based on the information about the files
cube_dea <- sits_cube(source = "DEAFRICA",
                      collection = "s2_l2a",
                      bands = c("B04", "B08"),
                      roi   = c("lat_min" = 17.379,
                                "lon_min" = 1.1573,
                                "lat_max" = 17.410,
                                "lon_max" = 1.1910),
                      start_date = "2019-01-01",
                      end_date = "2019-10-28"
)

# --- Access to open data Sentinel 2/2A level 2 collection in AWS
s2_cube <- sits_cube(source = "AWS",
                      collection = "sentinel-s2-l2a-cogs",
                      tiles = c("20LKP","20LLP"),
                      bands = c("B04", "B08", "B11"),
                      start_date = as.Date("2018-07-18"),
                      end_date = as.Date("2019-07-23")
)

# --- Create a cube based on a local MODIS data
data_dir <- system.file("extdata/raster/mod13q1", package = "sits")

modis_cube <- sits_cube(
    source = "BDC",
    collection = "MOD13Q1-6",
    data_dir = data_dir,
    delim = "_",
    parse_info = c("X1", "X2", "tile", "band", "date")
)

## End(Not run)