From 73b3728a481e22d47c94ced862cb8860dbb3356b Mon Sep 17 00:00:00 2001 From: kellijohnson-NOAA Date: Sat, 31 Aug 2024 17:11:45 -0700 Subject: [PATCH] doc(rcpp): Uses 3rd entry to document rcpp Was PR #652 and commit e0fbfb091ff27ac365481fae79396cbdf036ad02 but that was based on main and enough has changed that the commit had be redone for dev. There are still some interfaces that are not documented but they can be completed in #662. Thanks to @Bai-Li-NOAA for this commit :) Close #635 --- .../include/interface/rcpp/rcpp_interface.hpp | 221 ++++++++++++------ .../interface/rcpp/rcpp_objects/rcpp_data.hpp | 2 +- .../rcpp/rcpp_objects/rcpp_fleet.hpp | 4 +- .../rcpp/rcpp_objects/rcpp_population.hpp | 8 +- .../rcpp/rcpp_objects/rcpp_recruitment.hpp | 6 +- .../rcpp_objects/rcpp_tmb_distribution.hpp | 12 +- .../population_dynamics/fleet/fleet.hpp | 14 +- .../population/population.hpp | 6 +- .../recruitment/functors/recruitment_base.hpp | 10 +- .../recruitment/functors/sr_beverton_holt.hpp | 9 +- vignettes/fims-demo.Rmd | 2 +- 11 files changed, 182 insertions(+), 112 deletions(-) diff --git a/inst/include/interface/rcpp/rcpp_interface.hpp b/inst/include/interface/rcpp/rcpp_interface.hpp index 4d48416eb..90f936a22 100644 --- a/inst/include/interface/rcpp/rcpp_interface.hpp +++ b/inst/include/interface/rcpp/rcpp_interface.hpp @@ -344,35 +344,53 @@ void clear() { RCPP_EXPOSED_CLASS(Parameter) RCPP_EXPOSED_CLASS(ParameterVector) RCPP_MODULE(fims) { - Rcpp::function("CreateTMBModel", &CreateTMBModel); - Rcpp::function("get_fixed", &get_fixed_parameters_vector); - Rcpp::function("get_random", &get_random_parameters_vector); - Rcpp::function("get_parameter_names", &get_parameter_names); - Rcpp::function("clear", clear); - Rcpp::function("clear_logs", clear_logs); - Rcpp::function("clear_fims_log", clear_fims_log); - Rcpp::function("clear_info_log", clear_info_log); - Rcpp::function("clear_error_log", clear_error_log); - Rcpp::function("clear_data_log", clear_data_log); - Rcpp::function("clear_population_log", clear_population_log); - Rcpp::function("clear_model_log", clear_model_log); - Rcpp::function("clear_recruitment_log", clear_recruitment_log); - Rcpp::function("clear_fleet_log", clear_fleet_log); - Rcpp::function("clear_growth_log", clear_growth_log); - Rcpp::function("clear_maturity_log", clear_maturity_log); - Rcpp::function("clear_selectivity_log", clear_selectivity_log); - Rcpp::function("clear_debug_log", clear_debug_log); + Rcpp::function("CreateTMBModel", &CreateTMBModel, + "Create the TMB model object and add interface objects to it. No inputs are required."); + Rcpp::function("get_fixed", &get_fixed_parameters_vector, + "Get fixed parameters vector. No inputs are required."); + Rcpp::function("get_random", &get_random_parameters_vector, + "Get random paramters vector. No inputs are required."); + Rcpp::function("get_parameter_names", &get_parameter_names, + "Get vector of parameter names that matches the output in report. No inputs are required."); + Rcpp::function("clear", clear, + "Clears the vector of independent variables. No inputs are required."); + Rcpp::function("clear_logs", clear_logs, + "Clears the contents of log files. No inputs are required."); + Rcpp::function("clear_fims_log", clear_fims_log, + "Clears the contents of fims log file. No inputs are required."); + Rcpp::function("clear_info_log", clear_info_log, + "Clears the contents of info log file. No inputs are required."); + Rcpp::function("clear_error_log", clear_error_log, + "Clears the contents of error log file. No inputs are required."); + Rcpp::function("clear_data_log", clear_data_log, + "Clears the contents of data log file. No inputs are required."); + Rcpp::function("clear_population_log", clear_population_log, + "Clears the contents of population log file. No inputs are required."); + Rcpp::function("clear_model_log", clear_model_log, + "Clears the contents of model log file. No inputs are required."); + Rcpp::function("clear_recruitment_log", clear_recruitment_log, + "Clears the contents of recruitment log file. No inputs are required."); + Rcpp::function("clear_fleet_log", clear_fleet_log, + "Clears the contents of fleet log file. No inputs are required."); + Rcpp::function("clear_growth_log", clear_growth_log, + "Clears the contents of growth log file. No inputs are required."); + Rcpp::function("clear_maturity_log", clear_maturity_log, + "Clears the contents of maturity log file. No inputs are required."); + Rcpp::function("clear_selectivity_log", clear_selectivity_log, + "Clears the contents of selectivity log file. No inputs are required."); + Rcpp::function("clear_debug_log", clear_debug_log, + "Clears the contents of debug log file. No inputs are required."); Rcpp::class_("Parameter", "FIMS Parameter Class") .constructor() .constructor() .constructor() - .field("value", &Parameter::value_m, "numeric parameter value") - .field("min", &Parameter::min_m, "minimum parameter value") - .field("max", &Parameter::max_m, "maximum parameter value") + .field("value", &Parameter::value_m, "Initial, numeric value of the parameter.") + .field("min", &Parameter::min_m, "Min value of the parameter. Default is -Infinity.") + .field("max", &Parameter::max_m, "Max value of the parameter. Default is Infinity.") .field("id", &Parameter::id_m, "unique id for parameter class") - .field("is_random_effect", &Parameter::is_random_effect_m, "boolean indicating whether or not parameter is a random effect; default value is FALSE") - .field("estimated", &Parameter::estimated_m, "boolean indicating whether or not parameter is estimated; default value is FALSE"); + .field("is_random_effect", &Parameter::is_random_effect_m, "A boolean indicating whether or not parameter is a random effect. Default is FALSE") + .field("estimated", &Parameter::estimated_m, "A boolean indicating whether or not parameter is estimated. Default is FALSE"); Rcpp::class_("ParameterVector") .constructor() @@ -389,49 +407,76 @@ RCPP_MODULE(fims) { Rcpp::class_("BevertonHoltRecruitment") .constructor() - .field("logit_steep", &BevertonHoltRecruitmentInterface::logit_steep) - .field("log_rzero", &BevertonHoltRecruitmentInterface::log_rzero) - .field("log_devs", &BevertonHoltRecruitmentInterface::log_devs) + .field("logit_steep", &BevertonHoltRecruitmentInterface::logit_steep, + "Recruitment relative to unfished recruitment at 20 percent of unfished spawning biomass. Steepness is subject to a logit transformation.") + .field("log_rzero", &BevertonHoltRecruitmentInterface::log_rzero, + "Natural log of unexploited recruitment. Unit: ln(number).") + .field("log_devs", &BevertonHoltRecruitmentInterface::log_devs, + "A vector of recruitment deviations in natural log space.") .field("estimate_log_devs", - &BevertonHoltRecruitmentInterface::estimate_log_devs) - .method("get_id", &BevertonHoltRecruitmentInterface::get_id) + &BevertonHoltRecruitmentInterface::estimate_log_devs, + "A flag to indicate if recruitment deviations are estimated or not. Default is true.") + .method("get_id", &BevertonHoltRecruitmentInterface::get_id, + "Get the ID of the interface object. No inputs are required.") .field("log_sigma_recruit", - &BevertonHoltRecruitmentInterface::log_sigma_recruit) - .method("evaluate", &BevertonHoltRecruitmentInterface::evaluate); + &BevertonHoltRecruitmentInterface::log_sigma_recruit, + "Natural log of standard deviation of natural log recruitment.") + .method("evaluate", &BevertonHoltRecruitmentInterface::evaluate, + "Calculates the expected recruitment for a given spawning input. Requires inputs of spawning output and number of spawners per recruit of an unfished population."); Rcpp::class_("Fleet") .constructor() - .field("is_survey", &FleetInterface::is_survey) - .field("log_q", &FleetInterface::log_q) - .field("log_Fmort", &FleetInterface::log_Fmort) - .field("nages", &FleetInterface::nages) - .field("nyears", &FleetInterface::nyears) - .field("estimate_q", &FleetInterface::estimate_q) - .field("random_q", &FleetInterface::random_q) - .field("log_expected_index", &FleetInterface::log_expected_index) - .field("proportion_catch_numbers_at_age", &FleetInterface::proportion_catch_numbers_at_age) - .method("SetSelectivity", &FleetInterface::SetSelectivity); + .field("is_survey", &FleetInterface::is_survey, + "Is this fleet object a fishing fleet or a survey? Default is false.") + .field("log_q", &FleetInterface::log_q, + "Estimated natural log of catchability for the fleet.") + .field("log_Fmort", &FleetInterface::log_Fmort, + "Estimated natural log of fishing mortality.") + .field("nages", &FleetInterface::nages, + "The number of ages in the model.") + .field("nyears", &FleetInterface::nyears, + "The number of years in the model.") + .field("estimate_q", &FleetInterface::estimate_q, + "Whether the parameter q should be estimated. Default is false.") + .field("random_q", &FleetInterface::random_q, + "Whether q should be a random effect. Default is false.") + .field("log_expected_index", &FleetInterface::log_expected_index, + "Model expected index of abundance.") + .field("proportion_catch_numbers_at_age", &FleetInterface::proportion_catch_numbers_at_age, + "Numbers at age for the catch in proportions.") + .method("SetSelectivity", &FleetInterface::SetSelectivity, + "Set the unique id for the Selectivity object."); Rcpp::class_("AgeComp") .constructor() - .field("age_comp_data", &AgeCompDataInterface::age_comp_data) - .method("get_id", &AgeCompDataInterface::get_id); + .field("age_comp_data", &AgeCompDataInterface::age_comp_data, + "The age composition data. Unit: number at age; proportion at age also works.") + .method("get_id", &AgeCompDataInterface::get_id, + "Get the ID of the interface object. No inputs are required."); Rcpp::class_("Index") .constructor() - .field("index_data", &IndexDataInterface::index_data) - .method("get_id", &IndexDataInterface::get_id); + .field("index_data", &IndexDataInterface::index_data, + "The index data. Unit: mt; it's possible to use other units as long as the survey index is assumed to be proportional to biomass.") + .method("get_id", &IndexDataInterface::get_id, + "Get the ID of the interface object. No inputs are required."); Rcpp::class_("Population") .constructor() - .method("get_id", &PopulationInterface::get_id) - .field("nages", &PopulationInterface::nages) - .field("nfleets", &PopulationInterface::nfleets) - .field("nseasons", &PopulationInterface::nseasons) - .field("nyears", &PopulationInterface::nyears) - .field("log_M", &PopulationInterface::log_M) - .field("log_init_naa", &PopulationInterface::log_init_naa) - .field("ages", &PopulationInterface::ages) + .method("get_id", &PopulationInterface::get_id, + "Get the ID of the interface object. No inputs are required.") + .field("nages", &PopulationInterface::nages, + "Number of ages.") + .field("nfleets", &PopulationInterface::nfleets, + "Number of fleets.") + .field("nseasons", &PopulationInterface::nseasons, + "Number of seasons.") + .field("nyears", &PopulationInterface::nyears, + "Number of years.") + .field("log_M", &PopulationInterface::log_M, + "Natural log of the natural mortality of the population.") + .field("log_init_naa", &PopulationInterface::log_init_naa, + "Natural log of the initial numbers at age. Unit: in number.") .field("ages", &PopulationInterface::ages) .method("evaluate", &PopulationInterface::evaluate) .method("SetMaturity", &PopulationInterface::SetMaturity) .method("SetGrowth", &PopulationInterface::SetGrowth) @@ -440,8 +485,10 @@ RCPP_MODULE(fims) { Rcpp::class_("TMBDnormDistribution") .constructor() - .method("get_id", &DnormDistributionsInterface::get_id) - .method("evaluate", &DnormDistributionsInterface::evaluate) + .method("get_id", &DnormDistributionsInterface::get_id, + "Get the id of the Dnorm distributions interface class object.") + .method("evaluate", &DnormDistributionsInterface::evaluate, + "Evaluate normal probability density function. It requires input for do_log to determine whether to return the natural log of the pdf.") .method("set_observed_data", &DnormDistributionsInterface::set_observed_data) .method("set_distribution_links", &DnormDistributionsInterface::set_distribution_links) .field("x", &DnormDistributionsInterface::x) @@ -450,41 +497,61 @@ RCPP_MODULE(fims) { Rcpp::class_("LogisticMaturity") .constructor() - .field("inflection_point", &LogisticMaturityInterface::inflection_point) - .field("slope", &LogisticMaturityInterface::slope) - .method("get_id", &LogisticMaturityInterface::get_id) - .method("evaluate", &LogisticMaturityInterface::evaluate); + .field("inflection_point", &LogisticMaturityInterface::inflection_point, + "The index value at which the response reaches 0.5.") + .field("slope", &LogisticMaturityInterface::slope, + "The width of the curve at the inflection_point.") + .method("get_id", &LogisticMaturityInterface::get_id, + "Get the ID of the interface object.") + .method("evaluate", &LogisticMaturityInterface::evaluate, + "Evaluate the logistic maturity function. The function requires input of the independent variable in the logistic function (e.g., age or size in maturity)."); Rcpp::class_("LogisticSelectivity") .constructor() .field("inflection_point", - &LogisticSelectivityInterface::inflection_point) - .field("slope", &LogisticSelectivityInterface::slope) - .method("get_id", &LogisticSelectivityInterface::get_id) - .method("evaluate", &LogisticSelectivityInterface::evaluate); + &LogisticSelectivityInterface::inflection_point, + "The index value at which the response reaches 0.5.") + .field("slope", &LogisticSelectivityInterface::slope, + "The width of the curve at the inflection_point.") + .method("get_id", &LogisticSelectivityInterface::get_id, + "Get the ID of the interface object.") + .method("evaluate", &LogisticSelectivityInterface::evaluate, + "Evaluate the logistic selectivity function. The function requires input of the independent variable in the logistic function (e.g., age or size in selectivity)."); Rcpp::class_("DoubleLogisticSelectivity") .constructor() .field("inflection_point_asc", - &DoubleLogisticSelectivityInterface::inflection_point_asc) - .field("slope_asc", &DoubleLogisticSelectivityInterface::slope_asc) + &DoubleLogisticSelectivityInterface::inflection_point_asc, + "The index value at which the response reaches 0.5 on the ascending limb of the function.") + .field("slope_asc", &DoubleLogisticSelectivityInterface::slope_asc, + "The width of the curve at the inflection point of the ascending limb of the function.") .field("inflection_point_desc", - &DoubleLogisticSelectivityInterface::inflection_point_desc) - .field("slope_desc", &DoubleLogisticSelectivityInterface::slope_desc) - .method("get_id", &DoubleLogisticSelectivityInterface::get_id) - .method("evaluate", &DoubleLogisticSelectivityInterface::evaluate); + &DoubleLogisticSelectivityInterface::inflection_point_desc, + "The index value at which the response reaches 0.5 on the descending limb of the function.") + .field("slope_desc", &DoubleLogisticSelectivityInterface::slope_desc, + "The width of the curve at the inflection point of the descending limb of the function.") + .method("get_id", &DoubleLogisticSelectivityInterface::get_id, + "Get the id for the double logistic selectivity interface.") + .method("evaluate", &DoubleLogisticSelectivityInterface::evaluate, + "Evaluate the double logistic selectivity function. The function requires input of the independent variable in the logistic function (e.g., age or size in selectivity)."); Rcpp::class_("EWAAgrowth") .constructor() - .field("ages", &EWAAGrowthInterface::ages) - .field("weights", &EWAAGrowthInterface::weights) - .method("get_id", &EWAAGrowthInterface::get_id) - .method("evaluate", &EWAAGrowthInterface::evaluate); + .field("ages", &EWAAGrowthInterface::ages, + "Ages for each age class.") + .field("weights", &EWAAGrowthInterface::weights, + "Weights for each age class. Unit: mt.") + .method("get_id", &EWAAGrowthInterface::get_id, + "Get the id of the interface object.") + .method("evaluate", &EWAAGrowthInterface::evaluate, + "Rcpp interface to the EWAAgrowth evaluate method. The function requires input of an age."); Rcpp::class_("TMBDlnormDistribution") .constructor() - .method("get_id", &DlnormDistributionsInterface::get_id) - .method("evaluate", &DlnormDistributionsInterface::evaluate) + .method("get_id", &DlnormDistributionsInterface::get_id, + "Get the id of the Dlnorm distributions interface class object.") + .method("evaluate", &DlnormDistributionsInterface::evaluate, + "Evaluate lognormal probability density function. It requires input for do_log to determine whether to return the natural log of the pdf.") .method("set_observed_data", &DlnormDistributionsInterface::set_observed_data) .method("set_distribution_links", &DlnormDistributionsInterface::set_distribution_links) .field("input_type", &DlnormDistributionsInterface::input_type) @@ -494,8 +561,10 @@ RCPP_MODULE(fims) { Rcpp::class_("TMBDmultinomDistribution") .constructor() - .method("evaluate", &DmultinomDistributionsInterface::evaluate) - .method("get_id", &DmultinomDistributionsInterface::get_id) + .method("evaluate", &DmultinomDistributionsInterface::evaluate, + "Evaluate multinom probability density function. It requires input for do_log to determine whether to return the natural log of the pdf.") + .method("get_id", &DmultinomDistributionsInterface::get_id, + "Get the id of the Dmultinom distributions interface class object.") .method("set_observed_data", &DmultinomDistributionsInterface::set_observed_data) .method("set_distribution_links", &DmultinomDistributionsInterface::set_distribution_links) .field("x", &DmultinomDistributionsInterface::x) diff --git a/inst/include/interface/rcpp/rcpp_objects/rcpp_data.hpp b/inst/include/interface/rcpp/rcpp_objects/rcpp_data.hpp index 3f25e3f7e..47c62bcbd 100644 --- a/inst/include/interface/rcpp/rcpp_objects/rcpp_data.hpp +++ b/inst/include/interface/rcpp/rcpp_objects/rcpp_data.hpp @@ -128,7 +128,7 @@ class AgeCompDataInterface : public DataInterfaceBase { class IndexDataInterface : public DataInterfaceBase { public: int ymax; /**< second dimension of the data */ - Rcpp::NumericVector index_data; /**growth_id = growth_id; } /** - * @brief Set the unique id for the Maturity object + * @brief Set the unique id for the recruitment object * - * @param recruitment_id Unique id for the Maturity object + * @param recruitment_id Unique id for the recruitment object */ void SetRecruitment(uint32_t recruitment_id) { this->recruitment_id = recruitment_id; diff --git a/inst/include/interface/rcpp/rcpp_objects/rcpp_recruitment.hpp b/inst/include/interface/rcpp/rcpp_objects/rcpp_recruitment.hpp index 733f8a74e..57976916e 100644 --- a/inst/include/interface/rcpp/rcpp_objects/rcpp_recruitment.hpp +++ b/inst/include/interface/rcpp/rcpp_objects/rcpp_recruitment.hpp @@ -64,11 +64,11 @@ std::map */ class BevertonHoltRecruitmentInterface : public RecruitmentInterfaceBase { public: - Parameter logit_steep; /**< steepness or the productivity of the stock*/ + Parameter logit_steep; /**< steepness or the productivity of the population*/ Parameter log_rzero; /**< recruitment at unfished biomass */ Parameter - log_sigma_recruit; /**< the log of the stock recruit standard deviation */ - ParameterVector log_devs; /**< log recruitment deviations*/ + log_sigma_recruit; /**< the natural log of the stock recruit standard deviation */ + ParameterVector log_devs; /**< natural log recruitment deviations*/ bool estimate_log_devs = false; /**< boolean describing whether to estimate */ BevertonHoltRecruitmentInterface() : RecruitmentInterfaceBase() {} diff --git a/inst/include/interface/rcpp/rcpp_objects/rcpp_tmb_distribution.hpp b/inst/include/interface/rcpp/rcpp_objects/rcpp_tmb_distribution.hpp index d09fdd738..ec73323e2 100644 --- a/inst/include/interface/rcpp/rcpp_objects/rcpp_tmb_distribution.hpp +++ b/inst/include/interface/rcpp/rcpp_objects/rcpp_tmb_distribution.hpp @@ -127,10 +127,10 @@ class DnormDistributionsInterface : public DistributionsInterfaceBase { /** * @brief Evaluate normal probability density function, default returns the - * log of the pdf + * natural log of the pdf * * @tparam T - * @return log pdf + * @return natural log of the pdf */ virtual double evaluate() { fims_distributions::NormalLPDF dnorm; @@ -265,10 +265,10 @@ class DlnormDistributionsInterface : public DistributionsInterfaceBase { /** * @brief Evaluate lognormal probability density function, default returns the - * log of the pdf + * natural log of the pdf * * @tparam T - * @return log pdf + * @return natural log of the pdf */ virtual double evaluate() { fims_distributions::LogNormalLPDF dlnorm; @@ -400,10 +400,10 @@ class DmultinomDistributionsInterface : public DistributionsInterfaceBase { /** * @brief Evaluate multinom probability density function, default returns the - * log of the pdf + * natural log of the pdf * * @tparam T - * @return log pdf + * @return natural log of the pdf */ virtual double evaluate() { fims_distributions::MultinomialLPMF dmultinom; diff --git a/inst/include/population_dynamics/fleet/fleet.hpp b/inst/include/population_dynamics/fleet/fleet.hpp index 9ca0db58e..7edc29f6b 100644 --- a/inst/include/population_dynamics/fleet/fleet.hpp +++ b/inst/include/population_dynamics/fleet/fleet.hpp @@ -35,11 +35,11 @@ struct Fleet : public fims_model_object::FIMSObject { // Mortality and catchability fims::Vector - log_Fmort; /*!< estimated parameter: log Fishing mortality*/ - Type log_q; /*!< estimated parameter: catchability of the fleet */ + log_Fmort; /*!< estimated parameter: natural log Fishing mortality*/ + Type log_q; /*!< estimated parameter: natural log of catchability of the fleet */ fims::Vector Fmort; /*!< transformed parameter: Fishing mortality*/ - Type q; /*!< transofrmed parameter: the catchability of the fleet */ + Type q; /*!< transformed parameter: the catchability of the fleet */ // derived quantities fims::Vector catch_at_age; /*! { fims::Vector catch_numbers_at_age; /*! proportion_catch_numbers_at_age; /*! catch_weight_at_age; /*! *of; @@ -99,8 +99,8 @@ struct Fleet : public fims_model_object::FIMSObject { } /** - * @brief Prepare to run the fleet module. Called at each model itartion, and - * used to exponentiate the log q and Fmort parameters prior to evaluation. + * @brief Prepare to run the fleet module. Called at each model iteration, and + * used to exponentiate the natural log q and Fmort parameters prior to evaluation. * */ void Prepare() { @@ -152,7 +152,7 @@ struct Fleet : public fims_model_object::FIMSObject { } /** - * Evaluate the log of the expected index. + * Evaluate the natural log of the expected index. */ void evaluate_index() { for(size_t i=0; iexpected_index.size(); i++){ diff --git a/inst/include/population_dynamics/population/population.hpp b/inst/include/population_dynamics/population/population.hpp index 67d6e1f8f..446d8d3ea 100644 --- a/inst/include/population_dynamics/population/population.hpp +++ b/inst/include/population_dynamics/population/population.hpp @@ -46,8 +46,8 @@ struct Population : public fims_model_object::FIMSObject { // parameters are estimated; after initialize in create_model, push_back to // parameter list - in information.hpp (same for initial F in fleet) fims::Vector - log_init_naa; /*!< estimated parameter: log numbers at age*/ - fims::Vector log_M; /*!< estimated parameter: log Natural Mortality*/ + log_init_naa; /*!< estimated parameter: natural log of numbers at age*/ + fims::Vector log_M; /*!< estimated parameter: natural log of natural mortality*/ // Transformed values fims::Vector M; /*!< transformed parameter: Natural Mortality*/ @@ -386,7 +386,7 @@ struct Population : public fims_model_object::FIMSObject { POPULATION_LOG << "phi0 = " << phi0 << std::endl; POPULATION_LOG << "spawning_biomass[year - 1] = " << this->spawning_biomass[year - 1] << std::endl; - POPULATION_LOG << "log recruit devs = " + POPULATION_LOG << "natural log of recruit devs = " << this->recruitment->log_recruit_devs[i_dev - 1] << std::endl; POPULATION_LOG << "rec eval = " diff --git a/inst/include/population_dynamics/recruitment/functors/recruitment_base.hpp b/inst/include/population_dynamics/recruitment/functors/recruitment_base.hpp index 9ea8a4bc7..044baf51a 100644 --- a/inst/include/population_dynamics/recruitment/functors/recruitment_base.hpp +++ b/inst/include/population_dynamics/recruitment/functors/recruitment_base.hpp @@ -33,13 +33,13 @@ struct RecruitmentBase : public fims_model_object::FIMSObject { static uint32_t id_g; /**< reference id for recruitment object*/ fims::Vector - log_recruit_devs; /*!< A vector of log recruitment deviations */ + log_recruit_devs; /*!< A vector of natural log of recruitment deviations */ bool constrain_deviations = false; /*!< A flag to indicate if recruitment - deviations are summing to zero or not */ + deviations are summing to zero or not. */ - fims::Vector log_sigma_recruit; /**< Log standard deviation of log recruitment - deviations */ - fims::Vector log_rzero; /**< Log of unexploited recruitment.*/ + fims::Vector log_sigma_recruit; /**< Natural log of the standard deviation of the natural log of recruitment + deviations. */ + fims::Vector log_rzero; /**< Natural log of unexploited recruitment.*/ bool estimate_log_recruit_devs = true; /*!< A flag to indicate if recruitment deviations are estimated or not */ diff --git a/inst/include/population_dynamics/recruitment/functors/sr_beverton_holt.hpp b/inst/include/population_dynamics/recruitment/functors/sr_beverton_holt.hpp index 6072d691e..480d8dc98 100644 --- a/inst/include/population_dynamics/recruitment/functors/sr_beverton_holt.hpp +++ b/inst/include/population_dynamics/recruitment/functors/sr_beverton_holt.hpp @@ -18,11 +18,12 @@ namespace fims_popdy { -/** @brief BevertonHolt class that returns the Beverton Holt SR - * from fims_math. +/** @brief BevertonHolt class that returns the Beverton Holt stock--recruitment + * function from fims_math. * * @param logit_steep Recruitment relative to unfished recruitment at - * 20% of unfished spawning biomass. Should be a value between 0.2 and 1.0. + * 20 percent of unfished spawning biomass. Steepness is subject to a logit + * transformation. */ template struct SRBevertonHolt : public RecruitmentBase { @@ -30,7 +31,7 @@ struct SRBevertonHolt : public RecruitmentBase { // function. These members are needed by Beverton Holt but will not be common // to all recruitment functions like spawners is below. fims::Vector logit_steep; /**< Transformed value of recruitment relative to unfished - recruitment at 20% of unfished spawning biomass.*/ + recruitment at 20 percent of unfished spawning biomass.*/ SRBevertonHolt() : RecruitmentBase() {} diff --git a/vignettes/fims-demo.Rmd b/vignettes/fims-demo.Rmd index 4919a6a86..52c703ef3 100644 --- a/vignettes/fims-demo.Rmd +++ b/vignettes/fims-demo.Rmd @@ -257,7 +257,7 @@ methods::show(BevertonHoltRecruitment) There are three parameters we need to set-up: *log_sigma_recruit*, *log_rzero*, and *logit_steep*. ```{r set-up-recruitment} -recruitment$log_rzero$value <- log(1e+06) # unit: log(number) +recruitment$log_rzero$value <- log(1e+06) # unit: ln(number) recruitment$log_rzero$is_random_effect <- FALSE recruitment$log_rzero$estimated <- TRUE recruitment$logit_steep$value <- -log(1.0 - 0.75) + log(0.75 - 0.2)