From 9e2d7b53b9c6a2472dc4fb964d49723c01710df3 Mon Sep 17 00:00:00 2001 From: Samuel Buis Date: Fri, 9 Oct 2020 14:41:01 +0200 Subject: [PATCH] Update function documentation --- DESCRIPTION | 2 +- man/estim_param.Rd | 31 ++++++++++++++++++++++--------- man/get_params_bounds.Rd | 3 ++- man/get_params_init_values.Rd | 3 ++- man/get_params_names.Rd | 3 ++- man/is.sim.Rd | 17 +++-------------- man/optim_switch.Rd | 3 ++- man/wrap_BayesianTools.Rd | 3 ++- man/wrap_nloptr.Rd | 3 ++- man/wrap_optim.Rd | 3 ++- 10 files changed, 40 insertions(+), 31 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index c2501a1..1f16df4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -12,7 +12,7 @@ Authors@R: c(person("Samuel", "Buis",, "samuel.buis@inra.fr", c("aut", "cre")), Description: CroptimizR allow users to perform parameter estimation, uncertainty and sensitivity analysis for the Stics model. Learn more ar https://SticsRPacks.github.io/CroptimizR/. URL: https://github.com/SticsRPacks/CroptimizR BugReports: https://github.com/SticsRPacks/CroptimizR/issues -License: CeCILL-C +License: file LICENSE Encoding: UTF-8 LazyData: true ByteCompile: true diff --git a/man/estim_param.Rd b/man/estim_param.Rd index 388b681..b529b9d 100644 --- a/man/estim_param.Rd +++ b/man/estim_param.Rd @@ -7,7 +7,7 @@ estim_param(obs_list, crit_function = crit_log_cwss, model_function, model_options = NULL, optim_method = "nloptr.simplex", optim_options, param_info, transform_obs = NULL, transform_sim = NULL, - satisfy_par_const = NULL) + satisfy_par_const = NULL, var_names = NULL) } \arguments{ \item{obs_list}{List of observed values to use for parameter estimation @@ -18,7 +18,7 @@ the variable is not observed at the given date.} \item{crit_function}{Function implementing the criterion to optimize (optional, see default value in the function signature). See -\href{https://sticsrpacks.github.io/CroptimizR/reference/ls_criterion.html}{here} +\href{https://sticsrpacks.github.io/CroptimizR/reference/ls_criteria.html}{here} for more details about the list of proposed criterion.} \item{model_function}{Crop Model wrapper function to use.} @@ -53,13 +53,23 @@ a named list containing for each parameter the list of situations per group (\code{sit_list}), the vector of upper and lower bounds (one value per group) (\code{ub} and \code{lb}) and the list of initial values per group \code{init_values} (data.frame, one column per group, optional). -(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} for an example)} +(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} +for an example)} -\item{transform_obs}{User function for transforming observations before each criterion evaluation (optional), see details section for more information} +\item{transform_obs}{User function for transforming observations before each criterion +evaluation (optional), see details section for more information} -\item{transform_sim}{User function for transforming simulations before each criterion evaluation (optional), see details section for more information} +\item{transform_sim}{User function for transforming simulations before each criterion +evaluation (optional), see details section for more information} -\item{satisfy_par_const}{User function for including constraints on estimated parameters (optional), see details section for more information} +\item{satisfy_par_const}{User function for including constraints on estimated +parameters (optional), see details section for more information} + +\item{var_names}{(optional) List of variables for which the wrapper must return results. +By default the wrapper is asked to simulate only the observed variables. However, +it may be useful to simulate also other variables, typically when transform_sim +and/or transform_obs functions are used. Note however that it is active only if +the model_function used handles this argument.} } \value{ prints, graphs and a list containing the results of the parameter estimation, @@ -73,7 +83,8 @@ main function for parameter estimation The optional argument \code{transform_obs} must be a function with 4 arguments: o model_results: the list of simulated results returned by the mode_wrapper used o obs_list: the list of observations as given to estim_param function -o param_values: a named vector containing the current parameters values proposed by the estimation algorithm +o param_values: a named vector containing the current parameters values proposed +by the estimation algorithm o model_options: the list of model options as given to estim_param function It must return a list of observations (same format as \code{obs_list} argument) that will be used to compute the criterion to optimize. @@ -81,13 +92,15 @@ will be used to compute the criterion to optimize. The optional argument \code{transform_sim} must be a function with 4 arguments: o model_results: the list of simulated results returned by the mode_wrapper used o obs_list: the list of observations as given to estim_param function -o param_values: a named vector containing the current parameters values proposed by the estimation algorithm +o param_values: a named vector containing the current parameters values proposed +by the estimation algorithm o model_options: the list of model options as given to estim_param function It must return a list of simulated results (same format as this returned by the model wrapper used) that will be used to compute the criterion to optimize. The optional argument \code{satisfy_par_const} must be a function with 2 arguments: -o param_values: a named vector containing the current parameters values proposed by the estimation algorithm +o param_values: a named vector containing the current parameters values proposed +by the estimation algorithm o model_options: the list of model options as given to estim_param function It must return a logical indicating if the parameters values satisfies the constraints (freely defined by the user in the function body) or not. diff --git a/man/get_params_bounds.Rd b/man/get_params_bounds.Rd index 2af6618..d7a365b 100644 --- a/man/get_params_bounds.Rd +++ b/man/get_params_bounds.Rd @@ -24,7 +24,8 @@ a named list containing for each parameter the list of situations per group (\code{sit_list}), the vector of upper and lower bounds (one value per group) (\code{ub} and \code{lb}) and the list of initial values per group \code{init_values} (data.frame, one column per group, optional). -(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} for an example)} +(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} +for an example)} } \value{ A list containing the vectors of lower and upper bounds (\code{ub} and \code{lb}) diff --git a/man/get_params_init_values.Rd b/man/get_params_init_values.Rd index 3950f12..c685387 100644 --- a/man/get_params_init_values.Rd +++ b/man/get_params_init_values.Rd @@ -24,7 +24,8 @@ a named list containing for each parameter the list of situations per group (\code{sit_list}), the vector of upper and lower bounds (one value per group) (\code{ub} and \code{lb}) and the list of initial values per group \code{init_values} (data.frame, one column per group, optional). -(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} for an example)} +(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} +for an example)} } \value{ A dataframe containing initial values for the different parameters to diff --git a/man/get_params_names.Rd b/man/get_params_names.Rd index f26753c..f76d6cd 100644 --- a/man/get_params_names.Rd +++ b/man/get_params_names.Rd @@ -24,7 +24,8 @@ a named list containing for each parameter the list of situations per group (\code{sit_list}), the vector of upper and lower bounds (one value per group) (\code{ub} and \code{lb}) and the list of initial values per group \code{init_values} (data.frame, one column per group, optional). -(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} for an example)} +(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} +for an example)} \item{short_list}{TRUE to return a list without replicated parameters which happens for simultaneous estimation of specific and varietal parameters diff --git a/man/is.sim.Rd b/man/is.sim.Rd index 45e365d..50ae860 100644 --- a/man/is.sim.Rd +++ b/man/is.sim.Rd @@ -17,31 +17,20 @@ Check format of simulated data list } \examples{ -sim_list <- vector("list",2) -sim_list[[1]] <- list(sit1=data.frame(Date=as.POSIXct(c("2009-11-30","2009-12-10")), - var1=c(1.1,1.5),var2=c(NA,2.1)), - sit2=data.frame(Date=as.POSIXct(c("2009-11-30","2009-12-5")), - var1=c(1.3,2))) -sim_list[[2]] <- list(sit1=data.frame(Date=as.POSIXct(c("2009-11-30","2009-12-10")), +sim_list <- list(sit1=data.frame(Date=as.POSIXct(c("2009-11-30","2009-12-10")), var1=c(1.1,1.5),var2=c(NA,2.1)), sit2=data.frame(Date=as.POSIXct(c("2009-11-30","2009-12-5")), var1=c(1.3,2))) CroptimizR:::is.sim(sim_list) # Missing Date column -sim_list <- vector("list",2) -sim_list[[1]] <- list(sit1=data.frame(Date=as.POSIXct(c("2009-11-30","2009-12-10")), - var1=c(1.1,1.5),var2=c(NA,2.1)), - sit2=data.frame(Date=as.POSIXct(c("2009-11-30","2009-12-5")), - var1=c(1.3,2))) -sim_list[[2]] <- list(sit1=data.frame(var1=c(1.1,1.5),var2=c(NA,2.1)), +sim_list <- list(sit1=data.frame(var1=c(1.1,1.5),var2=c(NA,2.1)), sit2=data.frame(Date=as.POSIXct(c("2009-11-30","2009-12-5")), var1=c(1.3,2))) CroptimizR:::is.sim(sim_list) # Bad Date format -sim_list <- vector("list",1) -sim_list[[1]] <- list(sit1=data.frame(Date=c("2009-11-30","2009-12-10"), +sim_list <- list(sit1=data.frame(Date=c("2009-11-30","2009-12-10"), var1=c(1.1,1.5),var2=c(NA,2.1)), sit2=data.frame(Date=c("2009-11-30","2009-12-5"),var1=c(1.3,2))) CroptimizR:::is.sim(sim_list) diff --git a/man/optim_switch.Rd b/man/optim_switch.Rd index 0ff89b6..a3d6a3e 100644 --- a/man/optim_switch.Rd +++ b/man/optim_switch.Rd @@ -38,7 +38,8 @@ a named list containing for each parameter the list of situations per group (\code{sit_list}), the vector of upper and lower bounds (one value per group) (\code{ub} and \code{lb}) and the list of initial values per group \code{init_values} (data.frame, one column per group, optional). -(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} for an example)} +(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} +for an example)} \item{crit_options}{List containing several arguments given to \code{estim_param} function: \code{param_names}, \code{obs_list}, \code{crit_function}, \code{model_function}, \code{model_options}, diff --git a/man/wrap_BayesianTools.Rd b/man/wrap_BayesianTools.Rd index d8cbe74..e11d339 100644 --- a/man/wrap_BayesianTools.Rd +++ b/man/wrap_BayesianTools.Rd @@ -32,7 +32,8 @@ a named list containing for each parameter the list of situations per group (\code{sit_list}), the vector of upper and lower bounds (one value per group) (\code{ub} and \code{lb}) and the list of initial values per group \code{init_values} (data.frame, one column per group, optional). -(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} for an example)} +(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} +for an example)} \item{crit_options}{List containing several arguments given to \code{estim_param} function: \code{param_names}, \code{obs_list}, \code{crit_function}, \code{model_function}, \code{model_options}, diff --git a/man/wrap_nloptr.Rd b/man/wrap_nloptr.Rd index ef6d9f9..7d5f8da 100644 --- a/man/wrap_nloptr.Rd +++ b/man/wrap_nloptr.Rd @@ -32,7 +32,8 @@ a named list containing for each parameter the list of situations per group (\code{sit_list}), the vector of upper and lower bounds (one value per group) (\code{ub} and \code{lb}) and the list of initial values per group \code{init_values} (data.frame, one column per group, optional). -(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} for an example)} +(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} +for an example)} \item{crit_options}{List containing several arguments given to \code{estim_param} function: \code{param_names}, \code{obs_list}, \code{crit_function}, \code{model_function}, \code{model_options}, diff --git a/man/wrap_optim.Rd b/man/wrap_optim.Rd index 5716af6..ad09b04 100644 --- a/man/wrap_optim.Rd +++ b/man/wrap_optim.Rd @@ -32,7 +32,8 @@ a named list containing for each parameter the list of situations per group (\code{sit_list}), the vector of upper and lower bounds (one value per group) (\code{ub} and \code{lb}) and the list of initial values per group \code{init_values} (data.frame, one column per group, optional). -(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} for an example)} +(see \href{https://sticsrpacks.github.io/CroptimizR/articles/Parameter_estimation_Specific_and_Varietal.html}{here} +for an example)} \item{crit_options}{List containing several arguments given to \code{estim_param} function: \code{param_names}, \code{obs_list}, \code{crit_function}, \code{model_function}, \code{model_options},