[Refactor]: Define recruitment_deviations in log space.

[nathanvaughan-NOAA]

Refactor request

recruitment_deviations are currently defined as proportions of expected recruitment and then log transformed when the nll is calculated. These should maybe be defined in log space.

Discussion from pull request review.
@ChristineStawitz-NOAA
question: we're not clear - should recruitment_deviations be entered in log space rather than being logged only within the likelihood?

@timjmiller
yeah, this looks wrong unless "recruit_deviations" are ratios of recruitment from one time step to the next.

@Andrea-Havron-NOAA
recruit deviations are in linear space when input into the model and when used in CalculateRecruitment. If we update rec devs to be in logspace, we will need to update code in these two locations. I personally find it hard to keep track of what is supposed to be in log versus linear space and would prefer renaming recruitment_deviations to log_recruitment_deviations or some variety of logR if we want to convert this to log space.

ChristineStawitz-NOAA reacted with thumbs up emoji

@iantaylor-NOAA
I think "deviations", either in variable names or plain language, should refer to values that are distributed on either side of 0. At least I would find that much less confusing. If it's important to maintain non-log values for annual recruitment values, I would call them something like recruitment_scalars or recruitment_multipliers.

Expected behavior

Defining recruitment deviations in log space would be clearer to users.

Code of Conduct

• I agree to follow this project's Code of Conduct

[Cole-Monnahan-NOAA]

I agree to have them defined in log space. Don't we need this eventually when we treat them as random effects? I don't think we should apply the Laplace approximation in the natural space. It seems like any random effects should always been parameterized this way. I also agree with the interpretation of "deviation" and that a consistent naming convention would be helpful.

[Andrea-Havron-NOAA]

@Cole-Monnahan-NOAA, good point about defining them in log space to be consistent with random effects parameterization.

[Andrea-Havron-NOAA]

Linking issue #364 as this change will resolve the constrain deviations error mentioned in the conversation

[iantaylor-NOAA]

Working on this now with @Andrea-Havron-NOAA and @KyleShertzer-NOAA.

Files that need to be changed

• inst/include/population_dynamics/recruitment/functors/recruitment_base.hpp
• inst/include/population_dynamics/population/population.hpp
• inst/include/interface/rcpp/rcpp_objects/rcpp_recruitment.hpp
• tests/gtest/test_population_Recruitment.cpp
• tests/gtest/test_population_dynamics_recruitment_base.cpp
• tests/integration/integration_class.hpp