Skip to content

Commit

Permalink
Merge pull request #1 from AAGI-AUS/devel
Browse files Browse the repository at this point in the history
  • Loading branch information
adamhsparks authored Nov 1, 2024
2 parents a9d9611 + e9d22d7 commit 7ffb387
Show file tree
Hide file tree
Showing 13 changed files with 412 additions and 29 deletions.
4 changes: 3 additions & 1 deletion DESCRIPTION
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@ Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.2
Imports:
cli,
curl,
data.table,
lubridate,
rlang,
terra
terra,
utils
3 changes: 3 additions & 0 deletions NAMESPACE
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# Generated by roxygen2: do not edit by hand

export(download_gtiff)
export(get_key)
export(get_smips)
export(plot)
export(read_cog)
export(read_cog_dt)
importFrom(terra,plot)
44 changes: 44 additions & 0 deletions R/internal_functions.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@



.make_smips_url <- function(.collection, .day) {
url_date <- gsub("-", "", .day)

approved_collections <- c("totalbucket",
"SMindex",
"bucket1",
"bucket2",
"deepD",
"runnoff")
collection <- rlang::arg_match(.collection, approved_collections)

.check_collection_agreement(.collection = .collection, .day = .day)

collection_url <- data.table::fcase(
collection == "totalbucket",
paste0("smips_totalbucket_mm_", url_date, ".tif"),
collection == "SMindex",
paste0("smips_smi_perc_", url_date, ".tif"),
collection == "bucket1",
paste0("smips_bucket1_mm_", url_date, ".tif"),
collection == "bucket2",
paste0("smips_bucket2_mm_", url_date, ".tif"),
collection == "deepD",
paste0("smips_deepD_mm_", url_date, ".tif"),
collection == "runoff",
paste0("smips_runoff_mm_", url_date, ".tif")
)
}


.check_collection_agreement <- function(.collection, .day) {
.this_year <- lubridate::year(lubridate::today())
.last_week <- lubridate::today() - 7
.url_year <- lubridate::year(.day)

if (.collection == "totalbucket" &&
.url_year < 2005 ||
.day > .last_week) {
cli::cli_abort("The data are not available before 2005 and past {.last_week}")
}
}
68 changes: 68 additions & 0 deletions R/read_cog.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
#' Read COGs from TERN
#'
#' Read Cloud Optimised Geotiff (\acronym{COG}) files from \acronym{TERN} in
#' your active \R session.
#'
#' @note
#' Currently only Soil Moisture Integration and Prediction System
#' (\acronym{SMIPS}) v1.0 is supported.
#'
#' @param data A character vector of the data source to be queried, currently
#' only \dQuote{smips}.
#' @param collection A character vector of the data collection to be queried,
#' currenly only \dQuote{smips} is supported with the following collections:
#' * SMindex
#' * bucket1
#' * bucket2
#' * deepD
#' * runoff
#' * totalbucket
#' Defaults to \dQuote{totalbucket}.
#' @param day A single day's date to query, _e.g._, `day = "2017-12-31"`, both
#' `Character` and `Date` classes are accepted.
#' @param api_key A `character` string containing your \acronym{API} key,
#' a random string provided to you by \acronym{TERN}, for the request.
#' Defaults to automatically detecting your key from your local .Renviron,
#' .Rprofile or similar. Alternatively, you may directly provide your key as
#' a string here or use functionality like that from \CRANpkg{keyring}. If
#' nothing is provided, you will be prompted on how to set up your \R session
#' so that it is auto-detected and a browser window will open at the
#' \acronym{TERN} website for you to request a key.
#'
#' @family COGs
#'
#' @examplesIf interactive()
#'
#' r <- read_cog(day = "2024-01-01")
#'
#' # terra::plot() is re-exported for convenience
#' plot(r)
#'
#' @return A [terra::rast] object
#' @references <https://portal.tern.org.au/metadata/TERN/d1995ee8-53f0-4a7d-91c2-ad5e4a23e5e0https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/d1995ee8-53f0-4a7d-91c2-ad5e4a23e5e0>
#' @export

read_cog <- function(data = "smips",
collection = "totalbucket",
day,
api_key = get_key()) {
day <- lubridate::ymd(day)
url_year <- lubridate::year(day)

if (data == "smips") {
collection_url <- .make_smips_url(.collection = collection, .day = day)
return(terra::rast(
paste0(
"/vsicurl/https://",
paste0("apikey:", api_key),
"@data.tern.org.au/model-derived/smips/v1_0/",
collection,
"/",
url_year,
"/",
.make_smips_url(.collection = collection, .day = day)
)
)
)
}
}
37 changes: 37 additions & 0 deletions R/read_cog_dt.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
#' Read COGs from TERN
#'
#' Read Cloud Optimised Geotiff (\acronym{COG}) files from \acronym{TERN} in
#' your active \R session as a \CRANpkg{data.table} object.
#'
#' @note
#' Currently only Soil Moisture Integration and Prediction System
#' (\acronym{SMIPS}) v1.0 is supported.
#'
#' @inherit read_cog
#'
#' @family COGs
#'
#' @examplesIf interactive()
#'
#' r <- read_cog_dt(day = "2024-01-01")
#'
#' r
#'
#' @return A [data.table::data.table] object
#' @references <https://portal.tern.org.au/metadata/TERN/d1995ee8-53f0-4a7d-91c2-ad5e4a23e5e0https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/d1995ee8-53f0-4a7d-91c2-ad5e4a23e5e0>
#' @export

read_cog_dt <- function(data = "smips",
collection = "totalbucket",
day,
api_key = get_key()) {
r <- read_cog(
data = data,
collection = collection,
day = day,
api_key = api_key
)
r <- data.table::setDT(terra::as.data.frame(r, xy = TRUE))
data.table::setnames(r, old = c("x", "y"), new = c("lon", "lat"))
return(r)
}
21 changes: 16 additions & 5 deletions README.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -26,21 +26,32 @@ The goal of {nert} is to provide access to Australian TERN (Terrestrial Ecosyste

You can install the development version of {nert} from [GitHub](https://github.com/AAGI-AUS/nert) with:

```{r install}
```{r install, eval=FALSE}
if (!require("pak")) {
install.packages("pak")
}
pak::pak("AAGI-AUS/nert")
```

## Example
## Example: reading a COG as a spatial object

This is a basic example which shows you how you can fetch one day's data and visualise it:
This is a basic example which shows you how you can fetch one day's data from the SMIPS data (currently the only supported data set in TERN) and visualise it:

```{r example}
```{r example_cog}
library(nert)
r <- get_smips(day = "2024-01-01")
r <- read_cog(day = "2024-01-01")
plot(r)
```

## Example reading a COG as a data.table

This is a basic example which shows you how you can fetch one day's data from the SMIPS data as a data.table:

```{r example_dt}
library(nert)
r <- read_cog_dt(day = "2024-01-01")
r
```
61 changes: 38 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,43 +1,36 @@
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->



# nert

<!-- badges: start -->

[![R-CMD-check](https://github.com/AAGI-AUS/nert/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/AAGI-AUS/nert/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/AAGI-AUS/nert/graph/badge.svg)](https://app.codecov.io/gh/AAGI-AUS/nert)
[![Codecov test
coverage](https://codecov.io/gh/AAGI-AUS/nert/graph/badge.svg)](https://app.codecov.io/gh/AAGI-AUS/nert)
<!-- badges: end -->

The goal of {nert} is to provide access to Australian TERN (Terrestrial Ecosystem Research Network) data in your R session.
The goal of {nert} is to provide access to Australian TERN (Terrestrial
Ecosystem Research Network) data in your R session.

## Installation

You can install the development version of {nert} from [GitHub](https://github.com/AAGI-AUS/nert) with:

You can install the development version of {nert} from
[GitHub](https://github.com/AAGI-AUS/nert) with:

``` r
if (!require("pak")) {
install.packages("pak")
}
#> Loading required package: pak

pak::pak("AAGI-AUS/nert")
#>
#> Found 1 deps for 0/1 pkgs [⠋] Resolving AAGI-AUS/nert Found 1 deps for 0/1 pkgs [⠙] Resolving AAGI-AUS/nert Found 1 deps for 0/1 pkgs [⠹] Resolving AAGI-AUS/nert Found 1 deps for 0/1 pkgs [⠸] Resolving AAGI-AUS/nert Found 1 deps for 0/1 pkgs [⠼] Resolving AAGI-AUS/nertℹ Loading metadata database ✔ Loading metadata database ... done
#> Found 1 deps for 0/1 pkgs [⠼] Resolving AAGI-AUS/nert Found 7 deps for 1/1 pkgs [⠴] Checking installed packages Found 7 deps for 1/1 pkgs [⠦] Checking installed packages Found 7 deps for 1/1 pkgs [⠧] Resolving standard (CRAN/BioC) packages
#> ℹ No downloads are needed
#> Installing... ✔ 1 pkg + 8 deps: kept 8 [4.6s]
```

## Example

This is a basic example which shows you how you can fetch one day's data and visualise it:
## Example: reading a COG as a spatial object

This is a basic example which shows you how you can fetch one day’s data
from the SMIPS data (currently the only supported data set in TERN) and
visualise it:

``` r
library(nert)
Expand All @@ -49,12 +42,34 @@ library(nert)
#> The following object is masked from 'package:base':
#>
#> plot
r <- get_smips(day = "2024-01-01")
r <- read_cog(day = "2024-01-01")

plot(r)
```

<div class="figure">
<img src="man/figures/README-example-1.png" alt="plot of chunk example" width="100%" />
<p class="caption">plot of chunk example</p>
</div>
<img src="man/figures/README-example_cog-1.png" width="100%" />

## Example reading a COG as a data.table

This is a basic example which shows you how you can fetch one day’s data
from the SMIPS data as a data.table:

``` r
library(nert)
r <- read_cog_dt(day = "2024-01-01")

r
#> lon lat smips_totalbucket_mm_20240101
#> <num> <num> <num>
#> 1: 142.5328 -10.69951 38.68500
#> 2: 142.5228 -10.70951 43.40917
#> 3: 142.5328 -10.70951 41.99442
#> 4: 142.4428 -10.71951 38.94186
#> 5: 142.4928 -10.71951 43.28778
#> ---
#> 6873516: 146.8517 -43.62003 40.96997
#> 6873517: 146.8617 -43.62003 38.49732
#> 6873518: 146.8717 -43.62003 48.08897
#> 6873519: 146.8517 -43.63003 33.92958
#> 6873520: 146.8617 -43.63003 32.85794
```
69 changes: 69 additions & 0 deletions man/download_gtiff.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Binary file removed man/figures/README-example-1.png
Binary file not shown.
Binary file added man/figures/README-example_cog-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed man/figures/README-pressure-1.png
Binary file not shown.
Loading

0 comments on commit 7ffb387

Please sign in to comment.