sits (version 1.1.0)

sits_cube: Create data cubes from image collections

Description

Creates a data cube based on spatial and temporal restrictions in collections available in cloud services or local repositories. The following cloud providers are supported, based on the STAC protocol:

• "AWS": Amazon Web Services (AWS), see https://registry.opendata.aws/

• "BDC": Brazil Data Cube (BDC), see http://brazildatacube.org/

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

• "MPC": Microsoft Planetary Computer, see https://planetarycomputer.microsoft.com/

• "USGS":USGS LANDSAT collection, see https://registry.opendata.aws/usgs-landsat/

Data cubes can also be created using local files (see details).

Usage

sits_cube(source, collection, ..., data_dir = NULL)
# S3 method for stac_cube
sits_cube(
  source,
  collection,
  ...,
  data_dir = NULL,
  bands = NULL,
  tiles = NULL,
  roi = NULL,
  start_date = NULL,
  end_date = NULL,
  platform = NULL
)
# S3 method for local_cube
sits_cube(
  source,
  collection,
  data_dir,
  ...,
  bands = NULL,
  start_date = NULL,
  end_date = NULL,
  labels = NULL,
  parse_info = NULL,
  delim = "_",
  multicores = 2,
  progress = TRUE
)

Value

A tibble describing the contents of a data cube.

Arguments

source

Data source (one of "AWS", "BDC", "DEAFRICA", "MPC", "USGS").

collection

Image collection in data source (To find out the supported collections, use sits_list_collections()).

...

Other parameters to be passed for specific types.

data_dir

Local directory where images are stored (for local cubes).

bands

Spectral bands and indices to be included in the cube (optional).

tiles

Tiles from the collection to be included in the cube (see details below).

roi

Filter collection by region of interest (see details below).

start_date, end_date

Initial and final dates to include images from the collection in the cube (optional).

platform

Optional parameter specifying the platform in case of collections that include more than one satellite.

labels

Labels associated to the classes (only for result cubes).

parse_info

Parsing information for local files.

delim

Delimiter for parsing local files.

multicores

Number of workers for parallel processing

progress

Show a progress bar?

Details

To create cubes from cloud providers, users need to inform:

• source: One of "AWS", "BDC", "DEAFRICA", "MPC", "USGS".

• collection: Use sits_list_collections() to see which collections are supported.

• tiles: A set of tiles defined according to the collection tiling grid.

• roi: Region of interest in WGS84 coordinates.

Either tiles or roi must be informed. The parameters bands, start_date, and end_date are optional for cubes created from cloud providers.

The roi parameter allows a selection of an area of interest, either using a named vector ("lon_min", "lat_min", "lon_max", "lat_max") in WGS84, 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; it only selects images that intersect the roi.

To create a cube from local files, users need to inform:

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

• collection:Collection where the data has been extracted from.

• data_dir: Local directory where images are stored.

• parse_info: Parsing information for files (see below).

• delim: Delimiter character for parsing files (see below).

To create a cube from local files, all images should have the same spatial resolution and projection and each file should contain a single image band for a single date. Files can belong to different tiles of a spatial reference system and file names need to 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 values of tile, band, and date. In the examples above, the parsing info is c("X1", "tile", "band", "date") and the delimiter is "_".

It is also possible to create result cubes; these are local cubes that have been produced by classification or post-classification algorithms. In this case, there are more parameters that are required (see below) and the parameter parse_info is specified differently:

• band: The band name is associated to the type of result. Use "probs", for probability cubes produced by sits_classify(); "bayes", or "bilat" (bilateral) according to the function selected when using sits_smooth(); "entropy" when using sits_uncertainty(), or "class" for cubes produced by sits_label_classification().

• labels: Labels associated to the classification results.

• parse_info: File name parsing information has to allow sits to deduce the values of "tile", "start_date", "end_date" from the file name. Default is c("X1", "X2", "tile", "start_date", "end_date", "band"). Note that, unlike non-classified image files, cubes with results have both "start_date" and "end_date".

References

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

Examples

if (sits_run_examples()) {

    # --- 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"
    )

    # --- Access to Digital Earth Africa
    # create a raster cube file based on the information about the files
    # DEAFRICA does not support definition of tiles
    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 AWS open data Sentinel 2/2A level 2 collection
    s2_cube <- sits_cube(
        source = "AWS",
        collection = "sentinel-s2-l2a-cogs",
        tiles = c("20LKP", "20LLP"),
        bands = c("B04", "B08", "B11"),
        start_date = "2018-07-18",
        end_date = "2019-07-23"
    )

    # --- Access to USGS Landsat cubes (requester pays)
    # --- Need to provide AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
    usgs_cube <- sits_cube(
        source = "USGS",
        collection = "landsat-c2l2-sr",
        bands = c("B04", "CLOUD"),
        roi = c(
            "xmin" = -50.379,
            "ymin" = -10.1573,
            "xmax" = -50.410,
            "ymax" = -10.1910
        ),
        start_date = "2019-01-01",
        end_date = "2019-10-28"
    )


    # -- Creating Sentinel cube from MPC"
    s2_cube <- sits_cube(
        source = "MPC",
        collection = "sentinel-2-l2a",
        tiles = "20LKP",
        bands = c("B05", "CLOUD"),
        start_date = "2018-07-18",
        end_date = "2018-08-23"
    )

    # -- Creating Landsat cube from MPC"
    mpc_cube <- sits_cube(
        source = "MPC",
        collection = "LANDSAT-C2-L2",
        bands = c("BLUE", "RED", "CLOUD"),
        roi = c(
            "xmin" = -50.379,
            "ymin" = -10.1573,
            "xmax" = -50.410,
            "ymax" = -10.1910
        ),
        start_date = "2005-01-01",
        end_date = "2006-10-28"
    )

    # --- 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 = "_"
    )
}