This vignette shows how some of the tidyverse verbs can be used on stars objects.
The stars and tidyverse packages are loaded by
library(stars) ## Loading required package: abind ## Loading required package: sf ## Linking to GEOS 3.5.0, GDAL 2.2.2, PROJ 4.8.0 library(dplyr) ## ## Attaching package: 'dplyr' ## The following objects are masked from 'package:stats': ## ## filter, lag ## The following objects are masked from 'package:base': ## ## intersect, setdiff, setequal, union
Methods now available for class stars are
methods(class = "stars") ## [1] [ [<- $<- adrop ## [5] aggregate aperm as_tibble as.data.frame ## [9] as.tbl_cube c coerce contour ## [13] cut dim dimnames dimnames<- ## [17] droplevels filter image initialize ## [21] is.na Math merge mutate ## [25] Ops plot predict print ## [29] pull select show slice ## [33] slotsFromS3 split st_apply st_area ## [37] st_as_sf st_as_sfc st_as_stars st_bbox ## [41] st_coordinates st_crop st_crs st_crs<- ## [45] st_dimensions st_extract st_geometry st_interpolate_aw ## [49] st_intersects st_join st_mosaic st_normalize ## [53] st_redimension st_sample st_transform_proj st_transform ## [57] write_stars ## see '?methods' for accessing help and source code
We will work with a three-band section of a landsat image:
system.file("tif/L7_ETMs.tif", package = "stars") %>% read_stars -> x x ## 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 PROJCS["UTM Zone 25, Sout... FALSE NULL [x] ## y 1 352 9120761 -28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [y] ## band 1 6 NA NA NA NA NULL
slice
slice slices a sub-array out of the cube; this is done by specifying the dimension on which to act, and the slice number.
x %>% slice(band, 6) -> x6 x6 ## stars object with 2 dimensions and 1 attribute ## attribute(s): ## L7_ETMs.tif ## Min. : 1.00 ## 1st Qu.: 32.00 ## Median : 60.00 ## Mean : 59.98 ## 3rd Qu.: 88.00 ## Max. :255.00 ## dimension(s): ## from to offset delta refsys point values ## x 1 349 288776 28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [x] ## y 1 352 9120761 -28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [y]
It returns a lower-dimensional array if a single element is selected along the slice dimension.
filter
Similar to slice, filter selects on dimensions but evaluates their values rather than their index: in
x %>% filter(x > 289000, x < 291000, band > 3) -> x7 ## Registered S3 methods overwritten by 'cubelyr': ## method from ## as.data.frame.tbl_cube dplyr ## as.table.tbl_cube dplyr ## as_tibble.tbl_cube dplyr ## auto_copy.tbl_cube dplyr ## dim.tbl_cube dplyr ## group_by.tbl_cube dplyr ## group_vars.tbl_cube dplyr ## groups.tbl_cube dplyr ## print.tbl_cube dplyr ## rename.tbl_cube dplyr ## same_src.tbl_cube dplyr ## select.tbl_cube dplyr ## summarise.tbl_cube dplyr ## tbl_vars.tbl_cube dplyr x7 ## stars object with 3 dimensions and 1 attribute ## attribute(s): ## L7_ETMs.tif ## Min. : 5.00 ## 1st Qu.: 54.00 ## Median : 70.00 ## Mean : 71.79 ## 3rd Qu.: 88.00 ## Max. :252.00 ## dimension(s): ## from to offset delta refsys point values ## x 1 70 289004 28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [x] ## y 1 352 9120761 -28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [y] ## band 1 3 4 1 NA NA NULL
the subarray is created based on the x coordinate values.
Note that filter converts the object to a tbl_cube, and uses the dplyr filter method for tbl_cube objects. This has the limitation that stars objects with rectilinear, curvilinear or simple feature geometries cannot be handled. For such objects, using regular [ selection or using st_crop may be an alternative.
mutate
x %>% mutate(band2 = 2 * L7_ETMs.tif) -> x2 x2 ## stars object with 3 dimensions and 2 attributes ## attribute(s): ## L7_ETMs.tif band2 ## Min. : 1.00 Min. : 2.0 ## 1st Qu.: 54.00 1st Qu.:108.0 ## Median : 69.00 Median :138.0 ## Mean : 68.91 Mean :137.8 ## 3rd Qu.: 86.00 3rd Qu.:172.0 ## Max. :255.00 Max. :510.0 ## dimension(s): ## from to offset delta refsys point values ## x 1 349 288776 28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [x] ## y 1 352 9120761 -28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [y] ## band 1 6 NA NA NA NA NULL
select
select selects an attribute, or a set of attributes:
x2 %>% select(band2) -> x9 x9 ## stars object with 3 dimensions and 1 attribute ## attribute(s): ## band2 ## Min. : 2.0 ## 1st Qu.:108.0 ## Median :138.0 ## Mean :137.8 ## 3rd Qu.:172.0 ## Max. :510.0 ## dimension(s): ## from to offset delta refsys point values ## x 1 349 288776 28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [x] ## y 1 352 9120761 -28.5 PROJCS["UTM Zone 25, Sout... FALSE NULL [y] ## band 1 6 NA NA NA NA NULL
geom_stars
geom_raster is a ggplot2 geom function that accepts stars objects as its data argument and
- sets up the raster or vector spatial coordinates as plot dimensions, and the first attribute as the fill variable
- allows for downsampling (without choosing a suitable downsampling level)
- chooses between using
geom_raster,geom_rectandgeom_sfdepending on whether the geometry is regular, rectilinear or has vector geometries
An example use is
library(ggplot2) library(viridis) ## Loading required package: viridisLite ggplot() + geom_stars(data = x) + coord_equal() + facet_wrap(~band) + theme_void() + scale_fill_viridis() + scale_x_discrete(expand = c(0, 0)) + scale_y_discrete(expand = c(0, 0))
