Merge pull request #70 from njtierney/release-010-68

Release 0.1.0

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,23 +23,23 @@ 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
 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

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.

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)

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

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

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

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)
 <!-- badges: end -->
 
-`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.

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)
 <!-- badges: end -->
 
-`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,36 +54,22 @@ 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()`
 - `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.
+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.