Package 'nert' reference manual

Title:	An API Client for TERN Data
Description:	Provides access to Australia's TERN (Terrestrial Ecosystem Research Network) data through the API, <https://www.tern.org.au/>.
Authors:	Adam H. Sparks [aut] (ORCID: <https://orcid.org/0000-0002-0061-8359>), Wasin Pipattungsakul [aut], Russell Edson [aut] (ORCID: <https://orcid.org/0000-0002-4607-5396>), Sam Rogers [cre, aut] (ORCID: <https://orcid.org/0000-0002-8147-1239>), Max Moldovan [aut] (ORCID: <https://orcid.org/0000-0001-9680-8474>), Curtin University [cph] (Provided support through Adam Sparks's time., ROR: <https://ror.org/02n415q13>), Grains Research and Development Corporation [fnd, cph] (GRDC Project CUR2210-005OPX (AAGI-CU), ROR: <https://ror.org/02xwr1996>)
Maintainer:	Sam Rogers <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.0
Built:	2026-06-09 03:56:37 UTC
Source:	https://github.com/AAGI-AUS/nert

Collect TERN Data Over Time and Space

Description

Extract values from one or more TERN datasets at given location(s) over a date range. Returns a data.table with one row per (date, location) and one column per dataset layer. Static datasets are repeated across all dates.

Usage

collect_tern_data(
  date_range,
  lon = NULL,
  lat = NULL,
  xy = NULL,
  datasets = NULL,
  depth = "all",
  stat = "EV",
  smips_collection = "all",
  api_key = NULL,
  verbose = TRUE,
  na.rm = FALSE
)
collect_tern_data(
  date_range,
  lon = NULL,
  lat = NULL,
  xy = NULL,
  datasets = NULL,
  depth = "all",
  stat = "EV",
  smips_collection = "all",
  api_key = NULL,
  verbose = TRUE,
  na.rm = FALSE
)

Arguments

date_range

A Date vector or character vector of dates (e.g.\ seq(as.Date("2024-01-01"), as.Date("2024-01-31"), by = "day")) OR a length-2 vector giving start and end dates (e.g.\ c("2024-01-01", "2024-01-31")).

lon

Longitude(s) (WGS84, EPSG:4326). Numeric scalar or vector (same length as lat). Omit if using xy notation.

lat

Latitude(s) (WGS84, EPSG:4326). Numeric scalar or vector (same length as lon). Omit if using xy notation.

xy

Optional: a data.frame, data.table, or matrix with coordinate columns named lon/lat or x/y. Takes precedence over lon/lat when supplied.

datasets

character vector of dataset aliases to collect. Default: all 14 datasets (SMIPS, ASC, AET, AWC, CLY, SND, SLT, BDW, PHC, PHW, NTO, SOILDIV, CANOPY, PHENOLOGY). Use NULL or "all" for all datasets.

depth

For SLGA datasets: depth interval (default "all"). Options: "000_005", "005_015", "015_030", "030_060", "060_100", "100_200", or "all" for all six GlobalSoilMap depths. Ignored for non-SLGA datasets.

stat

For SLGA datasets: "EV" (estimate, default) or "CI" (confidence interval). Ignored for non-SLGA datasets.

smips_collection

For SMIPS: "all" (default, all six variants), "totalbucket", "SMindex", "bucket1", "bucket2", "deepD", or "runoff". Ignored for non-SMIPS datasets.

api_key

TERN API key. Default: get_key().

verbose

Logical. If TRUE, print progress messages.

na.rm

Logical. If TRUE, drop rows where all dataset columns are NA.

Details

Vectorised extraction. For each unique COG required (a (dataset, date, variant, depth) tuple), the function opens the COG once and calls terra::extract() once with all requested coordinates as a single SpatVector. Returning M locations × N dates across K work items therefore costs K COG opens and K extract calls, not M × K. Time-series datasets contribute one work item per date; static datasets contribute one work item total (the value is replicated across the date axis at output assembly time).

Column naming.

SMIPS with smips_collection = "all": six columns named SMIPS_totalbucket, SMIPS_SMindex, SMIPS_bucket1, SMIPS_bucket2, SMIPS_deepD, SMIPS_runoff.
SMIPS with a single collection: one column ⁠SMIPS_<collection>⁠.
SLGA with depth = "all": six columns per dataset (e.g.\ AWC_000_005 ... AWC_100_200).
SLGA with a single depth: one column named for the dataset alias.
AET: one column AET.
ASC: one column ASC (character soil-order class).
CANOPY, SOILDIV, PHENOLOGY: one column each named for the alias.

Failure handling. If a work item's COG fetch or extract fails, the corresponding column(s) remain NA for the affected rows and a cli::cli_warn() identifies the dataset/date/error. The output schema (column count and names) is fixed at planning time and is invariant under per-COG failure.

Value

A data.table with columns:

date: Date.
lon, lat: coordinates (always included; constant when a single location is requested).
One column per dataset layer. See Details for naming.

Examples


# Single location, single dataset
dates <- seq(as.Date("2024-01-01"), as.Date("2024-01-05"), by = "day")
d_t <- collect_tern_data(
  date_range = dates,
  lon = 138.6,
  lat = -34.9,
  datasets = c("SMIPS", "CLY")
)
head(d_t)

# Multiple locations (vectorised across points within each COG)
d_t_multi <- collect_tern_data(
  lon = c(138.6, 139.5),
  lat = c(-34.9, -35.5),
  date_range = dates,
  datasets = c("SMIPS", "CANOPY")
)

# xy data.frame notation
xy <- data.frame(lon = c(138.6, 139.5), lat = c(-34.9, -35.5))
d_t_xy <- collect_tern_data(
  xy = xy,
  date_range = dates,
  datasets = "CLY"
)

# Single location, single dataset
dates <- seq(as.Date("2024-01-01"), as.Date("2024-01-05"), by = "day")
d_t <- collect_tern_data(
  date_range = dates,
  lon = 138.6,
  lat = -34.9,
  datasets = c("SMIPS", "CLY")
)
head(d_t)

# Multiple locations (vectorised across points within each COG)
d_t_multi <- collect_tern_data(
  lon = c(138.6, 139.5),
  lat = c(-34.9, -35.5),
  date_range = dates,
  datasets = c("SMIPS", "CANOPY")
)

# xy data.frame notation
xy <- data.frame(lon = c(138.6, 139.5), lat = c(-34.9, -35.5))
d_t_xy <- collect_tern_data(
  xy = xy,
  date_range = dates,
  datasets = "CLY"
)

Get or Set Up API Key for TERN

Description

Checks first to get key from your .Rprofile or .Renviron (or similar) file. If it's not found, then it suggests setting it up. Can be used to check that your key that R is using is the key that you wish to be using or for guidance in setting up the keys.

Usage

get_key()
get_key()

Value

A string value with your API key value.

Requesting an API Key

To request an API key, go to https://account.tern.org.au/authenticated_user/apikeys and click on "Sign In" in the upper right corner. Sign in with your proper credentials. Then, from the left-hand menu, click on "Create API Key". Once this is done, copy the key and put it in your .Renviron using usethis::edit_r_environ() as TERN_API_KEY="your_api_key". Restart your R session and the query should work.

The suggestion is to use your .Renviron to set up the API key. However, if you regularly interact with the APIs outside of R using some other language you may wish to set these up in your .bashrc, .zshrc, or config.fish for cross-language use.

Note

TERN creates API keys that have special characters that include “/”, which causes the query to fail. Currently, the ⁠read_*()⁠ functions will test for these problematic characters and replace them with the HTML-safe equivalents where necessary so that the query will work properly. However, get_key() simply returns the API key verbatim.

Examples

## Not run: 
get_key()

## End(Not run)

## Not run: 
get_key()

## End(Not run)

Synthetic dataset for a grain production experiment in South Australia

Description

Data from a fabricated experiment investigating the effects of Nitrogen application and seeding rate on grain production for a crop, conducted across 10 fictional sites in South Australia. The variables are as follows:

Site: The experiment site locations.
Latitude: Latitude for the site, recorded in decimal degrees Northing.
Longitude: Longitude for the site, in decimal degrees Easting.
SowDate: The date that the crops were sown.
NitrogenDate: The date that the Nitrogen treatments were applied.
Rep: Replicate number. (Each site has 3 replicates.)
Variety: The anonymised variety (8 levels).
Nitrogen_kgNha: The applied Nitrogen rate treatment, in kg N/ha.
SeedRate_plantsm2: The seeding rate, measured in target establishment plants/m2.
Yield_Tha: The measured grain yield for the plot in T/ha.

Usage

data(grain)
data(grain)

Format

A data frame with 2880 rows and 10 variables

Read CMRSET Actual Evapotranspiration Data

Description

Wrapper around read_tern() for TERN/CMRSET evapotranspiration data. Provides monthly estimates of actual ET (mm/month) at 30 m resolution from February 2000 onwards.

Usage

read_aet(
  date,
  collection = "ETa",
  api_key = NULL,
  max_tries = NULL,
  initial_delay = NULL
)
read_aet(
  date,
  collection = "ETa",
  api_key = NULL,
  max_tries = NULL,
  initial_delay = NULL
)

Arguments

date

A month to download (Date or character, e.g. "2023-06-01" or as.Date("2023-06-01")). The value is snapped to the first of the month internally. Required.

collection

One of "ETa" (actual evapotranspiration in mm/month, default) or "pixel_qa" (quality assurance flags).

api_key

A character string containing your TERN API key. Defaults to automatic detection from your .Renviron or .Rprofile. See get_key() for setup.

max_tries

Maximum number of download retries before an error is raised. When NULL (default), resolved from getOption("nert.max_tries", 3L). Pass an integer to override for a single call.

initial_delay

Initial retry delay in seconds (doubles with each attempt). When NULL (default), resolved from getOption("nert.initial_delay", 1L). Pass an integer to override for a single call.

Value

A terra::rast() object of the requested ET collection.

References

CMRSET portal: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/9fefa68b-dbed-4c20-88db-a9429fb4ba97

CMRSET DOI: doi:10.25901/gg27-ck96

Examples


# Actual evapotranspiration (ETa) for June 2023 (mm/month)
r_eta <- read_aet("2023-06-01")
autoplot(r_eta)

# January 2023 ET
r_jan <- read_aet("2023-01-01")

# Quality assurance flags for June 2023
r_qa <- read_aet("2023-06-01", collection = "pixel_qa")

# ET from February 2000 (earliest available)
r_early <- read_aet("2000-02-01")

# Current/recent ET (within last month)
r_recent <- read_aet(Sys.Date())

# Actual evapotranspiration (ETa) for June 2023 (mm/month)
r_eta <- read_aet("2023-06-01")
autoplot(r_eta)

# January 2023 ET
r_jan <- read_aet("2023-01-01")

# Quality assurance flags for June 2023
r_qa <- read_aet("2023-06-01", collection = "pixel_qa")

# ET from February 2000 (earliest available)
r_early <- read_aet("2000-02-01")

# Current/recent ET (within last month)
r_recent <- read_aet(Sys.Date())

Read Australian Soil Classification (ASC) Data

Description

Wrapper around read_tern() for Australian Soil Classification (ASC) soil order classes at 90 m resolution. Returns character soil order descriptions (e.g., "2 - Sodosol") with optional mapping reliability (confusion index).

Usage

read_asc(
  confusion_index = FALSE,
  api_key = get_key(),
  max_tries = NULL,
  initial_delay = NULL
)
read_asc(
  confusion_index = FALSE,
  api_key = get_key(),
  max_tries = NULL,
  initial_delay = NULL
)

Arguments

confusion_index

A logical value. If FALSE (default), returns estimated ASC soil order classes (character). If TRUE, returns the Confusion Index (numeric, 0-100) indicating mapping reliability.

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

Maximum number of download retries before an error is raised. When NULL (default), resolved from getOption("nert.max_tries", 3L). Pass an integer to override for a single call.

initial_delay

Initial retry delay in seconds (doubles with each attempt). When NULL (default), resolved from getOption("nert.initial_delay", 1L). Pass an integer to override for a single call.

Details

The ASC dataset provides soil order classifications based on the Australian Soil Classification system. Each pixel contains the predicted soil order and associated reliability/uncertainty estimates.

Output data type: Character (soil order names and codes)

Reliability: Confusion Index indicates mapping uncertainty (lower = more reliable)

Value

A terra::rast() object.

Source

ASC mosaic metadata (estimated soil-order class and confusion index): https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/15728dba-b49c-4da5-9073-13d8abe67d7c. The underlying COG endpoints (ASC_EV_C_P_AU_TRN_N.cog.tif and ASC_CI_C_P_AU_TRN_N.cog.tif under /model-derived/slga/NationalMaps/SoilClassifications/ASC/90m/ on data.tern.org.au) require an authenticated request and are constructed internally by this package.

References

https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/15728dba-b49c-4da5-9073-13d8abe67d7c

Examples



# Australian Soil Classification (soil orders as character)
r_asc <- read_asc()
autoplot(r_asc)

# Confusion Index (mapping reliability, lower = more reliable)
r_ci <- read_asc(confusion_index = TRUE)
autoplot(r_ci)

# Australian Soil Classification (soil orders as character)
r_asc <- read_asc()
autoplot(r_asc)

# Confusion Index (mapping reliability, lower = more reliable)
r_ci <- read_asc(confusion_index = TRUE)
autoplot(r_ci)

Read Canopy Height from TERN

Description

Read the OzTreeMap Canopy Height composite Cloud Optimised GeoTIFF (COG) from TERN. This product provides a nationwide canopy height map at 30 m resolution derived from Landsat imagery.

Usage

read_canopy_height(api_key = get_key(), max_tries = NULL, initial_delay = NULL)
read_canopy_height(api_key = get_key(), max_tries = NULL, initial_delay = NULL)

Arguments

api_key

A character string containing your TERN API key. Defaults to automatic detection via get_key().

max_tries

Maximum number of download retries before an error is raised. When NULL (default), resolved from getOption("nert.max_tries", 3L). Pass an integer to override for a single call.

initial_delay

Initial retry delay in seconds (doubles with each attempt). When NULL (default), resolved from getOption("nert.initial_delay", 1L). Pass an integer to override for a single call.

Details

This is a single static product — no date or collection arguments are required.

This is a convenience wrapper around read_tern("CANOPY"); see read_tern() for full details and additional datasets.

Value

A terra::rast() object of the national OzTreeMap canopy height composite.

References

https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/36c98155-c137-44b8-b4e0-6a3e824bbfba

Examples


r <- read_canopy_height()
autoplot(r)

r <- read_canopy_height()
autoplot(r)

Read Land Surface Phenology from TERN

Description

Read Australian Land Surface Phenology Cloud Optimised GeoTIFF (COG) files from TERN. This product provides phenological metrics derived from MODIS MYD13A1 imagery at 500 m resolution. Data are available for years 2003–2018, with up to two growing seasons per year.

Usage

read_phenology(
  year = NULL,
  season = 1L,
  collection = "SGS",
  api_key = get_key(),
  max_tries = NULL,
  initial_delay = NULL
)
read_phenology(
  year = NULL,
  season = 1L,
  collection = "SGS",
  api_key = get_key(),
  max_tries = NULL,
  initial_delay = NULL
)

Arguments

year

An integer year (2003–2018).

season

Season number: 1 (default) or 2.

collection

Phenology metric abbreviation. One of "SGS" (default), "PGS", "EGS", "LGS", "SOS", "POS", "EOS", "LOS", "ROG", or "ROS".

api_key

A character string containing your TERN API key. Defaults to automatic detection via get_key().

max_tries

Maximum number of download retries before an error is raised. When NULL (default), resolved from getOption("nert.max_tries", 3L). Pass an integer to override for a single call.

initial_delay

Initial retry delay in seconds (doubles with each attempt). When NULL (default), resolved from getOption("nert.initial_delay", 1L). Pass an integer to override for a single call.

Value

A terra::rast() object of the national phenology mosaic for the requested year, season, and metric.

Phenology metrics

Ten phenological metrics are available (use as the collection argument):

"SGS": Start of Growing Season (default).
"PGS": Peak of Growing Season.
"EGS": End of Growing Season.
"LGS": Length of Growing Season.
"SOS": Start of Season.
"POS": Peak of Season.
"EOS": End of Season.
"LOS": Length of Season.
"ROG": Rate of Greening.
"ROS": Rate of Senescence.

This is a convenience wrapper around read_tern("PHENOLOGY", ...); see read_tern() for full details and additional datasets.

References

https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/2bb0c81a-5a09-4a0e-bd86-5cd2be8def26

Examples


# Read Start of Growing Season for 2018, Season 1
r <- read_phenology(year = 2018)
autoplot(r)

# Read End of Growing Season for 2015, Season 2
r_egs <- read_phenology(year = 2015, season = 2, collection = "EGS")
autoplot(r_egs)

# Rate of Greening
r_rog <- read_phenology(year = 2010, collection = "ROG")

# Read Start of Growing Season for 2018, Season 1
r <- read_phenology(year = 2018)
autoplot(r)

# Read End of Growing Season for 2015, Season 2
r_egs <- read_phenology(year = 2015, season = 2, collection = "EGS")
autoplot(r_egs)

# Rate of Greening
r_rog <- read_phenology(year = 2010, collection = "ROG")

Read SLGA Soil Attributes from TERN

Description

Read Soil and Landscape Grid of Australia (SLGA) Cloud Optimised GeoTIFF (COG) files from TERN. Eight soil attributes are available as static 90 m national products, each with six standard depth layers and two statistics (estimated value or confidence interval).

Usage

read_slga(
  attribute,
  depth = "000_005",
  collection = "EV",
  api_key = get_key(),
  max_tries = NULL,
  initial_delay = NULL
)
read_slga(
  attribute,
  depth = "000_005",
  collection = "EV",
  api_key = get_key(),
  max_tries = NULL,
  initial_delay = NULL
)

Arguments

attribute

One of "AWC", "CLY", "SND", "SLT", "BDW", "PHC", "PHW", or "NTO".

depth

One of "000_005" (default), "005_015", "015_030", "030_060", "060_100", or "100_200".

collection

One of "EV" (estimated value, default) or "CI" (confidence interval).

api_key

A character string containing your TERN API key. Defaults to automatic detection via get_key().

max_tries

Maximum number of download retries before an error is raised. When NULL (default), resolved from getOption("nert.max_tries", 3L). Pass an integer to override for a single call.

initial_delay

Initial retry delay in seconds (doubles with each attempt). When NULL (default), resolved from getOption("nert.initial_delay", 1L). Pass an integer to override for a single call.

Value

A terra::rast() object of the national SLGA mosaic for the requested attribute, depth, and statistic.

Supported attributes

"AWC": Available Water Capacity (mm)
"CLY": Clay content (percent)
"SND": Sand content (percent)
"SLT": Silt content (percent)
"BDW": Bulk Density whole earth (g/cm3)
"PHC": pH (CaCl2)
"PHW": pH (water)
"NTO": Total Nitrogen (percent)

Depth layers

Six standard GlobalSoilMap depth intervals are available (values in cm):

"000_005" — 0--5 cm (default)

"005_015" — 5--15 cm

"015_030" — 15--30 cm

"030_060" — 30--60 cm

"060_100" — 60--100 cm

"100_200" — 100--200 cm

This is a convenience wrapper around read_tern(<attribute>, ...); see read_tern() for full details and additional datasets.

References

AWC: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/482301c2-2837-4b0b-bf95-4883a04e5ff7

SLGA: https://esoil.io/TERNLandscapes/Public/Pages/SLGA/

Examples


# Read clay content at 0-5 cm depth
r <- read_slga("CLY")
autoplot(r)

# Read available water capacity at 15-30 cm
r_awc <- read_slga("AWC", depth = "015_030")

# Read pH (CaCl2) confidence interval at 30-60 cm
r_phc <- read_slga("PHC", depth = "030_060", collection = "CI")

# Read clay content at 0-5 cm depth
r <- read_slga("CLY")
autoplot(r)

# Read available water capacity at 15-30 cm
r_awc <- read_slga("AWC", depth = "015_030")

# Read pH (CaCl2) confidence interval at 30-60 cm
r_phc <- read_slga("PHC", depth = "030_060", collection = "CI")

Read TERN SMIPS Soil Moisture Data

Description

Wrapper around read_tern() for TERN/SMIPS daily soil moisture data. Provides soil moisture estimates at 1 km resolution from November 2015 to approximately 7 days before today.

Usage

read_smips(
  date,
  collection = "totalbucket",
  api_key = NULL,
  max_tries = NULL,
  initial_delay = NULL
)
read_smips(
  date,
  collection = "totalbucket",
  api_key = NULL,
  max_tries = NULL,
  initial_delay = NULL
)

Arguments

date

A day to download (Date or character, e.g. "2024-01-15" or as.Date("2024-01-15")). Required.

collection

SMIPS collection variant (default "totalbucket"). Options:

"totalbucket": Total soil moisture in the full active layer (mm). Represents the total water stored in all soil layers of the active profile. Use for: Overall soil water availability, drought monitoring. Output column: SMIPS_totalbucket
"SMindex": Soil Moisture Index, 0-100% (standardized metric). Rescaled to 0-100% for comparison across regions and seasons. Use for: Regional comparisons, anomaly detection, percentage-based thresholds. Output column: SMIPS_SMindex
"bucket1": Top soil layer moisture (mm, typically 0-10 cm). Represents water in surface soil where seeds germinate and shallow roots operate. Use for: Shallow-rooting plants, seed germination, surface runoff prediction. Output column: SMIPS_bucket1
"bucket2": Second soil layer moisture (mm, typically 10-40 cm). Represents water in intermediate soil depth where many plant roots develop. Use for: Typical crop rooting depth, plant-available water. Output column: SMIPS_bucket2
"deepD": Deep soil layer moisture (mm, typically >40 cm). Represents water in deeper soil layers accessed by deep-rooting plants. Use for: Deep-rooting trees/shrubs, groundwater recharge, long-term drought. Output column: SMIPS_deepD
"runoff": Surface runoff (mm). Represents water predicted to run off the surface (not infiltrate). Use for: Flood risk, erosion modeling, drainage engineering. Output column: SMIPS_runoff

api_key

A character string containing your TERN API key. Defaults to automatic detection from your .Renviron or .Rprofile. See get_key() for setup.

max_tries

Maximum number of download retries before an error is raised. When NULL (default), resolved from getOption("nert.max_tries", 3L). Pass an integer to override for a single call.

initial_delay

Initial retry delay in seconds (doubles with each attempt). When NULL (default), resolved from getOption("nert.initial_delay", 1L). Pass an integer to override for a single call.

Value

A terra::rast() object of the requested SMIPS collection.

References

SMIPS portal: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/d1995ee8-53f0-4a7d-91c2-ad5e4a23e5e0

Examples


# Total bucket soil moisture (default)
r <- read_smips("2024-01-15")
autoplot(r)

# Soil moisture index (0-100%)
r_smi <- read_smips("2024-01-15", collection = "SMindex")

# Top soil bucket (shallow rooting plants)
r_bucket1 <- read_smips("2024-01-15", collection = "bucket1")

# Deep soil layer (deep rooting plants)
r_deep <- read_smips("2024-01-15", collection = "deepD")

# Surface runoff
r_runoff <- read_smips("2024-01-15", collection = "runoff")

# Total bucket soil moisture (default)
r <- read_smips("2024-01-15")
autoplot(r)

# Soil moisture index (0-100%)
r_smi <- read_smips("2024-01-15", collection = "SMindex")

# Top soil bucket (shallow rooting plants)
r_bucket1 <- read_smips("2024-01-15", collection = "bucket1")

# Deep soil layer (deep rooting plants)
r_deep <- read_smips("2024-01-15", collection = "deepD")

# Surface runoff
r_runoff <- read_smips("2024-01-15", collection = "runoff")

Read Soil Beta Diversity from TERN

Description

Read Soil Beta Diversity Cloud Optimised GeoTIFF (COG) files from TERN. This product provides Non-metric Multidimensional Scaling (NMDS) axes 1–3 for soil Bacteria and Fungi communities across Australia at 90 m resolution.

Usage

read_soil_diversity(
  collection = "Bacteria",
  axis = 1L,
  api_key = get_key(),
  max_tries = NULL,
  initial_delay = NULL
)
read_soil_diversity(
  collection = "Bacteria",
  axis = 1L,
  api_key = get_key(),
  max_tries = NULL,
  initial_delay = NULL
)

Arguments

collection

One of "Bacteria" (default) or "Fungi".

axis

NMDS axis number: 1 (default), 2, or 3.

api_key

A character string containing your TERN API key. Defaults to automatic detection via get_key().

max_tries

Maximum number of download retries before an error is raised. When NULL (default), resolved from getOption("nert.max_tries", 3L). Pass an integer to override for a single call.

initial_delay

Initial retry delay in seconds (doubles with each attempt). When NULL (default), resolved from getOption("nert.initial_delay", 1L). Pass an integer to override for a single call.

Value

A terra::rast() object of the national Soil Beta Diversity mosaic for the requested organism and NMDS axis.

Collections

"Bacteria": Bacterial community beta diversity (default).
"Fungi": Fungal community beta diversity.

This is a static product (no date argument required).

This is a convenience wrapper around read_tern("SOILDIV", ...); see read_tern() for full details and additional datasets.

References

https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/4a428d52-d15c-4bfc-8a67-80697f8c0aa0

Examples


# Read bacterial diversity NMDS axis 1
r <- read_soil_diversity()
autoplot(r)

# Read fungal diversity NMDS axis 2
r_f2 <- read_soil_diversity(collection = "Fungi", axis = 2)
autoplot(r_f2)

# Read bacterial diversity NMDS axis 1
r <- read_soil_diversity()
autoplot(r)

# Read fungal diversity NMDS axis 2
r_f2 <- read_soil_diversity(collection = "Fungi", axis = 2)
autoplot(r_f2)

Read TERN COG Datasets

Description

A unified interface for reading Cloud Optimised GeoTIFF (COG) data from TERN and related repositories. Dispatches to a dataset-specific handler based on dataset_id and passes any additional arguments through .... The returned object is a terra::rast() that can be plotted, cropped, or extracted with standard terra or tidyterra workflows.

Usage

read_tern(
  dataset_id,
  ...,
  api_key = NULL,
  max_tries = NULL,
  initial_delay = NULL
)
read_tern(
  dataset_id,
  ...,
  api_key = NULL,
  max_tries = NULL,
  initial_delay = NULL
)

Arguments

dataset_id

A character string identifying the dataset. Accepts a short alias, the full TERN portal key (e.g.\ "TERN/d1995ee8-53f0-4a7d-91c2-ad5e4a23e5e0"), or the 8-character key prefix (e.g.\ "TERN/d1995ee8"). See the Dataset aliases section for the complete table of supported aliases.

...

Dataset-specific arguments — date, collection, etc. See the relevant section above for each dataset.

api_key

A character string containing your TERN API key. Defaults to automatic detection from your .Renviron or .Rprofile. See get_key for setup instructions.

max_tries

Maximum number of download retries before an error is raised. When NULL (default), resolved from getOption("nert.max_tries", 3L). Pass an integer to override for a single call.

initial_delay

Initial retry delay in seconds (doubles with each attempt). When NULL (default), resolved from getOption("nert.initial_delay", 1L). Pass an integer to override for a single call.

Value

A terra::rast() object of the national mosaic for the requested dataset (and, where applicable, date/collection).

Dataset aliases

In addition to full TERN portal keys and 8-character prefixes, read_tern() accepts short human-readable aliases (case-insensitive):

Alias	Dataset ID	Description
`"SMIPS"`	`TERN/d1995ee8`	Daily soil moisture (~1 km)
`"ASC"`	`TERN/15728dba`	Australian Soil Classification (90 m)
`"AET"`	`TERN/9fefa68b`	Monthly evapotranspiration (CMRSET)
`"AWC"`	`TERN/482301c2`	Available Water Capacity (90 m)
`"CLY"`	SLGA	Clay content (90 m)
`"SND"`	SLGA	Sand content (90 m)
`"SLT"`	SLGA	Silt content (90 m)
`"BDW"`	SLGA	Bulk density whole earth (90 m)
`"PHC"`	SLGA	pH CaCl2 (90 m)
`"PHW"`	SLGA	pH water (90 m)
`"NTO"`	SLGA	Total Nitrogen (90 m)
`"SOILDIV"`	`TERN/4a428d52`	Soil Beta Diversity (90 m)
`"CANOPY"`	`TERN/36c98155`	Canopy Height (30 m)
`"PHENOLOGY"`	`TERN/2bb0c81a`	Land Surface Phenology (500 m)

Convenience wrappers read_smips(), read_asc(), read_aet(), read_slga(), read_soil_diversity(), read_canopy_height(), and read_phenology() are also provided for direct access to each dataset.

SMIPS — daily soil moisture (`"TERN/d1995ee8"`)

date: Required. A single day to query, e.g. "2024-01-15" or as.Date("2024-01-15"). Both Character and Date classes are accepted.
collection: One of "totalbucket" (default), "SMindex", "bucket1", "bucket2", "deepD", or "runoff".

Data availability: 2015-11-20 to approximately 7 days before today.

ASC – Australian Soil Classification (`"TERN/15728dba"`)

collection: One of "EV" (estimated soil order class, default) or "CI" (confusion index – a measure of mapping reliability). No date argument required; this is a static product.

AET – Actual Evapotranspiration/CMRSET (`"TERN/9fefa68b"`)

date: Required. A month to query, e.g. "2023-06-01" or as.Date("2023-06-01"). Both Character and Date classes are accepted. The value is snapped to the first of the month internally.
collection: One of "ETa" (primary AET band in mm/month, default) or "pixel_qa" (quality assurance flags).

Data availability: 2000-02-01 onwards.

SLGA soil attributes (`"AWC"`, `"CLY"`, etc.)

Eight SLGA (Soil and Landscape Grid of Australia) soil attributes are available as static 90 m products, each with six standard depth layers and two statistics:

depth: One of "000_005" (default), "005_015", "015_030", "030_060", "060_100", or "100_200" (cm).
collection: One of "EV" (estimated value, default) or "CI" (confidence interval).

Supported attributes (use as the dataset_id alias):

"AWC": Available Water Capacity (mm)
"CLY": Clay content (percent)
"SND": Sand content (percent)
"SLT": Silt content (percent)
"BDW": Bulk Density whole earth (g/cm3)
"PHC": pH (CaCl2)
"PHW": pH (water)
"NTO": Total Nitrogen (percent)

Convenience wrapper: read_slga().

Soil Beta Diversity (`"SOILDIV"`, `TERN/4a428d52`)

collection: One of "Bacteria" (default) or "Fungi".
axis: NMDS axis number: 1 (default), 2, or 3.

Static 90 m product. Convenience wrapper: read_soil_diversity().

Canopy Height (`"CANOPY"`, `TERN/36c98155`)

Single static 30 m composite from the OzTreeMap project. No additional arguments required. Convenience wrapper: read_canopy_height().

Land Surface Phenology (`"PHENOLOGY"`, `TERN/2bb0c81a`)

year: Required. An integer year (2003–2018).
season: Season number: 1 (default) or 2.
collection: Phenology metric — one of "SGS" (Start of Growing Season, default), "PGS" (Peak), "EGS" (End), "LGS" (Length), "SOS" (Start of Season), "POS" (Peak of Season), "EOS" (End of Season), "LOS" (Length of Season), "ROG" (Rate of Greening), "ROS" (Rate of Senescence).

500 m MODIS resolution. Convenience wrapper: read_phenology().

Datasets not accessible

The following datasets are tracked in the TERN catalogue but cannot be accessed via COG HTTP range requests:

TERN/0997cb3c — Seasonal Fractional Cover (Landsat)
TERN/fe9d86e1 — Seasonal Ground Cover (Landsat)

Datasets with integration level L2 or higher (e.g.\ AusEFlux via THREDDS/OPeNDAP, GEE-based products, site-level API streams) cannot be read via simple COG HTTP range requests and are outside the current scope of nert.

Package options

nert reads two package-level options on every call. Both are set to package defaults at load time and may be overridden globally (e.g.\ in .Rprofile) without changing any individual call:

nert.max_tries: Default maximum number of download retries. Default 3L.
nert.initial_delay: Default initial retry delay in seconds (doubles each attempt). Default 1L.

Per-call values supplied via the max_tries or initial_delay arguments always override the option. Example:

  options(nert.max_tries = 5L, nert.initial_delay = 2L)

Closes AAGI-AUS/nert#20.

References

SMIPS: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/d1995ee8-53f0-4a7d-91c2-ad5e4a23e5e0

ASC: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/15728dba-b49c-4da5-9073-13d8abe67d7c

AET: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/9fefa68b-dbed-4c20-88db-a9429fb4ba97

AWC: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/482301c2-2837-4b0b-bf95-4883a04e5ff7

Soil Beta Diversity: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/4a428d52-d15c-4bfc-8a67-80697f8c0aa0

Canopy Height: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/36c98155-c137-44b8-b4e0-6a3e824bbfba

Land Surface Phenology: https://geonetwork.tern.org.au/geonetwork/srv/eng/catalog.search#/metadata/2bb0c81a-5a09-4a0e-bd86-5cd2be8def26

Examples


# Using aliases (recommended) ----------------------------------------
r <- read_tern("SMIPS", date = "2024-01-15")
r_asc <- read_tern("ASC")
autoplot(r_asc)

# SLGA soil attributes — depth and collection
r_clay <- read_tern("CLY", depth = "000_005")
r_awc  <- read_tern("AWC", depth = "015_030", collection = "CI")

# Soil Beta Diversity
r_bact <- read_tern("SOILDIV", collection = "Bacteria", axis = 1)

# Canopy Height (single static product)
r_ch <- read_tern("CANOPY")

# Land Surface Phenology
r_phen <- read_tern("PHENOLOGY", year = 2018, collection = "SGS")

# Full TERN keys still work ----------------------------------------
r2 <- read_tern("TERN/d1995ee8", date = "2024-01-15")

# Using aliases (recommended) ----------------------------------------
r <- read_tern("SMIPS", date = "2024-01-15")
r_asc <- read_tern("ASC")
autoplot(r_asc)

# SLGA soil attributes — depth and collection
r_clay <- read_tern("CLY", depth = "000_005")
r_awc  <- read_tern("AWC", depth = "015_030", collection = "CI")

# Soil Beta Diversity
r_bact <- read_tern("SOILDIV", collection = "Bacteria", axis = 1)

# Canopy Height (single static product)
r_ch <- read_tern("CANOPY")

# Land Surface Phenology
r_phen <- read_tern("PHENOLOGY", year = 2018, collection = "SGS")

# Full TERN keys still work ----------------------------------------
r2 <- read_tern("TERN/d1995ee8", date = "2024-01-15")

Package 'nert'

Help Index

Collect TERN Data Over Time and Space

Description

Usage

Arguments

Details

Value

Examples

Get or Set Up API Key for TERN

Description

Usage

Value

Requesting an API Key

Note

Examples

Synthetic dataset for a grain production experiment in South Australia

Description

Usage

Format

Read CMRSET Actual Evapotranspiration Data

Description

Usage

Arguments

Value

References

See Also

Examples

Read Australian Soil Classification (ASC) Data

Description

Usage

Arguments

Details

Value

Source

References

See Also

Examples

Read Canopy Height from TERN

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Read Land Surface Phenology from TERN

Description

Usage

Arguments

Value

Phenology metrics

References

See Also

Examples

Read SLGA Soil Attributes from TERN

Description

Usage

Arguments

Value

Supported attributes

Depth layers

References

See Also

Examples

Read TERN SMIPS Soil Moisture Data

Description

Usage

Arguments

Value

References

See Also

Examples

Read Soil Beta Diversity from TERN

Description

Usage

Arguments

Value

Collections

SMIPS — daily soil moisture (`"TERN/d1995ee8"`)

ASC – Australian Soil Classification (`"TERN/15728dba"`)

AET – Actual Evapotranspiration/CMRSET (`"TERN/9fefa68b"`)

SLGA soil attributes (`"AWC"`, `"CLY"`, etc.)

Soil Beta Diversity (`"SOILDIV"`, `TERN/4a428d52`)

Canopy Height (`"CANOPY"`, `TERN/36c98155`)

Land Surface Phenology (`"PHENOLOGY"`, `TERN/2bb0c81a`)