From 6988613adaac0b3181037dc97f93e07451256b65 Mon Sep 17 00:00:00 2001 From: njtierney Date: Tue, 14 May 2024 12:10:55 +1000 Subject: [PATCH 1/7] tidy NEWS --- NEWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. From 4f959773636bb825df6eb1868431e446b51d1922 Mon Sep 17 00:00:00 2001 From: njtierney Date: Tue, 14 May 2024 12:18:42 +1000 Subject: [PATCH 2/7] update README --- README.Rmd | 40 +++++++++++++++++--------------- README.md | 68 ++++++++++++++++++++++++++++++++---------------------- 2 files changed, 62 insertions(+), 46 deletions(-) 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. From 4341e22a1ab0e9adebb125b5c1e954cb3218057b Mon Sep 17 00:00:00 2001 From: njtierney Date: Tue, 14 May 2024 12:33:01 +1000 Subject: [PATCH 3/7] add return documentation --- R/tar-terra-rast.R | 1 + R/tar-terra-sprc.R | 1 + R/tar-terra-vect.R | 1 + man/tar_terra_rast.Rd | 3 +++ man/tar_terra_sprc.Rd | 3 +++ man/tar_terra_vect.Rd | 3 +++ 6 files changed, 12 insertions(+) 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/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. } From cc9e39b2e831680399b18e2912d936ac4d9be3c5 Mon Sep 17 00:00:00 2001 From: njtierney Date: Tue, 14 May 2024 12:37:54 +1000 Subject: [PATCH 4/7] add return information --- R/geotargets-option.R | 26 ++++++++++++++++++++++++++ man/geotargets-options.Rd | 27 +++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) 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/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") +} From 97ca85e8bdf81c41a1c250022b8accb5dca122bf Mon Sep 17 00:00:00 2001 From: njtierney Date: Tue, 14 May 2024 12:37:59 +1000 Subject: [PATCH 5/7] use version 0.1.0 --- DESCRIPTION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index b4159a2..9cc5cfe 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: geotargets Title: Targets extensions for geospatial formats -Version: 0.0.0.9000 +Version: 0.1.0 Authors@R: c( person( given = "Nicholas", From 5982051cec0489c37c3ffc01c564c45407372ddd Mon Sep 17 00:00:00 2001 From: njtierney Date: Tue, 14 May 2024 12:45:07 +1000 Subject: [PATCH 6/7] update DESCRIPTION in line with extrachecks --- DESCRIPTION | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 9cc5cfe..0aaa007 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: geotargets -Title: Targets extensions for geospatial formats +Title: 'Targets' Extensions for Geospatial Formats Version: 0.1.0 Authors@R: c( person( @@ -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 From ea9a7db8d6822eb9d3df074a6d009f22ee3c1134 Mon Sep 17 00:00:00 2001 From: njtierney Date: Wed, 15 May 2024 13:40:45 +1000 Subject: [PATCH 7/7] * Add min versions to packages in imports and suggests. * Update geotargets-package docs --- DESCRIPTION | 10 +++++----- man/geotargets-package.Rd | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 0aaa007..3923783 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -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/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: