From 62f4605e81a20275be0d1a14fb09180c5ac94922 Mon Sep 17 00:00:00 2001
From: CJ Yetman <cj@cjyetman.com>
Date: Thu, 5 Sep 2024 10:44:01 +0200
Subject: [PATCH] add basic cookbook vignette (#100)

---
 vignettes/cookbook.Rmd | 74 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 vignettes/cookbook.Rmd

diff --git a/vignettes/cookbook.Rmd b/vignettes/cookbook.Rmd
new file mode 100644
index 00000000..12543b16
--- /dev/null
+++ b/vignettes/cookbook.Rmd
@@ -0,0 +1,74 @@
+---
+title: "cookbook"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{cookbook}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+# Config
+
+All of the functions take a `config` argument, which can either be a path to a `config.yml` file (see `vignette("config_yml")`) or a config list object containing previously imported settings from a `config.yml` file. All of the settings/options are configured with this `config.yml` file.
+
+# Setup
+
+You'll likely want to load the package and save the path to the `config.yml` file in a variable first:
+
+```r
+library(workflow.multi.loanbook)
+config_path <- "config.yml"
+```
+
+# Data preparation
+
+Your ABCD data will need to be prepared first with the `prepare_abcd()` function. If you want to use a custom sector split, that will also need to be prepared with the `prepare_sector_split()` function:
+
+```r
+prepare_abcd(config_path)
+prepare_sector_split(config_path)
+```
+
+# Matching process
+
+To run the matching process, you will use the `run_matching()` function.
+
+```r
+run_matching(config_path)
+```
+
+After the matching process is complete, you will need to do some manual matching.
+
+# Prioritization
+
+To prioritize the data in your loanbooks, you will use the `run_match_prioritize()` function.
+
+```r
+run_match_prioritize(config_path)
+```
+
+# Match success and coverage stats
+
+After the matching and prioritization process is complete, you may want to review the match success rate and loanbook coverage stats. This can be done with the `run_calculate_match_success_rate()` and `run_calculate_loanbook_coverage()` functions. In case you are not satisfied with your match success rate, you may have to go back to the manual matching process and try to match additional loans. You can then rerun `run_calculate_match_success_rate()` and `run_calculate_loanbook_coverage()` to check if your additional matching has improved coverage.
+
+```r
+run_calculate_match_success_rate(config_path)
+run_calculate_loanbook_coverage(config_path)
+```
+
+# PACTA analysis
+
+To run PACTA on all of your previously matched and prioritized loanbooks, you will use the `run_pacta()` function.
+
+```r
+run_pacta(config_path)
+```
+
+# PACTA metrics and plots
+
+Once the PACTA analysis has been run on your loanbooks, you may want to calculate aggregate alignment metrics and export some plots, which can be done with the `run_aggregate_alignment_metric()` and `plot_aggregate_loanbooks()` functions.
+
+```r
+run_aggregate_alignment_metric(config_path)
+plot_aggregate_loanbooks(config_path)
+```