Skip to contents

Extract soil moisture data from TERN's SMIPS using Australian GPS coordinates

Source: R/extract_smips.R
extract_smips.Rd

Extracts the soil moisture at the GPS points provided assuming that they are land-based coordinates in Australia from the Soil Moisture Integration and Prediction System SMIPS data set.

Usage

extract_smips(
  xy,
  day,
  locations = NULL,
  lonlat = NULL,
  collection = "totalbucket",
  api_key = nert::get_key(),
  max_tries = 3L,
  initial_delay = 1L
)

Source

You must be logged in to view this. https://data.tern.org.au/model-derived/smips/v1_0/

Arguments

xy

A list or data.frame object with names containing pairings of longitude and latitude values expressed as decimal degree values in that order. A data.frame may also be an sf points object. See Details for more.

day

A vector of date(s) to query, e.g., day = "2017-12-31" or day = seq.Date(as.Date("2017-12-01"), as.Date("2017-12-31"), "days"), both Character and Date classes are accepted.

locations

The column in which the location names are located as an Integer value. Defaults to 1.

lonlat

A vector of integer values indicating the column index in which the longitude and latitude values are contained. Defaults to 2:3.

collection

A character vector of the data collection to be queried, currently only “smips” is supported with the following collections:

  • SMindex

  • bucket1

  • bucket2

  • deepD

  • runoff

  • totalbucket.

Defaults to “totalbucket”. Multiple collections are supported, e.g., collection = c("SMindex", "totalbucket").

api_key

A character string containing your API key, a random string provided to you by 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 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 TERN website for you to request a key.

max_tries

An integer Integer with the number of times to retry a failed download before emitting an error message. Defaults to 3.

initial_delay

An Integer with the number of seconds to delay before retrying the download. This increases as the tries increment. Defaults to 1.

Value

A data.table::data.table() with the provided GPS coordinates and the respective soil moisture data from SMIPS and coordinates from the SMIPS ("smips_longitude" and "smips_latitude").

xy

xy as a List Object

If xy is a list object, each individual vector's items should be named “x” (longitude) and “y” (latitude), respectively. The list item names should be descriptive of the individual vectors and will be included in a “location” column of the output.

xy as a Data Frame Object

If xy is a data.frame, it should be a three column object with the first column being the location name, the second longitude and the third, latitude both as decimal degrees in numeric format.

xy as an sf Object

If xy is an sf object, it should only be point geometry. If the data are projected, they will be reprojected to "EPSG:4326", Geographic Coordinate System WGS 84 before the extraction.

References

https://portal.tern.org.au/metadata/TERN/d1995ee8-53f0-4a7d-91c2-ad5e4a23e5e0

Examples

locs <- list(
  "Merredin" = c(x = 118.28, y = -31.48),
  "Corrigin" = c(x = 117.87, y = -32.33),
  "Tamworth" = c(x = 150.84, y = -31.07)
)

extract_smips(xy = locs, day = "2023-09-23")
#>   location      x      y smips_totalbucket_mm  smips_x   smips_y       date
#> 1 Corrigin 117.87 -32.33             49.20638 117.8688 -32.33328 2023-09-23
#> 2 Merredin 118.28 -31.48             44.84359 118.2787 -31.48353 2023-09-23
#> 3 Tamworth 150.84 -31.07             87.90719 150.8408 -31.07365 2023-09-23