Skip to contents

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 1.630118
#> 2  ID-02 1.552282
#> 3  ID-03 2.102782
#> 4  ID-04 1.299461
#> 5  ID-05 3.557990
#> 6  ID-06 2.411554
#> 7  ID-07 2.094646
#> 8  ID-08 2.381750
#> 9  ID-09 1.890465
#> 10 ID-10 1.601506
#> 11 ID-11 1.224481
#> 12 ID-12 1.605464
#> 13 ID-13 1.988281
#> 14 ID-14 2.173477
#> 15 ID-15 2.423967
#> 16 ID-16 2.144691
extract_at(rrast, nc, "NAME", "mean")
#> Switch terra class to sf...
#>             NAME     mean
#> 1           Ashe 2.032982
#> 2      Alleghany 1.965819
#> 3          Surry 2.047563
#> 4      Currituck 1.970431
#> 5    Northampton 1.978815
#> 6       Hertford 1.994044
#> 7         Camden 2.007749
#> 8          Gates 2.055456
#> 9         Warren 1.981976
#> 10        Stokes 2.045821
#> 11       Caswell 2.027450
#> 12    Rockingham 2.018353
#> 13     Granville 1.983555
#> 14        Person 1.981137
#> 15         Vance 2.009515
#> 16       Halifax 2.013973
#> 17    Pasquotank 2.036883
#> 18        Wilkes 2.021287
#> 19       Watauga 1.958765
#> 20    Perquimans 2.010861
#> 21        Chowan 2.049015
#> 22         Avery 1.968544
#> 23        Yadkin 1.954717
#> 24      Franklin 1.973464
#> 25       Forsyth 1.977364
#> 26      Guilford 1.969632
#> 27      Alamance 2.053568
#> 28        Bertie 2.014483
#> 29        Orange 2.028664
#> 30        Durham 1.895999
#> 31          Nash 1.930161
#> 32      Mitchell 2.020947
#> 33     Edgecombe 2.019365
#> 34      Caldwell 2.031065
#> 35        Yancey 2.023336
#> 36        Martin 1.966750
#> 37          Wake 2.057888
#> 38       Madison 2.009320
#> 39       Iredell 2.064115
#> 40         Davie 1.902576
#> 41     Alexander 1.921725
#> 42      Davidson 1.988640
#> 43         Burke 1.961076
#> 44    Washington 2.027965
#> 45       Tyrrell 1.926573
#> 46      McDowell 1.973173
#> 47      Randolph 1.989624
#> 48       Chatham 2.008221
#> 49        Wilson 1.970300
#> 50         Rowan 1.986545
#> 51          Pitt 1.997716
#> 52       Catawba 2.027744
#> 53      Buncombe 2.032583
#> 54      Johnston 2.026467
#> 55       Haywood 2.022436
#> 56          Dare 2.000511
#> 57      Beaufort 2.032175
#> 58         Swain 2.077188
#> 59        Greene 1.989197
#> 60           Lee 2.048345
#> 61    Rutherford 1.995117
#> 62         Wayne 1.967940
#> 63       Harnett 2.009033
#> 64     Cleveland 2.034668
#> 65       Lincoln 1.976689
#> 66       Jackson 2.052383
#> 67         Moore 2.010714
#> 68   Mecklenburg 1.993389
#> 69      Cabarrus 2.030702
#> 70    Montgomery 1.943899
#> 71        Stanly 2.023706
#> 72     Henderson 2.020371
#> 73        Graham 2.021611
#> 74        Lenoir 2.032743
#> 75  Transylvania 1.986009
#> 76        Gaston 2.005659
#> 77          Polk 1.983960
#> 78         Macon 1.985322
#> 79       Sampson 1.932612
#> 80       Pamlico 2.053480
#> 81      Cherokee 2.007918
#> 82    Cumberland 1.952759
#> 83         Jones 1.967918
#> 84         Union 2.055588
#> 85         Anson 1.968707
#> 86          Hoke 1.944859
#> 87          Hyde 2.004758
#> 88        Duplin 1.954873
#> 89      Richmond 1.999966
#> 90          Clay 2.045456
#> 91        Craven 1.995648
#> 92      Scotland 1.974353
#> 93        Onslow 2.013076
#> 94       Robeson 2.015269
#> 95      Carteret 2.023871
#> 96        Bladen 1.968223
#> 97        Pender 1.998836
#> 98      Columbus 1.970665
#> 99   New Hanover 1.957875
#> 100    Brunswick 2.014300
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.032982
#> 2      Alleghany 1.965819
#> 3          Surry 2.047563
#> 4      Currituck 1.970431
#> 5    Northampton 1.978815
#> 6       Hertford 1.994044
#> 7         Camden 2.007749
#> 8          Gates 2.055456
#> 9         Warren 1.981976
#> 10        Stokes 2.045821
#> 11       Caswell 2.027450
#> 12    Rockingham 2.018353
#> 13     Granville 1.983555
#> 14        Person 1.981137
#> 15         Vance 2.009515
#> 16       Halifax 2.013973
#> 17    Pasquotank 2.036883
#> 18        Wilkes 2.021287
#> 19       Watauga 1.958765
#> 20    Perquimans 2.010861
#> 21        Chowan 2.049015
#> 22         Avery 1.968544
#> 23        Yadkin 1.954717
#> 24      Franklin 1.973464
#> 25       Forsyth 1.977364
#> 26      Guilford 1.969632
#> 27      Alamance 2.053568
#> 28        Bertie 2.014483
#> 29        Orange 2.028664
#> 30        Durham 1.895999
#> 31          Nash 1.930161
#> 32      Mitchell 2.020947
#> 33     Edgecombe 2.019365
#> 34      Caldwell 2.031065
#> 35        Yancey 2.023336
#> 36        Martin 1.966750
#> 37          Wake 2.057888
#> 38       Madison 2.009320
#> 39       Iredell 2.064115
#> 40         Davie 1.902576
#> 41     Alexander 1.921725
#> 42      Davidson 1.988640
#> 43         Burke 1.961076
#> 44    Washington 2.027965
#> 45       Tyrrell 1.926573
#> 46      McDowell 1.973173
#> 47      Randolph 1.989624
#> 48       Chatham 2.008221
#> 49        Wilson 1.970300
#> 50         Rowan 1.986545
#> 51          Pitt 1.997716
#> 52       Catawba 2.027744
#> 53      Buncombe 2.032583
#> 54      Johnston 2.026467
#> 55       Haywood 2.022436
#> 56          Dare 2.000511
#> 57      Beaufort 2.032175
#> 58         Swain 2.077188
#> 59        Greene 1.989197
#> 60           Lee 2.048345
#> 61    Rutherford 1.995117
#> 62         Wayne 1.967940
#> 63       Harnett 2.009033
#> 64     Cleveland 2.034668
#> 65       Lincoln 1.976689
#> 66       Jackson 2.052383
#> 67         Moore 2.010714
#> 68   Mecklenburg 1.993389
#> 69      Cabarrus 2.030702
#> 70    Montgomery 1.943899
#> 71        Stanly 2.023706
#> 72     Henderson 2.020371
#> 73        Graham 2.021611
#> 74        Lenoir 2.032743
#> 75  Transylvania 1.986009
#> 76        Gaston 2.005659
#> 77          Polk 1.983960
#> 78         Macon 1.985322
#> 79       Sampson 1.932612
#> 80       Pamlico 2.053480
#> 81      Cherokee 2.007918
#> 82    Cumberland 1.952759
#> 83         Jones 1.967918
#> 84         Union 2.055588
#> 85         Anson 1.968707
#> 86          Hoke 1.944859
#> 87          Hyde 2.004758
#> 88        Duplin 1.954873
#> 89      Richmond 1.999966
#> 90          Clay 2.045456
#> 91        Craven 1.995648
#> 92      Scotland 1.974353
#> 93        Onslow 2.013076
#> 94       Robeson 2.015269
#> 95      Carteret 2.023871
#> 96        Bladen 1.968223
#> 97        Pender 1.998836
#> 98      Columbus 1.970665
#> 99   New Hanover 1.957875
#> 100    Brunswick 2.014300
# 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.05
#>  2 Alexander  1.92
#>  3 Alleghany  1.97
#>  4 Anson      1.97
#>  5 Ashe       2.03
#>  6 Avery      1.97
#>  7 Beaufort   2.03
#>  8 Bertie     2.01
#>  9 Bladen     1.97
#> 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.05
#>  2 Alexander  1.92
#>  3 Alleghany  1.97
#>  4 Anson      1.97
#>  5 Ashe       2.03
#>  6 Avery      1.97
#>  7 Beaufort   2.03
#>  8 Bertie     2.01
#>  9 Bladen     1.97
#> 10 Brunswick  2.01
#> # ℹ 90 more rows