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 end points. 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 retrive and process data.

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

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

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

- "AWS": Amazon Web Services (AWS)

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

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 quering repositories, please use the package 'rstac'.

- spatial extent: The spatial extent of the data cube can be defined in two ways: (a) a region of interest('roi') 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 'bdc_cube'
    sits_cube(
      source = "BDC",
      ...,
      name = "bdc_cube",
      url = NULL,
      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 'local_cube'
    sits_cube(
      source = "LOCAL",
      ...,
      name = "local_cube",
      satellite,
      sensor,
      bands = NULL,
      start_date = NULL,
      end_date = NULL,
      data_dir,
      parse_info = c("X1", "X2", "tile", "band", "date"),
      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 "SATVEG", "LOCAL", "BDC", "AWS", "DEAFRICA", "PROBS").
`...` | 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)
`satellite` | Satellite that produced the images. (only for creating data cubes from local files)
`sensor` | Sensor that produced the images.
`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)
`probs_labels` | Labels associated to a probabilities cube
`probs_files` | File names (used for creating a cube from probabilities)

### Details

The "bbox" parameters 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. # 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 date and band information, since times and bands are deduced from filenames. 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"
    )

    # --- 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"),
                          roi = 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",
        satellite = "CBERS-4",
        sensor = "AWFI",
        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.12.0 Index]