add ca fertilization harmonization and ncc compost support

modules/data.land/NAMESPACE

@@ -46,8 +46,8 @@ export(get_veg_module)
 export(ic_process)
 export(id_resolveable)
 export(load_veg)
-export(look_up_ca_compost_amendment)
 export(look_up_ca_n_rate)
+export(look_up_ca_organic_amendment)
 export(look_up_fertilizer_components)
 export(matchInventoryRings)
 export(match_pft)

modules/data.land/NEWS.md

@@ -12,11 +12,12 @@
 * Datasets
   *  `landiq_crop_mapping_codes` dataset mapping LandIQ crop classification codes to human-readable crop names.
   *  `bism_kc_by_crop` dataset containing BISm crop coefficient schedules and stage timing references for use in ET estimation, including columns that map to LandIQ class and subclass.
-  *  `ca_n_application_rate` dataset with recommended N application rates (g N/m2) for 33 California crops from CDFA-FREP and UC ANR sources.
-  *  `ca_compost_amendment` dataset with C:N ratios, carbon, nitrogen, and PAN (g/m2) for 32 organic amendment materials.
+  *  `ca_n_application_rate` dataset with recommended N application rates (g N/m2) for 40 California crops from CDFA-FREP, UC ANR, Rosenstock 2013, Brown 2020 NBMP (Almonds age stages) and Lazicki 2016 (Potato) sources.
+  *  `ca_organic_amendment_properties` dataset with C:N ratios, nitrogen, and PAN for 32 organic amendment materials, plus a `material_class` column mapping each material to the CalRecycle taxonomy (14 CCR section 17852).
+  *  `ca_organic_amendment_app_rate` dataset with row-crop and orchard application rate envelopes (64 rows = 32 materials x 2 crop structures) that joins to `ca_organic_amendment_properties` on `material`.
 * Functions
   *  `look_up_ca_n_rate()` for looking up crop-specific N application rates by name (exact match first, partial match suggestions on miss).
-  *  `look_up_ca_compost_amendment()` for looking up organic amendment properties by material name.
+  *  `look_up_ca_organic_amendment()` for looking up organic amendment properties by material name.
   *  `to_co2e()` for converting SOC change, CH4, and N2O to CO2-equivalent emissions using IPCC Global Warming Potential values.
 
 ## Changed

modules/data.land/R/data.R

@@ -209,84 +209,108 @@
 
 #' California recommended N application rates by crop
 #'
-#' Crop-specific recommended nitrogen fertilizer application rates for
-#' California agriculture. Contains total-season rates (not per-stage
-#' breakdowns). When multiple sources report rates for the same crop,
-#' the rate represents the envelope (min of minimums, max of maximums)
-#' across sources.
-#'
-#' @format A tibble with one row per crop and the following columns:
+#' Recommended nitrogen fertilizer application rates for California crops.
+#' When multiple sources report rates for the same crop the value is the
+#' envelope across sources. Crops reported only as within year stages
+#' (Barley, Beans, Cauliflower, Melons) have stages summed to an annual
+#' total. Crops reported only by age (Almonds) get the envelope across
+#' ages.
+#'
+#' @format A tibble with one row per crop and the columns:
 #' \describe{
-#'   \item{pft_group}{\code{character}. Plant functional type group
-#'     (e.g. "row", "woody", "rice").}
-#'   \item{crop}{\code{character}. Crop name as given in the source.}
-#'   \item{min_n_lbs_acre}{\code{numeric}. Minimum recommended N rate
-#'     (lbs N/acre).}
-#'   \item{max_n_lbs_acre}{\code{numeric}. Maximum recommended N rate
-#'     (lbs N/acre).}
-#'   \item{source}{\code{character}. Short citation for the source(s).
-#'     Multiple sources are separated by "; ".}
-#'   \item{min_n_g_m2}{\code{numeric}. Minimum N rate in SI units
-#'     (g N/m\eqn{^2}). Conversion: 1 lb/acre = 0.112085 g/m\eqn{^2}.}
-#'   \item{max_n_g_m2}{\code{numeric}. Maximum N rate in SI units
-#'     (g N/m\eqn{^2}).}
+#'   \item{pft_group}{Plant functional type group: \code{"row"},
+#'     \code{"woody"}, or \code{"rice"}.}
+#'   \item{crop}{Crop name as given in the source.}
+#'   \item{min_n_lbs_acre, max_n_lbs_acre}{Recommended N rate range
+#'     (lbs N / acre).}
+#'   \item{source}{Short citation. Multiple sources are joined with
+#'     \code{"; "}.}
+#'   \item{min_n_g_m2, max_n_g_m2}{Same range in SI units (g N / m\eqn{^2}).}
 #' }
 #'
-#' @source Rosenstock, T. S., Liptzin, D., Six, J., & Tomich, T. P. (2013).
+#' @source Rosenstock, T. S., Liptzin, D., Six, J., Tomich, T. P. (2013).
 #'   Nitrogen fertilizer use in California: Assessing the data, trends and a
-#'   way forward. California Agriculture, 67(1).
+#'   way forward. California Agriculture 67(1).
 #'   \url{https://escholarship.org/uc/item/5mk2q1sm}
-#' @source Meyer, R. D., Marcum, D. B., Orloff, S. B., & Schmierer, J. L.
+#' @source Meyer, R. D., Marcum, D. B., Orloff, S. B., Schmierer, J. L.
 #'   (2007). Alfalfa fertilization strategies. UC ANR Publication 8296.
+#' @source Brown, P. H. et al. (2020). Nitrogen Best Management Practices
+#'   for Almonds. Almond Board of California. Source for Almonds rates by
+#'   age.
+#' @source Lazicki, P., Geisseler, D., Horwath, W. R. (2016). Potato
+#'   Production in California. CDFA FREP / UC Davis. Source for Potato.
 #'
-#' @seealso \code{\link{look_up_ca_n_rate}} for looking up rates by crop name.
-#'   \code{\link{look_up_fertilizer_components}} for fertilizer nutrient
-#'   composition (N/C fractions) from the SWAT/DayCent database.
+#' @seealso \code{\link{look_up_ca_n_rate}}.
 "ca_n_application_rate"
 
-#' California organic amendment (compost) properties
+#' California organic amendment properties
 #'
-#' Properties of organic amendment materials used in California agriculture,
-#' including C:N ratios, carbon and nitrogen content, plant-available nitrogen
-#' (PAN), and application rates. Some materials appear in multiple rows when
-#' values are reported by different sources (e.g. Corn stalks, Cow manure,
-#' Vegetable waste). The \code{source} column disambiguates these.
+#' Properties of organic amendment materials used in California
+#' agriculture: C:N ratio range, total N, plant available N at 4 weeks
+#' (PAN), and CalRecycle feedstock class (14 CCR section 17852).
+#' Materials reported by more than one source appear once per source;
+#' the \code{source} column disambiguates. Application rates live in
+#' \code{\link{ca_organic_amendment_app_rate}} and join on
+#' \code{material}.
 #'
-#' @format A tibble with 32 rows and the following columns:
+#' @format A tibble with 32 rows and the columns:
 #' \describe{
-#'   \item{material}{\code{character}. Amendment material name.}
-#'   \item{cn_min, cn_max, cn_avg}{\code{numeric}. Carbon-to-nitrogen ratio
-#'     range and average.}
-#'   \item{c_pct}{\code{numeric}. Assumed carbon content (percent).}
-#'   \item{n_pct}{\code{numeric}. Total nitrogen content (percent).}
-#'   \item{pan_pct}{\code{numeric}. Plant-available nitrogen after 4 weeks
-#'     (percent). Negative values indicate N immobilization.}
-#'   \item{n_class}{\code{character}. "LOWER" or "HIGHER" N content class.}
-#'   \item{app_rate_min, app_rate_max}{\code{numeric}. Application rate range
-#'     (lbs/acre).}
-#'   \item{total_c_min_lbs_acre, total_c_max_lbs_acre}{\code{numeric}.
-#'     Total carbon applied (lbs C/acre).}
-#'   \item{total_n_min_lbs_acre, total_n_max_lbs_acre}{\code{numeric}.
-#'     Total nitrogen applied (lbs N/acre).}
-#'   \item{total_c_min_g_m2, total_c_max_g_m2}{\code{numeric}.
-#'     Total carbon in SI units (g C/m\eqn{^2}).}
-#'   \item{total_n_min_g_m2, total_n_max_g_m2}{\code{numeric}.
-#'     Total nitrogen in SI units (g N/m\eqn{^2}).}
-#'   \item{source}{\code{character}. Short citation for the data source.}
+#'   \item{material}{Material name.}
+#'   \item{material_class}{CalRecycle feedstock class
+#'     (14 CCR section 17852): one of \code{"ag"}, \code{"food"},
+#'     \code{"green"}, \code{"wood"}, \code{"yard"}, \code{"biosolids"}.}
+#'   \item{cn_min, cn_max, cn_avg}{C:N ratio range.}
+#'   \item{n_pct}{Total N (percent of dry mass).}
+#'   \item{pan_pct}{Plant available N at 4 weeks (percent of total N).
+#'     Negative values indicate net immobilization.}
+#'   \item{n_class}{N tier reported in the source (\code{"LOWER"} or
+#'     \code{"HIGHER"}).}
+#'   \item{source}{Short citation.}
 #' }
 #'
 #' @source Eghball, B. Composting Manure and Other Organic Residues.
-#'   University of Nebraska-Lincoln Extension, Publication G2222.
+#'   University of Nebraska Lincoln Extension, Publication G2222.
 #'   \url{https://extensionpubs.unl.edu/publication/g2222/na/html/view}
 #' @source Rynk, R. (ed.) Compost Production and Use in Sustainable
 #'   Farming Systems. NC State Extension.
 #'   \url{https://content.ces.ncsu.edu/compost-production-and-use-in-sustainable-farming-systems}
 #'
-#' @seealso \code{\link{look_up_ca_compost_amendment}} for looking up
-#'   amendments by material name.
-#'   \code{\link{look_up_fertilizer_components}} for fertilizer nutrient
-#'   composition (N/C fractions) from the SWAT/DayCent database.
-"ca_compost_amendment"
+#' @seealso \code{\link{ca_organic_amendment_app_rate}}.
+#'   \code{\link{look_up_ca_organic_amendment}}.
+"ca_organic_amendment_properties"
+
+#' California organic amendment application rates
+#'
+#' Recommended application rates for each material in
+#' \code{\link{ca_organic_amendment_properties}}, broken out by crop
+#' structure (row crops vs orchards). The two rate sets are identical
+#' for most materials in the source, but a handful of N rich materials
+#' (Blood meal, poultry manure) differ between row and tree applications.
+#'
+#' @format A tibble with 64 rows (32 materials x 2 crop structures) and
+#' the columns:
+#' \describe{
+#'   \item{material}{Material name. Joins to
+#'     \code{\link{ca_organic_amendment_properties}}.}
+#'   \item{crop_structure}{\code{"rows"} for annual row crops,
+#'     \code{"trees"} for perennial orchards.}
+#'   \item{app_rate_min, app_rate_max}{Amendment application rate range
+#'     (lbs of amendment / acre).}
+#'   \item{total_n_min_lbs_acre, total_n_max_lbs_acre}{Total N delivered
+#'     at those rates (lbs N / acre).}
+#'   \item{source}{Short citation.}
+#'   \item{total_n_min_g_m2, total_n_max_g_m2}{Same N range in SI units
+#'     (g N / m\eqn{^2}).}
+#' }
+#'
+#' @source Eghball, B. Composting Manure and Other Organic Residues.
+#'   University of Nebraska Lincoln Extension, Publication G2222.
+#' @source Rynk, R. (ed.) Compost Production and Use in Sustainable
+#'   Farming Systems. NC State Extension.
+#'
+#' @seealso \code{\link{ca_organic_amendment_properties}}.
+#'   \code{\link{look_up_ca_organic_amendment}}.
+"ca_organic_amendment_app_rate"
 
 #' Crop-specific rooting depths and water-depletion thresholds
 #'

modules/data.land/R/look_up_ca_n_rate.R

@@ -100,10 +100,12 @@ look_up_ca_n_rate <- function(
 }
 
 
-#' Look up California compost amendment properties
+#' Look up California organic amendment properties
 #'
 #' Returns properties of organic amendment materials including carbon and
 #' nitrogen content, C:N ratio, and plant-available nitrogen (PAN).
+#' Application rates live in
+#' \code{\link{ca_organic_amendment_app_rate}}; join on \code{material}.
 #'
 #' Matching is case-insensitive. Exact matches are returned directly.
 #' If no exact match is found, partial matching suggests possible materials.
@@ -117,10 +119,8 @@ look_up_ca_n_rate <- function(
 #' @param aggregate Character, one of "none" (default) or "mean".
 #'   If "mean", rows for the same material are averaged into a single row.
 #'
-#' @return A tibble with columns: `material`, `cn_min`, `cn_max`,
-#'   `cn_avg`, `c_pct`, `n_pct`, `pan_pct`, `n_class`,
-#'   `total_c_min_g_m2`, `total_c_max_g_m2`,
-#'   `total_n_min_g_m2`, `total_n_max_g_m2`, `source`.
+#' @return A tibble with columns: `material`, `material_class`,
+#'   `cn_min`, `cn_max`, `cn_avg`, `n_pct`, `pan_pct`, `n_class`, `source`.
 #'   Returns an empty tibble (with a warning) if no match is found.
 #'
 #' @source Eghball, B. Composting Manure and Other Organic Residues.
@@ -132,21 +132,22 @@ look_up_ca_n_rate <- function(
 #'
 #' @seealso [look_up_fertilizer_components()] for fertilizer nutrient
 #'   composition (N/C fractions) from the SWAT/DayCent database.
-#'   [ca_compost_amendment] for the underlying dataset.
+#'   [ca_organic_amendment_properties] for the underlying dataset.
+#'   [ca_organic_amendment_app_rate] for the matching application rates.
 #'
 #' @examples
-#' look_up_ca_compost_amendment("Cow manure")
-#' look_up_ca_compost_amendment("Cow manure", aggregate = "mean")
-#' look_up_ca_compost_amendment("Poultry litter", n_class = "LOWER")
+#' look_up_ca_organic_amendment("Cow manure")
+#' look_up_ca_organic_amendment("Cow manure", aggregate = "mean")
+#' look_up_ca_organic_amendment("Poultry litter", n_class = "LOWER")
 #'
 #' @export
-look_up_ca_compost_amendment <- function(
+look_up_ca_organic_amendment <- function(
     material,
     n_class = NULL,
     aggregate = c("none", "mean")
 ) {
   aggregate <- match.arg(aggregate)
-  dat <- PEcAn.data.land::ca_compost_amendment
+  dat <- PEcAn.data.land::ca_organic_amendment_properties
 
   if (!is.null(n_class)) {
     dat <- dat |>
@@ -170,37 +171,33 @@ look_up_ca_compost_amendment <- function(
       )
     } else {
       PEcAn.logger::logger.warn(
-        "No compost amendment found for material '", material, "'"
+        "No organic amendment found for material '", material, "'"
       )
     }
     return(dplyr::tibble(
-      material = character(), cn_min = numeric(), cn_max = numeric(),
-      cn_avg = numeric(), c_pct = numeric(),
+      material = character(), material_class = character(),
+      cn_min = numeric(), cn_max = numeric(), cn_avg = numeric(),
       n_pct = numeric(), pan_pct = numeric(), n_class = character(),
-      total_c_min_g_m2 = numeric(), total_c_max_g_m2 = numeric(),
-      total_n_min_g_m2 = numeric(), total_n_max_g_m2 = numeric(),
       source = character()
     ))
   }
 
   out <- result |>
     dplyr::select(
-      "material", "cn_min", "cn_max", "cn_avg",
-      "c_pct", "n_pct", "pan_pct", "n_class",
-      "total_c_min_g_m2", "total_c_max_g_m2",
-      "total_n_min_g_m2", "total_n_max_g_m2",
+      "material", "material_class",
+      "cn_min", "cn_max", "cn_avg",
+      "n_pct", "pan_pct", "n_class",
       "source"
     )
 
   if (aggregate == "mean" && nrow(out) > 1) {
     numeric_cols <- c(
-      "cn_min", "cn_max", "cn_avg", "c_pct", "n_pct", "pan_pct",
-      "total_c_min_g_m2", "total_c_max_g_m2",
-      "total_n_min_g_m2", "total_n_max_g_m2"
+      "cn_min", "cn_max", "cn_avg", "n_pct", "pan_pct"
     )
     out <- out |>
       dplyr::summarize(
         dplyr::across(dplyr::all_of(numeric_cols), mean),
+        material_class = dplyr::first(.data$material_class),
         n_class = dplyr::first(.data$n_class),
         source = paste(unique(.data$source), collapse = "; "),
         .by = "material"

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

@@ -27,3 +27,103 @@ 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/`.
+
+
+# California fertilization datasets
+
+Three datasets for nitrogen management on California crops. Like BADM
+above, each one ships as a harmonized CSV in this folder, and its
+`create_*.R` script just reads that CSV and writes the `.rda`, nothing
+fancy. `ca_n_application_rate` carries recommended N rate ranges for 40
+crops. `ca_organic_amendment_properties` carries the intrinsic
+properties of 32 amendment materials (C:N, total N, plant available N at
+4 weeks, and the CalRecycle feedstock class).
+`ca_organic_amendment_app_rate` carries how much of each material you
+put down, 64 rows because every material gets one rate for row crops and
+one for orchards.
+
+The CSVs are not where the work happens. They fall out of
+`harmonize_fertilization_data.R`, which lives with the rest of the CCMMF
+management workflow under
+`/projectnb/dietzelab/ccmmf/management/fertilization/`, outside this
+package. That script reads the curated TSV exports of the CCMMF
+fertilization spreadsheet, maps the source URLs to short author-year
+citations, folds the per-stage N rows into one range per crop, converts
+lbs/acre to g/m2 with `PEcAn.utils::ud_convert`, splits the
+spreadsheet's wide Rows/Trees layout into the long properties and
+app-rate tables, drops a couple of bad columns, and assigns the
+`material_class`. Whatever lands in the three CSVs here is what the
+package builds from.
+
+## Where the numbers come from
+
+The N rates trace back to Rosenstock et al. 2013 (*California
+Agriculture* 67(1), doi:10.3733/ca.E.v067n01p68), the CDFA-FREP and UC
+Davis fertilization guidelines, Meyer et al. 2007 for alfalfa (UC ANR
+pubs 8292 and 8296), Brown et al. 2020 NBMP Table 2 for almonds by age
+(Almond Board of California), and Lazicki, Geisseler and Horwath 2016
+for potato (CDFA-FREP / UC Davis). The citation for each crop sits in
+its `source` column. The `pft_group` labels (row, woody, rice) come
+straight off the spreadsheet, hand-authored rather than mapped from
+`cadwr_pfts.csv`, though they follow the same grouping it uses.
+
+The amendment numbers come from Eghball (UNL Extension G2222) and Rynk
+(NC State Extension compost handbook), again cited per row.
+`material_class` is the one field we set by hand, slotting each material
+into the CalRecycle feedstock taxonomy from 14 CCR 17852. The current 32
+materials only land in four of the classes (ag, food, yard, wood); green
+and biosolids are valid classes but nothing here falls in them.
+
+Everything else is verbatim off the spreadsheet: crop, pft_group,
+material, total N, PAN, the C:N range, the N tier, and the raw Rows and
+Trees application rates. The pieces we computed or assigned are the
+per-crop N range (aggregated as below), the short citation strings, the
+`material_class`, the `crop_structure` label, and every g/m2 column
+(converted from lbs/acre).
+
+## How the per-crop N range gets built
+
+Most crops, 33 of them, report a whole season rate, so we take that
+range as is. Six report only by growth stage (Barley, the three Beans,
+Cauliflower, Melons), so their within year stages get summed into a
+season total. Almonds are the odd one out, reporting by orchard age
+across 8 NBMP stages, so there we envelope the low and high across all
+ages. Onions drop out, since its only row is a "1/3 of total N at
+preplant" note with no rate attached.
+
+## Fixes we made at the source
+
+A few things in the spreadsheet were wrong and got fixed upstream before
+harmonizing:
+
+- Dropped `Peach, bell` and `Peach, chili`. Their numbers were
+  byte for byte copies of `Pepper, bell` and `Pepper, chili`, and the
+  paper they cite (Rosenstock 2013 Table 2, p. 76) lists no peach-bell
+  or peach-chili at all. Clearly a copy paste slip.
+- Added `Potato` at 189 to 248 lb N/acre from Lazicki, Geisseler and
+  Horwath 2016. Worth being upfront: Rosenstock 2013 p. 76 says outright
+  that no UC ANR guideline exists for potato in California, so this is a
+  grower-reported envelope, not an official guideline.
+- Tossed the `Total_C` columns. The spreadsheet built them as
+  `Total_N * C_assumed` instead of `AppRate * C_assumed`, which is
+  dimensionally wrong and would feed the model garbage carbon inputs.
+- Added the `material_class` column with the 32 hand-assigned CalRecycle
+  classes.
+
+One more on the amendment rates: for 30 of the 32 materials the row-crop
+and orchard rates match in the spreadsheet, but two N-rich materials
+(Blood meal and fresh poultry manure) carry lower rates on trees than on
+rows. Splitting into the long app-rate table keeps both rather than
+picking one.
+
+## Updating the data
+
+1. Edit the source TSV under
+   `/projectnb/dietzelab/ccmmf/management/fertilization/`.
+2. Rerun `harmonize_fertilization_data.R` from that folder. It
+   overwrites the three `ca_*.csv` files there.
+3. Copy those three CSVs into this folder.
+4. Rerun `create_ca_n_application_rate.R` and
+   `create_ca_organic_amendment.R`.
+5. Bump the package version, add a `NEWS.md` line, and regenerate the
+   man pages with `devtools::document()`.