sits (version 1.5.2)

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: Amazon Web Services (AWS), Brazil Data Cube (BDC), Copernicus Data Space Ecosystem (CDSE), Digital Earth Africa (DEAFRICA), Digital Earth Australia (DEAUSTRALIA), Microsoft Planetary Computer (MPC), Nasa Harmonized Landsat/Sentinel (HLS), Swiss Data Cube (SDC), TERRASCOPE or USGS Landsat (USGS). Data cubes can also be created using local files.

Usage

sits_cube(source, collection, ...)
# S3 method for sar_cube
sits_cube(
  source,
  collection,
  ...,
  orbit = "ascending",
  bands = NULL,
  tiles = NULL,
  roi = NULL,
  crs = NULL,
  start_date = NULL,
  end_date = NULL,
  platform = NULL,
  multicores = 2,
  progress = TRUE
)
# S3 method for stac_cube
sits_cube(
  source,
  collection,
  ...,
  bands = NULL,
  tiles = NULL,
  roi = NULL,
  crs = NULL,
  start_date = NULL,
  end_date = NULL,
  platform = NULL,
  multicores = 2,
  progress = TRUE
)
# S3 method for local_cube
sits_cube(
  source,
  collection,
  ...,
  data_dir,
  vector_dir = NULL,
  tiles = NULL,
  bands = NULL,
  vector_band = NULL,
  start_date = NULL,
  end_date = NULL,
  labels = NULL,
  parse_info = NULL,
  version = "v1",
  delim = "_",
  multicores = 2L,
  progress = TRUE
)

Value

A tibble describing the contents of a data cube.

Arguments

source

Data source (one of "AWS", "BDC", "DEAFRICA", "MPC", "SDC", "USGS" - character vector of length 1).

collection

Image collection in data source (character vector of length 1). To find out the supported collections, use sits_list_collections()).

...

Other parameters to be passed for specific types.

orbit

Orbit name ("ascending", "descending") for SAR cubes.

bands

Spectral bands and indices to be included in the cube (optional - character vector). Use sits_list_collections() to find out the bands available for each collection.

tiles

Tiles from the collection to be included in the cube (see details below) (character vector of length 1).

roi

Region of interest (either an sf object, shapefile, SpatExtent, or a numeric vector with named XY values ("xmin", "xmax", "ymin", "ymax") or named lat/long values ("lon_min", "lat_min", "lon_max", "lat_max").

crs

The Coordinate Reference System (CRS) of the roi. It must be specified when roi is named XY values ("xmin", "xmax", "ymin", "ymax") or SpatExtent

start_date, end_date

Initial and final dates to include images from the collection in the cube (optional). (Date in YYYY-MM-DD format).

platform

Optional parameter specifying the platform in case of collections that include more than one satellite (character vector of length 1).

multicores

Number of workers for parallel processing (integer, min = 1, max = 2048).

progress

Logical: show a progress bar?

data_dir

Local directory where images are stored (for local cubes - character vector of length 1).

vector_dir

Local director where vector files are stored (for local vector cubes - character vector of length 1).

vector_band

Band for vector cube ("segments", "probs", "class")

labels

Labels associated to the classes (Named character vector for cubes of classes "probs_cube" or "class_cube").

parse_info

Parsing information for local files (for local cubes - character vector).

version

Version of the classified and/or labelled files. (for local cubes - character vector of length 1).

delim

Delimiter for parsing local files (single character)

Examples

if (sits_run_examples()) {
    # --- Access to the Brazil Data Cube
    # create a raster cube file based on the information in the BDC
    cbers_tile <- sits_cube(
        source = "BDC",
        collection = "CBERS-WFI-16D",
        bands = c("NDVI", "EVI"),
        tiles = "007004",
        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_deafrica <- sits_cube(
        source = "DEAFRICA",
        collection = "SENTINEL-2-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 Digital Earth Australia
    cube_deaustralia <- sits_cube(
        source = "DEAUSTRALIA",
        collection = "GA_LS8CLS9C_GM_CYEAR_3",
        bands = c("RED", "GREEN", "BLUE"),
        roi = c(
            lon_min = 137.15991,
            lon_max = 138.18467,
            lat_min = -33.85777,
            lat_max = -32.56690
        ),
        start_date = "2018-01-01",
        end_date = "2018-12-31"
    )
    # --- Access to CDSE open data Sentinel 2/2A level 2 collection
    # --- remember to set the appropriate environmental variables
    # It is recommended that `multicores` be used to accelerate the process.
    s2_cube <- sits_cube(
        source = "CDSE",
        collection = "SENTINEL-2-L2A",
        tiles = c("20LKP"),
        bands = c("B04", "B08", "B11"),
        start_date = "2018-07-18",
        end_date = "2019-01-23"
    )

    ## --- Sentinel-1 SAR from CDSE
    # --- remember to set the appropriate environmental variables
    roi_sar <- c("lon_min" = 33.546, "lon_max" = 34.999,
                 "lat_min" = 1.427, "lat_max" = 3.726)
    s1_cube_open <- sits_cube(
       source = "CDSE",
       collection = "SENTINEL-1-RTC",
       bands = c("VV", "VH"),
       orbit = "descending",
       roi = roi_sar,
       start_date = "2020-01-01",
       end_date = "2020-06-10"
    )

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

    # --- 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
    roi <- c("lon_min" = -50.410, "lon_max" = -50.379,
             "lat_min" = -10.1910 , "lat_max" = -10.1573)
    mpc_cube <- sits_cube(
        source = "MPC",
        collection = "LANDSAT-C2-L2",
        bands = c("BLUE", "RED", "CLOUD"),
        roi = roi,
        start_date = "2005-01-01",
        end_date = "2006-10-28"
    )

    ## Sentinel-1 SAR from MPC
    roi_sar <- c("lon_min" = -50.410, "lon_max" = -50.379,
                 "lat_min" = -10.1910, "lat_max" = -10.1573)

    s1_cube_open <- sits_cube(
       source = "MPC",
       collection = "SENTINEL-1-GRD",
       bands = c("VV", "VH"),
       orbit = "descending",
       roi = roi_sar,
       start_date = "2020-06-01",
       end_date = "2020-09-28"
    )
    # --- Access to World Cover data (2021) via Terrascope
    cube_terrascope <- sits_cube(
        source = "TERRASCOPE",
        collection = "WORLD-COVER-2021",
        roi = c(
            lon_min = -62.7,
            lon_max = -62.5,
            lat_min = -8.83,
            lat_max = -8.70
        )
    )
    # --- Create a cube based on a local MODIS data
    # MODIS local files have names such as
    # "TERRA_MODIS_012010_NDVI_2013-09-14.jp2"
    # see the parse info parameter as an example on how to
    # decode local files
    data_dir <- system.file("extdata/raster/mod13q1", package = "sits")
    modis_cube <- sits_cube(
        source = "BDC",
        collection = "MOD13Q1-6.1",
        data_dir = data_dir,
        parse_info = c("satellite", "sensor", "tile", "band", "date")
    )

}