read raster/array dataset from file or connection

read_stars(
  .x,
  ...,
  options = character(0),
  driver = character(0),
  sub = TRUE,
  quiet = FALSE,
  NA_value = NA_real_,
  along = NA_integer_,
  RasterIO = list(),
  proxy = FALSE,
  curvilinear = character(0),
  normalize_path = TRUE
)

Arguments

.x

character vector with name(s) of file(s) or data source(s) to be read

...

passed on to st_as_stars if curvilinear was set

options

character; opening options

driver

character; driver to use for opening file. To override fixing for subdatasets and autodetect them as well, use NULL.

sub

character, integer or logical; name, index or indicator of sub-dataset(s) to be read

quiet

logical; print progress output?

NA_value

numeric value to be used for conversion into NA values; by default this is read from the input file

along

length-one character or integer, or list; determines how several arrays are combined, see Details.

RasterIO

list with named parameters for GDAL's RasterIO, to further control the extent, resolution and bands to be read from the data source; see details.

proxy

logical; if TRUE, an object of class stars_proxy is read which contains array metadata only; if FALSE the full array data is read in memory.

curvilinear

length two character vector with names of subdatasets holding longitude and latitude values for all raster cells.

normalize_path

logical; if FALSE, suppress a call to normalizePath on .x

Value

object of class stars

Details

In case .x contains multiple files, they will all be read and combined with c.stars. Along which dimension, or how should objects be merged? If along is set to NA it will merge arrays as new attributes if all objects have identical dimensions, or else try to merge along time if a dimension called time indicates different time stamps. A single name (or positive value) for along will merge along that dimension, or create a new one if it does not already exist. If the arrays should be arranged along one of more dimensions with values (e.g. time stamps), a named list can passed to along to specify them; see example.

RasterIO is a list with zero or more of the following named arguments: nXOff, nYOff (both 1-based: the first row/col has offset value 1), nXSize, nYSize, nBufXSize, nBufYSize, bands, coderesample. see https://www.gdal.org/classGDALDataset.html#a80d005ed10aefafa8a55dc539c2f69da for their meaning; bands is an integer vector containing the band numbers to be read (1-based: first band is 1) Note that if nBufXSize or nBufYSize are specified for downsampling an image, resulting in an adjusted geotransform. resample reflects the resampling method and has to be one of: "nearest_neighbour" (the default), "bilinear", "cubic", "cubic_spline", "lanczos", "average", "mode", or "Gauss".

Examples

tif = system.file("tif/L7_ETMs.tif", package = "stars") (x1 = read_stars(tif))
#> stars object with 3 dimensions and 1 attribute #> attribute(s): #> L7_ETMs.tif #> Min. : 1.00 #> 1st Qu.: 54.00 #> Median : 69.00 #> Mean : 68.91 #> 3rd Qu.: 86.00 #> Max. :255.00 #> dimension(s): #> from to offset delta refsys point values #> x 1 349 288776 28.5 +proj=utm +zone=25 +south... FALSE NULL [x] #> y 1 352 9120761 -28.5 +proj=utm +zone=25 +south... FALSE NULL [y] #> band 1 6 NA NA NA NA NULL
(x2 = read_stars(c(tif, tif)))
#> stars object with 3 dimensions and 2 attributes #> attribute(s): #> L7_ETMs.tif L7_ETMs.tif.1 #> Min. : 1.00 Min. : 1.00 #> 1st Qu.: 54.00 1st Qu.: 54.00 #> Median : 69.00 Median : 69.00 #> Mean : 68.91 Mean : 68.91 #> 3rd Qu.: 86.00 3rd Qu.: 86.00 #> Max. :255.00 Max. :255.00 #> dimension(s): #> from to offset delta refsys point values #> x 1 349 288776 28.5 +proj=utm +zone=25 +south... FALSE NULL [x] #> y 1 352 9120761 -28.5 +proj=utm +zone=25 +south... FALSE NULL [y] #> band 1 6 NA NA NA NA NULL
(x3 = read_stars(c(tif, tif), along = "band"))
#> stars object with 3 dimensions and 1 attribute #> attribute(s), summary of first 1e+05 cells: #> L7_ETMs.tif #> Min. : 47.00 #> 1st Qu.: 65.00 #> Median : 76.00 #> Mean : 77.34 #> 3rd Qu.: 87.00 #> Max. :255.00 #> dimension(s): #> from to offset delta refsys point values #> x 1 349 288776 28.5 +proj=utm +zone=25 +south... FALSE NULL [x] #> y 1 352 9120761 -28.5 +proj=utm +zone=25 +south... FALSE NULL [y] #> band 1 12 NA NA NA NA NULL
(x4 = read_stars(c(tif, tif), along = "new_dimensions")) # create 4-dimensional array
#> stars object with 4 dimensions and 1 attribute #> attribute(s), summary of first 1e+05 cells: #> L7_ETMs.tif #> Min. : 47.00 #> 1st Qu.: 65.00 #> Median : 76.00 #> Mean : 77.34 #> 3rd Qu.: 87.00 #> Max. :255.00 #> dimension(s): #> from to offset delta refsys point values #> x 1 349 288776 28.5 +proj=utm +zone=25 +south... FALSE NULL #> y 1 352 9120761 -28.5 +proj=utm +zone=25 +south... FALSE NULL #> band 1 6 NA NA NA NA NULL #> new_dimensions 1 2 NA NA NA NA NULL #> #> x [x] #> y [y] #> band #> new_dimensions
x1o = read_stars(tif, options = "OVERVIEW_LEVEL=1") t1 = as.Date("2018-07-31") # along is a named list indicating two dimensions: read_stars(c(tif, tif, tif, tif), along = list(foo = c("bar1", "bar2"), time = c(t1, t1+2)))
#> stars object with 5 dimensions and 1 attribute #> attribute(s), summary of first 1e+05 cells: #> L7_ETMs.tif #> Min. : 47.00 #> 1st Qu.: 65.00 #> Median : 76.00 #> Mean : 77.34 #> 3rd Qu.: 87.00 #> Max. :255.00 #> dimension(s): #> from to offset delta refsys point values #> x 1 349 288776 28.5 +proj=utm +zone=25 +south... FALSE NULL #> y 1 352 9120761 -28.5 +proj=utm +zone=25 +south... FALSE NULL #> band 1 6 NA NA NA NA NULL #> foo 1 2 NA NA NA NA bar1, bar2 #> time 1 2 2018-07-31 2 days Date NA NULL #> #> x [x] #> y [y] #> band #> foo #> time
m = matrix(1:120, nrow = 12, ncol = 10) dim(m) = c(x = 10, y = 12) # named dim st = st_as_stars(m) attr(st, "dimensions")$y$delta = -1 attr(st, "dimensions")$y$offset = 12 st
#> stars object with 2 dimensions and 1 attribute #> attribute(s): #> A1 #> Min. : 1.00 #> 1st Qu.: 30.75 #> Median : 60.50 #> Mean : 60.50 #> 3rd Qu.: 90.25 #> Max. :120.00 #> dimension(s): #> from to offset delta refsys point values #> x 1 10 0 1 NA FALSE NULL [x] #> y 1 12 12 -1 NA FALSE NULL [y]
tmp = tempfile(fileext = ".tif") write_stars(st, tmp) (red <- read_stars(tmp))
#> stars object with 2 dimensions and 1 attribute #> attribute(s): #> file23e47edd1681.tif #> Min. : 1.00 #> 1st Qu.: 30.75 #> Median : 60.50 #> Mean : 60.50 #> 3rd Qu.: 90.25 #> Max. :120.00 #> dimension(s): #> from to offset delta refsys point values #> x 1 10 0 1 NA NA NULL [x] #> y 1 12 12 -1 NA NA NULL [y]
read_stars(tmp, RasterIO = list(nXOff = 1, nYOff = 1, nXsize = 10, nYSize = 12, nBufXSize = 2, nBufYSize = 2))[[1]]
#> [,1] [,2] #> [1,] 33 93 #> [2,] 38 98
(red <- read_stars(tmp, RasterIO = list(nXOff = 1, nYOff = 1, nXsize = 10, nYSize = 12, nBufXSize = 2, nBufYSize = 2)))
#> stars object with 2 dimensions and 1 attribute #> attribute(s): #> file23e47edd1681.tif #> Min. :33.00 #> 1st Qu.:36.75 #> Median :65.50 #> Mean :65.50 #> 3rd Qu.:94.25 #> Max. :98.00 #> dimension(s): #> from to offset delta refsys point values #> x 1 2 0 5 NA NA NULL [x] #> y 1 2 12 -6 NA NA NULL [y]
red[[1]] # cell values of subsample grid:
#> [,1] [,2] #> [1,] 33 93 #> [2,] 38 98
plot(st, reset = FALSE, axes = TRUE, ylim = c(-.1,12.1), xlim = c(-.1,10.1), main = "nBufXSize & nBufYSize demo", text_values = TRUE)
plot(st_as_sfc(red, as_points = TRUE), add = TRUE, col = 'red', pch = 16)
plot(st_as_sfc(st_as_stars(st), as_points = FALSE), add = TRUE, border = 'grey')
plot(st_as_sfc(red, as_points = FALSE), add = TRUE, border = 'green', lwd = 2)
#> [1] TRUE