From 8a35ac7b8cda8500e48bfaba7b5bb53ded79a35c Mon Sep 17 00:00:00 2001 From: Koen Hufkens Date: Mon, 7 Aug 2023 11:13:11 +0200 Subject: [PATCH] update documentation --- README.md | 62 ++++++++++++++++++++++++++++++--- vignettes/hwsdr-v2-vignette.Rmd | 20 +++++------ 2 files changed, 67 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index addfc14..585c08f 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,9 @@ library("hwsdr") ### development release +> Breaking change: as of version 1.1 the order of the coordinates in the +location string has changed from (lat, lon, lat, lon) to (lon, lat, lon, lat)! + To install the development releases of the package run the following commands: @@ -45,24 +48,26 @@ library("hwsdr") ## Use -### Single pixel location download +### HWSD v1.2 (ORNL DAAC API) + +#### Single pixel location download Get world soil values for a single site using the following format, specifying coordinates as a pair of latitude, longitude coordinates. Here all available soil layers are queried. ``` r - all <- ws_subset( +all <- ws_subset( site = "HWSD", location = c(34, -81), param = "ALL" ) ``` -### Gridded data +#### Gridded data You can download gridded data by specifying a bounding box c(lat, lon, lat, lon) defined by a bottom left and top right coordinates. Here the call only extracts the top soil fraction of sand (% weight). ``` r - t_sand <- ws_subset( +t_sand <- ws_subset( site = "HWSD", location = c(32, -81, 34, -80), param = "T_SAND", @@ -70,10 +75,57 @@ You can download gridded data by specifying a bounding box c(lat, lon, lat, lon) internal = TRUE ) ``` -## Parameters +### Parameters By default all parameters are downloaded, a complete list of the individual parameters is provided on the ORNL webpage (). Alternatively you may find a similar list of data in the `hwsd_meta_data` dataset as provided by the package. +### HWSD v2.0 (FAO) + +This is an experimental feature, awaiting an update of the ORNL DAAC API to version 2.0 of the HWSD database. Although functionally complete the procedure is more complex as it includes a bulk download of a base map. + +#### Download the base map + +The HWSD v2.0 data is distributed as a gridded spatial map where homogeneous regions are indicated with indices (integers). Although the underlying database is included in the package and can be accessed using `hwsdr::hwsd2`, the spatial data accompanying the database is too large for inclusion in the package. This spatial data needs to be downloaded explicitly to a desired path before any other functions will work. + +```{r eval = FALSE} +# set the ws_path variable using a FULL path name +path <- ws_download( + ws_path = "/your/full/path", + verbose = TRUE +) +``` + +### Single pixel location download + +Get world soil values for a single site using the following format, specifying coordinates as a pair of longitude, latitude coordinates (longitude, latitude). Here the call only extracts the top soil (layer = "D1") fraction of sand and silt (% weight) for one specific location. Note that you will need to specify the correct version to be used in processing. + +```{r eval = FALSE} +values <- ws_subset( + site = "HWSD_V2", + location = c(-81, 34), + param = c("SAND","SILT"), + layer = "D1", + version = "2.0", # set correct HWSD version + ws_path = "/your/full/path" # specify grid map directory + ) +``` + +### Gridded data + +You can grab gridded data by specifying a bounding box c(lon, lat, lon, lat) defined by a bottom left and top right coordinates. Here the call only extracts the top soil (D1 layer) fraction of sand (%). + +```{r eval = FALSE} +sand <- ws_subset( + location = c(32, -81, 34, -80), + param = "SAND", + layer = "D1", + version = "2.0", + ws_path = Sys.getenv("WS_PATH"), + # ws_path = "/your/full/path", + internal = TRUE + ) +``` + ## References Wieder, W.R., J. Boehnert, G.B. Bonan, and M. Langseth. 2014. Regridded Harmonized World Soil Database v1.2. Data set. Available on-line from Oak Ridge National Laboratory Distributed Active Archive Center, Oak Ridge, Tennessee, USA. (). diff --git a/vignettes/hwsdr-v2-vignette.Rmd b/vignettes/hwsdr-v2-vignette.Rmd index a2e47bf..7644a44 100644 --- a/vignettes/hwsdr-v2-vignette.Rmd +++ b/vignettes/hwsdr-v2-vignette.Rmd @@ -45,7 +45,7 @@ Although the package provides support for the programmatic interface to the Harm ### Download the base map -The HWSD v2.0 data is distributed as a spatial map where homogenous regions are indicated with indices (integers). Although the underlying database is included in the package and can be accessed using `hwsdr::hwsd2`, the spatial data accompanying the database is too large for inclusion in the package. This spatial data needs to be downloaded explicitly. +The HWSD v2.0 data is distributed as a spatial map where homogeneous regions are indicated with indices (integers). Although the underlying database is included in the package and can be accessed using `hwsdr::hwsd2`, the spatial data accompanying the database is too large for inclusion in the package. This spatial data needs to be downloaded explicitly. Ideally, to speed up processing between sessions you download the data to a fixed location (directory) on your computer. The function `ws_download()` will download the data there. If successful the function will return the path where the data is located. @@ -79,13 +79,13 @@ Get world soil values for a single site using the following format, specifying c ```{r eval = FALSE} values <- ws_subset( - site = "HWSD_V2", - location = c(-81, 34), - param = c("SAND","SILT"), - layer = "D1", - version = "2.0", - ws_path = "/your/full/path" - ) + site = "HWSD_V2", + location = c(-81, 34), + param = c("SAND","SILT"), + layer = "D1", + version = "2.0", + ws_path = "/your/full/path" +) ``` At this location we have a top soil fraction of sand of 78% weight and a silt fraction of 12 % weight! Data are returned as tidy data frames including basic meta-data of the query for later subsetting. @@ -99,8 +99,8 @@ print(values) You can grab gridded data by specifying a bounding box c(lon, lat, lon, lat) defined by a bottom left and top right coordinates. Here the call only extracts the top soil (D1 layer) fraction of sand (%). ```{r eval = FALSE} - sand <- ws_subset( - ws_subset( +sand <- ws_subset( + location = c(-81, 32, -80, 34), param = "SAND", layer = "D1", version = "2.0",