clarify keys that options are referring to

vignettes/cookbook_running_the_analysis.Rmd

@@ -59,8 +59,8 @@ pacta.multi.loanbook::prepare_abcd(config_path)
 
 The `prepare_abcd()` function has a number of options that can be set in the `config.yml` file. These options include:
 
-- whether or not inactive companies should be removed from the ABCD data (For more information on the options available, see the [relevant section on preparing the ABCD](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#prepare_abcd) in the `vignette("config_yml")`.)
-- if and how a company sector split should be applied in the calculations (For more information on the options available, see the [relevant section on the sector split](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#sector_split) in the `vignette("config_yml")`). Additionally, see the documentation of the sector split methodology in `vignette("sector_split")`.
+- `remove_inactive_companies`{.yaml}: whether or not inactive companies should be removed from the ABCD data (For more information on the options available, see the [relevant section on preparing the ABCD](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#prepare_abcd) in the `vignette("config_yml")`.)
+- `sector_split`{.yaml}: if and how a company sector split should be applied in the calculations (For more information on the options available, see the [relevant section on the sector split](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#sector_split) in the `vignette("config_yml")`). Additionally, see the documentation of the sector split methodology in `vignette("sector_split")`.
 
 ### Sector split
 
@@ -93,8 +93,8 @@ You can find more detailed information about the matching process in the [traini
 
 The `match_loanbooks()` function has a number of options that can be set in the `config.yml` file. These options include:
 
-- specifications for the approach to matching the raw loan book with the ABCD [relevant section on matching](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#matching) in the `vignette("config_yml")`). Note that these parameters are all based on the `r2dii.match::match_name` function and pass the parameters directly to that function. For more information on the options available, see the [documentation of the r2dii.match package](https://rmi-pacta.github.io/r2dii.match/reference/match_name.html). This also covers matching based on unique identifiers, which is the most reliable way to match companies, but requires that both the raw loan books and the ABCD contain such identifiers.
-- whether to use a manually prepared sector classification system for matching the loan books to in-scope PACTA sectors, see the [relevant section on matching](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#matching) in the `vignette("config_yml")`), or not. If there is no need to use a manually prepared sector classification file, the sector classification systems provided in `r2dii.data::sector_classifications` can be used, which currently cover the following sector classifications: `r unique(r2dii.data::sector_classifications$code_system)`. If it is not possible to map the loans in your loan books to any of these systems, you can prepare your own mapping file that follows the same structure as the sector classification files in `r2dii.data::sector_classifications` and use the config file to instruct the code to use this file for matching. Note that this will only be a promising approach if the classifications you are using are sufficiently granular to map to PACTA sectors without excessive ambiguity.
+- `params_match_name`{.yaml}: multiple options to specify the approach to matching the raw loan book with the ABCD [relevant section on matching](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#matching) in the `vignette("config_yml")`). Note that these parameters are all based on the `r2dii.match::match_name` function and pass the parameters directly to that function. For more information on the options available, see the [documentation of the r2dii.match package](https://rmi-pacta.github.io/r2dii.match/reference/match_name.html). This also covers matching based on unique identifiers, which is the most reliable way to match companies, but requires that both the raw loan books and the ABCD contain such identifiers.
+- `manual_sector_classification`{.yaml}: whether to use a manually prepared sector classification system for matching the loan books to in-scope PACTA sectors, see the [relevant section on matching](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#matching) in the `vignette("config_yml")`), or not. If there is no need to use a manually prepared sector classification file, the sector classification systems provided in `r2dii.data::sector_classifications` can be used, which currently cover the following sector classifications: `r unique(r2dii.data::sector_classifications$code_system)`. If it is not possible to map the loans in your loan books to any of these systems, you can prepare your own mapping file that follows the same structure as the sector classification files in `r2dii.data::sector_classifications` and use the config file to instruct the code to use this file for matching. Note that this will only be a promising approach if the classifications you are using are sufficiently granular to map to PACTA sectors without excessive ambiguity.
 
 ### Addressing misclassfied loans
 
@@ -123,7 +123,8 @@ pacta.multi.loanbook::prioritise_and_diagnose(config_path)
 
 The `prioritise_and_diagnose()` function has a number of options that can be set in the `config.yml` file. These options include:
 
-- the option to set a specific order for prioritizing the matches. This is an option that is passed directly to the `r2dii.match::prioritize` function. `NULL` is a valid default value and is usually a setting that works well, at least as a starting point. For more information, see the [relevant section on the prioritization of matched loan books](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#match_prioritize) in the `vignette("config_yml")` or the [documentation of the r2dii.match::prioritize() function here](https://rmi-pacta.github.io/r2dii.match/reference/prioritize.html).
+- `priority`{.yaml}: the option to set a specific order for prioritizing the matches. This is an option that is passed directly to the `r2dii.match::prioritize` function. `NULL` is a valid default value and is usually a setting that works well, at least as a starting point. For more information, see the [relevant section on the prioritization of matched loan books](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#match_prioritize) in the `vignette("config_yml")` or the [documentation of the r2dii.match::prioritize() function here](https://rmi-pacta.github.io/r2dii.match/reference/prioritize.html).
+- `by_group`{.yaml}: by which variables to group the loan books to produce grouped results of the analysis. This parameter is used across multiple steps of the analysis, both in the diagnostics and in the analysis. This is because it slices and/or aggregates the loan books such that the analysis will produce results along the indicated dimension. If no `by_group`{.yaml} parameter is passed (i.e. `NULL`{.yaml}), all loan books will be aggregated. Otherwise, loan books can either be kept separate (`group_id`{.yaml}) or grouped by any other variable that is provided in each of the raw loan books. Although `by_group`{.yaml} is considered a project parameter mainly relevant to the main section of the analysis it does affect the split of the prioritzed loan books and how their coverage metrics are returned, so it is good to be aware of this parameter at this point. See the [relevant section on the `by_group` parameter in the documentation of the `config.yml` file](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#by_group).
 
 
 ## Run PACTA for Supervisors analysis
@@ -138,12 +139,12 @@ pacta.multi.loanbook::analyse(config_path)
 
 The `analysis()` function has a number of options that can be set in the `config.yml` file. These options include:
 
-- which source should be used for allocating climate transition scenario pathways to the companies and loan books. This refers to the relevant scenario publication and usually contains the name and the year of the publication, e.g.: `"weo_2023"` or `"geco_2023"`.
-- which scenario should be used for reference in the net aggregate alignment metric. This must be a scenario that is included in the source indicated above.
-- which region to use as a reference for the analysis. This will filter the underlying production capacity to assets in the relevant region and will measure alignment against the scenario trajectory for the relevant region. It must therefore be a region, for which scenario data is available in the source selected above.
-- the start year of the analysis. This must be a year that is available both in the ABCD data and for which the scenario data has been prepared. The loan book data is assumed to be a snapshot of the end of the same year.
-- the time frame of the analysis, which refers to the number of forward looking years after the start year that are to be considered in the alignment analysis. Usually this time frame is set to 5 years. Specifically, it must be a time frame for which scenario data values and ABCD data values are available for all sectors that are to be analyzed. There are not many cases, in which it is expected to change the time frame to something else than its default value of 5 years.
-- by which variables to group the loan books to produce grouped results of the analysis. This parameter is used across multiple steps of the analysis, both in the diagnostics and in the analysis. This is because it slices and/or aggregates the loan books such that the analysis will produce results along the indicated dimension. If no `by_group` parameter is passed (i.e. `NULL`), all loan books will be aggregated. Otherwise, loan books can either be kept separate (`group_id`) or grouped by any other variable that is provided in each of the raw loan books.
+- `scenario_source`{.yaml}: which source should be used for allocating climate transition scenario pathways to the companies and loan books. This refers to the relevant scenario publication and usually contains the name and the year of the publication, e.g.: `"weo_2023"`{.yaml} or `"geco_2023"`{.yaml}.
+- `scenario_select`{.yaml}: which scenario should be used for reference in the net aggregate alignment metric. This must be a scenario that is included in the `scenario_source`{.yaml} indicated above.
+- `region_select`{.yaml}: which region to use as a reference for the analysis. This will filter the underlying production capacity to assets in the relevant region and will measure alignment against the scenario trajectory for the relevant region. It must therefore be a region, for which scenario data is available in the source selected above. Note that usually, `"global"`{.yaml} is also a valid region.
+- `start_year`{.yaml}: the start year of the analysis. This must be a year that is available both in the ABCD data and for which the scenario data has been prepared. The loan book data is assumed to be a snapshot of the end of the same year.
+- `time_frame`{.yaml}: the time frame of the analysis, which refers to the number of forward looking years after the start year that are to be considered in the alignment analysis. Usually this time frame is set to 5 years. Specifically, it must be a time frame for which scenario data values and ABCD data values are available for all sectors that are to be analyzed. There are not many cases, in which it is expected to change the time frame to something else than its default value of 5 years.
+- `by_group`{.yaml}: by which variables to group the loan books to produce grouped results of the analysis. This parameter is used across multiple steps of the analysis, both in the diagnostics and in the analysis. This is because it slices and/or aggregates the loan books such that the analysis will produce results along the indicated dimension. If no `by_group`{.yaml} parameter is passed (i.e. `NULL`{.yaml}), all loan books will be aggregated. Otherwise, loan books can either be kept separate (`group_id`{.yaml}) or grouped by any other variable that is provided in each of the raw loan books.
 
 All these options are documented in more detail the [section on project parameters](https://rmi-pacta.github.io/pacta.multi.loanbook/articles/config_yml.html#project_parameters) in the `vignette("config_yml")`.