Add helper function to extract patient level random effects

[gowerc]

Closes #423

I really wanted to be able to just re-use the Quantities() group of functions/objects as they are functionally very similar but there was just enough differences in how they are constructed and handled that it become more burden than it was worth to try and marry the code so ended up just splitting up into its own separate object family. Bit verbose but hopefully less complexity as a result.

Basic Explanation:

• getRandomEffectsNames() is a helper method to map the Stan object parameter names to the human readable labels for each model
• LongitudinalRandomEffects() is the main user-facing function that users should call on the Joint Model samples object which constructs a RandomEffectQuantities object
• Users can then call summary() or as.data.frame() on the RandomEffectQuantities object to get either the summary stats or the individual samples respectively.
• Most of the file changes are documentation updates due to the use of @family to cross link

EDIT ---

Looks like the default lintr has been updated to reject explicit returns so there are a few other random edits just to stop it from erroring.

[github-actions]

Code Coverage Summary

Filename                           Stmts    Miss  Cover    Missing
-------------------------------  -------  ------  -------  -------------------------------------
R/brier_score.R                      167       0  100.00%
R/DataJoint.R                         76       2  97.37%   264, 270
R/DataLongitudinal.R                 119       1  99.16%   244
R/DataSubject.R                       85       1  98.82%   142
R/DataSurvival.R                      98       0  100.00%
R/defaults.R                          10       6  40.00%   18-57, 84
R/generics.R                          36       5  86.11%   52, 382, 402, 464, 481
R/Grid.R                              27       1  96.30%   173
R/GridEven.R                          32       0  100.00%
R/GridEvent.R                         22       0  100.00%
R/GridFixed.R                         30       0  100.00%
R/GridGrouped.R                       52       0  100.00%
R/GridManual.R                        23       3  86.96%   78-80
R/GridObserved.R                      20       0  100.00%
R/GridPopulation.R                    31       4  87.10%   61, 69-71
R/GridPrediction.R                    36       6  83.33%   83, 91-95
R/JointModel.R                       130      11  91.54%   146-151, 201, 205, 247, 293, 299, 322
R/JointModelSamples.R                 71       0  100.00%
R/link_generics.R                     16       4  75.00%   59, 76, 91, 106
R/Link.R                              62       4  93.55%   200-203
R/LinkComponent.R                     19       3  84.21%   88, 120-121
R/LongitudinalClaretBruno.R           90       6  93.33%   168-172, 187
R/LongitudinalGSF.R                  101       0  100.00%
R/LongitudinalModel.R                 19       0  100.00%
R/LongitudinalQuantities.R            71       0  100.00%
R/LongitudinalRandomEffects.R         53      17  67.92%   80-105
R/LongitudinalRandomSlope.R           45       6  86.67%   102-106, 119
R/LongitudinalSteinFojo.R             91      10  89.01%   159-163, 194-198
R/Parameter.R                         14       0  100.00%
R/ParameterList.R                     42       1  97.62%   184
R/Prior.R                            270       6  97.78%   547, 691-705
R/Promise.R                           25       0  100.00%
R/Quantities.R                        60       0  100.00%
R/QuantityGeneratorPopulation.R       22       0  100.00%
R/QuantityGeneratorPrediction.R       48       0  100.00%
R/QuantityGeneratorSubject.R          19       0  100.00%
R/settings.R                          12      12  0.00%    55-69
R/SimGroup.R                           5       0  100.00%
R/SimJointData.R                      72       1  98.61%   103
R/SimLongitudinal.R                    5       2  60.00%   22, 40
R/SimLongitudinalClaretBruno.R        74       0  100.00%
R/SimLongitudinalGSF.R                80       0  100.00%
R/SimLongitudinalRandomSlope.R        42       0  100.00%
R/SimLongitudinalSteinFojo.R          69       0  100.00%
R/SimSurvival.R                      116       0  100.00%
R/StanModel.R                         15       0  100.00%
R/StanModule.R                       176       6  96.59%   192-193, 235, 246, 383, 411
R/SurvivalExponential.R               10       0  100.00%
R/SurvivalGamma.R                     13       0  100.00%
R/SurvivalLoglogistic.R               11       0  100.00%
R/SurvivalModel.R                     19       0  100.00%
R/SurvivalQuantities.R               170       1  99.41%   125
R/SurvivalWeibullPH.R                 13       0  100.00%
R/utilities.R                        144       2  98.61%   13, 335
R/zzz.R                               29      26  10.34%   4-8, 10-31, 38-47
TOTAL                               3207     147  95.42%

Diff against main

Filename                         Stmts    Miss  Cover
-----------------------------  -------  ------  --------
R/generics.R                        +2      +1  -2.12%
R/JointModel.R                      +1      +1  -0.71%
R/LongitudinalGSF.R                 +6       0  +100.00%
R/LongitudinalRandomEffects.R      +53     +17  +67.92%
R/LongitudinalRandomSlope.R         +1      +1  -1.97%
R/LongitudinalSteinFojo.R           +5      +5  -5.18%
TOTAL                              +68     +25  -0.70%

Results for commit: 98f4936

Minimum allowed coverage is 80%

♻️ This comment has been updated with latest results

[github-actions]

Unit Tests Summary

    1 files    182 suites   6m 50s ⏱️
  160 tests   148 ✅ 12 💤 0 ❌
1 106 runs  1 093 ✅ 13 💤 0 ❌

Results for commit 98f4936.

[github-actions]

Unit Test Performance Difference

Test Suite	$Status$	Time on main	$±Time$	$±Tests$	$±Skipped$	$±Failures$	$±Errors$
LongitudinalRandomEffects	👶		$+3.97$	$+4$	$0$	$0$	$0$
compile	💚	$10.32$	$-3.17$	$0$	$0$	$0$	$0$
extract_quantities	💚	$12.14$	$-11.71$	$0$	$0$	$0$	$0$
misc_models	💚	$13.49$	$-5.84$	$0$	$0$	$0$	$0$
model_multi_chain	💚	$53.23$	$-24.81$	$0$	$0$	$0$	$0$

Additional test case details

Test Suite	$Status$	Time on main	$±Time$	Test Case
Grid	💚	$101.58$	$-57.93$	Grid_objects_work_with_QuantityGenerator_and_QuantityCollapser
GridPrediction	💔	$113.35$	$+9.47$	GridPrediction_works_as_expected_for_Survival_models
JointModelSamples	💔	$10.38$	$+22.71$	print_works_as_expected_for_JointModelSamples
LongitudinalClaretBruno	💚	$2790.26$	$-2783.75$	LongitudinalClaretBruno_works_as_expected_with_default_arguments
LongitudinalGSF	💚	$702.44$	$-694.91$	LongitudinalGSF_works_as_expected_with_default_arguments
LongitudinalQuantiles	💚	$40.92$	$-34.60$	Test_that_LongitudinalQuantities_works_as_expected
LongitudinalRandomEffects	👶		$+3.97$	LongitudinalRandomEffects_works_as_expected
LongitudinalRandomSlope	💚	$71.03$	$-12.14$	Print_method_for_LongitudinalRandomSlope_works_as_expected
LongitudinalSteinFojo	💚	$1448.67$	$-1448.09$	LongitudinalSteinFojo_works_as_expected_with_default_arguments
SimSurvival	💚	$4.03$	$-3.34$	SimSurvivalExponential_creates_a_dataset_with_the_correct_parameter
SurvivalExponential	💚	$24.50$	$-23.07$	Can_load_and_compile_SurvivalExponential_model
SurvivalGamma	💚	$194.74$	$-193.95$	Print_method_for_SurvivalGamma_works_as_expected
SurvivalLoglogistic	💚	$40.38$	$-39.45$	Can_load_and_compile_SurvivalLogLogistic_model
SurvivalQuantities	💚	$79.53$	$-24.95$	SurvivalQuantities_and_autoplot.SurvivalQuantities_works_as_expected
SurvivalWeibullPH	💚	$13.20$	$-11.81$	Print_method_for_SurvivalWeibullPH_works_as_expected
brierScore	💚	$67.59$	$-62.23$	brierScore_SurvivalQuantities_returns_same_results_as_survreg
brms_compare	💚	$341.28$	$-341.20$	jmpost_and_brms_get_similar_loo_for_longitudinal_models
compile	💚	$10.32$	$-3.17$	compileStanModel_doesn_t_error_if_the_directory_doesn_t_exist
extract_quantities	💚	$12.14$	$-11.71$	extract_quantities_works_as_expected
misc_models	💚	$13.49$	$-5.84$	Longitudinal_Model_doesn_t_print_sampler_rejection_messages
model_multi_chain	💚	$53.23$	$-24.81$	Can_recover_known_distribution_parameters_from_random_slope_model_when_using_multiple_chains
stan_functions	💚	$27.17$	$-27.12$	GSF_SLD_function_works_as_expected

Results for commit 31631c1

♻️ This comment has been updated with latest results.

[gravesti]

This looks great @gowerc !