diff --git a/DESCRIPTION b/DESCRIPTION index b4159a2..3923783 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: geotargets -Title: Targets extensions for geospatial formats -Version: 0.0.0.9000 +Title: 'Targets' Extensions for Geospatial Formats +Version: 0.1.0 Authors@R: c( person( given = "Nicholas", @@ -23,9 +23,9 @@ Authors@R: c( ) ) Description: Provides extensions for various geospatial file formats, - such as shapefiles and rasters. See the vignettes for worked - examples and demonstrations and explanations of how to use the various - package extensions. + such as shapefiles and rasters. Currently provides support for the 'terra' + geospatial formats. See the vignettes for worked examples, demonstrations, + and explanations of how to use the various package extensions. License: MIT + file LICENSE Encoding: UTF-8 Language: en-GB @@ -33,13 +33,13 @@ Roxygen: list(markdown = TRUE) RoxygenNote: 7.3.1 Imports: targets (>= 1.7.0), - rlang, - cli + rlang (>= 1.1.3), + cli (>= 3.6.2) Suggests: - crew, - terra, + crew (>= 0.9.2), + terra (>= 1.7.71), testthat (>= 3.0.0), - withr + withr (>= 3.0.0) Config/testthat/edition: 3 URL: https://github.com/njtierney/geotargets, https://njtierney.github.io/geotargets/ BugReports: https://github.com/njtierney/geotargets/issues diff --git a/NEWS.md b/NEWS.md index 04c3f66..a99d594 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# geotargets 0.0.0.9000 (development version) +# geotargets 0.1.0 (14 May 2024) * Created `tar_terra_rast()` and `tar_terra_vect()` for targets that create `SpatRaster` and `SpatVector` objects, respectively * Created `tar_terra_sprc()` that creates a `SpatRasterCollection` object. diff --git a/R/geotargets-option.R b/R/geotargets-option.R index 3c05527..ea0e89f 100644 --- a/R/geotargets-option.R +++ b/R/geotargets-option.R @@ -27,9 +27,32 @@ #' `geotargets_options_set(gdal_raster_driver = "GTiff")` is equivalent to #' `options("geotargets.gdal.raster.driver" = "GTiff")`. #' +#' @return Specific options, such as "gdal.raster.driver". See "Details" for +#' more information. +#' #' #' @rdname geotargets-options #' @export +#' @examples +#' if (Sys.getenv("TAR_LONG_EXAMPLES") == "true") { +#' targets::tar_dir({ # tar_dir() runs code from a temporary directory. +#' library(geotargets) +#' op <- getOption("geotargets.gdal.raster.driver") +#' withr::defer(options("geotargets.gdal.raster.driver" = op)) +#' geotargets_option_set(gdal_raster_driver = "COG") +#' targets::tar_script({ +#' list( +#' geotargets::tar_terra_rast( +#' terra_rast_example, +#' system.file("ex/elev.tif", package = "terra") |> terra::rast() +#' ) +#' ) +#' }) +#' targets::tar_make() +#' x <- targets::tar_read(terra_rast_example) +#' }) +#'} +#' geotargets_option_set <- function( gdal_raster_driver = NULL, gdal_raster_creation_options = NULL, @@ -54,6 +77,9 @@ geotargets_option_set <- function( #' @param name character; option name to get. #' #' @rdname geotargets-options +#' @examples +#' geotargets_option_get("gdal.raster.driver") +#' geotargets_option_get("gdal.raster.creation.options") #' @export geotargets_option_get <- function(name) { option_name <- geotargets_repair_option_name(name) diff --git a/R/tar-terra-rast.R b/R/tar-terra-rast.R index cd0faac..85795aa 100644 --- a/R/tar-terra-rast.R +++ b/R/tar-terra-rast.R @@ -9,6 +9,7 @@ #' @param ... Additional arguments not yet used #' #' @inheritParams targets::tar_target +#' @returns target class "tar_stem" for use in a target pipeline #' @importFrom rlang %||% arg_match0 #' @seealso [targets::tar_target_raw()] #' @export diff --git a/R/tar-terra-sprc.R b/R/tar-terra-sprc.R index 520c962..7c9f356 100644 --- a/R/tar-terra-sprc.R +++ b/R/tar-terra-sprc.R @@ -10,6 +10,7 @@ #' @param ... Additional arguments not yet used #' #' @inheritParams targets::tar_target +#' @returns target class "tar_stem" for use in a target pipeline #' @seealso [targets::tar_target_raw()] #' @author Andrew Gene Brown #' @author Nicholas Tierney diff --git a/R/tar-terra-vect.R b/R/tar-terra-vect.R index 0302d29..37e8fdb 100644 --- a/R/tar-terra-vect.R +++ b/R/tar-terra-vect.R @@ -8,6 +8,7 @@ #' passed to [terra::writeVector()]. #' @param ... Additional arguments not yet used #' @inheritParams targets::tar_target +#' @returns target class "tar_stem" for use in a target pipeline #' #' @note Although you may pass any supported GDAL vector driver to the #' `filetype` argument, not all formats are guaranteed to work with diff --git a/README.Rmd b/README.Rmd index ee8145b..1fd67e5 100644 --- a/README.Rmd +++ b/README.Rmd @@ -22,9 +22,21 @@ knitr::opts_chunk$set( [![Codecov test coverage](https://codecov.io/gh/njtierney/geotargets/branch/master/graph/badge.svg)](https://app.codecov.io/gh/njtierney/geotargets?branch=master) -`geotargets` extends targets to work with geospatial data formats, such as rasters and vectors (e.g., shapefiles). +`geotargets` extends [`targets`](https://github.com/ropensci/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`](https://github.com/rspatial/terra) package -A relatively common gotcha moment when using popular libraries like `terra` with targets is running into erros 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. +## Installation + +You can install the development version of geotargets like so: + +``` r +install.packages("geotargets", repos = c("https://njtierney.r-universe.dev", "https://cran.r-project.org")) +``` + +## Why `geotargets` + +If you want to use geospatial data formats (such as `terra`) with the [`targets`](https://github.com/ropensci/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: @@ -39,31 +51,19 @@ or Error: external pointer is not valid ``` -When trying to read in a geospatial raster or vector in targets, then this is for you :) - -## Installation - -You can install the development version of geotargets like so: - -``` r -install.packages("geotargets", repos = c("https://njtierney.r-universe.dev", "https://cran.r-project.org")) -``` - -## A note on development - -`geotargets` is still undergoing development, and we would love for people to use the package to kick the tyres. We are using it in our own work, but want users to know that the API could change in subtle or breaking ways. +When trying to read in a geospatial raster or vector in targets, then `geotargets` for you :) # Examples -Below we show three examples of target factories: +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()` -You would use these in place of `tar_target()` in your targets pipeline, when you are doing work with terra raster or terra vector data. +You would use these in place of `tar_target()` in your targets pipeline, when you are doing work with `terra` raster, vector, or raster collection data. -It is a bit tricky to implement targets workflows in a README, but if you would like to see and download working examples for yourself, see the repo, [demo-geotargets](https://github.com/njtierney/demo-geotargets). +If you would like to see and download working examples for yourself, see the repo, [demo-geotargets](https://github.com/njtierney/demo-geotargets). ## `tar_terra_rast()`: targets with terra rasters @@ -153,3 +153,7 @@ targets::tar_dir({ # tar_dir() runs code from a temporary directory. ## Code of Conduct Please note that the geotargets project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. + +## A note on development + +`geotargets` is still undergoing development. We currently consider the extensions with `terra` maturing and approaching stability. We would love for people to use the package to kick the tyres. We are using it in our own work, but want users to know that the API could change in subtle or breaking ways. diff --git a/README.md b/README.md index c916954..f527180 100644 --- a/README.md +++ b/README.md @@ -15,16 +15,34 @@ Targetopia](https://img.shields.io/badge/R_Targetopia-member-blue?style=flat&lab coverage](https://codecov.io/gh/njtierney/geotargets/branch/master/graph/badge.svg)](https://app.codecov.io/gh/njtierney/geotargets?branch=master) -`geotargets` extends targets to work with geospatial data formats, such -as rasters and vectors (e.g., shapefiles). +`geotargets` extends [`targets`](https://github.com/ropensci/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`](https://github.com/rspatial/terra) package -A relatively common gotcha moment when using popular libraries like -`terra` with targets is running into erros 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. +## Installation + +You can install the development version of geotargets like so: + +``` r +install.packages("geotargets", repos = c("https://njtierney.r-universe.dev", "https://cran.r-project.org")) +``` + +## Why `geotargets` + +If you want to use geospatial data formats (such as `terra`) with the +[`targets`](https://github.com/ropensci/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: @@ -36,25 +54,11 @@ or Error: external pointer is not valid When trying to read in a geospatial raster or vector in targets, then -this is for you :) - -## Installation - -You can install the development version of geotargets like so: - -``` r -install.packages("geotargets", repos = c("https://njtierney.r-universe.dev", "https://cran.r-project.org")) -``` - -## A note on development - -`geotargets` is still undergoing development, and we would love for -people to use the package to kick the tyres. We are using it in our own -work, but want users to know that the API could change in subtle or -breaking ways. +`geotargets` for you :) # Examples +We currently provide support for the `terra` package with `targets`. Below we show three examples of target factories: - `tar_terra_rast()` @@ -62,10 +66,10 @@ Below we show three examples of target factories: - `tar_terra_sprc()` You would use these in place of `tar_target()` in your targets pipeline, -when you are doing work with terra raster or terra vector data. +when you are doing work with `terra` raster, vector, or raster +collection data. -It is a bit tricky to implement targets workflows in a README, but if -you would like to see and download working examples for yourself, see +If you would like to see and download working examples for yourself, see the repo, [demo-geotargets](https://github.com/njtierney/demo-geotargets). @@ -152,3 +156,11 @@ Please note that the geotargets project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. + +## A note on development + +`geotargets` is still undergoing development. We currently consider the +extensions with `terra` maturing and approaching stability. We would +love for people to use the package to kick the tyres. We are using it in +our own work, but want users to know that the API could change in subtle +or breaking ways. diff --git a/man/geotargets-options.Rd b/man/geotargets-options.Rd index dfbcc77..84639cd 100644 --- a/man/geotargets-options.Rd +++ b/man/geotargets-options.Rd @@ -39,6 +39,10 @@ driver: \item{name}{character; option name to get.} } +\value{ +Specific options, such as "gdal.raster.driver". See "Details" for +more information. +} \description{ Get or set behavior for geospatial data target stores using geotargets-specific global options. @@ -48,3 +52,26 @@ These options can also be set using \code{options()}. For example, \code{geotargets_options_set(gdal_raster_driver = "GTiff")} is equivalent to \code{options("geotargets.gdal.raster.driver" = "GTiff")}. } +\examples{ +if (Sys.getenv("TAR_LONG_EXAMPLES") == "true") { + targets::tar_dir({ # tar_dir() runs code from a temporary directory. + library(geotargets) + op <- getOption("geotargets.gdal.raster.driver") + withr::defer(options("geotargets.gdal.raster.driver" = op)) + geotargets_option_set(gdal_raster_driver = "COG") + targets::tar_script({ + list( + geotargets::tar_terra_rast( + terra_rast_example, + system.file("ex/elev.tif", package = "terra") |> terra::rast() + ) + ) + }) + targets::tar_make() + x <- targets::tar_read(terra_rast_example) + }) +} + +geotargets_option_get("gdal.raster.driver") +geotargets_option_get("gdal.raster.creation.options") +} diff --git a/man/geotargets-package.Rd b/man/geotargets-package.Rd index d9558a9..714dc5f 100644 --- a/man/geotargets-package.Rd +++ b/man/geotargets-package.Rd @@ -4,9 +4,9 @@ \name{geotargets-package} \alias{geotargets} \alias{geotargets-package} -\title{geotargets: Targets extensions for geospatial formats} +\title{geotargets: 'Targets' Extensions for Geospatial Formats} \description{ -Provides extensions for various geospatial file formats, such as shapefiles and rasters. See the vignettes for worked examples and demonstrations and explanations of how to use the various package extensions. +Provides extensions for various geospatial file formats, such as shapefiles and rasters. Currently provides support for the 'terra' geospatial formats. See the vignettes for worked examples, demonstrations, and explanations of how to use the various package extensions. } \seealso{ Useful links: diff --git a/man/tar_terra_rast.Rd b/man/tar_terra_rast.Rd index 4d0a8dc..b94b5e1 100644 --- a/man/tar_terra_rast.Rd +++ b/man/tar_terra_rast.Rd @@ -217,6 +217,9 @@ explicitly from another language. \item{cue}{An optional object from \code{tar_cue()} to customize the rules that decide whether the target is up to date.} } +\value{ +target class "tar_stem" for use in a target pipeline +} \description{ Provides a target format for \link[terra:SpatRaster-class]{terra::SpatRaster} objects. } diff --git a/man/tar_terra_sprc.Rd b/man/tar_terra_sprc.Rd index 0d1315d..98506c9 100644 --- a/man/tar_terra_sprc.Rd +++ b/man/tar_terra_sprc.Rd @@ -217,6 +217,9 @@ explicitly from another language. \item{cue}{An optional object from \code{tar_cue()} to customize the rules that decide whether the target is up to date.} } +\value{ +target class "tar_stem" for use in a target pipeline +} \description{ Provides a target format for \link[terra:SpatRaster-class]{terra::SpatRasterCollection} objects, which have no restriction in the extent or other geometric parameters. diff --git a/man/tar_terra_vect.Rd b/man/tar_terra_vect.Rd index 2d07b81..4561501 100644 --- a/man/tar_terra_vect.Rd +++ b/man/tar_terra_vect.Rd @@ -217,6 +217,9 @@ explicitly from another language. \item{cue}{An optional object from \code{tar_cue()} to customize the rules that decide whether the target is up to date.} } +\value{ +target class "tar_stem" for use in a target pipeline +} \description{ Provides a target format for \link[terra:SpatVector-class]{terra::SpatVector} objects. }