Conscious uncoupling / grouped naming-scheme

[patrickbarks]

A few Rage functions (primarily vitalRates, matrixElementPerturbation, and vitalRatePerturbation) involve a lot of intermediate steps, and have complex outputs. I suggest breaking these down into simpler functions to allow users more flexibility (following #20).

Relatedly, I think we should consider transitioning to a naming scheme where groups of similar functions have the same prefix, so that they're easier for users to locate. E.g. Instead of matrixElementPerturbation and vitalRatePerturbation, we could use perturb_transitions and perturb_vitals. The vital rate functions I propose below could all begin with vitals_ or vr_, and @iainmstott's shape functions with shape_.

Break apart vitalRates

I suggest three layers of functions:

(1.) matrix-returning functions (element-specific vital rates of growth, shrinkage, stasis, and reproduction, all conditional on survival)

• vr_mat_U and vr_mat_R

(2.) vector-returning functions (stage-specific vital rate sums)

• vr_vec_survival, vr_vec_growth, vr_vec_shrinkage, vr_vec_stasis, vr_vec_reproduction, vr_vec_dormancy

(3.) scalar-returning functions (average vital rates across all stages, possibly weighted)

• vr_survival, vr_growth, vr_shrinkage, vr_stasis, vr_reproduction, vr_dormancy

Each of these should allow the user to specify the set of possible transitions so that we can distinguish between structural zeros and sampled zeros, and to specify stages that should be excluded from calculation (e.g. dormant stages).

Break apart perturbation functions

I haven't thought as much about these, but we could start with pulling the nested loop that's common to both functions into a separate function (i.e. given matA return a sensitivity matrix based either on lambda or a user-supplied demogstat argument).

I think we should also avoid returning both sensitivities and elasticities in a single functional call. The type of output could be specified with an additional argument type, or perhaps we could use separate sensitivity_ and elasticity_ functions.

[iainmstott]

Agreed, agreed, agreed, agreed. I like consistency, and coherency.

Two points to add:

1. Maybe camel case rather than snake, to match RCompadre.
2. For me, smaller function names are better: I don't like how some of the current Rage functions are so long and unwieldy. I favour e.g. vr over vitals.

But yes, I think it's a very good idea and I think the package needs it.

[patrickbarks]

Cool cool cool. I can work on keeping the function names brief. Rcompadre does use snake_case now, so I think we could switch Rage as well to standardize.

[iainmstott]

I missed that change! Must have been during the move. No problem then

[patrickbarks]

Here are my suggestions for updating/standardizing the remaining function names. Feedback / suggestions encouraged!

# mpm transform
collapseMatrix    ->  mpm_collapse
rearrangeMatrix   ->  mpm_rearrange
spitMatrix        ->  mpm_split
standardizeMatrix ->  mpm_standardize

# mpm transform helpers
reprodStages         ->  standardized_stages
identifyReprodStages ->  id_repro_stages

# life history traits
dEntropy          ->  entropy_d
kEntropy          ->  entropy_k
lifeExpectancy    ->  life_expect
longevity         ->  longevity
R0                ->  net_repro_rate
lifeTimeRepEvents ->  mature_prob
                  ->  mature_age
                  ->  mature_life_expect

# other
qsdConverge       ->  qsd_converge

# pace and shape
(new)             ->  shape_surv
(new)             ->  shape_repro

# life table
ageSpecificSurv   ->  mpm_to_lx
(new)             ->  mpm_to_hx
(new)             ->  mpm_to_px
ageSpecificRepro  ->  mpm_to_mx
makeLifeTable     ->  mpm_to_table

# perturbation
(new)                     -> perturb_matrix
vitalRatePerturbation     -> perturb_trans
matrixElementPerturbation -> perturb_vitals

# vital rates
vitalRates  -> vr_[...]
            -> vr_vec_[...]
            -> vr_mat_[...]

[iainmstott]

They all look good to me and I agree with the move to snake case. I like continuity. Only query is about standardized_stages as it's quite different to the current and doesn't mention reproduction

[patrickbarks]

Ya, partly I'm trying to distinguish it from the similar-sounding function identifyReprodStages. reprodStages takes arguments matR, a vector of repro stages based on the mean matrix, and the vector matrixClassOrganized, and returns a list of which stages correspond to the standardized stage groups:

• propagule
• pre-reproductive
• reproductive
• post-reproductive

A 'FIXME' note suggests it may eventually incorporate a 'dormant' class. So I think the former name reproStages was not particularly fitting, and something like standardized_stages works better. But I'm open to alternatives.

[jonesor]

This has been done now.
A useful addition to the documentation could be to add @family tags to allow grouping of the function documentation of these natural groups. I've added another issue about this.