R: Build a regular data cube from an irregular one

sits_regularize {sits}

R Documentation

Build a regular data cube from an irregular one

Description

Creates cubes with regular time intervals using the gdalcubes package. Cubes can be composed using "median" or "least_cc_first" functions. Users need to provide an time interval which is used by the composition function.

Usage

sits_regularize(
  cube,
  output_dir,
  period,
  res,
  roi = NULL,
  agg_method = "least_cc_first",
  resampling = "bilinear",
  multicores = 1,
  multithreads = 2,
  progress = TRUE,
  cloud_mask = FALSE
)

Arguments

`cube`	A `sits_cube` object whose spacing of observation times is not constant and will be regularized by the `gdalcubes` package.
`output_dir`	A `character` with a valid directory where the regularized images will be written by `gdalcubes`.
`period`	A `character` with ISO8601 time period for regular data cubes produced by `gdalcubes`, with number and unit, e.g., "P16D" for 16 days. Use "D", "M" and "Y" for days, month and year.
`res`	A `numeric` with spatial resolution of the image that will be aggregated.
`roi`	A named `numeric` vector with a region of interest. See more above
`agg_method`	A `character` with method that will be applied by `gdalcubes` for aggregation. Options: `median` and `least_cc_first`. The default aggregation method is `least_cc_first`. See more above.
`resampling`	A `character` with method to be used by `gdalcubes` for resampling in mosaic operation. Options: `near`, `bilinear`, `bicubic` or others supported by gdalwarp (see https://gdal.org/programs/gdalwarp.html). Default is bilinear.
`multicores`	A `numeric` with the number of cores used for regularization. This parameter specifies how many bands from different tiles should be processed in parallel. By default, 1 core is used.
`multithreads`	A `numeric` value that specifies the number of threads used in the gdalcubes package. This parameter determines how many chunks are executed in parallel. The gdalcubes package divides data cubes into smaller chunks, where the generated chunk creates a 3-dimensional array of band, latitude, and longitude information. By default 2 threads are used.
`progress`	A `logical` value. Show progress bar?
`cloud_mask`	A `logical` to use cloud band for aggregation by `gdalcubes`. Deprecated as of SITS version 0.16.0. Default is `FALSE`.

Value

A sits_cube object with aggregated images.

Note

If malformed images with the same required tiles and bands are found in the current directory, these images are deleted and recreated.

The "roi" parameter defines a region of interest. It can be an sf_object, a shapefile, or a bounding box vector with named XY values ("xmin", "xmax", "ymin", "ymax") or named lat/long values ("lat_min", "lat_max", "long_min", "long_max")

The "least_cc_first" aggregation method sorts the images based on cloud cover, where images with the fewest clouds at the top of the stack. Once the stack of images is sorted, the method uses the first valid value to create the temporal aggregation.

If the supplied data cube contains cloud band, the values indicated as clouds or cloud shadow will be removed.

References

APPEL, Marius; PEBESMA, Edzer. On-demand processing of data cubes from satellite image collections with the gdalcubes library. Data, v. 4, n. 3, p. 92, 2019. DOI: 10.3390/data4030092.

Examples

{
## Not run: 

# --- Access to the AWS STAC

# define an AWS data cube
  s2_cube <- sits_cube(source = "AWS",
                      collection = "sentinel-s2-l2a-cogs",
                      bands = c("B08", "SCL"),
                      tiles = c("20LKP"),
                      start_date = as.Date("2018-07-18"),
                      end_date = as.Date("2018-08-18")
  )

# create a directory to store the resulting images
dir.create(paste0(tempdir(),"/images/"))

# Build a data cube of equal intervals using the "gdalcubes" package
gc_cube <- sits_regularize(cube       = s2_cube,
                           output_dir = paste0(tempdir(),"/images/"),
                           period     = "P1M",
                           res        = 320)

## End(Not run)
}

[Package sits version 0.16.2 Index]