st_as_stars: convert objects into a stars object

In stars: Spatiotemporal Arrays, Raster and Vector Data Cubes

convert objects into a stars object

Description

convert objects into a stars object

Usage

## S3 method for class 'cubble_df'
st_as_stars(.x, ..., check_times = FALSE)

## S3 method for class 'ncdfgeom'
st_as_stars(.x, ..., sf_geometry = NA)

## S3 method for class 'OpenStreetMap'
st_as_stars(.x, ..., as_col = FALSE)

## S3 method for class 'stars_proxy'
st_as_stars(
  .x,
  ...,
  downsample = 0,
  url = attr(.x, "url"),
  envir = parent.frame()
)

## S3 method for class 'data.frame'
st_as_stars(.x, ..., dims = coords, xy, y_decreasing = TRUE, coords = 1:2)

## S3 method for class 'Raster'
st_as_stars(.x, ..., att = 1, ignore_file = FALSE)

## S3 method for class 'SpatRaster'
st_as_stars(
  .x,
  ...,
  ignore_file = FALSE,
  as_attributes = all(terra::is.factor(.x))
)

## S3 method for class 'sf'
st_as_stars(.x, ..., dims = attr(.x, "sf_column"))

st_as_stars(.x, ...)

## S3 method for class 'list'
st_as_stars(.x, ..., dimensions = NULL)

## Default S3 method:
st_as_stars(.x = NULL, ..., raster = NULL)

## S3 method for class 'stars'
st_as_stars(.x, ..., curvilinear = NULL, crs = st_crs("OGC:CRS84"))

## S3 method for class 'bbox'
st_as_stars(
  .x,
  ...,
  nx,
  ny,
  dx = dy,
  dy = dx,
  xlim = .x[c("xmin", "xmax")],
  ylim = .x[c("ymin", "ymax")],
  values = 0,
  n = 64800,
  pretty = FALSE,
  inside = FALSE,
  nz,
  proxy = FALSE
)

## S3 method for class 'xts'
st_as_stars(.x, ..., dimensions, name = "attr")

Arguments

.x	object to convert
...	in case .x is of class bbox, arguments passed on to pretty. In case .x is of class nc_proxy, arguments passed on to read_ncdf.
check_times	logical; should we check that the time stamps of all time series are identical?
sf_geometry	sf data.frame with geometry and attributes to be added to stars object. Must have same number of rows as timeseries instances.
as_col	logical; return rgb numbers (FALSE) or (character) color values (TRUE)?
downsample	integer: if larger than 0, downsample with this rate (number of pixels to skip in every row/column); if length 2, specifies downsampling rate in x and y.
url	character; URL of the stars endpoint where the data reside
envir	environment to resolve objects in
dims	the column names or indices that form the cube dimensions
xy	the x and y raster dimension names or indices; only takes effect after dims has been specified, see details
y_decreasing	logical; if TRUE, (numeric) y values get a negative delta (decrease with increasing index)
coords	same as dims, for symmetry with st_as_sf
att	see factorValues; column in the RasterLayer's attribute table
ignore_file	logical; if TRUE, ignore the SpatRaster object file name
as_attributes	logical; if TRUE and .x has more than one layer, load these as separate attributes rather than as a band or time dimension (only implemented for the case where ignore_file is TRUE)
dimensions	object of class dimensions
raster	character; the names of the dimensions that denote raster dimensions
curvilinear	only for creating curvilinear grids: named length 2 list holding longitude and latitude matrices or stars arrays, or the names of the corresponding attributes in .x; the names of this vector should correspond to raster dimensions the matrices are associated with; see Details.
crs	object of class crs with the coordinate reference system of the values in curvilinear; see details
nx	integer; number of cells in x direction; see details
ny	integer; number of cells in y direction; see details
dx	numeric or object of class units; cell size in x direction; see details
dy	numeric or object of class units; cell size in y direction; see details
xlim	length 2 numeric vector with extent (min, max) in x direction
ylim	length 2 numeric vector with extent (min, max) in y direction
values	value(s) to populate the raster values with
n	the (approximate) target number of grid cells
pretty	logical; should cell coordinates have pretty values?
inside	logical; should all cells entirely fall inside the bbox, potentially not covering it completely (TRUE), or always cover the bbox (FALSE), or find a good approximation (NA, default)?
nz	integer; number of cells in z direction; if missing no z-dimension is created.
proxy	logical; should a stars_proxy object be created? (requires gdal_create binary when sf < 1.0-6)
name	character; attribute name for array from an xts object

Details

For the ncdfgeom method: objects are point-timeseries with optional line or polygon geometry for each timeseries specified with the sf_geometry parameter. See ncdfgeom for more about this NetCDF-based format for geometry and timeseries.

If xy is not specified and the first two dimensions in dims are both numeric, then it is set to these two dimensions.

The st_as_stars method for sf objects without any additional arguments returns a one-dimensional data cube with a dimension for the simple features geometries, and all remaining attributes as data cube attributes. When used with further arguments, the method for data.frames is called.

if curvilinear is a list with stars objects with longitude and latitude values, its coordinate reference system is typically not that of the latitude and longitude values. If curvilinear contains the names of two arrays in .x, then these are removed from the returned object.

For the bbox method: if pretty is TRUE, raster cells may extend the coordinate range of .x on all sides. If in addition to nx and ny, dx and dy are also missing, these are set to a single value computed as sqrt(diff(xlim)*diff(ylim)/n).

If nx and ny are missing and values is a matrix, the number of columns and rows of the matrix are taken.

Otherwise, if nx and ny are missing, they are computed as the (ceiling, floor, or rounded to integer value) of the ratio of the (x or y) range divided by (dx or dy), depending on the value of inside. Positive dy will be made negative. Further named arguments (...) are passed on to pretty. If dx or dy are units objects, their value is converted to the units of st_crs(.x) (only when sf >= 1.0-7).

for the xts methods, if dimensions are provided, time has to be the first dimension.

Examples

if (require(plm, quietly = TRUE)) {
 data(Produc, package = "plm")
 st_as_stars(Produc)
}
if (require(dplyr, quietly = TRUE)) {
  # https://stackoverflow.com/questions/77368957/
spatial_dim <- st_sf(
  ID = 1:3,
  geometry = list(
    st_polygon(list(
      cbind(c(0, 1, 1, 0, 0), c(0, 0, 1, 1, 0))
    )),
    st_polygon(list(
      cbind(c(1, 2, 2, 1, 1), c(0, 0, 1, 1, 0))
    )),
    st_polygon(list(
      cbind(c(2, 3, 3, 2, 2), c(0, 0, 1, 1, 0))
    ))
  )
)
weekdays_dim <- data.frame(weekdays = c("Monday", "Tuesday", "Wednesday", 
    "Thursday", "Friday", "Saturday", "Sunday"))
hours_dim <- data.frame(hours = c("8am", "11am", "4pm", "11pm"))
sf_dta <- spatial_dim |>
  cross_join(weekdays_dim)|>
  cross_join(hours_dim) |>
  mutate(population = rnorm(n(), mean = 1000, sd = 200)) |>
  select(everything(), geometry)

st_as_stars(sf_dta, dims = c("weekdays", "hours", "geometry"))
}
demo(nc, echo=FALSE,ask=FALSE)
st_as_stars(nc)
st_as_stars(st_drop_geometry(nc), dims = "NAME")
data.frame(expand.grid(x=1:5, y = 1:5), z = rnorm(25)) |> st_as_stars()
nc = st_read(system.file("gpkg/nc.gpkg", package="sf"))
st_as_stars(nc)

stars documentation built on May 29, 2024, 8:59 a.m.