add additional info on config options

vignettes/config_yml.Rmd

@@ -201,7 +201,7 @@ A full example `sector_split`{.yaml} section might look like:
 
 #### sector_split_type
 
-`sector_split_type`{.yaml}. As an example:
+`sector_split_type`{.yaml} describes the method by which to apply a sector split to the loans in the loan book. It is only used if `apply_sector_split`{.yaml} is set to to `TRUE`{.yaml}. It must be a single string/character value, and it must define a valid sector split method that can be processed by the package. Currently, the only method that is supported is `"equal_weights"`{.yaml}, although other options are imaginable (for example splits based on market shares within each sector). As an example:
 
 ```yaml
     sector_split_type: "equal_weights"
@@ -250,7 +250,7 @@ A full example `sector_split`{.yaml} section might look like:
 ## matching:
 
 A full example `matching`{.yaml} section might look like:
-
+#> TODO: remove prep_input_level?
 ```yaml
   matching:
     prep_input_level: "direct_loantaker"
@@ -331,10 +331,10 @@ A full example `params_match_name`{.yaml} section might look like:
 
 #### join_id
 
-`join_id`{.yaml}. Further explanation of this argument can be found in the documentation for [`r2dii.match::match_name()`{.R}](https://rmi-pacta.github.io/r2dii.match/reference/match_name.html). As an example:
+`join_id`{.yaml} is an optional parameter that allows defining by which variable to match the loans to the the companies in the `abcd`. Its intended use case is join based on unambiguous identifiers, such as the `lei`, where such data is available. It can be `NULL`{.yaml} to use standard name matching when no common identifiers are given. Must be a join specification which is internally passed to `dplyr::inner_join`. If it is an unnamed character/string vector, the values are assumed to refer to identically named join columns. If it is a named character vector, the names are used as the join columns in the `loanbook` and the values are used as the join columns in the `abcd`. Further explanation of this argument can be found in the documentation for [`r2dii.match::match_name()`{.R}](https://rmi-pacta.github.io/r2dii.match/reference/match_name.html). As an example:
 
 ```yaml
-      join_id: NULL
+      join_id: c(lei_direct_loantaker = "lei")
 ```
 
 ### own_sector_classification:
@@ -350,7 +350,7 @@ A full example `own_sector_classification`{.yaml} section might look like:
 
 #### use_own_sector_classification
 
-`use_own_sector_classification`{.yaml}. It must be a single logical value (either `TRUE`{.yaml} or `FALSE`{.yaml}). As an example:
+`use_own_sector_classification`{.yaml} determines if the matching should use an internally provided sector classification system or if it should use one provided by the user instead. Internal sector classification systems are given in `r2dii.data::sector_classifications` - see also additional [documentation in `r2dii.data`](https://rmi-pacta.github.io/r2dii.data/reference/sector_classifications.html). The function will automatically attempt to use one of the sector classification systems, based on the inputs in the raw loan book files. If an externally prepared sector classification system is to be used, for example because the loans are classified using a system that is not provided in r2dii.data out of the box, the data must be prepared following the same structure as found in `r2dii.data::sector_classifications`. It must be a single logical value (either `TRUE`{.yaml} or `FALSE`{.yaml}). As an example:
 
 ```yaml
       use_own_sector_classification: FALSE
@@ -383,7 +383,7 @@ A full example `match_prioritize`{.yaml} section might look like:
 
 #### priority
 
-`priority`{.yaml}. As an example:
+`priority`{.yaml} indicates the level of matching that should be prioritized when a loan can be matched at multiple levels. It must be a single string/character value or `NULL`{.yaml}, and it must refer to a valid, accessible, local file. Further explanation of this argument can be found in the documentation for [`r2dii.match::priortize()`{.R}](https://rmi-pacta.github.io/r2dii.match/reference/prioritize.html). As an example:
 
 ```yaml
     priority: NULL
@@ -400,7 +400,7 @@ A full example `prepare_abcd`{.yaml} section might look like:
 
 #### remove_inactive_companies
 
-`remove_inactive_companies`{.yaml} It must be a single logical value (either `TRUE`{.yaml} or `FALSE`{.yaml}). As an example:
+`remove_inactive_companies`{.yaml} determines if inactive companies should be removed from the abcd dataset or not. "Companies" here refers to company-sector combinations and "inactive" characterizes such company-sector combinations that are inactive at the end of the time frame analysed. When focusing forward looking analysis on exposures in the end year, such inactive companies may not produce meaningful results. It must be a single logical value (either `TRUE`{.yaml} or `FALSE`{.yaml}). As an example:
 
 ```yaml
     remove_inactive_companies: TRUE
@@ -461,7 +461,7 @@ A full example `aggregate_alignment_metric`{.yaml} section might look like:
 
 #### by_group
 
-`by_group`{.yaml}. It must be a single string/character value. As an example:
+`by_group`{.yaml} allows specifying the level of disaggregation to be used in the analysis. It determines the variable(s) along which the loan books are grouped and thus the dimension by which to compare the PACTA calculations. For example, one may want to calculate system-wide results without disaggregation, using `NULL`{.yaml} or one may want to analyse alignment along bank specific traits, such as `"group_id"`{.yaml} or `"bank_type"`{.yaml}. It can be `NULL`{.yaml}, a single string/character value, or a character vector. If it is not `NULL`{.yaml}, the indicated name must be a variable that is provided in the input loan books and it must be complete (`"group_id"` is automatically created when reading in the loan books, so the user does not have to add it to the raw loan books). If more than value is provided, the analysis will create all combinations of groups between the variables. However, not all plots support more than one level of disaggregation. As an example:
 
 ```yaml
     by_group: "group_id"