R: Defines a data cube

sits_cube {sits}

R Documentation

Defines a data cube

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/
"LOCAL": Defines a cube from on a set of local files.
"PROBS": Defines a cube to from a set of classified image files.
"SATVEG": Defines a cube to use the SATVEG web service, see also https://www.satveg.cnptia.embrapa.br/satveg/login.html

For big data sources such as AWS, BDC, and DEA users need to provide:

collection: Collections are the highest level of aggregation on bug data repositories. Each repository has its own set of collections, described by STAC. To use STAC for querying repositories, please see the package 'rstac' for examples.
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

Usage

sits_cube(source, ...)

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

## S3 method for class 'bdc_cube'
sits_cube(
  source = "BDC",
  ...,
  name = "bdc_cube",
  collection,
  bands = NULL,
  tiles = NULL,
  bbox = NULL,
  start_date = NULL,
  end_date = NULL
)

## S3 method for class 'deafrica_cube'
sits_cube(
  source = "DEAFRICA",
  ...,
  name = "deafrica_cube",
  url = NULL,
  collection = "S2_L2A",
  bands = NULL,
  tiles = NULL,
  bbox = NULL,
  start_date = NULL,
  end_date = NULL
)

## S3 method for class 'aws_cube'
sits_cube(
  source = "AWS",
  ...,
  name = "aws_cube",
  url = NULL,
  collection = "sentinel-s2-l2a",
  tiles = NULL,
  bands = NULL,
  bbox = NULL,
  s2_resolution = 20,
  start_date = NULL,
  end_date = NULL
)

## S3 method for class 'usgs_cube'
sits_cube(
  source = "USGS",
  ...,
  name = "usgs_cube",
  url = NULL,
  collection = "landsat-c2l2-sr",
  tiles = NULL,
  bands = NULL,
  bbox = NULL,
  start_date = NULL,
  end_date = NULL
)

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

## S3 method for class 'probs_cube'
sits_cube(
  source = "PROBS",
  ...,
  name = "probs_cube",
  satellite,
  sensor,
  start_date,
  end_date,
  probs_labels,
  probs_files
)

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

Arguments

`source`	Data source (one of "AWS", "BDC", "DEAFRICA", "LOCAL", "PROBS", "SATVEG", "USGS", "WTSS").
`...`	Other parameters to be passed for specific types.
`name`	Name of the output data cube.
`url`	URL for the STAC endpoint of the data source.
`collection`	Collection to be searched in the data source.
`bands`	Bands to be included.
`tiles`	Tiles from the collection to be included in the data cube.
`bbox`	Area of interest (see details below).
`start_date`	Initial date for the cube (optional).
`end_date`	Final date for the cube (optional).
`s2_resolution`	Resolution of S2 images ("10m", "20m" or "60m"). used to build cubes (only for AWS cubes).
`data_dir`	directory where local data is located (only for creating data cubes from local files).
`parse_info`	parsing information for files without STAC information (only for creating data cubes from local files).
`delim`	delimiter for parsing files without STAC information (only for creating data cubes from local files).
`satellite`	Satellite that produced the images (only for creating data cubes from local files).
`sensor`	Sensor that produced the images.
`probs_labels`	Labels associated to a probabilities cube.
`probs_files`	File names (used for creating a cube from probabilities).

Details

The bbox parameter allows a selection of an area of interest. Either using a named vector ("xmin", "ymin", "xmax", "ymax") with values in WGS 84, a sfc or sf object from sf package, or a GeoJSON geometry (RFC 7946). Note that this parameter does not crop a region, but only selects the images that intersect with it.

Value

The description of a data cube

Note

For AWS, sits currently only works with collection "s2_l2a". Users need to provide AWS credentials using environment variables. # Sys.setenv( # "AWS_ACCESS_KEY_ID" = <your_access_key>, # "AWS_SECRET_ACCESS_KEY" = <your_secret_access_key>, # "AWS_DEFAULT_REGION" = <your AWS region>, # "AWS_S3_ENDPOINT" = "s3.amazonaws.com", # "AWS_REQUEST_PAYER" = "requester" # )

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 "B02", "B03", "B04", "B05", "B06", "BO7", B08", "B8A", "B11", and "B12". All 12 bands are available at 60m resolution. For creating data cubes from Sentinel-2/2A, users also have to specify the 's2_resolution' parameter.

For DEA, sits currently only works with collections 'ga_s2_gm' and 's2_l2a'. DEA users also need to provide their AWS credentials.

BDC users need to provide their credentials using environmental variables.To create your credentials, please see "https://brazildatacube.dpi.inpe.br/portal/explore" # Sys.setenv( # "BDC_ACCESS_KEY" = <your_bdc_access_key> # )

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).

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
Sys.setenv(
    "BDC_ACCESS_KEY" = <your_bdc_access_key>
)

# create a raster cube file based on the information in the BDC
cbers_tile <- sits_cube(
    source = "BDC",
    collection = "CB4_64_16D_STK-1",
    name = "cbers_022024",
    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
Sys.setenv(
    "BDC_ACCESS_KEY" = <your_bdc_access_key>
)

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

# --- Access to Digital Earth Africa
# Provide your AWS credentials as environment variables
Sys.setenv(
    "AWS_ACCESS_KEY_ID" = <your_aws_access_key>,
    "AWS_SECRET_ACCESS_KEY" = <your_aws_secret_access_key>
)

# create a raster cube file based on the information about the files
cube_dea <- sits_cube(source = "DEAFRICA",
                      name = "deafrica_cube",
                      collection = "s2_l2a",
                      bands = c("B04", "B08"),
                      bbox = c("xmin" = 17.379,
                              "ymin" = 1.1573,
                              "xmax" = 17.410,
                               "ymax" = 1.1910),
                      start_date = "2019-01-01",
                      end_date = "2019-10-28")

# --- Access to Sentinel 2/2A level 2 data in AWS
# Provide your AWS credentials as environment variables
Sys.setenv(
    "AWS_ACCESS_KEY_ID" = <your_aws_access_key>,
    "AWS_SECRET_ACCESS_KEY" = <your_aws_secret_access_key>
)

s2_cube <- sits_cube(source = "AWS",
                      name = "T20LKP_2018_2019",
                      collection = "sentinel-s2-l2a",
                      tiles = c("20LKP","20LLP"),
                      start_date = as.Date("2018-07-18"),
                      end_date = as.Date("2018-07-23"),
                      s2_resolution = 20
)

# --- Create a cube based on a stack of CBERS data
data_dir <- system.file("extdata/raster/cbers", package = "sits")

cbers_cube <- sits_cube(
    source = "LOCAL",
    name = "022024",
    origin = "BDC",
    collection = "CB4_64-1",
    data_dir = data_dir,
    delim = "_",
    parse_info = c("X1", "X2", "tile", "band", "date")
)

# Create a raster cube based on files with probability information
# inform the files that make up a raster probs brick with 23 time instances
probs_file <- c(system.file(
    "extdata/raster/probs/sinop-2014_probs_2013_9_2014_8_v1.tif",
    package = "sits"
))

# inform the labels
labels <- c("Cerrado", "Fallow_Cotton", "Forest", "Pasture", "Soy_Corn",
"Soy_Cotton", "Soy_Fallow", "Soy_Millet", "Soy_Sunflower")


# create a raster cube file based on the information about the files
probs_cube <- sits_cube(
    source = "PROBS",
    name = "Sinop-crop-probs",
    satellite = "TERRA",
    sensor  = "MODIS",
    start_date = as.Date("2013-09-14"),
    end_date = as.Date("2014-08-29"),
    probs_labels = labels,
    probs_files = probs_file
)

## End(Not run)

[Package sits version 0.14.0 Index]