Prep for V1 (#15)

* save the original materials from JZ * save a functional copy of JZ's legacy work * save work in progress * Update the naming * passing checks * passing jz old new comparison, add check to make sure the state vector is set up correctly. * passing checks and tests * saving progress * Update the configuration tables. * update the model configurations * Expand on R package documenation related to model configurations. * update the read me * Correct the author section. * Update to reflect the new Read Me work flow * update the model configurations * Add model configs, documenation, and color guide. * Add colorMEMCPalette function example * Update exmples for the manucript text * update to pass tests and checks
Microbial-Explicit-Model · Aug 15, 2023 · 00bb9ed · 00bb9ed
1 parent 82d0f94
commit 00bb9ed
Show file tree

Hide file tree

Showing 106 changed files with 3,013,843 additions and 7,220 deletions.
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -1,7 +1,9 @@
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^data-raw$
+^misc$
 ^analysis$
+^legacy$
 ^_pkgdown\.yml$
 ^pkgdown$
 ^\.github/workflows/pkgdown\.yaml$
@@ -16,3 +18,4 @@
 
 # Specific files
 CODE_OF_CONDUCT.md
+^README\.Rmd$
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -2,7 +2,8 @@ Package: MEMC
 Type: Package
 Title: Microbial Explicit Model Comparison: a R package supporting model exploration
 Version: 0.1.0.999999
-Author: c(person("Kalyn", "Dorheim", email = "kalyn.dorheim@pnnl.gov", role = c("aut", "cre", "main"), comment = ORCID = "0000-0001-8093-8397"), person("Jianqiu", "Zheng", role = c("aut", "cre", "main"), comment = ORCID = "0000-0002-1609-9004"))
+Authors@R: c(person("Kalyn", "Dorheim", ,email = "kalyn.dorheim@pnnl.gov", role = "aut", comment = c(ORCID = "0000-0001-8093-8397")),
+          person("Jianqiu", "Zheng", ,email = "jianqiu.zheng@pnnl.gov", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-1609-9004")))
 Maintainer: Kalyn Dorheim <kalyn.dorheim@pnnl.gov>
 Description: This is an R package representation of different microbial explicit carbon models in a flexible framework for model comparison exercises. 
 Depends: R (>= 3.6)
@@ -15,7 +16,9 @@ Suggests:
     rmarkdown (>= 2.11),
     ggplot2 (>= 3.3.5),
     data.table (>= 1.14.2),
-    covr
+    dplyr (>= 1.1.0),
+    covr,
+    learnr
 Imports: 
     assertthat (>= 0.2.1), 
     deSolve (>= 1.30), 

diff --git a/NAMESPACE b/NAMESPACE
@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(colorMEMCPalette)
 export(configure_model)
 export(format_sensout)
 export(memc_modfit)

diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,3 @@
-# MEMC 0.1.0
+# MEMC 0.1.0.999999
 
 * Added a `NEWS.md` file to track changes to the package.
diff --git a/R/aadoc.R b/R/aadoc.R
@@ -0,0 +1,59 @@
+#### Documentation objects
+
+#' Configurations
+#'
+#' The various model configurations that are
+#' shipped with the MEMC package, such as:
+#' \code{BAMS_model}, \code{COMISSION_model},
+#' \code{CORPSE_model}, \code{MEND_model},
+#' \code{MIMCS_model}, and \code{MEMS_model}.
+#' All supported model configurations are listed
+#' in \code{model_configs}.
+#'
+#' These model configurations can be used with the \code{solve_model} function to
+#' complete the desired model simulations.
+#' @name configurations
+#' @seealso dynamics, fluxes
+#'
+#' @examples
+#' ## Using solve_model with the MEND_model configuration.
+#' out <- solve_model(mod = MEND_model, time = 0:10)
+NULL
+
+
+#' MEMC supported SOM flux dynamics
+#'
+#' These identifiers correspond to the various dynamics users can select
+#' from when setting up a model configuration using the \code{\link{configure_model}} function.
+#'
+#' @section Dynamics:
+#' \describe{The MEMC package allows users to select the dynamics used for DOMuptake, POMdecomp, and
+#' MBdecay from the following list:
+#' \item{MM}{Michaelis–Menten kinetics}
+#' \item{RMM}{Reverse Michaelis-Menten kinetics, as in (Schimel and Weintraub, 2003) and (Sulman et al. 2014)}
+#' \item{ECA}{Equilibrium Chemistry Approximation, based on RESOM (Tang and Riley, 2014)}
+#' \item{DD}{Density Dependent decomposition (only applicable for MB decay)}
+#' \item{LM}{Linear odel, as in (Robertson et al. 2019)}
+#' }
+#' @name dynamics
+#' @references \href{doi:10.1016/s0038-0717(03)00015-4}{Schimel, J. P., and M. N. Weintraub (2003), The implications of exoenzyme activity on microbial carbon and nitrogen limitation in soil: A theoretical model, Soil Biol. Biochem., 35(4), 549–563, doi:10.1016/s0038-0717(03)00015-4}
+#' @references \href{doi:10.1038/nclimate2436}{Sulman, B. N., R. P. Phillips, A. C. Oishi, E. Shevliakova, and S. W. Pacala (2014), Microbe-driven turnover offsets mineral-mediated storage of soil carbon under elevated CO2, Nat. Clim. Change, 4(12), 1099–1102, doi:10.1038/nclimate2436.}
+#' @references \href{https://doi.org/10.1038/nclimate2438}{Tang, J., Riley, W. Weaker soil carbon–climate feedbacks resulting from microbial and abiotic interactions. Nature Clim Change 5, 56–60 (2015). https://doi.org/10.1038/nclimate2438}
+#' @references \href{https://doi.org/10.5194/bg-16-1225-2019}{Robertson, A. D., Paustian, K., Ogle, S., Wallenstein, M. D., Lugato, E., and Cotrufo, M. F.: Unifying soil organic matter formation and persistence frameworks: the MEMS model, Biogeosciences, 16, 1225–1248, https://doi.org/10.5194/bg-16-1225-2019, 2019.}
+#' @seealso configurations, fluxes
+NULL
+
+
+
+#' Flexible SOM fluxes
+#'
+#' Description of the flexible SOM fluxes that users may change with \code{\link{configure_model}} function.
+#'
+#' \describe{The MEMC package supports flexible definitions for the following SOM fluxes:
+#' \item{DOMuptake}{dissovled organic uptake by microbial biomass, the flux describing the DOM that is broken down for microbial biomoass uptake.}
+#' \item{POMdecomp}{particulate oranic matter decomposition, the flux describing the POM that is broken down into DOM.}
+#' \item{MBdecay}{microbial biomass decay, the flux descirbing the micorbial biomass mortality/turn over.}
+#' }
+#' @name fluxes
+#' @seealso configurations, fluxes, dynamics
+NULL
diff --git a/R/adoc.R b/R/adoc.R
diff --git a/R/argument_tests.R b/R/argument_tests.R
@@ -78,8 +78,8 @@ is_state_vector <- function(state) {
   assert_that(is.vector(state))
   assert_that(is.numeric(state))
 
-  req_names <- c("P", "M", "Q", "B", "D", "EP", "EM", "IC", "Tot")
-  missing <- req_names[!names(state) %in% req_names]
+  req_names <- c("POM", "MOM", "QOM", "MB", "DOM", "EP", "EM", "IC", "Tot")
+  missing <- req_names[!req_names %in% names(state)]
   assert_that(length(missing) == 0,
               msg = paste0(
                 "state is missing a value(s) for: ",

diff --git a/R/data.R b/R/data.R
@@ -4,7 +4,7 @@
 #' @usage data(default_params)
 #' @keywords datasets
 #'
-#' @format A data table consisting of 4 columns with inputs from \href{doi.org/10.1890/12-0681.1}{Wang et al. 2013}.
+#' @format A data frame of 20 rows and 4 columns containing the model parameter values from \href{doi.org/10.1890/12-0681.1}{Wang et al. 2013}.
 #' \describe{
 #' \item{parameter}{String character of the default MEND parameters.}
 #' \item{description}{String character describing the parameter.}
@@ -14,77 +14,172 @@
 #' @family inputs
 #' @references \href{https://doi.org/10.1890/12-0681.1}{Wang et al. 2013}
 #' @examples
-#' default_params
+#' print(default_params)
 "default_params"
 
 
-#' The default inital carbon pool values the basic MEMC model configurations from Wang et al. 2013
+#' The default initial carbon pool values used by the default MEMC model configurations
 #'
-#' @format A vector of the intial states of the Carbon pools from MEND 2013 \href{doi.org/10.1890/12-0681.1}{Wang et al. 2013}.
+#' @format A named vector of the initial states of the carbon pools.
 #' \describe{ a named vector of the Carbon pools
-#' \item{'P'}{'Particulate organic carbon or POC'}
-#' \item{'M'}{'Mineral associated organic carbon or MOC, note that this excludes Q'}
-#' \item{'Q'}{'Adsorbed phase of DOC'}
-#' \item{'B'}{'Microbial biomass carbon or MBC'}
-#' \item{'D'}{'Dissolved organic carbon or DOC'}
-#' \item{'EP'}{'Enzyme for decomposition of P'}
-#' \item{'EM'}{'Ensyme for decomposition of M'}
-#' \item{'IC'}{'Accumulated CO2 flux'}
-#' \item{'Tot'}{'Total carbon in the patch'}
+#' \item{POM}{Particulate organic carbon or POC}
+#' \item{MOM}{Mineral associated organic carbon or MOC, note that this excludes QOM}
+#' \item{QOM}{Adsorbed phase of DOC}
+#' \item{MB}{Microbial biomass carbon or MBC}
+#' \item{DOM}{Dissolved organic carbon or DOC}
+#' \item{EP}{Enzyme for decomposition of POM}
+#' \item{EM}{Enzyme for decomposition of MOM}
+#' \item{IC}{Accumulated CO2 flux}
+#' \item{Tot}{Total carbon in the patch}
 #' }
 #' @family inputs
 #' @references \href{https://doi.org/10.1890/12-0681.1}{Wang et al. 2013}
 #' @examples
-#' default_initial
 #' print(default_initial)
 "default_initial"
 
-
-#' MEMC model configurations for MEND Wang et al. 2013
+#' The MEMC model configuration for MEND
 #'
+#' The MEND configuration is based off of Wang et al. 2013, this
+#' configuration uses MM for DOM uptake, MM for
+#' POM decomposition, and a LM for MB decay, see \link{dynamics} for more
+#' details.
 #'
 #' @format an object created form \code{configure_model}.
 #' \describe{
-#' \item{name}{MEND, the model name}
-#' \item{table}{table describing the user selected kinetics}
-#' \item{params}{the default MEMC parameter table}
-#' \item{state}{the default inital state values for MEMC}
+#' \item{name}{MEND}
+#' \item{table}{table of the dynamics used by this model configuration, see \link{dynamics} for more details.}
+#' \item{params}{data table of the model parameters, see \link{default_params} for more details.}
+#' \item{state}{vector of the initial state values, see \link{default_initial} for more details.}
 #' }
-#' @family models
+#' @family {configurations}
+#' @references \href{https://doi.org/10.1890/12-0681.1}{Wang et al. 2013}
 #' @examples
-#' MEND_model
+#' ## Use solve_model to run the simulation using this configuration.
+#' print(MEND_model)
 #' solve_model(mod = MEND_model, time = 1:10)
 "MEND_model"
 
-#' MEMC model configurations for MEND Wang et al. 2013
+#' The MEMC model configuration for COMISSION
 #'
+#' The COMISSION configuration is based off of Ahrens et al. 2015, the model uses MM for the
+#' DOM uptake, RMM for POM decomposition, and a LM for MB decay, see \link{dynamics} for more
+#' details.
 #'
-#' @format an object created form \code{configure_model}.
+#' @format an object created form \code{configure_model}, containing the following elements.
 #' \describe{
-#' \item{name}{COMISSION, the model name}
-#' \item{table}{table describing the user selected kinetics}
-#' \item{params}{the default MEMC parameter table}
-#' \item{state}{the default inital state values for MEMC}
+#' \item{name}{COMISSION}
+#' \item{table}{table of the dynamics used by this model configuration, see \link{dynamics} for more details.}
+#' \item{params}{data table of the model parameters, see \link{default_params} for more details.}
+#' \item{state}{vector of the initial state values, see \link{default_initial} for more details.}
 #' }
-#' @family models
+#' @family {configurations}
+#' @references \href{https://doi.org/10.1016/j.soilbio.2015.06.008}{Ahrens et al. 2015}
 #' @examples
-#' COMISSION_model
+#' ## Use solve_model to run the simulation using this configuration.
+#' print(COMISSION_model)
 #' solve_model(mod = COMISSION_model, time = 1:10)
 "COMISSION_model"
 
-
-#' MEMC model configurations
+#' The MEMC model configuration for CORPSE
 #'
+#' The CORPSE configuration is based off of Sulman et al. 2018, this model uses RMM for
+#' DOM uptake, LM for POM decomposition, and a LM for MB decay, see \link{dynamics} for more
+#' details.
 #'
-#' @format an object created form \code{configure_model}.
+#' @format an object created form \code{configure_model}, containing the following elements.
 #' \describe{
-#' \item{name}{CORPSE, the model name}
-#' \item{table}{table describing the user selected kinetics}
-#' \item{params}{the default MEMC parameter table}
-#' \item{state}{the default inital state values for MEMC}
+#' \item{name}{CORPSE}
+#' \item{table}{table of the dynamics used by this model configuration, see \link{dynamics} for more details.}
+#' \item{params}{data table of the model parameters, see \link{default_params} for more details.}
+#' \item{state}{vector of the initial state values, see \link{default_initial} for more details.}
 #' }
-#' @family models
+#' @family {configurations}
+#' @references \href{https://doi.org/10.1007/s10533-018-0509-z}{Sulman et al. 2018}
 #' @examples
-#' CORPSE_model
+#' ## Use solve_model to run the simulation using this configuration.
+#' print(CORPSE_model)
 #' solve_model(mod = CORPSE_model, time = 1:10)
 "CORPSE_model"
+
+#' The MEMC model configuration for MIMCS
+#'
+#' The MIMCS configuration is based off of Wieder et al. 2015, this model uses MM for the DOM
+#' uptake, MM for POM decomposition, and a DD for MB decay, see \link{dynamics} for more
+#' details.
+#'
+#' @format an object created form \code{configure_model}, containing the following elements.
+#' \describe{
+#' \item{name}{MIMCS}
+#' \item{table}{table of the dynamics used by this model configuration, see \link{dynamics} for more details.}
+#' \item{params}{data table of the model parameters, see \link{default_params} for more details.}
+#' \item{state}{vector of the initial state values, see \link{default_initial} for more details.}
+#' }
+#' @family {configurations}
+#' @references \href{https://doi.org/10.1002/2015GB005188}{Wieder et al. 2015}
+#' @examples
+#' ## Use solve_model to run the simulation using this configuration.
+#' print(MIMCS_model)
+#' solve_model(mod = MIMCS_model, time = 1:10)
+"MIMCS_model"
+
+#' The MEMC model configuration for MEMS
+#'
+#' The MEMS configuration is based off of Robertson et al. 2019, this model uses LM for the DOM
+#' uptake, LM for POM decomposition, and a LM for MB decay, see \link{dynamics} for more
+#' details.
+#'
+#' @format an object created form \code{configure_model}, containing the following elements.
+#' \describe{
+#' \item{name}{MEMS}
+#' \item{table}{table of the dynamics used by this model configuration, see \link{dynamics} for more details.}
+#' \item{params}{data table of the model parameters, see \link{default_params} for more details.}
+#' \item{state}{vector of the initial state values, see \link{default_initial} for more details.}
+#' }
+#' @family {configurations}
+#' @references \href{https://doi.org/10.5194/bg-16-1225-2019}{Robertson et al. 2019}
+#' @examples
+#' ## Use solve_model to run the simulation using this configuration.
+#' print(MEMS_model)
+#' solve_model(mod = MEMS_model, time = 1:10)
+"MEMS_model"
+
+#' The MEMC model configuration for BAMS
+#'
+#' The BAMS configuration is based off of Tang et al. 2022, this model uses MM for the DOM
+#' uptake, MM for POM decomposition, and a LM for MB decay, see \link{dynamics} for more
+#' details.
+#'
+#' @format an object created form \code{configure_model}, containing the following elements.
+#' \describe{
+#' \item{name}{BAMS}
+#' \item{table}{table of the dynamics used by this model configuration, see \link{dynamics} for more details.}
+#' \item{params}{data table of the model parameters, see \link{default_params} for more details.}
+#' \item{state}{vector of the initial state values, see \link{default_initial} for more details.}
+#' }
+#' @family {configurations}
+#' @references \href{https://doi.org/10.5194/bg-16-1225-2019}{Robertson et al. 2019}
+#' @examples
+#' ## Use solve_model to run the simulation using this configuration.
+#' print(BAMS_model)
+#' solve_model(mod = MEMS_model, time = 1:10)
+"BAMS_model"
+
+
+#' Data table of all the pre-defined MEMC model configurations
+#'
+#'
+#' @format data table containing 4 columns
+#' \describe{
+#' \item{model}{model configuration name}
+#' \item{DOMuptake}{DOM uptake by microbial biomass, see \link{dynamics} for more details.}
+#' \item{POMdecomp}{POM decomposition, see \link{dynamics} for more details.}
+#' \item{MBdecay}{microbial biomass decay, see \link{default_initial} for more details.}
+#' }
+#' @family {configurations}
+#' @examples
+#' print(model_configs)
+"model_configs"
+
+
+