Skip to contents

Extract raster values with point buffers or polygons

Source: R/processing.R
extract_at.Rd

Extract raster values with point buffers or polygons

Usage

extract_at(x, y, ...)

# S4 method for class 'SpatRaster,sf'
extract_at(
  x = NULL,
  y = NULL,
  id = NULL,
  func = "mean",
  extent = NULL,
  radius = NULL,
  out_class = "sf",
  kernel = NULL,
  kernel_func = stats::weighted.mean,
  bandwidth = NULL,
  max_cells = 3e+07,
  .standalone = TRUE,
  ...
)

# S4 method for class 'character,character'
extract_at(
  x = NULL,
  y = NULL,
  id = NULL,
  func = "mean",
  extent = NULL,
  radius = NULL,
  out_class = "sf",
  kernel = NULL,
  kernel_func = stats::weighted.mean,
  bandwidth = NULL,
  max_cells = 3e+07,
  .standalone = TRUE,
  ...
)

# S4 method for class 'SpatRaster,character'
extract_at(
  x = NULL,
  y = NULL,
  id = NULL,
  func = "mean",
  extent = NULL,
  radius = NULL,
  out_class = "sf",
  kernel = NULL,
  kernel_func = stats::weighted.mean,
  bandwidth = NULL,
  max_cells = 3e+07,
  .standalone = TRUE,
  ...
)

# S4 method for class 'SpatRaster,SpatVector'
extract_at(
  x = NULL,
  y = NULL,
  id = NULL,
  func = "mean",
  extent = NULL,
  radius = NULL,
  out_class = "sf",
  kernel = NULL,
  kernel_func = stats::weighted.mean,
  bandwidth = NULL,
  max_cells = 3e+07,
  .standalone = TRUE,
  ...
)

# S4 method for class 'character,sf'
extract_at(
  x = NULL,
  y = NULL,
  id = NULL,
  func = "mean",
  extent = NULL,
  radius = NULL,
  out_class = "sf",
  kernel = NULL,
  kernel_func = stats::weighted.mean,
  bandwidth = NULL,
  max_cells = 3e+07,
  .standalone = TRUE,
  ...
)

# S4 method for class 'character,SpatVector'
extract_at(
  x = NULL,
  y = NULL,
  id = NULL,
  func = "mean",
  extent = NULL,
  radius = NULL,
  out_class = "sf",
  kernel = NULL,
  kernel_func = stats::weighted.mean,
  bandwidth = NULL,
  max_cells = 3e+07,
  .standalone = TRUE,
  ...
)

Arguments

x

SpatRaster object or file path(s) with extensions that are GDAL-compatible. When multiple file paths are used, the rasters must have the same extent and resolution.

y

sf/SpatVector object or file path.

...

Placeholder.

id

character(1). Unique identifier of each point.

func

function taking one numeric vector argument. Default is "mean" for all supported signatures in arguments x and y.

extent

numeric(4) or SpatExtent. Extent of clipping vector. It only works with points of character(1) file path.

radius

numeric(1). Buffer radius.

out_class

character(1). Output class. One of sf or terra.

kernel

character(1). Name of a kernel function One of "uniform", "triweight", "quartic", and "epanechnikov"

kernel_func

function. Kernel function to apply to the extracted values. Default is stats::weighted.mean()

bandwidth

numeric(1). Kernel bandwidth.

max_cells

integer(1). Maximum number of cells in memory.

.standalone

logical(1). Default is TRUE, which means that the function will be executed in a standalone mode. When using this function in par_* functions, set this to FALSE.

Value

A data.frame object with summarized raster values with respect to the mode (polygon or buffer) and the function.

Details

Inputs are preprocessed in different ways depending on the class.

  • Vector inputs in y: sf is preferred, thus character and SpatVector inputs will be converted to sf object. If radius is not NULL, sf::st_buffer is used to generate circular buffers as subsequent raster-vector overlay is done with exactextractr::exact_extract.

  • Raster input in x: SpatRaster is preferred. If the input is not SpatRaster, it will be converted to SpatRaster object.

See also

Other Macros for calculation: kernelfunction(), summarize_aw(), summarize_sedc()

Author

Insang Song geoissong@gmail.com

Examples

ncpath <- system.file("gpkg/nc.gpkg", package = "sf")
rastpath <- file.path(tempdir(), "test.tif")

nc <- terra::vect(ncpath)
nc <- terra::project(nc, "EPSG:5070")
rrast <- terra::rast(nc, nrow = 300, ncol = 660)
terra::values(rrast) <- rgamma(1.98e5, 4, 2)
rpnt <- terra::spatSample(rrast, 16L, as.points = TRUE)
rpnt$pid <- sprintf("ID-%02d", seq(1, 16))

extract_at(rrast, rpnt, "pid", "mean", radius = 1000)
#> Switch terra class to sf...
#>      pid     mean
#> 1  ID-01 2.304678
#> 2  ID-02 1.876471
#> 3  ID-03 1.812805
#> 4  ID-04 2.901904
#> 5  ID-05 2.345931
#> 6  ID-06 1.675186
#> 7  ID-07 1.885388
#> 8  ID-08 1.767254
#> 9  ID-09 1.905041
#> 10 ID-10 2.127524
#> 11 ID-11 1.915131
#> 12 ID-12 2.330560
#> 13 ID-13 3.260970
#> 14 ID-14 1.475079
#> 15 ID-15 1.883214
#> 16 ID-16 1.488772
extract_at(rrast, nc, "NAME", "mean")
#> Switch terra class to sf...
#>             NAME     mean
#> 1           Ashe 2.020456
#> 2      Alleghany 1.940603
#> 3          Surry 2.052454
#> 4      Currituck 1.970880
#> 5    Northampton 1.989684
#> 6       Hertford 1.992686
#> 7         Camden 2.009349
#> 8          Gates 2.053602
#> 9         Warren 1.980904
#> 10        Stokes 2.027218
#> 11       Caswell 2.037605
#> 12    Rockingham 2.015657
#> 13     Granville 1.982146
#> 14        Person 1.981977
#> 15         Vance 2.049742
#> 16       Halifax 1.986947
#> 17    Pasquotank 2.031331
#> 18        Wilkes 2.008740
#> 19       Watauga 1.971118
#> 20    Perquimans 2.011126
#> 21        Chowan 2.022323
#> 22         Avery 1.988661
#> 23        Yadkin 1.997267
#> 24      Franklin 1.991710
#> 25       Forsyth 1.972969
#> 26      Guilford 1.983665
#> 27      Alamance 2.042984
#> 28        Bertie 2.021307
#> 29        Orange 1.998132
#> 30        Durham 1.956006
#> 31          Nash 1.921319
#> 32      Mitchell 1.989676
#> 33     Edgecombe 2.029441
#> 34      Caldwell 2.041854
#> 35        Yancey 2.049162
#> 36        Martin 1.969348
#> 37          Wake 2.036850
#> 38       Madison 2.001096
#> 39       Iredell 2.034859
#> 40         Davie 1.895780
#> 41     Alexander 1.937515
#> 42      Davidson 1.998460
#> 43         Burke 1.947224
#> 44    Washington 2.033003
#> 45       Tyrrell 1.965489
#> 46      McDowell 1.999944
#> 47      Randolph 1.990211
#> 48       Chatham 2.001254
#> 49        Wilson 1.982204
#> 50         Rowan 2.012542
#> 51          Pitt 2.017377
#> 52       Catawba 2.022499
#> 53      Buncombe 2.034685
#> 54      Johnston 2.030662
#> 55       Haywood 2.026524
#> 56          Dare 2.010891
#> 57      Beaufort 2.027408
#> 58         Swain 2.071742
#> 59        Greene 1.963715
#> 60           Lee 2.026932
#> 61    Rutherford 1.997621
#> 62         Wayne 1.977614
#> 63       Harnett 2.001271
#> 64     Cleveland 2.030814
#> 65       Lincoln 2.012945
#> 66       Jackson 2.046988
#> 67         Moore 2.018466
#> 68   Mecklenburg 1.960130
#> 69      Cabarrus 2.058463
#> 70    Montgomery 1.963255
#> 71        Stanly 1.962456
#> 72     Henderson 1.995068
#> 73        Graham 1.979657
#> 74        Lenoir 2.015227
#> 75  Transylvania 2.033446
#> 76        Gaston 2.030488
#> 77          Polk 2.003313
#> 78         Macon 1.978571
#> 79       Sampson 1.932338
#> 80       Pamlico 2.040469
#> 81      Cherokee 2.022352
#> 82    Cumberland 1.970722
#> 83         Jones 1.953258
#> 84         Union 2.048984
#> 85         Anson 1.981594
#> 86          Hoke 1.917422
#> 87          Hyde 1.988905
#> 88        Duplin 1.959774
#> 89      Richmond 2.001290
#> 90          Clay 2.064368
#> 91        Craven 2.001500
#> 92      Scotland 1.956283
#> 93        Onslow 2.027830
#> 94       Robeson 2.012189
#> 95      Carteret 2.014055
#> 96        Bladen 1.985855
#> 97        Pender 1.991776
#> 98      Columbus 1.971150
#> 99   New Hanover 1.984182
#> 100    Brunswick 2.011332
extract_at(rrast, ncpath, "NAME", "mean")
#> ℹ Input is a character. Trying to read with sf.
#> Reading layer `nc.gpkg' from data source 
#>   `/github/home/R/x86_64-pc-linux-gnu-library/4.5/sf/gpkg/nc.gpkg' 
#>   using driver `GPKG'
#> Simple feature collection with 100 features and 14 fields
#> Geometry type: MULTIPOLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -84.32385 ymin: 33.88199 xmax: -75.45698 ymax: 36.58965
#> Geodetic CRS:  NAD27
#>             NAME     mean
#> 1           Ashe 2.020456
#> 2      Alleghany 1.940603
#> 3          Surry 2.052454
#> 4      Currituck 1.970880
#> 5    Northampton 1.989684
#> 6       Hertford 1.992686
#> 7         Camden 2.009349
#> 8          Gates 2.053602
#> 9         Warren 1.980904
#> 10        Stokes 2.027218
#> 11       Caswell 2.037605
#> 12    Rockingham 2.015657
#> 13     Granville 1.982146
#> 14        Person 1.981977
#> 15         Vance 2.049742
#> 16       Halifax 1.986947
#> 17    Pasquotank 2.031331
#> 18        Wilkes 2.008740
#> 19       Watauga 1.971118
#> 20    Perquimans 2.011126
#> 21        Chowan 2.022323
#> 22         Avery 1.988661
#> 23        Yadkin 1.997267
#> 24      Franklin 1.991710
#> 25       Forsyth 1.972969
#> 26      Guilford 1.983665
#> 27      Alamance 2.042984
#> 28        Bertie 2.021307
#> 29        Orange 1.998132
#> 30        Durham 1.956006
#> 31          Nash 1.921319
#> 32      Mitchell 1.989676
#> 33     Edgecombe 2.029441
#> 34      Caldwell 2.041854
#> 35        Yancey 2.049162
#> 36        Martin 1.969348
#> 37          Wake 2.036850
#> 38       Madison 2.001096
#> 39       Iredell 2.034859
#> 40         Davie 1.895780
#> 41     Alexander 1.937515
#> 42      Davidson 1.998460
#> 43         Burke 1.947224
#> 44    Washington 2.033003
#> 45       Tyrrell 1.965489
#> 46      McDowell 1.999944
#> 47      Randolph 1.990211
#> 48       Chatham 2.001254
#> 49        Wilson 1.982204
#> 50         Rowan 2.012542
#> 51          Pitt 2.017377
#> 52       Catawba 2.022499
#> 53      Buncombe 2.034685
#> 54      Johnston 2.030662
#> 55       Haywood 2.026524
#> 56          Dare 2.010891
#> 57      Beaufort 2.027408
#> 58         Swain 2.071742
#> 59        Greene 1.963715
#> 60           Lee 2.026932
#> 61    Rutherford 1.997621
#> 62         Wayne 1.977614
#> 63       Harnett 2.001271
#> 64     Cleveland 2.030814
#> 65       Lincoln 2.012945
#> 66       Jackson 2.046988
#> 67         Moore 2.018466
#> 68   Mecklenburg 1.960130
#> 69      Cabarrus 2.058463
#> 70    Montgomery 1.963255
#> 71        Stanly 1.962456
#> 72     Henderson 1.995068
#> 73        Graham 1.979657
#> 74        Lenoir 2.015227
#> 75  Transylvania 2.033446
#> 76        Gaston 2.030488
#> 77          Polk 2.003313
#> 78         Macon 1.978571
#> 79       Sampson 1.932338
#> 80       Pamlico 2.040469
#> 81      Cherokee 2.022352
#> 82    Cumberland 1.970722
#> 83         Jones 1.953258
#> 84         Union 2.048984
#> 85         Anson 1.981594
#> 86          Hoke 1.917422
#> 87          Hyde 1.988905
#> 88        Duplin 1.959774
#> 89      Richmond 2.001290
#> 90          Clay 2.064368
#> 91        Craven 2.001500
#> 92      Scotland 1.956283
#> 93        Onslow 2.027830
#> 94       Robeson 2.012189
#> 95      Carteret 2.014055
#> 96        Bladen 1.985855
#> 97        Pender 1.991776
#> 98      Columbus 1.971150
#> 99   New Hanover 1.984182
#> 100    Brunswick 2.011332
# Using SpatRaster object
suppressWarnings(
  extract_at(
    rrast, ncpath, "NAME", "mean",
    kernel = "epanechnikov",
    bandwidth = 1e5
  )
)
#> ℹ Input is a character. Trying to read with sf.
#> Reading layer `nc.gpkg' from data source 
#>   `/github/home/R/x86_64-pc-linux-gnu-library/4.5/sf/gpkg/nc.gpkg' 
#>   using driver `GPKG'
#> Simple feature collection with 100 features and 14 fields
#> Geometry type: MULTIPOLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -84.32385 ymin: 33.88199 xmax: -75.45698 ymax: 36.58965
#> Geodetic CRS:  NAD27
#> Kernel function [ epanechnikov ] is applied to calculate weights...
#> Switch sf class to terra...
#> # A tibble: 100 × 2
#>    NAME      value
#>    <chr>     <dbl>
#>  1 Alamance   2.04
#>  2 Alexander  1.94
#>  3 Alleghany  1.94
#>  4 Anson      1.98
#>  5 Ashe       2.02
#>  6 Avery      1.99
#>  7 Beaufort   2.03
#>  8 Bertie     2.02
#>  9 Bladen     1.99
#> 10 Brunswick  2.01
#> # ℹ 90 more rows
# Using raster path
terra::writeRaster(rrast, rastpath, overwrite = TRUE)
suppressWarnings(
  extract_at(
    rastpath, ncpath, "NAME", "mean",
    kernel = "epanechnikov",
    bandwidth = 1e5
  )
)
#> Input is a character. Attempt to read it with terra::rast...
#> ℹ Input is a character. Trying to read with sf.
#> Reading layer `nc.gpkg' from data source 
#>   `/github/home/R/x86_64-pc-linux-gnu-library/4.5/sf/gpkg/nc.gpkg' 
#>   using driver `GPKG'
#> Simple feature collection with 100 features and 14 fields
#> Geometry type: MULTIPOLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -84.32385 ymin: 33.88199 xmax: -75.45698 ymax: 36.58965
#> Geodetic CRS:  NAD27
#> Kernel function [ epanechnikov ] is applied to calculate weights...
#> Switch sf class to terra...
#> # A tibble: 100 × 2
#>    NAME      value
#>    <chr>     <dbl>
#>  1 Alamance   2.04
#>  2 Alexander  1.94
#>  3 Alleghany  1.94
#>  4 Anson      1.98
#>  5 Ashe       2.02
#>  6 Avery      1.99
#>  7 Beaufort   2.03
#>  8 Bertie     2.02
#>  9 Bladen     1.99
#> 10 Brunswick  2.01
#> # ℹ 90 more rows