diff --git a/DESCRIPTION b/DESCRIPTION index 6ce7085..3e9e024 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,19 +1,19 @@ Package: VPRMLandSfcModel Type: Package Title: R implementation of VPRM with parameter estimation -Version: 1.2.1 -Date: 2017-10-03 +Version: 1.3.0 +Date: 2023-07-07 Author: Timothy W. Hilton -Maintainer: Timothy W. Hilton +Maintainer: Timothy W. Hilton Description: Provides an R implementation of the Vegetation - Photosynthesis and Respiration Model (VPRM) and tools to estimate - VPRM parameter values from observations. VPRM is a simple - diagnostic land surface model based on light-use efficiency. VPRM - diagnoses gross ecosystem exchange (GEE) of carbon dioxide, - ecosystem respiration (R), and net ecosystem exchange (NEE) of - carbon dioxide. To cite the VPRMLandSfcModel R package or the VPRM - model itself in a publication, or for a more detailed description - of VPRM, see (within R) 'citation("VPRMLandSurfaceModel")'. + Photosynthesis and Respiration Model (VPRM), the urbanVPRM, and tools to + estimate VPRM parameter values from observations. VPRM is a simple + diagnostic land surface model based on light-use efficiency. VPRM diagnoses + gross ecosystem exchange (GEE) of carbon dioxide, ecosystem respiration (R), + and net ecosystem exchange (NEE) of carbon dioxide. To cite the + VPRMLandSfcModel R package or the (urban)VPRM model itself in a publication, or for + a more detailed description of VPRM, see (within R) + 'citation("VPRMLandSurfaceModel")'. License: GPL-3 LazyLoad: yes Imports: @@ -24,3 +24,5 @@ Suggests: knitr, rmarkdown VignetteBuilder: knitr +RoxygenNote: 7.2.3 +Encoding: UTF-8 diff --git a/NAMESPACE b/NAMESPACE index 100bab0..0d72488 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,11 +1,13 @@ -# Generated by roxygen2 (4.0.2): do not edit by hand +# Generated by roxygen2: do not edit by hand S3method(as.data.frame,VPRM_driver_data) +export(SWDN_2_PAR) export(VPRM_driver_data) export(detect_large_greenness_change_periods) export(estimate_VPRM_pars) export(getLSWI) export(getPscale) +export(getPscale_urban) export(getTscale) export(getWscale) export(interpMODIS) diff --git a/NEWS b/NEWS index e0d848f..0e4ba6b 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,6 @@ +New features in version 1.3.0 +- implement the urbanVPRM adaptation of VPRM to urban settings + New features in version 1.2.1 - added vignette to provide usage examples @@ -15,4 +18,4 @@ New features in version 1.1 - added Park_Falls dataset - added example code for all functions - changed package name from VPRMModel to VPRMLandSfcModel. See - ChangeLog for reasoning. \ No newline at end of file + ChangeLog for reasoning. diff --git a/R/VPRMLandSfcModel-package.R b/R/VPRMLandSfcModel-package.R new file mode 100644 index 0000000..a65cf64 --- /dev/null +++ b/R/VPRMLandSfcModel-package.R @@ -0,0 +1,6 @@ +#' @keywords internal +"_PACKAGE" + +## usethis namespace: start +## usethis namespace: end +NULL diff --git a/R/VPRM_driver_data.R b/R/VPRM_driver_data.R index 8fe4b33..571cfef 100644 --- a/R/VPRM_driver_data.R +++ b/R/VPRM_driver_data.R @@ -5,61 +5,70 @@ ##' necessary to run VPRM for a single eddy covariance site, ##' calculates "derived" fields, and interpolates phenology dynamics. ##' -##' "Derived fields" denote fields that are calculated from other -##' observed quanitities. For example, land surface water index -##' (LSWI) is a derived field, as it is calculated from MODIS -##' reflectances in the short infrared and near infrared bands. +##' "Derived fields" denote fields that are calculated from other observed +##' quanitities. For example, land surface water index (LSWI) is a derived +##' field, as it is calculated from MODIS reflectances in the short infrared and +##' near infrared bands. ##' @title build a VPRM_driver_data object -##' @param name_long character string; "short name" of the site. e.g. US-PFa -##' @param name_short character string; "long name" of the site. e.g. Park Falls +##' @param name_long character string; "short name" of the site. e.g. US-PFa +##' @param name_short character string; "long name" of the site. e.g. Park Falls ##' @param lat numeric; latitude of the site (deg N) -##' @param lon numeric; longitude of the site (deg E) -##' @param PFT character string; plant functional type. Will be converted to a factor. -##' @param note character string; optional note; could be anything the -##' user finds useful. -##' @param Tmin numeric; minimum temperature for photosynthesis (deg -##' C). See Mahadevan et al (2008) eq. 6. -##' @param Tmax numeric; maximim temperature for photosynthesis (deg -##' C). See Mahadevan et al (2008) eq. 6. -##' @param Topt numeric; optimum temperature for photosynthesis (deg -##' C). See Mahadevan et al (2008) eq. 6. -##' @param Tlow numeric; minimum temperature for respiration (deg C). -##' See Mahadevan et al (2008) eq. 10. -##' @param tower_date chron vector; timestamps for all tower -##' observations (NEE_obs, T, PAR) -##' @param NEE_obs numeric vector; eddy covariance observed net -##' ecosystem exchange (NEE, umol m-2 s-1) +##' @param lon numeric; longitude of the site (deg E) +##' @param PFT character string; plant functional type. Will be converted to a +##' factor. +##' @param note character string; optional note; could be anything the user +##' finds useful. +##' @param Tmin numeric; minimum temperature for photosynthesis (deg C). See +##' Mahadevan et al (2008) eq. 6. +##' @param Tmax numeric; maximim temperature for photosynthesis (deg C). See +##' Mahadevan et al (2008) eq. 6. +##' @param Topt numeric; optimum temperature for photosynthesis (deg C). See +##' Mahadevan et al (2008) eq. 6. +##' @param Tlow numeric; minimum temperature for respiration (deg C). See +##' Mahadevan et al (2008) eq. 10. +##' @param tower_date chron vector; timestamps for all tower observations +##' (NEE_obs, T, PAR) +##' @param NEE_obs numeric vector; eddy covariance observed net ecosystem +##' exchange (NEE, umol m-2 s-1) ##' @param T numeric vector; observed air temperature (deg C) -##' @param PAR numeric vector; observed photosynthetically active -##' radiation (umol m-2 s-1) +##' @param PAR numeric vector; observed photosynthetically active radiation +##' (umol m-2 s-1) ##' @param date_nir chron vector; timestamps for NIR reflectance. ##' @param rho_nir numeric vector; NIR reflectance values -##' @param date_swir chron vector; timestamps for SWIR reflectance. -##' @param rho_swir numeric vector; SWIR reflectance values -##' @param date_EVI chron vector; timestamps for enhanced vegetation index (EVI). +##' @param date_swir chron vector; timestamps for SWIR reflectance. +##' @param rho_swir numeric vector; SWIR reflectance values +##' @param date_EVI chron vector; timestamps for enhanced vegetation index +##' (EVI). ##' @param EVI numeric vector; EVI values. -##' @param phen factor; phenology dynamics. levels are ginc (onset -##' greenness increase), gdec (onset greenness decrease), gmin (onset -##' greenness minimum), gmax (onset greenness maximum). If not -##' specified, phenology dynsamics are calculated from EVI using a -##' method similar to Zhang et al (2003). -##' @return an object of class VPRM_driver_data. Has fields (see -##' above arguments for definitions): name_long, name_short, lat, lon, -##' PFT, note, Tmin, Tmax, Topt, Tlow. The data for NEE_obs, T, PAR, -##' rho_nir, rho_swir, EVI, and phen should be accessed using the -##' as.data.frame method. -##' @references Mahadevan, P., S. C. Wofsy, D. M. Matross, X. Xiao, -##' A. L. Dunn, J. C. Lin, C. Gerbig, J. W. Munger, V. Y. Chow, and -##' E. W. Gottlieb (2008), A satellite-based biosphere -##' parameterization for net ecosystem CO2 exchange: Vegetation -##' Photosynthesis and Respiration Model (VPRM), Global -##' Biogeochem. Cycles, 22, GB2005, doi:10.1029/2006GB002735. -##' @references Xiaoyang Zhang, Mark A. Friedl, Crystal B. Schaaf, -##' Alan H. Strahler, John C.F. Hodges, Feng Gao, Bradley C. Reed, -##' Alfredo Huete, Monitoring vegetation phenology using MODIS, Remote -##' Sensing of Environment, Volume 84, Issue 3, March 2003, Pages -##' 471-475, ISSN 0034-4257, -##' http://dx.doi.org/10.1016/S0034-4257(02)00135-9. +##' @param refEVI numeric vector; reference EVI values. Only required for +##' urbanVPRM. See Hardiman et al SI section S2.4. +##' @param ISA numeric vector; impervious surface area values. Only required for +##' urbanVPRM. Must vary between 0.0 and 1.0. +##' @param LSWI numeric vector; Land Surface Water Index. If not provided will +##' be calculated from rho_nir and rho_swir. +##' @param phen factor; phenology dynamics. levels are ginc (onset greenness +##' increase), gdec (onset greenness decrease), gmin (onset greenness +##' minimum), gmax (onset greenness maximum). If not specified, phenology +##' dynsamics are calculated from EVI using a method similar to Zhang et al +##' (2003). +##' @param model_form string, optional; form of VPRM model to use. Options are +##' "Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +##' (2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +##' (2017). If set to "urban". +##' @return an object of class VPRM_driver_data. Has fields (see above arguments +##' for definitions): name_long, name_short, lat, lon, PFT, note, Tmin, Tmax, +##' Topt, Tlow. The data for NEE_obs, T, PAR, rho_nir, rho_swir, EVI, and phen +##' should be accessed using the as.data.frame method. +##' @references Mahadevan, P., S. C. Wofsy, D. M. Matross, X. Xiao, A. L. Dunn, +##' J. C. Lin, C. Gerbig, J. W. Munger, V. Y. Chow, and E. W. Gottlieb (2008), +##' A satellite-based biosphere parameterization for net ecosystem CO2 +##' exchange: Vegetation Photosynthesis and Respiration Model (VPRM), Global +##' Biogeochem. Cycles, 22, GB2005, doi:10.1029/2006GB002735. +##' @references Xiaoyang Zhang, Mark A. Friedl, Crystal B. Schaaf, Alan H. +##' Strahler, John C.F. Hodges, Feng Gao, Bradley C. Reed, Alfredo Huete, +##' Monitoring vegetation phenology using MODIS, Remote Sensing of +##' Environment, Volume 84, Issue 3, March 2003, Pages 471-475, ISSN +##' 0034-4257, http://dx.doi.org/10.1016/S0034-4257(02)00135-9. ##' @author Timothy W. Hilton ##' @import chron ##' @export @@ -82,20 +91,16 @@ ##' EVI=PFa_evi[['evi']], ##' phen=NA) ##' print(head(as.data.frame(pfa_dd))) - -VPRM_driver_data <- function( name_long="", +VPRM_driver_data <- function(name_long="", name_short="", lat=NA, lon=NA, PFT=NA, note="", - ## scalars - Tmin=0, #minimum respiration temperature (C) - Tmax=40, #maximum respiration temperature (C) - Topt=20, #optimal respiration temperature (C) + Tmin=0, + Tmax=40, + Topt=20, Tlow=2, - ## --- - ## observed fields tower_date=NA, NEE_obs=NA, T=NA, @@ -106,10 +111,15 @@ VPRM_driver_data <- function( name_long="", rho_swir=NA, date_EVI, EVI=NA, - ## phen should be a data frame with columns "date" and "phen" - phen=NA ) { + refEVI=NA, + ISA=NA, + LSWI=NA, + phen=NA, + model_form='Mahadevan07') { -obj <- list( name_long=name_long, +## all the 'scalar' fields; that is, fields that are single values, not time +## series +obj <- list(name_long=name_long, name_short=name_short, lat=lat, lon=lon, @@ -117,39 +127,44 @@ obj <- list( name_long=name_long, PFT=PFT, Tmin=Tmin, Tmax=Tmax, - Topt=Topt ) + Topt=Topt, + Tlow=Tlow, + model_form=model_form) ## interpolate reflectances and EVI onto tower timestamps -EVI <- interpMODIS( date_EVI, EVI, tower_date, "linear" )[['val']] -rho_nir <- interpMODIS( date_nir, rho_nir, tower_date, "linear" )[['val']] -rho_swir <- interpMODIS( date_swir, rho_swir, tower_date, "linear" )[['val']] +EVI <- interpMODIS(date_EVI, EVI, tower_date, "linear")[['val']] +rho_nir <- interpMODIS(date_nir, rho_nir, tower_date, "linear")[['val']] +rho_swir <- interpMODIS(date_swir, rho_swir, tower_date, "linear")[['val']] ## if phen contains only NA, then calculate phenology transition dates ## from EVI -if ( identical( all( is.na( phen ) ), TRUE ) ) { +if (identical(all(is.na(phen)), TRUE)) { EVI_df <- data.frame(sitecode=name_short, t=tower_date, EVI=EVI) - phen <- detect_large_greenness_change_periods( EVI_df) + phen <- detect_large_greenness_change_periods(EVI_df) } ## interpolate phenology status (greenness increasing, greenness max, ## greenness decreasing, greenness minimum) onto tower dates -phen <- interp_phenology( phen, tower_date ) +phen <- interp_phenology(phen, tower_date) ## try/catch here! -obj[['data']] <- data.frame( date=tower_date, +obj[['data']] <- data.frame(date=tower_date, NEE_obs=NEE_obs, T=T, PAR=PAR, rho_nir=rho_nir, rho_swir=rho_swir, EVI=EVI, - phen=phen[['phen']] ) + refEVI=refEVI, + ISA=ISA, + LSWI=LSWI, + phen=phen[['phen']]) -class( obj ) <- c( 'VPRM_driver_data', class( obj ) ) +class(obj) <- c('VPRM_driver_data', class(obj)) -obj <- calculate_VPRM_derived_input_fields( obj ) +obj <- calculate_VPRM_derived_input_fields(obj) -return( obj ) +return(obj) } @@ -164,37 +179,43 @@ return( obj ) ## @return VPRM_driver_data object; same as input argument obj, but with ## derived fields filled in. ## @author Timothy W. Hilton -calculate_VPRM_derived_input_fields <- function( obj ) { +calculate_VPRM_derived_input_fields <- function(obj) { ## make sure class of obj is correct - if ( !( 'VPRM_driver_data' %in% class( obj ) ) ) - stop( 'obj must be a VPRM_driver_data object' ) - - obj[['data']][['LSWI']] <- with( obj[['data']], getLSWI( rho_nir, - rho_swir ) ) - obj[['data']][['Tscale']] <- getTscale( obj[['data']][['T']], + if (!('VPRM_driver_data' %in% class(obj))) + stop('obj must be a VPRM_driver_data object') + + + if (identical(all(is.na(obj[['data']][['LSWI']])), TRUE)) { + obj[['data']][['LSWI']] <- with(obj[['data']], + getLSWI(rho_nir, rho_swir)) + } + obj[['data']][['Tscale']] <- getTscale(obj[['data']][['T']], obj[['Tmax']], obj[['Tmin']], - obj[['Topt']] ) - if ( any( !is.na( obj[['data']][['phen']] ) ) ) { - ## for non-evergreen classes, derive Pscale from phenology - obj[['data']][['Pscale']] <- with( obj[['data']], getPscale( LSWI, phen ) ) + obj[['Topt']]) + if (obj[['model_form']] == 'urban') { + obj[['data']][['Pscale']] <- with(obj[['data']], getPscale_urban(EVI)) } else { - ## for evergreen classes, set Pscale to 1.0 (Mahadevan et al, 2008) - obj[['data']][['Pscale']] <- 1.0 + if (any(!is.na(obj[['data']][['phen']]))) { + ## for non-evergreen classes, derive Pscale from phenology + obj[['data']][['Pscale']] <- with(obj[['data']], getPscale(LSWI, phen)) + } else { + ## for evergreen classes, set Pscale to 1.0 (Mahadevan et al, 2008) + obj[['data']][['Pscale']] <- 1.0 + } } - obj[['data']][['Wscale']] <- with( obj[['data']], - getWscale( LSWI, max( LSWI, na.rm=TRUE ) ) ) + obj[['data']][['Wscale']] <- with(obj[['data']], + getWscale(LSWI, max(LSWI, na.rm=TRUE))) Tresp <- obj[['data']][['T']] Tresp[ Tresp < obj[['Tlow']] ] <- obj[['Tlow']] obj[['data']][['Tresp']] <- Tresp - return( obj ) + return(obj) } - ##' method for VPRM_driver_data ##' ##' The data field of the VPRM_driver_data object is kept. Other @@ -226,7 +247,25 @@ calculate_VPRM_derived_input_fields <- function( obj ) { ##' EVI=PFa_evi[['evi']], ##' phen=NA) ##' print(head(as.data.frame(pfa_dd))) -as.data.frame.VPRM_driver_data <- function( x, ... ) { - return( x[[ 'data' ]] ) +as.data.frame.VPRM_driver_data <- function(x, ...) { + return(x[[ 'data' ]]) } + +##' calculate photosynthetically available radiation (PAR) from incident +##' downward shortwave radiation (SWDN) +##' +##' uses the mean result from Britton and Dodd (1976) table I. Averages the +##' tables two values for Apr-May together, then averages all bimonthly +##' averages. +##' @title downward shortwave radiation to PAR +##' @param SWDN numeric vector; downward shortwave radiation (W m-2) +##' @return numeric vector containing PAR values (umol m-2 s-1) +##' @author Timothy W. Hilton +##' @references Britton, C. M. and Dodd, J. D., 1976. Relationships of +##' photosynthetically active radiation and shortwave irradiance. Agric. +##' Meteorol., 17: 1--7. https://doi.org/10.1016/0002-1571(76)90080-7 +##' @export +SWDN_2_PAR <- function(SWDN) { + return(SWDN * 2.17305) +} diff --git a/R/estimateVPRMPars.R b/R/estimateVPRMPars.R index 97ed792..a0e6113 100644 --- a/R/estimateVPRMPars.R +++ b/R/estimateVPRMPars.R @@ -7,41 +7,46 @@ ##' DEoptim package. ##' ##' @title estimate VPRM parameter values by minimizing SSE -##' @param all_data data frame; VPRM driver data to drive the -##' parameter estimation. Should usually be the 'data' field of a -##' VPRM_driver_data object. -##' @param opt_groups list of factors -- data will be split by the -##' levels of opt_groups and each combination optimized separately. -##' Groups containing less than six observations are ignored. If -##' unspecified parameters are estimated for all of all_data. -##' @param DE_itermax integer, maximum differential evolution -##' iterations (see DEoptim documentation). Should be something like -##' 800 for a production run -- this will take some time for a typical -##' data set. Run with a small number (5 or so) for a debugging run. -##' @param out_path character string; path to directory in which to -##' save the estimated parameters. Default is the value of getwd() -##' @param par_set_str character string; phrase to denote the -##' parameterization being considered -##' @param run_parallel TRUE|{FALSE}; if true, use Rmpi to run -##' optimization jobs in parallel -##' @param lambda_prior 2-element vector; upper and lower lambda -##' values for optimization. Default is c(0.0, 1.5). -##' @param alpha_prior 2-element vector; upper and lower alpha -##' values for optimization. Default is c(0.0, 1.5). -##' @param beta_prior 2-element vector; upper and lower beta -##' values for optimization. Default is c(-4.0, 4.0). -##' @param PAR0_prior 2-element vector; upper and lower PAR_0 -##' values for optimization. Default is c(0.1, 6000). -##' @return 0 on success. A list of DEoptim objects (see DEoptim -##' documentation), one for each unique combination of factors in -##' opt_groups, is written to an RDS file in the directory specified -##' by out_path. The file is named in the format -##' ParEst_PAR_SET_STR.de.rds, where PAR_SET_STR is the value of the -##' par_set_str argument to estimate_VPRM_pars. The best fit -##' parameter values are in a named vector in the -##' [['optim']][['bestmem']] field of the DEoptim objects. See -##' DEoptim documentation for further interpretation of DEoptim -##' objects. +##' @param all_data data frame; VPRM driver data to drive the parameter +##' estimation. Should usually be the 'data' field of a VPRM_driver_data +##' object. +##' @param opt_groups list of factors -- data will be split by the levels of +##' opt_groups and each combination optimized separately. Groups containing +##' less than six observations are ignored. If unspecified parameters are +##' estimated for all of all_data. +##' @param DE_itermax integer, maximum differential evolution iterations (see +##' DEoptim documentation). Should be something like 800 for a production run +##' -- this will take some time for a typical data set. Run with a small +##' number (5 or so) for a debugging run. +##' @param out_path character string; path to directory in which to save the +##' estimated parameters. Default is the value of getwd() +##' @param par_set_str character string; phrase to denote the parameterization +##' being considered +##' @param run_parallel TRUE|{FALSE}; if true, use Rmpi to run optimization jobs +##' in parallel +##' @param lambda_prior 2-element vector; upper and lower lambda values for +##' optimization. Default is c(0.0, 1.5). +##' @param alpha_prior 2-element vector; upper and lower alpha values for +##' optimization. Default is c(0.0, 1.5). +##' @param beta_prior 2-element vector; upper and lower beta values for +##' optimization. Default is c(-4.0, 4.0). +##' @param PAR0_prior 2-element vector; upper and lower PAR_0 values for +##' optimization. Default is c(0.1, 6000). +##' @param model_form string, optional; form of VPRM model to use. Options are +##' "Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +##' (2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +##' (2017). If set to "urban", the driver data must include variables ISA +##' proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +##' EVI). +##' @return 0 on success. A list of DEoptim objects (see DEoptim documentation), +##' one for each unique combination of factors in opt_groups, is written to an +##' RDS file in the directory specified by out_path. The file is named in the +##' format ParEst_PAR_SET_STR.de.rds, where PAR_SET_STR is the value of the +##' par_set_str argument to estimate_VPRM_pars. The best fit parameter values +##' are in a named vector in the [['optim']][['bestmem']] field of the DEoptim +##' objects. See DEoptim documentation for further interpretation of DEoptim +##' objects. + ##' @author Timothy W. Hilton ##' @import DEoptim ##' @export @@ -80,7 +85,8 @@ estimate_VPRM_pars <- function(all_data, lambda_prior=c(0.0, 1.5), alpha_prior=c(0.0, 1.5), beta_prior=c(-4.0, 4.0), - PAR0_prior=c(0.1 , 6000)) { + PAR0_prior=c(0.1 , 6000), + model_form='Mahadevan07') { if ( !is.null( opt_groups ) ) { chunk_list <- split( all_data, f=opt_groups ) @@ -103,7 +109,8 @@ estimate_VPRM_pars <- function(all_data, lambda_prior=lambda_prior, alpha_prior=alpha_prior, beta_prior=beta_prior, - PAR0_prior=PAR0_prior) } + PAR0_prior=PAR0_prior, + model_form=model_form) } ## ----- ## if parallel run is requested, check to see if Rmpi is installed. @@ -216,12 +223,27 @@ getAbsWeightedErr <- function(x) { ##' @param driver_data May be a VPRM_driver_data object or a data ##' frame. If a data frame, driver_data must contain the variables ##' Tscale, Pscale, Wscale, EVI, and PAR, and NEE_obs. +##' @param model_form string, optional; form of VPRM model to use. Options are +##' "Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +##' (2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +##' (2017). If set to "urban", the driver data must include variables ISA +##' proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +##' EVI). ##' @return sum of squared errors for VPRM NEE residuals for the ##' specified parameters and NEE observations. ##' @author Timothy W. Hilton -"L" <- function(par, driver_data) { +##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, +##' J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based +##' biosphere parameterization for net ecosystem CO2 exchange: Vegetation +##' Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, +##' GB2005, doi:10.1029/2006GB002735, 2008. +##' @references Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., +##' Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic +##' fluxes in regional carbon budgets. Science of The Total Environment, 592, +##' 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 +"L" <- function(par, driver_data, model_form='Mahadevan07') { driver_data <- as.data.frame(driver_data) - NEE_vprm <- vprm_calc_NEE(driver_data, par[1], par[2], par[3], par[4]) + NEE_vprm <- vprm_calc_NEE(driver_data, par[1], par[2], par[3], par[4], model_form) res <- driver_data[['NEE_obs']] - NEE_vprm return(getSSE(res)) } @@ -231,23 +253,37 @@ getAbsWeightedErr <- function(x) { ##' estimate_VPRM_pars. ##' ##' @title run DEoptim to estimate VPRM parameter values -##' @param driver_data May be a VPRM_driver_data object or a data -##' frame. If a data frame, driver_data must contain the variables -##' Tscale, Pscale, Wscale, EVI, and PAR, and NEE_obs. +##' @param driver_data May be a VPRM_driver_data object or a data frame. If a +##' data frame, driver_data must contain the variables Tscale, Pscale, Wscale, +##' EVI, and PAR, and NEE_obs. ##' @param DEcontrol DEoptim.control object ##' @param refresh how many DE iterations in between progress writeouts -##' @param msg character string; message to be displayed before DE is -##' called. Useful for log files. -##' @param lambda_prior 2-element vector; upper and lower lambda -##' values for optimization. Default is c(0.0, 1.5). -##' @param alpha_prior 2-element vector; upper and lower alpha -##' values for optimization. Default is c(0.0, 1.5). -##' @param beta_prior 2-element vector; upper and lower beta -##' values for optimization. Default is c(-4.0, 4.0). -##' @param PAR0_prior 2-element vector; upper and lower PAR_0 -##' values for optimization. Default is c(0.1, 6000). -##' @return DEoptim object. DEoptim output for best VPRM parameter -##' estimate. +##' @param msg character string; message to be displayed before DE is called. +##' Useful for log files. +##' @param lambda_prior 2-element vector; upper and lower lambda values for +##' optimization. Default is c(0.0, 1.5). +##' @param alpha_prior 2-element vector; upper and lower alpha values for +##' optimization. Default is c(0.0, 1.5). +##' @param beta_prior 2-element vector; upper and lower beta values for +##' optimization. Default is c(-4.0, 4.0). +##' @param PAR0_prior 2-element vector; upper and lower PAR_0 values for +##' optimization. Default is c(0.1, 6000). +##' @param model_form string, optional; form of VPRM model to use. Options are +##' "Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +##' (2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +##' (2017). If set to "urban", the driver data must include variables ISA +##' proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +##' EVI). +##' @return DEoptim object. DEoptim output for best VPRM parameter estimate. +##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, +##' J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based +##' biosphere parameterization for net ecosystem CO2 exchange: Vegetation +##' Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, +##' GB2005, doi:10.1029/2006GB002735, 2008. +##' @references Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., +##' Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic +##' fluxes in regional carbon budgets. Science of The Total Environment, 592, +##' 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 ##' @import DEoptim ##' @export ##' @author Timothy W. Hilton @@ -260,7 +296,8 @@ optimizeVPRM_DE <- function(driver_data, lambda_prior=c(0.0, 1.5), alpha_prior=c(0.0, 1.5), beta_prior=c(-4.0, 4.0), - PAR0_prior=c(0.1 , 6000)) { + PAR0_prior=c(0.1 , 6000), + model_form="Mahadevan07") { cat('within optimizeVPRM_DE:\n') cat('lambda_prior: ', lambda_prior, '\n') @@ -281,7 +318,7 @@ optimizeVPRM_DE <- function(driver_data, ##----- ##find optimized parameters - r <- DEoptim(fn=L, lower=lower, upper=upper, control=DEcontrol, driver_data) + r <- DEoptim(fn=L, lower=lower, upper=upper, control=DEcontrol, driver_data, model_form) ##----- ##do some bookkeeping diff --git a/R/vprm.R b/R/vprm.R index fc1545e..a72485b 100644 --- a/R/vprm.R +++ b/R/vprm.R @@ -5,7 +5,7 @@ ##' @param Tmax maximum temp at which photosynthesis occurs (C) ##' @param Tmin minimum temp at which photosynthesis occurs (C) ##' @param Topt optimal temperature for photosynthesis (C) -##' @return Tscale term in VPRM equation (eqn 12 in Mahadevan et al, +##' @return Tscale term in VPRM equation (eqn 6 in Mahadevan et al, ##' 2007) ##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, ##' A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A @@ -41,7 +41,7 @@ getTscale <- function (T, Tmax, Tmin, Topt) ##' @param LSWI 1xN numeric vector; land surface water index ##' @param phen 1xN factor vector; MODIS phenology (factor with levels ##' ginc, gmin, gmax, gdec) -##' @return Pscale term in VPRM equation (eqn 12 in Mahadevan et al, 2008) +##' @return Pscale term in VPRM equation (eqn 7 in Mahadevan et al, 2008) ##' @author Timothy W. Hilton ##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, ##' A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A @@ -76,7 +76,7 @@ getTscale <- function (T, Tmax, Tmin, Topt) ##' phen=NA) ##' pfa_df <- as.data.frame( pfa_dd ) ##' pscale <- getPscale( pfa_df[['LSWI']], pfa_df[['phen']] ) -getPscale <- function( LSWI, phen ) { +getPscale <- function(LSWI, phen) { Pscale <- (1 + LSWI)/2 Pscale[ phen == 'gmax' ] <- 1.0 @@ -84,12 +84,50 @@ getPscale <- function( LSWI, phen ) { } +##' calculates Pscale according to SI eqn 4 in Hardiman et al, 2017 +##' +##' @title calculate Pscale for urbanVPRM +##' @param EVI 1xN numeric vector; enhanced vegetation index +##' @return Pscale term in urbanVPRM GEE equation (eqn SI eqn 4 in Hardiman et al, 2017) +##' @author Timothy W. Hilton +##' @references Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., +##' Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic +##' fluxes in regional carbon budgets. Science of The Total Environment, 592, +##' 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 +##' @export +##' @examples +##' data(Park_Falls) +##' pfa_dd <- VPRM_driver_data(name_long="Park Falls", +##' name_short = "US-PFa", +##' lat=45.9459, +##' lon=-90.2723, +##' PFT='MF', +##' tower_date=PFa_tower_obs[['date']], +##' NEE_obs=PFa_tower_obs[['FC']], +##' T=PFa_tower_obs[['TA']], +##' PAR=PFa_tower_obs[['PAR']], +##' date_nir = PFa_refl[['date']], +##' rho_nir=PFa_refl[['nir']], +##' date_swir = PFa_refl[['date']], +##' rho_swir = PFa_refl[['swir']], +##' date_EVI = PFa_evi[['date']], +##' EVI=PFa_evi[['evi']], +##' phen=NA) +##' pfa_df <- as.data.frame(pfa_dd) +##' pscale <- getPscale_urban(pfa_df[['EVI']]) +getPscale_urban <- function(EVI) { + Pscale <- ((EVI - min(EVI, na.rm=TRUE)) / + (max(EVI, na.rm=TRUE) - EVI)) + return(Pscale) +} + + ##' calculates Wscale according to eqn 8 in Mahadevan et al, 2007 ##' ##' @title calculate Wscale ##' @param LSWI numeric vector; land surface water index ##' @param LSWI_max numeric; maximum LSWI for site (that is, a single value) -##' @return Pscale term in VPRM equation (eqn 12 in Mahadevan et al, 2007) +##' @return Wscale term in VPRM equation (eqn 8 in Mahadevan et al, 2007) ##' @author Timothy W. Hilton ##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, ##' A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A @@ -188,34 +226,44 @@ getLSWI <- function(rho_nir, rho_swir) { ##' same length as the number of observations in driver_data. ##' ##' The Tresp variable in driver_data is the temperature used to calculate -##' respiration. Tresp should be max(Tair, Tlow), where Tair is the -##' air temperature (deg C) and Tlow is the minimum air temperature -##' (deg C) for respiration. This is explained more fully in -##' Mahadevan et al (2008) section 2.2. +##' respiration. Tresp should be max(Tair, Tlow), where Tair is the air +##' temperature (deg C) and Tlow is the minimum air temperature (deg C) for +##' respiration. This is explained more fully in Mahadevan et al (2008) section +##' 2.2. ##' @title calculate VPRM NEE -##' @param driver_data May be a VPRM_driver_data object or a data -##' frame. If a data frame, driver_data must contain the variables -##' Tscale, Pscale, Wscale, EVI, PAR, and Tresp. The variables -##' lambda, alpha, beta, and PAR_0 are optional (see 'details'). +##' @param driver_data May be a VPRM_driver_data object or a data frame. If a +##' data frame, driver_data must contain the variables Tscale, Pscale, Wscale, +##' EVI, PAR, and Tresp. The variables lambda, alpha, beta, and PAR_0 are +##' optional (see 'details'). ##' @param lambda_param numeric, optional; VPRM parameter: maximum light use -##' efficiency. -##' @param alpha_param numeric, optional; VPRM parameter (slope of respiration with -##' respect to temperature) +##' efficiency. +##' @param alpha_param numeric, optional; VPRM parameter (slope of respiration +##' with respect to temperature) ##' @param beta_param numeric, optional; VPRM parameter (basal respiration rate) -##' @param PAR_0_param numeric, optional; VPRM parameter (LUE half-saturation value) +##' @param PAR_0_param numeric, optional; VPRM parameter (LUE half-saturation +##' value) +##' @param model_form string, optional; form of VPRM model to use. Options are +##' "Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +##' (2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +##' (2017). If set to "urban", the driver data must include variables ISA +##' proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +##' EVI). ##' @return vector of same length as number of rows in driver_data containin -##' VPRM NEE [umol m-2 s-1] +##' VPRM NEE [umol m-2 s-1] ##' @author Timothy W. Hilton -##' @references Hilton, T. W., Davis, K. J., Keller, K., and Urban, -##' N. M.: Improving North American terrestrial CO2 flux diagnosis -##' using spatial structure in land surface model residuals, -##' Biogeosciences, 10, 4607-4625, doi:10.5194/bg-10-4607-2013, 2013. -##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, -##' A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A -##' satellite-based biosphere parameterization for net ecosystem CO2 -##' exchange: Vegetation Photosynthesis and Respiration Model -##' (VPRM), Global Biogeochem. Cy., 22, GB2005, -##' doi:10.1029/2006GB002735, 2008. +##' @references Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: +##' Improving North American terrestrial CO2 flux diagnosis using spatial +##' structure in land surface model residuals, Biogeosciences, 10, 4607-4625, +##' doi:10.5194/bg-10-4607-2013, 2013. +##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, +##' J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based +##' biosphere parameterization for net ecosystem CO2 exchange: Vegetation +##' Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, +##' GB2005, doi:10.1029/2006GB002735, 2008. +##' @references Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., +##' Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic +##' fluxes in regional carbon budgets. Science of The Total Environment, 592, +##' 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 ##' @export ##' @examples ##' data(Park_Falls) @@ -239,11 +287,17 @@ getLSWI <- function(rho_nir, rho_swir) { ##' attach(all_all_VPRM_parameters) ##' NEE <- vprm_calc_NEE(pfa_dd, ##' lambda=lambda, PAR_0=PAR_0, alpha=alpha, beta=beta) -vprm_calc_NEE <- function(driver_data, lambda_param=NULL, alpha_param=NULL, beta_param=NULL, PAR_0_param=NULL) { - GEE <- vprm_calc_GEE(driver_data, lambda_param, PAR_0_param) - R <- vprm_calc_R(driver_data, alpha_param, beta_param) - NEE <- R - GEE - return(NEE) +vprm_calc_NEE <- function(driver_data, + lambda_param=NULL, + alpha_param=NULL, + beta_param=NULL, + PAR_0_param=NULL, + model_form='Mahadevan07') { + ## cat('calculating VPRM NEE using ', model_form, 'formulation\n') + GEE <- vprm_calc_GEE(driver_data, lambda_param, PAR_0_param) + R <- vprm_calc_R(driver_data, alpha_param, beta_param, model_form=model_form) + NEE <- R - GEE + return(NEE) } ##' calculate VPRM GEE according to Mahadevan et al (2008) eq. 9 @@ -331,8 +385,9 @@ vprm_calc_GEE <- function(driver_data, lambda_param=NULL, PAR_0_param=NULL) { } -##' calculates VPRM ecosystem respiration (R) according to eqn 10 -##' in Mahadevan et al, 2007 +##' calculates VPRM ecosystem respiration (R) according to either the VPRM +##' formulation of Mahadevan et al. (2007) eqn 10 or the urbanVPRM +##' formulation of Hardiman et al (2017) SI eqn 7 and SI eqn 8. ##' ##' Arguments alpha and beta may be omitted from the function call. ##' In this case they must be present as variables in data frame @@ -344,32 +399,46 @@ vprm_calc_GEE <- function(driver_data, lambda_param=NULL, PAR_0_param=NULL) { ##' length as the number of observations in driver_data. ##' ##' The Tresp variable in driver_data is the temperature used to calculate -##' respiration. Tresp should be max(Tair, Tlow), where Tair is the -##' air temperature (deg C) and Tlow is the minimum air temperature -##' (deg C) for respiration. This is explained more fully in -##' Mahadevan et al (2008) section 2.2. +##' respiration. Tresp should be max(Tair, Tlow), where Tair is the air +##' temperature (deg C) and Tlow is the minimum air temperature (deg C) for +##' respiration. This is explained more fully in Mahadevan et al (2008) section +##' 2.2. +##' +##' The urbanVPRM subdivides respiration into heterotrophic and autotrophic and +##' introduces a scaling factor based on a nearby pixel of similar land cover +##' with minimal impervious surface area. This scaling factor is derived from a +##' "reference EVI" term, described in more detail in the supplemental material +##' of Hardiman et al. (2017). ##' @title calculate VPRM ecosystem respiration -##' @param driver_data May be a VPRM_driver_data object or a data -##' frame. If a data frame, driver_data must contain the variables -##' Tscale, Pscale, Wscale, EVI, PAR, and Tresp. The variables alpha -##' and beta are optional (see 'details'). -##' @param alpha_param numeric, optional; VPRM parameter (slope of -##' respiration with respect to temperature) -##' @param beta_param numeric, optional; VPRM parameter (basal -##' respiration rate) +##' @param driver_data May be a VPRM_driver_data object or a data frame. If a +##' data frame, driver_data must contain the variables Tscale, Pscale, Wscale, +##' EVI, PAR, and Tresp. The variables alpha and beta are optional (see +##' 'details'). +##' @param alpha_param numeric, optional; VPRM parameter (slope of respiration +##' with respect to temperature) +##' @param beta_param numeric, optional; VPRM parameter (basal respiration rate) +##' @param model_form string, optional; form of VPRM model to use. Options are +##' "Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +##' (2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +##' (2017). If set to "urban", the driver data must include variables ISA +##' proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +##' EVI). ##' @return vector of same length as number of rows in driver_data containin -##' VPRM ecosystem respiration [umol m-2 s-1] +##' VPRM ecosystem respiration [umol m-2 s-1] ##' @author Timothy W. Hilton -##' @references Hilton, T. W., Davis, K. J., Keller, K., and Urban, -##' N. M.: Improving North American terrestrial CO2 flux diagnosis -##' using spatial structure in land surface model residuals, -##' Biogeosciences, 10, 4607-4625, doi:10.5194/bg-10-4607-2013, 2013. -##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, -##' A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A -##' satellite-based biosphere parameterization for net ecosystem CO2 -##' exchange: Vegetation Photosynthesis and Respiration Model -##' (VPRM), Global Biogeochem. Cy., 22, GB2005, -##' doi:10.1029/2006GB002735, 2008. +##' @references Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: +##' Improving North American terrestrial CO2 flux diagnosis using spatial +##' structure in land surface model residuals, Biogeosciences, 10, 4607-4625, +##' doi:10.5194/bg-10-4607-2013, 2013. +##' @references Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, +##' J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based +##' biosphere parameterization for net ecosystem CO2 exchange: Vegetation +##' Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, +##' GB2005, doi:10.1029/2006GB002735, 2008. +##' @references Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., +##' Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic +##' fluxes in regional carbon budgets. Science of The Total Environment, 592, +##' 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 ##' @export ##' @examples ##' data(Park_Falls) @@ -393,28 +462,79 @@ vprm_calc_GEE <- function(driver_data, lambda_param=NULL, PAR_0_param=NULL) { ##' data(VPRM_parameters) ##' attach(all_all_VPRM_parameters) ##' ER <- vprm_calc_R(pfa_dd, alpha=alpha, beta=beta) -vprm_calc_R <- function(driver_data, alpha_param=NULL, beta_param=NULL) { +vprm_calc_R <- function(driver_data, + alpha_param=NULL, + beta_param=NULL, + model_form='Mahadevan07') { - driver_data <- as.data.frame( driver_data ) + driver_data <- as.data.frame( driver_data ) - ## make sure VPRM parameters were specified as either function - ## parameters or within driver_data - if (is.null(alpha_param)) { - if ('alpha' %in% names( driver_data ) ) { - alpha_param <- driver_data[['alpha']] - } else { - stop('alpha is unspecified') - } + ## make sure VPRM parameters were specified as either function + ## parameters or within driver_data + if (is.null(alpha_param)) { + if ('alpha' %in% names( driver_data ) ) { + alpha_param <- driver_data[['alpha']] + } else { + stop('alpha is unspecified') } - if (is.null(beta_param)) { - if ('beta' %in% names( driver_data ) ) { - beta_param <- driver_data[['beta']] - } else { - stop('beta is unspecified') - } + } + if (is.null(beta_param)) { + if ('beta' %in% names( driver_data ) ) { + beta_param <- driver_data[['beta']] + } else { + stop('beta is unspecified') } + } + # calculate R for Mahadevan et al 2007 VPRM formulation + R <- alpha_param * driver_data[, "Tresp"] + beta_param + + if (model_form == 'urban') { + R <- urbanvprm_calc_R(R, driver_data, alpha_param, beta_param) + } + + return(R) +} + +##' calculates urbanVPRM ecosystem respiration (R) according to Hardiman et al. +##' (2017) SI eqn 7 and SI eqn 8 as described in SI section S2.4. +##' +##' .. content for \details{} .. +##' @title calculate urbanVPRM ecosystem respiration +##' @param Rinit numeric; the Rinit term, equal to the respiration for the +##' Mahadevan et al (2007) formulation. +##' @inherit vprm_calc_R return author references params +##' @param alpha_param numeric, optional; VPRM parameter (slope of respiration +##' with respect to temperature) +##' @param beta_param numeric, optional; VPRM parameter (basal respiration rate) +##' @param model_form string, optional; form of VPRM model to use. Options are +##' "Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +##' (2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +##' (2017). If set to "urban", the driver data must include variables ISA +##' proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +##' EVI). +##' @return vector of same length as number of rows in driver_data containin +##' urbanVPRM ecosystem respiration [umol m-2 s-1] +##' @author Timothy W. Hilton +urbanvprm_calc_R <- function(Rinit, driver_data, alpha_param, beta_param) { + + if (!('ISA' %in% names( driver_data ) )) { + stop('ISA is unspecified') + } + + if (!('refEVI' %in% names( driver_data ) )) { + stop('reference EVI is unspecified') + } - R <- alpha_param * driver_data[, "Tresp"] + beta_param + ## heterotrophic respiration; Hardiman et al 2017 SI eqn 7 + Rh <- ((1.0 - driver_data[['ISA']]) * Rinit) / 2.0 - return(R) + ## autotrophic respiration; Hardiman et al 2017 SI eqn 8 + Ra <- (((driver_data[['EVI']] + + (min(driver_data[['refEVI']]) * driver_data[['ISA']])) / + driver_data[['refEVI']]) * + Rinit) / 2.0 + ## Hardiman et al assume that autotrophic and heterotrophic respiration + ## contribute equally to ecosytem respiration (see SI section S2.4, first + ## paragraph). + return(Rh + Ra) } diff --git a/README.md b/README.md index 732ddb3..5835357 100644 --- a/README.md +++ b/README.md @@ -2,23 +2,23 @@ # Description: -Provides an R implementation of the Vegetation Photosynthesis and -Respiration Model (VPRM) of Mahadevan et al (2008) and tools to -estimate VPRM parameter values from observations. VPRM is a -simple diagnostic land surface model based on light-use -efficiency. VPRM diagnoses gross ecosystem exchange (GEE) of -carbon dioxide, ecosystem respiration (R), and net ecosystem -exchange (NEE) of carbon dioxide. VPRM parameters may be -estimated separately for different subsets of a dataset of -observations. If the Rmpi package is installed, such separate -parameter estimations may be run in parallel. +Provides an R implementation of the Vegetation Photosynthesis and Respiration +Model (VPRM) of Mahadevan et al (2008), the urbanVPRM of Hardiman et al (2017), +and tools to estimate VPRM parameter values from observations. VPRM is a simple +diagnostic land surface model based on light-use efficiency. VPRM diagnoses +gross ecosystem exchange (GEE) of carbon dioxide, ecosystem respiration (R), and +net ecosystem exchange (NEE) of carbon dioxide. The urbanVPRM adapts the VPRM to +urban settings by adjusting GEE and R to account for impervious surface area and +the urban heat island effect. (urban)VPRM parameters may be estimated separately +for different subsets of a dataset of observations. If the Rmpi package is +installed, such separate parameter estimations may be run in parallel. # Details: - Package: VPRMLandSfcModel - Type: Package -- Version: 1.2.1 -- Date: 2017-10-03 +- Version: 1.3.0 +- Date: 2023-07-07 - License: GPL-3 - LazyLoad: yes @@ -81,6 +81,12 @@ itself, use: > model (VPRM). Global Biogeochemical Cycles, 22, GB2005. > doi:10.1029/2006GB002735. +To cite the urban Vegetation Photosynthesis Respiration Model (urbanVPRM) use +> Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., Getson, J. M., & +> Friedl, M. A. (2017). Accounting for urban biogenic fluxes in regional carbon +> budgets. Science of The Total Environment, 592, 366–372. +> https://doi.org/https://doi.org/10.1016/j.scitotenv.2017.03.028 + To cite the R package 'VPRMLandSfcModel', use: > Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: > Improving North American terrestrial CO2 flux diagnosis using diff --git a/man/L.Rd b/man/L.Rd index 465be23..24a6234 100644 --- a/man/L.Rd +++ b/man/L.Rd @@ -1,9 +1,10 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimateVPRMPars.R \name{L} \alias{L} \title{cost function for VPRM parameterization} \usage{ -L(par, driver_data) +L(par, driver_data, model_form = "Mahadevan07") } \arguments{ \item{par}{four-element numeric vector containing lambda, alpha, @@ -12,6 +13,13 @@ beta, PAR_0 (in that order)} \item{driver_data}{May be a VPRM_driver_data object or a data frame. If a data frame, driver_data must contain the variables Tscale, Pscale, Wscale, EVI, and PAR, and NEE_obs.} + +\item{model_form}{string, optional; form of VPRM model to use. Options are +"Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +(2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +(2017). If set to "urban", the driver data must include variables ISA +proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +EVI).} } \value{ sum of squared errors for VPRM NEE residuals for the @@ -24,7 +32,18 @@ parameters and a a set of NEE observations. \details{ "L" abbreviations likelihood; currently SSE is a standin for a statistically proper likelihood function for land surface model residuals. } +\references{ +Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, + J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based + biosphere parameterization for net ecosystem CO2 exchange: Vegetation + Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, + GB2005, doi:10.1029/2006GB002735, 2008. + +Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., + Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic + fluxes in regional carbon budgets. Science of The Total Environment, 592, + 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 +} \author{ Timothy W. Hilton } - diff --git a/man/PFa_evi.Rd b/man/PFa_evi.Rd index 568ab31..da5fcc7 100644 --- a/man/PFa_evi.Rd +++ b/man/PFa_evi.Rd @@ -1,14 +1,17 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Park_Falls.R \docType{data} \name{PFa_evi} \alias{PFa_evi} \title{Park Falls EVI data} -\format{data frame containing MODIS enhanced vegetation index (EVI) for the Park Falls, Wisconsin tall tower Ameriflux site. The data frame contains the variables: +\format{ +data frame containing MODIS enhanced vegetation index (EVI) for the Park Falls, Wisconsin tall tower Ameriflux site. The data frame contains the variables: \describe{ \item{date}{chron object; EVI timestamps (date and time)} \item{evi}{the EVI value (unitless; 0 <= EVI <= 1)} \item{bird}{the satellite that made the measurements; (terra|aqua)} -}} +} +} \source{ These data are extracted from the Oak Ridge National Laboratory MODIS subsets for MODIS product MOD13Q1. } @@ -31,4 +34,3 @@ Oak Ridge National Laboratory Distributed Active Archive Center (ORNL DAAC). 201 \seealso{ \code{\link{Park_Falls}} } - diff --git a/man/PFa_phen.Rd b/man/PFa_phen.Rd index 6e5c12c..c69d2e3 100644 --- a/man/PFa_phen.Rd +++ b/man/PFa_phen.Rd @@ -1,13 +1,16 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Park_Falls.R \docType{data} \name{PFa_phen} \alias{PFa_phen} \title{Park Falls phenology transition data} -\format{data frame containing MODIS enhanced vegetation index (EVI) for the Park Falls, Wisconsin tall tower Ameriflux site. The data frame contains the variables: +\format{ +data frame containing MODIS enhanced vegetation index (EVI) for the Park Falls, Wisconsin tall tower Ameriflux site. The data frame contains the variables: \describe{ \item{date}{chron object; timestamps (date and time)} \item{phen}{factor; phenology dynamics. levels are ginc (onset greenness increase), gdec (onset greenness decrease), gmin (onset greenness minimum), gmax (onset greenness maximum).} -}} +} +} \source{ These data are extracted from the Oak Ridge National Laboratory MODIS subsets for MODIS product MOD12Q2. } @@ -28,4 +31,3 @@ Oak Ridge National Laboratory Distributed Active Archive Center (ORNL DAAC). 201 \seealso{ \code{\link{Park_Falls}} } - diff --git a/man/PFa_refl.Rd b/man/PFa_refl.Rd index b1f71d8..afe15b4 100644 --- a/man/PFa_refl.Rd +++ b/man/PFa_refl.Rd @@ -1,16 +1,19 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Park_Falls.R \docType{data} \name{PFa_refl} \alias{PFa_refl} \title{Park Falls MODIS reflectance data} -\format{data frame containing MODIS reflectances for the Park Falls, Wisconsin tall tower Ameriflux site. The data frame contains the variables: +\format{ +data frame containing MODIS reflectances for the Park Falls, Wisconsin tall tower Ameriflux site. The data frame contains the variables: \describe{ \item{date}{chron object; timestamps (date and time)} \item{red}{the reflectance value for the red band} \item{nir}{the reflectance value for the near infrared (NIR) band} \item{blue}{the reflectance value for the blue band} \item{swir}{the reflectance value for the shortwave infrade (SWIR) band} -}} +} +} \source{ These data are extracted from the Oak Ridge National Laboratory MODIS subsets for MODIS product MOD09A1. } @@ -41,4 +44,3 @@ Oak Ridge National Laboratory Distributed Active Archive Center (ORNL DAAC). 201 \seealso{ \code{\link{Park_Falls}} } - diff --git a/man/PFa_tower_obs.Rd b/man/PFa_tower_obs.Rd index 277f508..1491970 100644 --- a/man/PFa_tower_obs.Rd +++ b/man/PFa_tower_obs.Rd @@ -1,14 +1,17 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Park_Falls.R \docType{data} \name{PFa_tower_obs} \alias{PFa_tower_obs} \title{Park Falls CO2 flux, PAR, and surface temperature} -\format{data frame containing ground-based observations from the Park Falls, Wisconsin tall tower Ameriflux site. The data frame contains the variables: +\format{ +data frame containing ground-based observations from the Park Falls, Wisconsin tall tower Ameriflux site. The data frame contains the variables: \describe{ \item{date}{chron objects; the data timestamps} \item{TA}{surface air temperature (C)} \item{FC}{flux of CO2 (umol m-2 s-1)} -\item{PAR}{photosynthetically active radiation (umol m-2 s-1)}}} +\item{PAR}{photosynthetically active radiation (umol m-2 s-1)}} +} \source{ These data were extracted from the 2005 level II Ameriflux file for US-PFa on on 16 Dec 2013. @@ -32,4 +35,3 @@ with( PFa_tower_obs, plot(date, TA, \seealso{ \code{\link{Park_Falls}} } - diff --git a/man/Park_Falls.Rd b/man/Park_Falls.Rd index 426564d..aef305e 100644 --- a/man/Park_Falls.Rd +++ b/man/Park_Falls.Rd @@ -1,15 +1,18 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Park_Falls.R \docType{data} \name{Park_Falls} \alias{Park_Falls} \title{Park Falls, Wisconsin, USA eddy covariance data and MODIS data} -\format{The dataset Park_Falls contains four data frames: +\format{ +The dataset Park_Falls contains four data frames: \describe{ \item{PFa_evi}{timestamped MODIS EVI from NASA's Terra satellite (MODIS product MOD13Q1).} \item{PFa_refl}{timestamped MODIS surface reflectances in the red, blue, near infrared (NIR), and shortwave infrared (SWIR) bands (MODIS product MCD43A4).} \item{PFa_phen}{timestamped MODIS phenology dynamics data (MODIS product MOD12Q2)} \item{PFa_tower_obs}{timestamped air temperature (TA), net ecosystem exchange of carbon dioxide (FC), and photosynthetically active radiation (PAR) data.} -}} +} +} \source{ The data in PFa_tower_obs are from the Park Falls, Wisconsin Ameriflux level II dataset (\url{ameriflux.lbl.gov}). @@ -31,9 +34,6 @@ with( PFa_evi, plot(date, evi, ylab='MODIS EVI', xlab='date', main='Park Falls EVI' )) } -\author{ -Timothy W. Hilton -} \references{ MODIS snapshots: \url{http://daac.ornl.gov/MODIS/} @@ -49,4 +49,6 @@ Measurement Methodology. J. Atmos. Oceanic Technol., 18, 529-542. \code{\link{PFa_tower_obs}}, \code{\link{PFa_evi}}, \code{\link{PFa_refl}}, \code{\link{PFa_phen}} } - +\author{ +Timothy W. Hilton +} diff --git a/man/SWDN_2_PAR.Rd b/man/SWDN_2_PAR.Rd new file mode 100644 index 0000000..3e423cb --- /dev/null +++ b/man/SWDN_2_PAR.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/VPRM_driver_data.R +\name{SWDN_2_PAR} +\alias{SWDN_2_PAR} +\title{downward shortwave radiation to PAR} +\usage{ +SWDN_2_PAR(SWDN) +} +\arguments{ +\item{SWDN}{numeric vector; downward shortwave radiation (W m-2)} +} +\value{ +numeric vector containing PAR values (umol m-2 s-1) +} +\description{ +calculate photosynthetically available radiation (PAR) from incident +downward shortwave radiation (SWDN) +} +\details{ +uses the mean result from Britton and Dodd (1976) table I. Averages the +tables two values for Apr-May together, then averages all bimonthly +averages. +} +\references{ +Britton, C. M. and Dodd, J. D., 1976. Relationships of + photosynthetically active radiation and shortwave irradiance. Agric. + Meteorol., 17: 1--7. https://doi.org/10.1016/0002-1571(76)90080-7 +} +\author{ +Timothy W. Hilton +} diff --git a/man/VPRMLandSfcModel-package.Rd b/man/VPRMLandSfcModel-package.Rd index 0bdc467..59961cf 100644 --- a/man/VPRMLandSfcModel-package.Rd +++ b/man/VPRMLandSfcModel-package.Rd @@ -1,72 +1,11 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/VPRMLandSfcModel-package.R +\docType{package} \name{VPRMLandSfcModel-package} -\alias{VPRMLandSfcModel-package} \alias{VPRMLandSfcModel} -\docType{package} -\title{ -R implementation of VPRM -} +\alias{VPRMLandSfcModel-package} +\title{VPRMLandSfcModel: R implementation of VPRM with parameter estimation} \description{ -Provides an R implementation of the Vegetation Photosynthesis and -Respiration Model (VPRM) of Mahadevan et al (2008) and tools to estimate -VPRM parameter values from observations. VPRM is a simple diagnostic -land surface model based on light-use efficiency. VPRM diagnoses gross -ecosystem exchange (GEE) of carbon dioxide, ecosystem respiration (R), -and net ecosystem exchange (NEE) of carbon dioxide. VPRM parameters may -be estimated separately for different subsets of a dataset of -observations. If the Rmpi package is installed, such separate -parameter estimations may be run in parallel. -} -\details{ -\tabular{ll}{ -Package: \tab VPRMLandSfcModel\cr -Type: \tab Package\cr -Version: \tab 1.2\cr -Date: \tab 2014-01-09\cr -License: \tab GPL-3\cr -LazyLoad: \tab yes\cr -} -The literature in the references section provides a detailed description -of VPRM. - -The top-level function for running VPRM is vprm_calc_NEE. vprm_calc_NEE -calculates net ecosystem exchange (NEE) according to the VPRM (Mahadevan -et al (2008) eqn 12). - -The top-level function for estimating VPRM parameters from observations -is estimate_VPRM_pars. - -The other functions provide methods to obtain the necessary driver data -and to calculate some of the intermediate quantities that VPRM derives -from remote sensing observations (e.g. land surface water index, Tscale, -Pscale, etc.). - -The package includes two datasets: -\describe{ - \item{Park_Falls}{contains ground-observed as well as satellite-observed driver data for VPRM from the Park Falls, Wisconsin, USA Ameriflux site.} - \item{VPRM_parameters}{contains values for VPRM parameters lambda, - PAR_0, alpha, and beta. The parameter values were determined by - optimizing VPRM using 65 North American eddy covariance sites as - described in Hilton etal (2013).}}} - -\author{ -Timothy W. Hilton - -Maintainer: Timothy W. Hilton -} -\references{ - To cite the Vegetation Photosynthesis Respiration Model - (VPRM) itself, use:\cr - Mahadevan, P., Wofsy, S.C., Matross, D.M., Xiao, X., Dunn, A.L., Lin, - J.C., Gerbig, C., Munger, J.W., Chow, V.Y., and Gottlieb, E.W., 2008. A - satellite-based biosphere parameterization for net ecosystem CO2 - exchange: Vegetation photosynthesis and respiration model (VPRM). Global - Biogeochemical Cycles, 22, GB2005. doi:10.1029/2006GB002735. - - To cite the R package 'VPRMLandSfcModel', use:\cr - Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: Improving - North American terrestrial CO2 flux diagnosis using spatial structure - in land surface model residuals, Biogeosciences, 10, 4607-4625, - doi:10.5194/bg-10-4607-2013, 2013. +Provides an R implementation of the Vegetation Photosynthesis and Respiration Model (VPRM), the urbanVPRM, and tools to estimate VPRM parameter values from observations. VPRM is a simple diagnostic land surface model based on light-use efficiency. VPRM diagnoses gross ecosystem exchange (GEE) of carbon dioxide, ecosystem respiration (R), and net ecosystem exchange (NEE) of carbon dioxide. To cite the VPRMLandSfcModel R package or the (urban)VPRM model itself in a publication, or for a more detailed description of VPRM, see (within R) 'citation("VPRMLandSurfaceModel")'. } -\keyword{ package } - +\keyword{internal} diff --git a/man/VPRM_driver_data.Rd b/man/VPRM_driver_data.Rd index 74a8a4f..103a4a3 100644 --- a/man/VPRM_driver_data.Rd +++ b/man/VPRM_driver_data.Rd @@ -1,49 +1,74 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/VPRM_driver_data.R \name{VPRM_driver_data} \alias{VPRM_driver_data} \title{build a VPRM_driver_data object} \usage{ -VPRM_driver_data(name_long = "", name_short = "", lat = NA, lon = NA, - PFT = NA, note = "", Tmin = 0, Tmax = 40, Topt = 20, Tlow = 2, - tower_date = NA, NEE_obs = NA, T = NA, PAR = NA, date_nir = NA, - rho_nir = NA, date_swir, rho_swir = NA, date_EVI, EVI = NA, phen = NA) +VPRM_driver_data( + name_long = "", + name_short = "", + lat = NA, + lon = NA, + PFT = NA, + note = "", + Tmin = 0, + Tmax = 40, + Topt = 20, + Tlow = 2, + tower_date = NA, + NEE_obs = NA, + T = NA, + PAR = NA, + date_nir = NA, + rho_nir = NA, + date_swir, + rho_swir = NA, + date_EVI, + EVI = NA, + refEVI = NA, + ISA = NA, + LSWI = NA, + phen = NA, + model_form = "Mahadevan07" +) } \arguments{ -\item{name_long}{character string; "short name" of the site. e.g. US-PFa} +\item{name_long}{character string; "short name" of the site. e.g. US-PFa} -\item{name_short}{character string; "long name" of the site. e.g. Park Falls} +\item{name_short}{character string; "long name" of the site. e.g. Park Falls} \item{lat}{numeric; latitude of the site (deg N)} \item{lon}{numeric; longitude of the site (deg E)} -\item{PFT}{character string; plant functional type. Will be converted to a factor.} +\item{PFT}{character string; plant functional type. Will be converted to a +factor.} -\item{note}{character string; optional note; could be anything the -user finds useful.} +\item{note}{character string; optional note; could be anything the user +finds useful.} -\item{Tmin}{numeric; minimum temperature for photosynthesis (deg -C). See Mahadevan et al (2008) eq. 6.} +\item{Tmin}{numeric; minimum temperature for photosynthesis (deg C). See +Mahadevan et al (2008) eq. 6.} -\item{Tmax}{numeric; maximim temperature for photosynthesis (deg -C). See Mahadevan et al (2008) eq. 6.} +\item{Tmax}{numeric; maximim temperature for photosynthesis (deg C). See +Mahadevan et al (2008) eq. 6.} -\item{Topt}{numeric; optimum temperature for photosynthesis (deg -C). See Mahadevan et al (2008) eq. 6.} +\item{Topt}{numeric; optimum temperature for photosynthesis (deg C). See +Mahadevan et al (2008) eq. 6.} -\item{Tlow}{numeric; minimum temperature for respiration (deg C). -See Mahadevan et al (2008) eq. 10.} +\item{Tlow}{numeric; minimum temperature for respiration (deg C). See +Mahadevan et al (2008) eq. 10.} -\item{tower_date}{chron vector; timestamps for all tower -observations (NEE_obs, T, PAR)} +\item{tower_date}{chron vector; timestamps for all tower observations +(NEE_obs, T, PAR)} -\item{NEE_obs}{numeric vector; eddy covariance observed net -ecosystem exchange (NEE, umol m-2 s-1)} +\item{NEE_obs}{numeric vector; eddy covariance observed net ecosystem +exchange (NEE, umol m-2 s-1)} \item{T}{numeric vector; observed air temperature (deg C)} -\item{PAR}{numeric vector; observed photosynthetically active -radiation (umol m-2 s-1)} +\item{PAR}{numeric vector; observed photosynthetically active radiation +(umol m-2 s-1)} \item{date_nir}{chron vector; timestamps for NIR reflectance.} @@ -53,22 +78,36 @@ radiation (umol m-2 s-1)} \item{rho_swir}{numeric vector; SWIR reflectance values} -\item{date_EVI}{chron vector; timestamps for enhanced vegetation index (EVI).} +\item{date_EVI}{chron vector; timestamps for enhanced vegetation index +(EVI).} \item{EVI}{numeric vector; EVI values.} -\item{phen}{factor; phenology dynamics. levels are ginc (onset -greenness increase), gdec (onset greenness decrease), gmin (onset -greenness minimum), gmax (onset greenness maximum). If not -specified, phenology dynsamics are calculated from EVI using a -method similar to Zhang et al (2003).} +\item{refEVI}{numeric vector; reference EVI values. Only required for +urbanVPRM. See Hardiman et al SI section S2.4.} + +\item{ISA}{numeric vector; impervious surface area values. Only required for +urbanVPRM. Must vary between 0.0 and 1.0.} + +\item{LSWI}{numeric vector; Land Surface Water Index. If not provided will +be calculated from rho_nir and rho_swir.} + +\item{phen}{factor; phenology dynamics. levels are ginc (onset greenness +increase), gdec (onset greenness decrease), gmin (onset greenness +minimum), gmax (onset greenness maximum). If not specified, phenology +dynsamics are calculated from EVI using a method similar to Zhang et al +(2003).} + +\item{model_form}{string, optional; form of VPRM model to use. Options are +"Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +(2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +(2017). If set to "urban".} } \value{ -an object of class VPRM_driver_data. Has fields (see -above arguments for definitions): name_long, name_short, lat, lon, -PFT, note, Tmin, Tmax, Topt, Tlow. The data for NEE_obs, T, PAR, -rho_nir, rho_swir, EVI, and phen should be accessed using the -as.data.frame method. +an object of class VPRM_driver_data. Has fields (see above arguments + for definitions): name_long, name_short, lat, lon, PFT, note, Tmin, Tmax, + Topt, Tlow. The data for NEE_obs, T, PAR, rho_nir, rho_swir, EVI, and phen + should be accessed using the as.data.frame method. } \description{ class constructor for VPRM_driver_data. Accepts all driver data @@ -76,10 +115,10 @@ necessary to run VPRM for a single eddy covariance site, calculates "derived" fields, and interpolates phenology dynamics. } \details{ -"Derived fields" denote fields that are calculated from other -observed quanitities. For example, land surface water index -(LSWI) is a derived field, as it is calculated from MODIS -reflectances in the short infrared and near infrared bands. +"Derived fields" denote fields that are calculated from other observed +quanitities. For example, land surface water index (LSWI) is a derived +field, as it is calculated from MODIS reflectances in the short infrared and +near infrared bands. } \examples{ data(Park_Falls) @@ -101,22 +140,19 @@ pfa_dd <- VPRM_driver_data(name_long="Park Falls", phen=NA) print(head(as.data.frame(pfa_dd))) } +\references{ +Mahadevan, P., S. C. Wofsy, D. M. Matross, X. Xiao, A. L. Dunn, + J. C. Lin, C. Gerbig, J. W. Munger, V. Y. Chow, and E. W. Gottlieb (2008), + A satellite-based biosphere parameterization for net ecosystem CO2 + exchange: Vegetation Photosynthesis and Respiration Model (VPRM), Global + Biogeochem. Cycles, 22, GB2005, doi:10.1029/2006GB002735. + +Xiaoyang Zhang, Mark A. Friedl, Crystal B. Schaaf, Alan H. + Strahler, John C.F. Hodges, Feng Gao, Bradley C. Reed, Alfredo Huete, + Monitoring vegetation phenology using MODIS, Remote Sensing of + Environment, Volume 84, Issue 3, March 2003, Pages 471-475, ISSN + 0034-4257, http://dx.doi.org/10.1016/S0034-4257(02)00135-9. +} \author{ Timothy W. Hilton } -\references{ -Mahadevan, P., S. C. Wofsy, D. M. Matross, X. Xiao, -A. L. Dunn, J. C. Lin, C. Gerbig, J. W. Munger, V. Y. Chow, and -E. W. Gottlieb (2008), A satellite-based biosphere -parameterization for net ecosystem CO2 exchange: Vegetation -Photosynthesis and Respiration Model (VPRM), Global -Biogeochem. Cycles, 22, GB2005, doi:10.1029/2006GB002735. - -Xiaoyang Zhang, Mark A. Friedl, Crystal B. Schaaf, -Alan H. Strahler, John C.F. Hodges, Feng Gao, Bradley C. Reed, -Alfredo Huete, Monitoring vegetation phenology using MODIS, Remote -Sensing of Environment, Volume 84, Issue 3, March 2003, Pages -471-475, ISSN 0034-4257, -http://dx.doi.org/10.1016/S0034-4257(02)00135-9. -} - diff --git a/man/VPRM_parameters.Rd b/man/VPRM_parameters.Rd index a68dfcb..e5ea7df 100644 --- a/man/VPRM_parameters.Rd +++ b/man/VPRM_parameters.Rd @@ -1,13 +1,16 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/VPRM_parameters.R \docType{data} \name{VPRM_parameters} \alias{VPRM_parameters} \title{flux-tower-optimized VPRM parameter values} -\format{The dataset VPRM_parameters contains four data frames: +\format{ +The dataset VPRM_parameters contains four data frames: \describe{ \item{all_all_VPRM_parameters}{all-sites--all-available-data parameters from Hilton et al (2013).} \item{pft_all_VPRM_parameters}{PFT--all-time parameters from Hilton et al (2013). "PFT" abbreviates "Plant Functional Type".} -}} +} +} \source{ The VPRM parameter values were determined by optimizing to a set of 65 North American eddy covariance sites as described in @@ -20,9 +23,6 @@ The dataset VPRM_parameters contains the parameter values for the all-sites--all data(VPRM_parameters) print(pft_all_VPRM_parameters) } -\author{ -Timothy W. Hilton -} \references{ Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: Improving North American terrestrial CO2 flux diagnosis @@ -33,4 +33,6 @@ Biogeosciences, 10, 4607-4625, doi:10.5194/bg-10-4607-2013, 2013. \code{\link{all_all_VPRM_parameters}}, \code{\link{pft_all_VPRM_parameters}}, } - +\author{ +Timothy W. Hilton +} diff --git a/man/all_all_VPRM_parameters.Rd b/man/all_all_VPRM_parameters.Rd index b71e5ec..02519a1 100644 --- a/man/all_all_VPRM_parameters.Rd +++ b/man/all_all_VPRM_parameters.Rd @@ -1,10 +1,13 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/VPRM_parameters.R \docType{data} \name{all_all_VPRM_parameters} \alias{all_all_VPRM_parameters} \title{VPRM parameter set} -\format{data frame containing values for the VPRM parameters -lambda, PAR_0, alpha, and beta.} +\format{ +data frame containing values for the VPRM parameters +lambda, PAR_0, alpha, and beta. +} \source{ The parameter values were determined by optimizing to a set of 65 North American eddy covariance sites as described in @@ -22,9 +25,6 @@ all_all_VPRM_parameters is part of the data(VPRM_parameters) print(all_all_VPRM_parameters) } -\author{ -Timothy W. Hilton -} \references{ Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: Improving North American terrestrial CO2 flux diagnosis @@ -34,4 +34,6 @@ Biogeosciences, 10, 4607-4625, doi:10.5194/bg-10-4607-2013, 2013. \seealso{ \code{\link{VPRM_parameters}} } - +\author{ +Timothy W. Hilton +} diff --git a/man/as.data.frame.VPRM_driver_data.Rd b/man/as.data.frame.VPRM_driver_data.Rd index 44c23ba..3777020 100644 --- a/man/as.data.frame.VPRM_driver_data.Rd +++ b/man/as.data.frame.VPRM_driver_data.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/VPRM_driver_data.R \name{as.data.frame.VPRM_driver_data} \alias{as.data.frame.VPRM_driver_data} \title{coerce to a data frame} @@ -44,4 +45,3 @@ print(head(as.data.frame(pfa_dd))) \author{ Timothy W. Hilton } - diff --git a/man/detect_large_greenness_change_periods.Rd b/man/detect_large_greenness_change_periods.Rd index af40f93..89a3778 100644 --- a/man/detect_large_greenness_change_periods.Rd +++ b/man/detect_large_greenness_change_periods.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/EVI_to_phenology.R \name{detect_large_greenness_change_periods} \alias{detect_large_greenness_change_periods} \title{implememnts an approximation of the methods of Zhang et al @@ -35,9 +36,6 @@ print(head(PFa_evi)) phen_transition_dates <- detect_large_greenness_change_periods(PFa_evi) print(head(phen_transition_dates)) } -\author{ -Timothy W. Hilton -} \references{ Xiaoyang Zhang, Mark A. Friedl, Crystal B. Schaaf, Alan H. Strahler, John C.F. Hodges, Feng Gao, Bradley C. Reed, @@ -52,4 +50,6 @@ Spectroradiometer (MODIS): Evaluation of global patterns and comparison with in situ measurements, J. Geophys. Res., 111, G04017, doi:10.1029/2006JG000217. } - +\author{ +Timothy W. Hilton +} diff --git a/man/estimate_VPRM_pars.Rd b/man/estimate_VPRM_pars.Rd index 3526ad2..9160497 100644 --- a/man/estimate_VPRM_pars.Rd +++ b/man/estimate_VPRM_pars.Rd @@ -1,60 +1,75 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimateVPRMPars.R \name{estimate_VPRM_pars} \alias{estimate_VPRM_pars} \title{estimate VPRM parameter values by minimizing SSE} \usage{ -estimate_VPRM_pars(all_data, opt_groups = NULL, DE_itermax, - out_path = getwd(), par_set_str = "", run_parallel = FALSE, - lambda_prior = c(0, 1.5), alpha_prior = c(0, 1.5), beta_prior = c(-4, - 4), PAR0_prior = c(0.1, 6000)) +estimate_VPRM_pars( + all_data, + opt_groups = NULL, + DE_itermax, + out_path = getwd(), + par_set_str = "", + run_parallel = FALSE, + lambda_prior = c(0, 1.5), + alpha_prior = c(0, 1.5), + beta_prior = c(-4, 4), + PAR0_prior = c(0.1, 6000), + model_form = "Mahadevan07" +) } \arguments{ -\item{all_data}{data frame; VPRM driver data to drive the -parameter estimation. Should usually be the 'data' field of a -VPRM_driver_data object.} +\item{all_data}{data frame; VPRM driver data to drive the parameter +estimation. Should usually be the 'data' field of a VPRM_driver_data +object.} -\item{opt_groups}{list of factors -- data will be split by the -levels of opt_groups and each combination optimized separately. -Groups containing less than six observations are ignored. If -unspecified parameters are estimated for all of all_data.} +\item{opt_groups}{list of factors -- data will be split by the levels of +opt_groups and each combination optimized separately. Groups containing +less than six observations are ignored. If unspecified parameters are +estimated for all of all_data.} -\item{DE_itermax}{integer, maximum differential evolution -iterations (see DEoptim documentation). Should be something like -800 for a production run -- this will take some time for a typical -data set. Run with a small number (5 or so) for a debugging run.} +\item{DE_itermax}{integer, maximum differential evolution iterations (see +DEoptim documentation). Should be something like 800 for a production run +-- this will take some time for a typical data set. Run with a small +number (5 or so) for a debugging run.} -\item{out_path}{character string; path to directory in which to -save the estimated parameters. Default is the value of getwd()} +\item{out_path}{character string; path to directory in which to save the +estimated parameters. Default is the value of getwd()} -\item{par_set_str}{character string; phrase to denote the -parameterization being considered} +\item{par_set_str}{character string; phrase to denote the parameterization +being considered} -\item{run_parallel}{TRUE|{FALSE}; if true, use Rmpi to run -optimization jobs in parallel} +\item{run_parallel}{TRUE|{FALSE}; if true, use Rmpi to run optimization jobs +in parallel} -\item{lambda_prior}{2-element vector; upper and lower lambda -values for optimization. Default is c(0.0, 1.5).} +\item{lambda_prior}{2-element vector; upper and lower lambda values for +optimization. Default is c(0.0, 1.5).} -\item{alpha_prior}{2-element vector; upper and lower alpha -values for optimization. Default is c(0.0, 1.5).} +\item{alpha_prior}{2-element vector; upper and lower alpha values for +optimization. Default is c(0.0, 1.5).} -\item{beta_prior}{2-element vector; upper and lower beta -values for optimization. Default is c(-4.0, 4.0).} +\item{beta_prior}{2-element vector; upper and lower beta values for +optimization. Default is c(-4.0, 4.0).} -\item{PAR0_prior}{2-element vector; upper and lower PAR_0 -values for optimization. Default is c(0.1, 6000).} +\item{PAR0_prior}{2-element vector; upper and lower PAR_0 values for +optimization. Default is c(0.1, 6000).} + +\item{model_form}{string, optional; form of VPRM model to use. Options are +"Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +(2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +(2017). If set to "urban", the driver data must include variables ISA +proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +EVI).} } \value{ -0 on success. A list of DEoptim objects (see DEoptim -documentation), one for each unique combination of factors in -opt_groups, is written to an RData file in the directory specified -by out_path. The file is named in the format -ParEst_PAR_SET_STR.de.RData, where PAR_SET_STR is the value of the -par_set_str argument to estimate_VPRM_pars. The best fit -parameter values are in a named vector in the -[['optim']][['bestmem']] field of the DEoptim objects. See -DEoptim documentation for further interpretation of DEoptim -objects. +0 on success. A list of DEoptim objects (see DEoptim documentation), + one for each unique combination of factors in opt_groups, is written to an + RDS file in the directory specified by out_path. The file is named in the + format ParEst_PAR_SET_STR.de.rds, where PAR_SET_STR is the value of the + par_set_str argument to estimate_VPRM_pars. The best fit parameter values + are in a named vector in the [['optim']][['bestmem']] field of the DEoptim + objects. See DEoptim documentation for further interpretation of DEoptim + objects. } \description{ This is the main function for VPRM parameter estimation. It @@ -95,4 +110,3 @@ par_est_status <- \author{ Timothy W. Hilton } - diff --git a/man/getAbsWeightedErr.Rd b/man/getAbsWeightedErr.Rd index b95292f..47f9cc8 100644 --- a/man/getAbsWeightedErr.Rd +++ b/man/getAbsWeightedErr.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimateVPRMPars.R \name{getAbsWeightedErr} \alias{getAbsWeightedErr} \title{calculate sum of absolute errors.} @@ -22,4 +23,3 @@ issues an error if a cost function returns NA. \author{ Timothy W. Hilton } - diff --git a/man/getLSWI.Rd b/man/getLSWI.Rd index 97364e5..ac4c152 100644 --- a/man/getLSWI.Rd +++ b/man/getLSWI.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R \name{getLSWI} \alias{getLSWI} \title{calculate LSWI} @@ -45,9 +46,6 @@ pfa_df <- as.data.frame( pfa_dd ) LSWI <- getLSWI( rho_nir=pfa_df[['rho_nir']], rho_swir=pfa_df[['rho_swir']] ) } -\author{ -Timothy W. Hilton -} \references{ Xiangming Xiao, Qingyuan Zhang, Bobby Braswell, Shawn Urbanski, Stephen Boles, Steven Wofsy, Berrien Moore III, Dennis @@ -63,4 +61,6 @@ exchange: Vegetation Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, GB2005, doi:10.1029/2006GB002735, 2008. } - +\author{ +Timothy W. Hilton +} diff --git a/man/getLikelihood.Rd b/man/getLikelihood.Rd index 92bf74b..d9c6e9e 100644 --- a/man/getLikelihood.Rd +++ b/man/getLikelihood.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimateVPRMPars.R \name{getLikelihood} \alias{getLikelihood} \title{compute residual likelihood function} @@ -18,11 +19,10 @@ likelihood of residuals x \description{ computes likelihood function for residuals in x uses eq 4.54 from } -\author{ -Timothy W. Hilton -} \references{ Wilks, D.S. Statistical Methods in the Atmospheric Sciences. 2nd edition, 2006. } - +\author{ +Timothy W. Hilton +} diff --git a/man/getPscale.Rd b/man/getPscale.Rd index f2eba6b..ea6b891 100644 --- a/man/getPscale.Rd +++ b/man/getPscale.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R \name{getPscale} \alias{getPscale} \title{calculate Pscale} @@ -12,7 +13,7 @@ getPscale(LSWI, phen) ginc, gmin, gmax, gdec)} } \value{ -Pscale term in VPRM equation (eqn 12 in Mahadevan et al, 2008) +Pscale term in VPRM equation (eqn 7 in Mahadevan et al, 2008) } \description{ calculates Pscale according to eqn 7 in Mahadevan et al, 2007 @@ -45,9 +46,6 @@ pfa_dd <- VPRM_driver_data(name_long="Park Falls", pfa_df <- as.data.frame( pfa_dd ) pscale <- getPscale( pfa_df[['LSWI']], pfa_df[['phen']] ) } -\author{ -Timothy W. Hilton -} \references{ Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A @@ -63,4 +61,6 @@ Sensing of Environment, Volume 84, Issue 3, March 2003, Pages 471-475, ISSN 0034-4257, http://dx.doi.org/10.1016/S0034-4257(02)00135-9. } - +\author{ +Timothy W. Hilton +} diff --git a/man/getPscale_urban.Rd b/man/getPscale_urban.Rd new file mode 100644 index 0000000..bc940cc --- /dev/null +++ b/man/getPscale_urban.Rd @@ -0,0 +1,47 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R +\name{getPscale_urban} +\alias{getPscale_urban} +\title{calculate Pscale for urbanVPRM} +\usage{ +getPscale_urban(EVI) +} +\arguments{ +\item{EVI}{1xN numeric vector; enhanced vegetation index} +} +\value{ +Pscale term in urbanVPRM GEE equation (eqn SI eqn 4 in Hardiman et al, 2017) +} +\description{ +calculates Pscale according to SI eqn 4 in Hardiman et al, 2017 +} +\examples{ +data(Park_Falls) +pfa_dd <- VPRM_driver_data(name_long="Park Falls", + name_short = "US-PFa", + lat=45.9459, + lon=-90.2723, + PFT='MF', + tower_date=PFa_tower_obs[['date']], + NEE_obs=PFa_tower_obs[['FC']], + T=PFa_tower_obs[['TA']], + PAR=PFa_tower_obs[['PAR']], + date_nir = PFa_refl[['date']], + rho_nir=PFa_refl[['nir']], + date_swir = PFa_refl[['date']], + rho_swir = PFa_refl[['swir']], + date_EVI = PFa_evi[['date']], + EVI=PFa_evi[['evi']], + phen=NA) +pfa_df <- as.data.frame(pfa_dd) +pscale <- getPscale_urban(pfa_df[['EVI']]) +} +\references{ +Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., + Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic + fluxes in regional carbon budgets. Science of The Total Environment, 592, + 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 +} +\author{ +Timothy W. Hilton +} diff --git a/man/getSSE.Rd b/man/getSSE.Rd index eac84b2..f816e4f 100644 --- a/man/getSSE.Rd +++ b/man/getSSE.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimateVPRMPars.R \name{getSSE} \alias{getSSE} \title{calculate sum of squares} @@ -24,4 +25,3 @@ return a non-NA scalar. \author{ Timothy W. Hilton } - diff --git a/man/getTscale.Rd b/man/getTscale.Rd index 406f430..8427464 100644 --- a/man/getTscale.Rd +++ b/man/getTscale.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R \name{getTscale} \alias{getTscale} \title{calculate Tscale} @@ -15,7 +16,7 @@ getTscale(T, Tmax, Tmin, Topt) \item{Topt}{optimal temperature for photosynthesis (C)} } \value{ -Tscale term in VPRM equation (eqn 12 in Mahadevan et al, +Tscale term in VPRM equation (eqn 6 in Mahadevan et al, 2007) } \description{ @@ -25,9 +26,6 @@ calculates Tscale according to eqn 6 in Mahadevan et al, 2007 data(Park_Falls) Tscale <- getTscale( PFa_tower_obs[['TA']], Tmax=40, Tmin=0, Topt=20 ) } -\author{ -Timothy W. Hilton -} \references{ Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A @@ -36,4 +34,6 @@ exchange: Vegetation Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, GB2005, doi:10.1029/2006GB002735, 2008. } - +\author{ +Timothy W. Hilton +} diff --git a/man/getWscale.Rd b/man/getWscale.Rd index dbe2a8b..772eaa0 100644 --- a/man/getWscale.Rd +++ b/man/getWscale.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R \name{getWscale} \alias{getWscale} \title{calculate Wscale} @@ -11,7 +12,7 @@ getWscale(LSWI, LSWI_max) \item{LSWI_max}{numeric; maximum LSWI for site (that is, a single value)} } \value{ -Pscale term in VPRM equation (eqn 12 in Mahadevan et al, 2007) +Wscale term in VPRM equation (eqn 8 in Mahadevan et al, 2007) } \description{ calculates Wscale according to eqn 8 in Mahadevan et al, 2007 @@ -37,9 +38,6 @@ pfa_dd <- VPRM_driver_data(name_long="Park Falls", pfa_df <- as.data.frame( pfa_dd ) wscale <- getWscale(pfa_df[['LSWI']], max(pfa_df[['LSWI']], na.rm=TRUE )) } -\author{ -Timothy W. Hilton -} \references{ Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A @@ -48,4 +46,6 @@ exchange: Vegetation Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, GB2005, doi:10.1029/2006GB002735, 2008. } - +\author{ +Timothy W. Hilton +} diff --git a/man/get_time_bins.Rd b/man/get_time_bins.Rd index 2a07f77..80b5831 100644 --- a/man/get_time_bins.Rd +++ b/man/get_time_bins.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimateVPRMPars.R \name{get_time_bins} \alias{get_time_bins} \title{calculate temporal bin edges for VPRM parameter estimation.} @@ -24,4 +25,3 @@ calculate temporal bin edges for VPRM parameter estimation. \author{ Timothy W. Hilton } - diff --git a/man/interpMODIS.Rd b/man/interpMODIS.Rd index 93c4707..5d2d145 100644 --- a/man/interpMODIS.Rd +++ b/man/interpMODIS.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/interpMODIS.R \name{interpMODIS} \alias{interpMODIS} \title{interpolate MODIS band data to provide values at a given set of dates} @@ -30,7 +31,7 @@ interpolated_EVI <- interpMODIS(mod_date=PFa_evi[['date']], out_date=PFa_tower_obs[['date']], method='linear') plot(interpolated_EVI[['date']], interpolated_EVI[['val']], - type='l', lty='dashed', + type='l', lty='dashed', xlab='date', ylab='EVI', main='Park Falls') with(PFa_evi, points(date, evi, pch='*', cex=2.0, col='red')) legend( x='topright', @@ -43,4 +44,3 @@ legend( x='topright', \author{ Timothy W. Hilton } - diff --git a/man/interp_phenology.Rd b/man/interp_phenology.Rd index abc64c4..bfd387c 100644 --- a/man/interp_phenology.Rd +++ b/man/interp_phenology.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/interp_phenology.R \name{interp_phenology} \alias{interp_phenology} \title{fill MODIS phenology status to arbitrary dates.} @@ -27,10 +28,9 @@ them back, preserving their factor status for readability. } \examples{ data(Park_Falls) -interpolated_phen <- interp_phenology(phen=PFa_phen, +interpolated_phen <- interp_phenology(phen=PFa_phen, dates=PFa_tower_obs[['date']]) } \author{ Timothy W. Hilton } - diff --git a/man/optimizeVPRM_DE.Rd b/man/optimizeVPRM_DE.Rd index 2a3567d..27fcdf3 100644 --- a/man/optimizeVPRM_DE.Rd +++ b/man/optimizeVPRM_DE.Rd @@ -1,39 +1,54 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimateVPRMPars.R \name{optimizeVPRM_DE} \alias{optimizeVPRM_DE} \title{run DEoptim to estimate VPRM parameter values} \usage{ -optimizeVPRM_DE(driver_data, DEcontrol, refresh = 5, msg = "", - lambda_prior = c(0, 1.5), alpha_prior = c(0, 1.5), beta_prior = c(-4, - 4), PAR0_prior = c(0.1, 6000)) +optimizeVPRM_DE( + driver_data, + DEcontrol, + refresh = 5, + msg = "", + lambda_prior = c(0, 1.5), + alpha_prior = c(0, 1.5), + beta_prior = c(-4, 4), + PAR0_prior = c(0.1, 6000), + model_form = "Mahadevan07" +) } \arguments{ -\item{driver_data}{May be a VPRM_driver_data object or a data -frame. If a data frame, driver_data must contain the variables -Tscale, Pscale, Wscale, EVI, and PAR, and NEE_obs.} +\item{driver_data}{May be a VPRM_driver_data object or a data frame. If a +data frame, driver_data must contain the variables Tscale, Pscale, Wscale, +EVI, and PAR, and NEE_obs.} \item{DEcontrol}{DEoptim.control object} \item{refresh}{how many DE iterations in between progress writeouts} -\item{msg}{character string; message to be displayed before DE is -called. Useful for log files.} +\item{msg}{character string; message to be displayed before DE is called. +Useful for log files.} -\item{lambda_prior}{2-element vector; upper and lower lambda -values for optimization. Default is c(0.0, 1.5).} +\item{lambda_prior}{2-element vector; upper and lower lambda values for +optimization. Default is c(0.0, 1.5).} -\item{alpha_prior}{2-element vector; upper and lower alpha -values for optimization. Default is c(0.0, 1.5).} +\item{alpha_prior}{2-element vector; upper and lower alpha values for +optimization. Default is c(0.0, 1.5).} -\item{beta_prior}{2-element vector; upper and lower beta -values for optimization. Default is c(-4.0, 4.0).} +\item{beta_prior}{2-element vector; upper and lower beta values for +optimization. Default is c(-4.0, 4.0).} -\item{PAR0_prior}{2-element vector; upper and lower PAR_0 -values for optimization. Default is c(0.1, 6000).} +\item{PAR0_prior}{2-element vector; upper and lower PAR_0 values for +optimization. Default is c(0.1, 6000).} + +\item{model_form}{string, optional; form of VPRM model to use. Options are +"Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +(2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +(2017). If set to "urban", the driver data must include variables ISA +proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +EVI).} } \value{ -DEoptim object. DEoptim output for best VPRM parameter -estimate. +DEoptim object. DEoptim output for best VPRM parameter estimate. } \description{ define VPRM parameter windows (upper and lower) and call DEoptim @@ -43,7 +58,18 @@ estimate_VPRM_pars. \examples{ data(Park_Falls) } +\references{ +Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, + J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based + biosphere parameterization for net ecosystem CO2 exchange: Vegetation + Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, + GB2005, doi:10.1029/2006GB002735, 2008. + +Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., + Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic + fluxes in regional carbon budgets. Science of The Total Environment, 592, + 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 +} \author{ Timothy W. Hilton } - diff --git a/man/pft_all_VPRM_parameters.Rd b/man/pft_all_VPRM_parameters.Rd index 62f71bc..0622eca 100644 --- a/man/pft_all_VPRM_parameters.Rd +++ b/man/pft_all_VPRM_parameters.Rd @@ -1,9 +1,11 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/VPRM_parameters.R \docType{data} \name{pft_all_VPRM_parameters} \alias{pft_all_VPRM_parameters} \title{VPRM parameter set} -\format{data frame containing values for the VPRM parameters lambda, PAR_0, alpha, and beta by plant functional type. The PFT variable is a factor with levels: +\format{ +data frame containing values for the VPRM parameters lambda, PAR_0, alpha, and beta by plant functional type. The PFT variable is a factor with levels: \describe{ \item{W}{Water} \item{ENF}{Evergreen Needleleaf forest} @@ -22,7 +24,8 @@ \item{CNM}{Cropland/Natural vegetation mosaic} \item{SNO}{Snow and ice} \item{BAR}{Barren or sparsely vegetated} -}} +} +} \source{ The parameter values were determined by optimizing to a set of 65 North American eddy covariance sites as described in @@ -42,9 +45,6 @@ pft_all_VPRM_parameters is part of the data(VPRM_parameters) print(pft_all_VPRM_parameters) } -\author{ -Timothy W. Hilton -} \references{ Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: Improving North American terrestrial CO2 flux diagnosis @@ -58,4 +58,6 @@ Sens., 18, 3289-3295, DOI:10.1080/014311697217099, 1997. \seealso{ \code{\link{VPRM_parameters}} } - +\author{ +Timothy W. Hilton +} diff --git a/man/urbanvprm_calc_R.Rd b/man/urbanvprm_calc_R.Rd new file mode 100644 index 0000000..d842082 --- /dev/null +++ b/man/urbanvprm_calc_R.Rd @@ -0,0 +1,60 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R +\name{urbanvprm_calc_R} +\alias{urbanvprm_calc_R} +\title{calculate urbanVPRM ecosystem respiration} +\usage{ +urbanvprm_calc_R(Rinit, driver_data, alpha_param, beta_param) +} +\arguments{ +\item{Rinit}{numeric; the Rinit term, equal to the respiration for the +Mahadevan et al (2007) formulation.} + +\item{driver_data}{May be a VPRM_driver_data object or a data frame. If a +data frame, driver_data must contain the variables Tscale, Pscale, Wscale, +EVI, PAR, and Tresp. The variables alpha and beta are optional (see +'details').} + +\item{alpha_param}{numeric, optional; VPRM parameter (slope of respiration +with respect to temperature)} + +\item{beta_param}{numeric, optional; VPRM parameter (basal respiration rate)} + +\item{model_form}{string, optional; form of VPRM model to use. Options are +"Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +(2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +(2017). If set to "urban", the driver data must include variables ISA +proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +EVI).} +} +\value{ +vector of same length as number of rows in driver_data containin + urbanVPRM ecosystem respiration [umol m-2 s-1] +} +\description{ +calculates urbanVPRM ecosystem respiration (R) according to Hardiman et al. +(2017) SI eqn 7 and SI eqn 8 as described in SI section S2.4. +} +\details{ +.. content for \details{} .. +} +\references{ +Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: + Improving North American terrestrial CO2 flux diagnosis using spatial + structure in land surface model residuals, Biogeosciences, 10, 4607-4625, + doi:10.5194/bg-10-4607-2013, 2013. + +Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, + J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based + biosphere parameterization for net ecosystem CO2 exchange: Vegetation + Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, + GB2005, doi:10.1029/2006GB002735, 2008. + +Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., + Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic + fluxes in regional carbon budgets. Science of The Total Environment, 592, + 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 +} +\author{ +Timothy W. Hilton +} diff --git a/man/vprm_calc_GEE.Rd b/man/vprm_calc_GEE.Rd index 4a96fa0..c525d2f 100644 --- a/man/vprm_calc_GEE.Rd +++ b/man/vprm_calc_GEE.Rd @@ -1,4 +1,5 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R \name{vprm_calc_GEE} \alias{vprm_calc_GEE} \title{calculate VPRM GEE} @@ -56,9 +57,6 @@ data(VPRM_parameters) attach(all_all_VPRM_parameters) GEE <- vprm_calc_GEE(pfa_dd, lambda=lambda, PAR_0=PAR_0) } -\author{ -Timothy W. Hilton -} \references{ Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A @@ -67,4 +65,6 @@ exchange: Vegetation Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, GB2005, doi:10.1029/2006GB002735, 2008. } - +\author{ +Timothy W. Hilton +} diff --git a/man/vprm_calc_NEE.Rd b/man/vprm_calc_NEE.Rd index e5b52a5..0bd357a 100644 --- a/man/vprm_calc_NEE.Rd +++ b/man/vprm_calc_NEE.Rd @@ -1,30 +1,45 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R \name{vprm_calc_NEE} \alias{vprm_calc_NEE} \title{calculate VPRM NEE} \usage{ -vprm_calc_NEE(driver_data, lambda_param = NULL, alpha_param = NULL, - beta_param = NULL, PAR_0_param = NULL) +vprm_calc_NEE( + driver_data, + lambda_param = NULL, + alpha_param = NULL, + beta_param = NULL, + PAR_0_param = NULL, + model_form = "Mahadevan07" +) } \arguments{ -\item{driver_data}{May be a VPRM_driver_data object or a data -frame. If a data frame, driver_data must contain the variables -Tscale, Pscale, Wscale, EVI, PAR, and Tresp. The variables -lambda, alpha, beta, and PAR_0 are optional (see 'details').} +\item{driver_data}{May be a VPRM_driver_data object or a data frame. If a +data frame, driver_data must contain the variables Tscale, Pscale, Wscale, +EVI, PAR, and Tresp. The variables lambda, alpha, beta, and PAR_0 are +optional (see 'details').} \item{lambda_param}{numeric, optional; VPRM parameter: maximum light use efficiency.} -\item{alpha_param}{numeric, optional; VPRM parameter (slope of respiration with -respect to temperature)} +\item{alpha_param}{numeric, optional; VPRM parameter (slope of respiration +with respect to temperature)} \item{beta_param}{numeric, optional; VPRM parameter (basal respiration rate)} -\item{PAR_0_param}{numeric, optional; VPRM parameter (LUE half-saturation value)} +\item{PAR_0_param}{numeric, optional; VPRM parameter (LUE half-saturation +value)} + +\item{model_form}{string, optional; form of VPRM model to use. Options are +"Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +(2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +(2017). If set to "urban", the driver data must include variables ISA +proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +EVI).} } \value{ vector of same length as number of rows in driver_data containin -VPRM NEE [umol m-2 s-1] + VPRM NEE [umol m-2 s-1] } \description{ calculates VPRM net ecosystem exchange (NEE) according to eqn 12 @@ -41,10 +56,10 @@ alpha, beta, and PAR_0 may be single values or numeric vectors the same length as the number of observations in driver_data. The Tresp variable in driver_data is the temperature used to calculate -respiration. Tresp should be max(Tair, Tlow), where Tair is the -air temperature (deg C) and Tlow is the minimum air temperature -(deg C) for respiration. This is explained more fully in -Mahadevan et al (2008) section 2.2. +respiration. Tresp should be max(Tair, Tlow), where Tair is the air +temperature (deg C) and Tlow is the minimum air temperature (deg C) for +respiration. This is explained more fully in Mahadevan et al (2008) section +2.2. } \examples{ data(Park_Falls) @@ -69,20 +84,23 @@ attach(all_all_VPRM_parameters) NEE <- vprm_calc_NEE(pfa_dd, lambda=lambda, PAR_0=PAR_0, alpha=alpha, beta=beta) } -\author{ -Timothy W. Hilton -} \references{ -Hilton, T. W., Davis, K. J., Keller, K., and Urban, -N. M.: Improving North American terrestrial CO2 flux diagnosis -using spatial structure in land surface model residuals, -Biogeosciences, 10, 4607-4625, doi:10.5194/bg-10-4607-2013, 2013. +Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: + Improving North American terrestrial CO2 flux diagnosis using spatial + structure in land surface model residuals, Biogeosciences, 10, 4607-4625, + doi:10.5194/bg-10-4607-2013, 2013. -Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, -A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A -satellite-based biosphere parameterization for net ecosystem CO2 -exchange: Vegetation Photosynthesis and Respiration Model -(VPRM), Global Biogeochem. Cy., 22, GB2005, -doi:10.1029/2006GB002735, 2008. -} +Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, + J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based + biosphere parameterization for net ecosystem CO2 exchange: Vegetation + Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, + GB2005, doi:10.1029/2006GB002735, 2008. +Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., + Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic + fluxes in regional carbon budgets. Science of The Total Environment, 592, + 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 +} +\author{ +Timothy W. Hilton +} diff --git a/man/vprm_calc_R.Rd b/man/vprm_calc_R.Rd index 3047c32..473f52b 100644 --- a/man/vprm_calc_R.Rd +++ b/man/vprm_calc_R.Rd @@ -1,29 +1,42 @@ -% Generated by roxygen2 (4.0.2): do not edit by hand +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/vprm.R \name{vprm_calc_R} \alias{vprm_calc_R} \title{calculate VPRM ecosystem respiration} \usage{ -vprm_calc_R(driver_data, alpha_param = NULL, beta_param = NULL) +vprm_calc_R( + driver_data, + alpha_param = NULL, + beta_param = NULL, + model_form = "Mahadevan07" +) } \arguments{ -\item{driver_data}{May be a VPRM_driver_data object or a data -frame. If a data frame, driver_data must contain the variables -Tscale, Pscale, Wscale, EVI, PAR, and Tresp. The variables alpha -and beta are optional (see 'details').} +\item{driver_data}{May be a VPRM_driver_data object or a data frame. If a +data frame, driver_data must contain the variables Tscale, Pscale, Wscale, +EVI, PAR, and Tresp. The variables alpha and beta are optional (see +'details').} -\item{alpha_param}{numeric, optional; VPRM parameter (slope of -respiration with respect to temperature)} +\item{alpha_param}{numeric, optional; VPRM parameter (slope of respiration +with respect to temperature)} -\item{beta_param}{numeric, optional; VPRM parameter (basal -respiration rate)} +\item{beta_param}{numeric, optional; VPRM parameter (basal respiration rate)} + +\item{model_form}{string, optional; form of VPRM model to use. Options are +"Mahadevan07" (default) to use the VPRM formulation of Mahadevan et al. +(2007), or "urban" to use the urbanVPRM formulation of Hardiman et al. +(2017). If set to "urban", the driver data must include variables ISA +proportion (impervious surface area, 0.0 to 1.0) and refEVI (reference +EVI).} } \value{ vector of same length as number of rows in driver_data containin -VPRM ecosystem respiration [umol m-2 s-1] + VPRM ecosystem respiration [umol m-2 s-1] } \description{ -calculates VPRM ecosystem respiration (R) according to eqn 10 -in Mahadevan et al, 2007 +calculates VPRM ecosystem respiration (R) according to either the VPRM +formulation of Mahadevan et al. (2007) eqn 10 or the urbanVPRM +formulation of Hardiman et al (2017) SI eqn 7 and SI eqn 8. } \details{ Arguments alpha and beta may be omitted from the function call. @@ -36,10 +49,16 @@ alpha and beta may be single values or numeric vectors the same length as the number of observations in driver_data. The Tresp variable in driver_data is the temperature used to calculate -respiration. Tresp should be max(Tair, Tlow), where Tair is the -air temperature (deg C) and Tlow is the minimum air temperature -(deg C) for respiration. This is explained more fully in -Mahadevan et al (2008) section 2.2. +respiration. Tresp should be max(Tair, Tlow), where Tair is the air +temperature (deg C) and Tlow is the minimum air temperature (deg C) for +respiration. This is explained more fully in Mahadevan et al (2008) section +2.2. + +The urbanVPRM subdivides respiration into heterotrophic and autotrophic and +introduces a scaling factor based on a nearby pixel of similar land cover +with minimal impervious surface area. This scaling factor is derived from a +"reference EVI" term, described in more detail in the supplemental material +of Hardiman et al. (2017). } \examples{ data(Park_Falls) @@ -64,20 +83,23 @@ data(VPRM_parameters) attach(all_all_VPRM_parameters) ER <- vprm_calc_R(pfa_dd, alpha=alpha, beta=beta) } -\author{ -Timothy W. Hilton -} \references{ -Hilton, T. W., Davis, K. J., Keller, K., and Urban, -N. M.: Improving North American terrestrial CO2 flux diagnosis -using spatial structure in land surface model residuals, -Biogeosciences, 10, 4607-4625, doi:10.5194/bg-10-4607-2013, 2013. +Hilton, T. W., Davis, K. J., Keller, K., and Urban, N. M.: + Improving North American terrestrial CO2 flux diagnosis using spatial + structure in land surface model residuals, Biogeosciences, 10, 4607-4625, + doi:10.5194/bg-10-4607-2013, 2013. -Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, -A., Lin, J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A -satellite-based biosphere parameterization for net ecosystem CO2 -exchange: Vegetation Photosynthesis and Respiration Model -(VPRM), Global Biogeochem. Cy., 22, GB2005, -doi:10.1029/2006GB002735, 2008. -} +Mahadevan, P., Wofsy, S., Matross, D., Xiao, X., Dunn, A., Lin, + J., Gerbig, C., Munger, J., Chow, V., and Gottlieb, E.: A satellite-based + biosphere parameterization for net ecosystem CO2 exchange: Vegetation + Photosynthesis and Respiration Model (VPRM), Global Biogeochem. Cy., 22, + GB2005, doi:10.1029/2006GB002735, 2008. +Hardiman, B. S., Wang, J. A., Hutyra, L. R., Gately, C. K., + Getson, J. M., & Friedl, M. A. (2017). Accounting for urban biogenic + fluxes in regional carbon budgets. Science of The Total Environment, 592, + 366–372. https://doi.org/10.1016/j.scitotenv.2017.03.028 +} +\author{ +Timothy W. Hilton +} diff --git a/tests/testthat/test-GEE-1D-data.R b/tests/testthat/test-GEE-1D-data.R index 8378e3d..eb4e9d0 100644 --- a/tests/testthat/test-GEE-1D-data.R +++ b/tests/testthat/test-GEE-1D-data.R @@ -21,7 +21,7 @@ test_that('vprm_calc_GEE works for site-level driver data', { ## need some parameters -- the choice is arbitrary, really load(file.path(system.file("data", package="VPRMLandSfcModel"), - 'VPRM_parameters.Rdata')) + 'VPRM_parameters.RData')) ## attach(all_all_VPRM_parameters) ## NEE <- vprm_calc_NEE(pfa_dd, ## lambda_param=lambda,