document and lazy-load BADM and soil_class

modules/data.land/DESCRIPTION

@@ -66,7 +66,6 @@ Suggests:
     testthat (>= 1.0.2)
 License: BSD_3_clause + file LICENSE
 Copyright: Authors
-LazyLoad: yes
-LazyData: FALSE
+LazyData: true
 Encoding: UTF-8
 RoxygenNote: 7.2.3

modules/data.land/R/IC_BADM_Utilities.R

@@ -20,8 +20,7 @@ Read.IC.info.BADM <-function(lat, long){
   cov.factor <-1
   #Reading in the DB
   #
-  U.S.SB <-
-    load(system.file("data","BADM.rda", package = "PEcAn.data.land"))
+  U.S.SB <- PEcAn.data.land::BADM
 
 
   Regions <- EPA_ecoregion_finder(lat, long)

modules/data.land/R/data.R

@@ -0,0 +1,66 @@
+#' Biomass and soil data from FluxNet sites
+#'
+#' Contains data from 246 Fluxnet sites.
+#' Variables include aboveground and belowground biomass in various pools,
+#'   plus soil texture/chemistry/horizonation/C&N stocks.
+#'
+#' @format ## `BADM`
+#' A data frame with 12,300 rows and 13 columns:
+#' \describe{
+#'   \item{SITE_ID}{Fluxnet code for the site}
+#'   \item{LOCATION_ELEV, LOCATION_LAT, LOCATION_LON}{site coordinates}
+#'   \item{Date}{Measurement date}
+#'   \item{GROUP_ID}{TODO}
+#'   \item{VARIABLE_GROUP}{category, eg abovground biomass or soil chemistry}
+#'   \item{VARIABLE, DATAVALUE}{key and value for each measured variable}
+#'   \item{NA_L1CODE, NA_L1NAME, NA_L2CODE, NA_L2NAME}{
+#'		numeric IDs and names for the Level 1 and level 2 ecoregions where
+#'		this site is located}
+#' }
+#' @source Originally from Fluxnet <https://fluxnet.org/badm-data-product/>,
+#'  but the provenence and age of this specific file is not clear.
+"BADM"
+
+
+#' Default parameters for calculating soil properties from sand & clay content
+#'
+#'
+#' @format ## `soil_class`
+#' A list with 26 entries:
+#' \describe{
+#'   \item{air.cond, h2o.cond, sand.cond, silt.cond, clay.cond}{
+#'		thermal conductivity, W m^-1 K^-1}
+#'   \item{air.hcap, sand.hcap, silt.hcap, clay.hcap}{heat capacity,
+#'		J m^-3 K^-1}
+#'   \item{kair, ksand, ksilt, kclay}{relative conductivity factor}
+#'   \item{fieldcp.K}{hydraulic conductance at field capacity, mm day^-1}
+#'   \item{grav}{gravity acceleration, m s^-2}
+#'   \item{soil.key}{Abbreviations for each of 18 soil texture classes, e.g.
+#' 		"SiL", "LSa"}
+#'   \item{soil.name}{Names for 18 soil texture classes, e.g. "Sand",
+#'		"Silty clay"}
+#'   \item{soilcp.MPa}{soil water potential when air-dry, MPa}
+#'   \item{soilld.MPa}{soil water potential at critical water content, MPa}
+#'   \item{soilwp.MPa}{soil water potential at wilting point, MPa}
+#'   \item{stext.lines}{list of 18 lists, each giving minimum and maximum
+#'	  	sand/silt/clay contents for a soil texture class}
+#'   \item{stext.polygon}{list of 18 lists, each giving corner points in the
+#'		soil texture triangle for a soil texture class}
+#'   \item{texture}{data frame with 13 rows and 21 columns, giving default
+#'		parameter values for 13 named soil textures}
+#'   \item{theta.crit}{critical water content (fractional soil moisture at
+#'		which plants start dropping leaves), m^3 m^-3}
+#'   \item{xclay.def}{default volume fraction of sand in each of 18 soil
+#'		texture classes}
+#'   \item{xsand.def}{default volume fraction of clay in each of 18 soil
+#'		texture classes}
+#' }
+#' @source
+#' The hydraulic parameters are derived from Cosby et al 1984, "A Statistical
+#' Exploration of the Relationships of Soil Moisture Characteristics to the
+#' Physical Properties of Soils", Water Resources Research 20(6): 682-690.
+#' This implementation comes from one provided by the ED2 model,
+#' plus `texture.csv` from a source not recorded. Package `PEcAn.linkages`
+#' contains an identical texture.csv, also with no obvious source label.
+#' See also comments in soil_utils.R
+"soil_class"

modules/data.land/R/soil_utils.R

@@ -26,30 +26,30 @@
 #' soil_params(sand=sand,clay=clay)
 soil_params <- function(soil_type=NULL, sand=NULL, silt=NULL, clay=NULL, bulk=NULL){
   ## load soil parameters
-  soil_data <- new.env()
-  load(system.file("data/soil_class.RData",package = "PEcAn.data.land"), envir = soil_data)
   mysoil <- list()
-  air.cond <- soil_data$air.cond
-  air.hcap <- soil_data$air.hcap
-  clay.cond <- soil_data$clay.cond
-  clay.hcap <- soil_data$clay.hcap
-  fieldcp.K <- soil_data$fieldcp.K
-  grav <- soil_data$grav
-  h2o.cond <- soil_data$h2o.cond
-  kair <- soil_data$kair
-  kclay <- soil_data$kclay
-  ksand <- soil_data$ksand
-  ksilt <- soil_data$ksilt
-  sand.cond <- soil_data$sand.cond
-  sand.hcap <- soil_data$sand.hcap
-  silt.cond <- soil_data$silt.cond
-  silt.hcap <- soil_data$silt.hcap
-  soil.name <- soil_data$soil.name
-  soilcp.MPa <- soil_data$soilcp.MPa
-  soilwp.MPa <- soil_data$soilwp.MPa
-  texture <- soil_data$texture
-  xclay.def <- soil_data$xclay.def
-  xsand.def <- soil_data$xsand.def
+  # 'soil_class' is package data, lazy-loaded here when needed
+  #   see data-raw/build_soil_texture_variables.R
+  air.cond <- PEcAn.data.land::soil_class$air.cond
+  air.hcap <- PEcAn.data.land::soil_class$air.hcap
+  clay.cond <- PEcAn.data.land::soil_class$clay.cond
+  clay.hcap <- PEcAn.data.land::soil_class$clay.hcap
+  fieldcp.K <- PEcAn.data.land::soil_class$fieldcp.K
+  grav <- PEcAn.data.land::soil_class$grav
+  h2o.cond <- PEcAn.data.land::soil_class$h2o.cond
+  kair <- PEcAn.data.land::soil_class$kair
+  kclay <- PEcAn.data.land::soil_class$kclay
+  ksand <- PEcAn.data.land::soil_class$ksand
+  ksilt <- PEcAn.data.land::soil_class$ksilt
+  sand.cond <- PEcAn.data.land::soil_class$sand.cond
+  sand.hcap <- PEcAn.data.land::soil_class$sand.hcap
+  silt.cond <- PEcAn.data.land::soil_class$silt.cond
+  silt.hcap <- PEcAn.data.land::soil_class$silt.hcap
+  soil.name <- PEcAn.data.land::soil_class$soil.name
+  soilcp.MPa <- PEcAn.data.land::soil_class$soilcp.MPa
+  soilwp.MPa <- PEcAn.data.land::soil_class$soilwp.MPa
+  texture <- PEcAn.data.land::soil_class$texture
+  xclay.def <- PEcAn.data.land::soil_class$xclay.def
+  xsand.def <- PEcAn.data.land::soil_class$xsand.def
 
   #---------------------------------------------------------------------------------------#
   #     Find soil class and sand, silt, and clay fractions.                               #

modules/data.land/data-raw/README.md

@@ -0,0 +1,29 @@
+
+## BADM
+
+Various ancillary data from Fluxnet.
+Provenence of this  particular file not clear, but it contains data from
+246 Fluxnet sites. Variables include aboveground and belowground biomass
+in various pools, plus soil texture/chemistry/horizonation/C&N stocks.
+
+`load_BADM.R` simply reads `BADM.csv` and writes it as `../data/BADM.rda`.
+
+
+# Soil variables
+
+Default parameter values for soil of various texture classes.
+The values are apparently derived from Cosby et al 1984,
+"A Statistical Exploration of the Relationships of Soil Moisture
+Characteristics to the Physical Properties of Soils",
+Water Resources Research 20(6): 682-690.
+This implementation comes from one provided by the ED2 model.
+Not clear if texture.csv came from there or another source.
+	PEcAn.linkages contains an identical texture.csv,
+	also with no obvious source label.
+
+`build_soil_texture_variables.R` hardcodes the values for many parameters
+in a list named `soil_class` and saves it to `../data/soil_class.rda`,
+from which it is lazy-loaded when `soil_class` is used inside
+package functions.
+The saved file includes all of `texture.csv`, hence why that lives in
+`data-raw` rather than directly in `data/`.

modules/data.land/inst/build_soil_texture_variables.R → modules/data.land/data-raw/build_soil_texture_variables.R

@@ -28,8 +28,6 @@ nstext.lines      = length(stext.lines)
 for(n in 1:nstext.lines){
   stext.lines[[n]]$silt = pmax(0,pmin(1,1.-stext.lines[[n]]$sand-stext.lines[[n]]$clay))
 }#end for
-stext.lines   <<- stext.lines
-nstext.lines  <<- nstext.lines
 #==========================================================================================#
 #==========================================================================================#
 
@@ -99,8 +97,6 @@ for(n in 1:nstext.polygon){
   clay.now = stext.polygon[[n]]$clay
   stext.polygon[[n]]$silt = pmax(0,pmin(1,1.-sand.now-clay.now))
 }#end for
-stext.polygon  <<- stext.polygon
-nstext.polygon <<- nstext.polygon
 #==========================================================================================#
 #==========================================================================================#
 
@@ -116,7 +112,7 @@ soil.name = c("Sand","Loamy sand","Sandy loam","Silt loam","Loam","Sandy clay lo
               ,"Silty clay loam","Clayey loam","Sandy clay","Silty clay","Clay"
               ,"Peat","Bedrock","Silt","Heavy clay","Clayey sand","Clayey silt")
 
-texture <- read.csv("~/pecan/modules/data.land/data/texture.csv",header=TRUE,stringsAsFactors = FALSE)
+texture <- read.csv("texture.csv",header=TRUE,stringsAsFactors = FALSE)
 
 
 
@@ -156,4 +152,33 @@ ksilt <- 3. * h2o.cond / ( 2. * h2o.cond + silt.cond )
 kclay <- 3. * h2o.cond / ( 2. * h2o.cond + clay.cond )
 kair  <- 3. * h2o.cond / ( 2. * h2o.cond +  air.cond )
 
-save.image("~/pecan/modules/data.land/data/soil_class.RData")
+# TODO may be more useful to collect related variables into sublists...
+soil_class <- list(
+  air.cond = air.cond,
+  air.hcap = air.hcap,
+  clay.cond = clay.cond,
+  clay.hcap = clay.hcap,
+  fieldcp.K = fieldcp.K,
+  grav = grav,
+  h2o.cond = h2o.cond,
+  kair = kair,
+  kclay = kclay,
+  ksand = ksand,
+  ksilt = ksilt,
+  sand.cond = sand.cond,
+  sand.hcap = sand.hcap,
+  silt.cond = silt.cond,
+  silt.hcap = silt.hcap,
+  soil.key = soil.key,
+  soil.name = soil.name,
+  soilcp.MPa = soilcp.MPa,
+  soilld.MPa = soilld.MPa,
+  soilwp.MPa = soilwp.MPa,
+  stext.lines = stext.lines,
+  stext.polygon = stext.polygon,
+  texture = texture,
+  theta.crit = theta.crit,
+  xclay.def = xclay.def,
+  xsand.def = xsand.def)
+
+save(soil_class, file = "../data/soil_class.rda")