geotargets extends targets to
work with geospatial data formats, such as rasters and vectors (e.g.,
shapefiles). Currently we support raster and vector formats for the terra
package.
If you are unfamiliar with targets, we recommend watching “targets in 4 minutes”.
One example citation of geotargets could be as follows: “R packages used in this analysis included (list R packages used), targets, and geotargets (Tierney, N., Scott, E., & Brown, A, 2024). Here is the full bibliographic reference for your references:
Tierney N, Scott E, Brown A (2024). “geotargets: ‘Targets’ Extensions for Geospatial Formats.” https://docs.ropensci.org/geotargets/.
You can install the development version of geotargets like so:
install.packages("geotargets", repos = c("https://ropensci.r-universe.dev", "https://cran.r-project.org"))geotargetsIf you want to use geospatial data formats (such as
terra) with the targets
package to build analytic reproducible pipelines, it involves writing a
lot of custom targets wrappers. We wrote geotargets so you
can use geospatial data formats with targets.
To provide more detail on this, a common problem when using popular
libraries like terra with targets is running
into errors with read and write. Due to the limitations that come with
the underlying C++ implementation in the terra library,
there are specific ways to write and read these objects. See
?terra for details. geotargets helps handle
these write and read steps, so you don’t have to worry about them and
can use targets as you are used to.
In essence, if you’ve ever come across the error:
Error in .External(list(name = "CppMethod__invoke_notvoid", address = <pointer: 0x0>, :
NULL value passed as symbol addressor
Error: external pointer is not validWhen trying to read in a geospatial raster or vector in targets, then
geotargets for you :)
We currently provide support for the terra package with
targets. Below we show three examples of target
factories:
tar_terra_rast()tar_terra_vect()tar_terra_sprc()tar_terra_sds()tar_terra_tiles()tar_stars()You would use these in place of tar_target() in your
targets pipeline, e.g., when you are doing work with terra
raster, vector, or raster collection data.
If you would like to see and download working examples for yourself, see the repos:
tar_terra_rast():
targets with terra rasterslibrary(targets)
tar_dir({ # tar_dir() runs code from a temporary directory.
tar_script({
library(geotargets)
get_elev <- function() {
terra::rast(system.file("ex", "elev.tif", package = "terra"))
}
list(
tar_terra_rast(
terra_rast_example,
get_elev()
)
)
})
tar_make()
x <- tar_read(terra_rast_example)
x
})
#> + terra_rast_example dispatched
#> ✔ terra_rast_example completed [2ms, 8.52 kB]
#> ✔ ended pipeline [185ms, 1 completed, 0 skipped]
#> class : SpatRaster
#> dimensions : 90, 95, 1 (nrow, ncol, nlyr)
#> resolution : 0.008333333, 0.008333333 (x, y)
#> extent : 5.741667, 6.533333, 49.44167, 50.19167 (xmin, xmax, ymin, ymax)
#> coord. ref. : lon/lat WGS 84 (EPSG:4326)
#> source : terra_rast_example
#> name : elevation
#> min value : 141
#> max value : 547tar_terra_vect():
targets with terra vectorstar_dir({ # tar_dir() runs code from a temporary directory.
tar_script({
library(geotargets)
lux_area <- function(projection = "EPSG:4326") {
terra::project(
terra::vect(system.file("ex", "lux.shp",
package = "terra"
)),
projection
)
}
list(
tar_terra_vect(
terra_vect_example,
lux_area()
)
)
})
tar_make()
x <- tar_read(terra_vect_example)
x
})
#> + terra_vect_example dispatched
#> ✔ terra_vect_example completed [24ms, 117.65 kB]
#> ✔ ended pipeline [185ms, 1 completed, 0 skipped]
#> class : SpatVector
#> geometry : polygons
#> dimensions : 12, 6 (geometries, attributes)
#> extent : 5.74414, 6.528252, 49.44781, 50.18162 (xmin, xmax, ymin, ymax)
#> source : terra_vect_example
#> coord. ref. : lon/lat WGS 84 (EPSG:4326)
#> names : ID_1 NAME_1 ID_2 NAME_2 AREA POP
#> type : <num> <chr> <num> <chr> <num> <num>
#> values : 1 Diekirch 1 Clervaux 312 1.808e+04
#> 1 Diekirch 2 Diekirch 218 3.254e+04
#> 1 Diekirch 3 Redange 259 1.866e+04tar_terra_sprc():
targets with terra raster collectionstar_dir({ # tar_dir() runs code from a temporary directory.
tar_script({
library(geotargets)
elev_scale <- function(z = 1, projection = "EPSG:4326") {
terra::project(
terra::rast(system.file("ex", "elev.tif", package = "terra")) * z,
projection
)
}
list(
tar_terra_sprc(
raster_elevs,
# two rasters, one unaltered, one scaled by factor of 2 and
# reprojected to interrupted goode homolosine
command = terra::sprc(list(
elev_scale(1),
elev_scale(2, "+proj=igh")
))
)
)
})
tar_make()
x <- tar_read(raster_elevs)
x
})
#> + raster_elevs dispatched
#> ✔ raster_elevs completed [45ms, 37.90 kB]
#> ✔ ended pipeline [226ms, 1 completed, 0 skipped]
#> class : SpatRasterCollection
#> length : 2
#> nrow : 90, 115
#> ncol : 95, 114
#> nlyr : 1, 1
#> extent : 5.741667, 1558890, 49.44167, 5556741 (xmin, xmax, ymin, ymax)
#> crs (first) : lon/lat WGS 84 (EPSG:4326)
#> names : raster_elevs, raster_elevstar_stars():
targets with stars objectstar_dir({ # tar_dir() runs code from a temporary directory.
tar_script({
library(geotargets)
list(
tar_stars(
test_stars,
stars::read_stars(system.file("tif", "olinda_dem_utm25s.tif", package = "stars"))
)
)
})
tar_make()
x <- tar_read(test_stars)
x
})
#> + test_stars dispatched
#> ✔ test_stars completed [16ms, 49.90 kB]
#> ✔ ended pipeline [185ms, 1 completed, 0 skipped]
#> stars object with 2 dimensions and 1 attribute
#> attribute(s):
#> Min. 1st Qu. Median Mean 3rd Qu. Max.
#> test_stars -1 6 12 21.66521 35 88
#> dimension(s):
#> from to offset delta refsys point x/y
#> x 1 111 288776 89.99 UTM Zone 25, Southern Hem... FALSE [x]
#> y 1 111 9120761 -89.99 UTM Zone 25, Southern Hem... FALSE [y]Please note that the geotargets project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
Logo design by Hubert Hałun at Appsilon.