The package r2dii.match helps you to match counterparties from a loanbook to companies in a physical-asset database. Each section below shows you how.
Setup
We use the package r2dii.match to access the most important functions you’ll learn about. We also use example datasets from the package r2dii.data, and optional but convenient functions from the packages dplyr and readr.
library(dplyr, warn.conflicts = FALSE)
library(r2dii.data)
library(r2dii.match)Format input data loanbook and asset-based company data (abcd)
We need two datasets: a “loanbook” and an “asset-based company
dataset” (abcd). These should be formatted like: loanbook_demo
and abcd_demo
(from the r2dii.data
package).
A note on sector classification: Matches are preferred when the
sector from the loanbook matches the sector from the
abcd. The loanbook sector is determined
internally using the sector_classification_system and
sector_classification_direct_loantaker columns. Currently,
we only allow a couple specific values for
sector_classification_system:
sector_classifications$code_system %>%
unique()
#> [1] "CNB" "GICS" "ISIC" "NACE" "NAICS" "PSIC" "SIC"If you would like to use a different classification system, please raise an issue in r2dii.data and we can incorporate it.
loanbook_demo
#> # A tibble: 321 × 19
#> id_loan id_direct_l…¹ name_…² id_in…³ name_…⁴ id_ul…⁵ name_…⁶ loan_…⁷ loan_…⁸
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <dbl> <chr>
#> 1 L1 C294 Yuamen… NA NA UP15 Alpine… 225625 EUR
#> 2 L2 C293 Yuamen… NA NA UP84 Eco Wa… 301721 EUR
#> 3 L3 C292 Yuama … IP5 Yuama … UP288 Univer… 410297 EUR
#> 4 L4 C299 Yudaks… NA NA UP54 China … 233049 EUR
#> 5 L5 C305 Yukon … NA NA UP104 Garlan… 406585 EUR
#> 6 L6 C304 Yukon … NA NA UP83 Earthp… 185721 EUR
#> 7 L7 C227 Yaugoa… NA NA UP134 Ineos … 184793 EUR
#> 8 L8 C303 Yueyan… NA NA UP163 Kraftw… 291513 EUR
#> 9 L9 C301 Yuedxi… IP10 Yuedxi… UP138 Jai Bh… 407513 EUR
#> 10 L10 C302 Yuexi … NA NA UP32 Bhagwa… 186649 EUR
#> # … with 311 more rows, 10 more variables: loan_size_credit_limit <dbl>,
#> # loan_size_credit_limit_currency <chr>, sector_classification_system <chr>,
#> # sector_classification_input_type <chr>,
#> # sector_classification_direct_loantaker <dbl>, fi_type <chr>,
#> # flag_project_finance_loan <chr>, name_project <lgl>,
#> # lei_direct_loantaker <lgl>, isin_direct_loantaker <lgl>, and abbreviated
#> # variable names ¹id_direct_loantaker, ²name_direct_loantaker, …
abcd_demo
#> # A tibble: 17,668 × 14
#> company_id name_…¹ lei sector techn…² produ…³ year produ…⁴ emiss…⁵ count…⁶
#> <chr> <chr> <chr> <chr> <chr> <chr> <int> <dbl> <dbl> <chr>
#> 1 1 aba hy… 8360… power hydroc… MW 2013 133340. NA DM
#> 2 1 aba hy… 8360… power hydroc… MW 2014 131582. NA DM
#> 3 1 aba hy… 8360… power hydroc… MW 2015 129824. NA DM
#> 4 1 aba hy… 8360… power hydroc… MW 2016 128065. NA DM
#> 5 1 aba hy… 8360… power hydroc… MW 2017 126307. NA DM
#> 6 1 aba hy… 8360… power hydroc… MW 2018 124549. NA DM
#> 7 1 aba hy… 8360… power hydroc… MW 2019 122790. NA DM
#> 8 1 aba hy… 8360… power hydroc… MW 2020 121032. NA DM
#> 9 1 aba hy… 8360… power hydroc… MW 2021 119274. NA DM
#> 10 1 aba hy… 8360… power hydroc… MW 2022 117515. NA DM
#> # … with 17,658 more rows, 4 more variables: plant_location <chr>,
#> # is_ultimate_owner <lgl>, abcd_timestamp <chr>, emission_factor_unit <chr>,
#> # and abbreviated variable names ¹name_company, ²technology,
#> # ³production_unit, ⁴production, ⁵emission_factor, ⁶country_of_domicileIf you want to use loanbook_demo and
abcd_demo as template to create your own datasets, do
this:
- Write loanbook_demo.csv and abcd_demo.csv with:
# Writting to current working directory
loanbook_demo %>%
readr::write_csv(path = "loanbook_demo.csv")
abcd_demo %>%
readr::write_csv(path = "abcd_demo.csv")- For each dataset, replace our demo data with your data.
- Save each dataset as, for example, your_loanbook.csv and your_abcd.csv.
- Read your datasets back into R with:
# Reading from current working directory
your_loanbook <- readr::read_csv("your_loanbook.csv")
your_abcd <- readr::read_csv("your_abcd.csv")Here we continue to use the *_demo datasets, pretending
they contain the data of your own.
# WARNING: Skip this to avoid overwriting your data with our demo data
your_loanbook <- loanbook_demo
your_abcd <- abcd_demoScore the goodness of the match between the loanbook and abcd datasets
match_name() scores the match between names in a
loanbook dataset (lbk) and names in an asset-based company dataset
(abcd). The names come from the columns
name_direct_loantaker,
name_intermediate_parent_* and
name_ultimate_parent of the loanbook dataset, and from the
column name_company of the a asset-based company dataset.
There can be any number of name_intermediate_parent_*
columns, where * indicates the level up the corporate tree
from direct_loantaker.
The raw names are internally transformed applying best-practices commonly used in name matching algorithms, such as:
- Remove special characters.
- Replace language specific characters.
- Abbreviate certain names to reduce their importance in the matching.
- Removing corporate suffixes when necessary.
- Spell out numbers to increase their importance.
The similarity is then scored between the internally-transformed
names of the loanbook against the abcd. (For more information on the
scoring algorithm used, see: stringdist::stringsim()).
match_name(your_loanbook, your_abcd)
#> # A tibble: 410 × 28
#> id_loan id_direct_l…¹ name_…² id_in…³ name_…⁴ id_ul…⁵ name_…⁶ loan_…⁷ loan_…⁸
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <dbl> <chr>
#> 1 L1 C294 Yuamen… NA NA UP15 Alpine… 225625 EUR
#> 2 L3 C292 Yuama … IP5 Yuama … UP288 Univer… 410297 EUR
#> 3 L3 C292 Yuama … IP5 Yuama … UP288 Univer… 410297 EUR
#> 4 L5 C305 Yukon … NA NA UP104 Garlan… 406585 EUR
#> 5 L5 C305 Yukon … NA NA UP104 Garlan… 406585 EUR
#> 6 L6 C304 Yukon … NA NA UP83 Earthp… 185721 EUR
#> 7 L6 C304 Yukon … NA NA UP83 Earthp… 185721 EUR
#> 8 L8 C303 Yueyan… NA NA UP163 Kraftw… 291513 EUR
#> 9 L9 C301 Yuedxi… IP10 Yuedxi… UP138 Jai Bh… 407513 EUR
#> 10 L10 C302 Yuexi … NA NA UP32 Bhagwa… 186649 EUR
#> # … with 400 more rows, 19 more variables: loan_size_credit_limit <dbl>,
#> # loan_size_credit_limit_currency <chr>, sector_classification_system <chr>,
#> # sector_classification_input_type <chr>,
#> # sector_classification_direct_loantaker <dbl>, fi_type <chr>,
#> # flag_project_finance_loan <chr>, name_project <lgl>,
#> # lei_direct_loantaker <lgl>, isin_direct_loantaker <lgl>, id_2dii <chr>,
#> # level <chr>, sector <chr>, sector_abcd <chr>, name <chr>, …match_name() defaults to scoring matches between name
strings that belong to the same sector. Using
by_sector = FALSE removes this limitation – increasing
computation time, and the number of potentially incorrect matches to
manually validate.
match_name(your_loanbook, your_abcd, by_sector = FALSE) %>%
nrow()
#> [1] 676
# Compare
match_name(your_loanbook, your_abcd, by_sector = TRUE) %>%
nrow()
#> [1] 410min_score allows you to minimum threshold
score.
matched <- match_name(your_loanbook, your_abcd, min_score = 0.9)
range(matched$score)
#> [1] 0.9058824 1.0000000Maybe overwrite matches
If you are happy with the matching coverage achieved, proceed to the
next step. Otherwise, you can manually add matches, not found
automatically by match_name(). To do this, manually inspect
the abcd and find a company you would like to match to your
loanbook. Once a match is found, use excel to write a .csv file similar
to overwrite_demo,
where:
-
levelindicates the level that the manual match should be added to (e.g.direct_loantaker) -
id_2diiis the id of the loanbook company you would like to match (from the output ofmatch_name()) -
nameis the abcd company you would like to manually link to -
sectoroptionally you can also overwrite the sector. -
sourcethis can be used later to determine where all manual matches came from.
matched <- match_name(
your_loanbook, your_abcd,
min_score = 0.9, overwrite = overwrite_demo
)
#> Warning: You should only overwrite a sector at the level of the 'direct
#> loantaker' (DL). If you overwrite a sector at the level of the 'ultimate
#> parent' (UP) you consequently overwrite all children of that sector,
#> which most likely is a mistake.Notice the warning.
Validate matches
Write the output of match_name() into a .csv file
with:
# Writting to current working directory
matched %>%
readr::write_csv("matched.csv")Compare, edit, and save the data manually:
- Open matched.csv with any spreadsheet editor (Excel, Google Sheets, etc.).
- Compare the columns
nameandname_abcdmanually to determine if the match is valid. Other information can be used in conjunction with just the names to ensure the two entities match (sector, internal information on the company structure, etc.) - Edit the data:
- If you are happy with the match, set the
scorevalue to1. - Otherwise set or leave the
scorevalue to anything other than1.
- If you are happy with the match, set the
- Save the edited file as, say, valid_matches.csv.
Re-read the edited file (validated) with:
# Reading from current working directory
valid_matches <- readr::read_csv("valid_matches.csv")Prioritize validated matches by level
The validated dataset may have multiple matches per loan. Consider
the case where a loan is given to “Acme Power USA”, a subsidiary of
“Acme Power Co.”. There may be both “Acme Power USA” and “Acme Power
Co.” in the abcd, and so there could be two valid matches
for this loan. To get the best match only, use prioritize()
– it picks rows where score is 1 and level per
loan is of highest priority():
# Pretend we validated the matched dataset
valid_matches <- matched
some_interesting_columns <- c("id_2dii", "level", "score")
valid_matches %>%
prioritize() %>%
select(all_of(some_interesting_columns))
#> # A tibble: 216 × 3
#> id_2dii level score
#> <chr> <chr> <dbl>
#> 1 DL294 direct_loantaker 1
#> 2 DL304 direct_loantaker 1
#> 3 DL297 direct_loantaker 1
#> 4 DL287 direct_loantaker 1
#> 5 DL286 direct_loantaker 1
#> 6 DL285 direct_loantaker 1
#> 7 DL283 direct_loantaker 1
#> 8 DL282 direct_loantaker 1
#> 9 DL281 direct_loantaker 1
#> 10 DL280 direct_loantaker 1
#> # … with 206 more rowsBy default, highest priority refers to the most granular match
(direct_loantaker). The default priority is set internally
via prioritize_levels().
prioritize_level(matched)
#> [1] "direct_loantaker" "intermediate_parent_1" "ultimate_parent"You may use a different priority. One way to do that is to pass a
function to priority. For example, use rev to
reverse the default priority.
matched %>%
prioritize(priority = rev) %>%
select(all_of(some_interesting_columns))
#> # A tibble: 216 × 3
#> id_2dii level score
#> <chr> <chr> <dbl>
#> 1 UP288 ultimate_parent 1
#> 2 UP104 ultimate_parent 1
#> 3 UP83 ultimate_parent 1
#> 4 UP163 ultimate_parent 1
#> 5 UP138 ultimate_parent 1
#> 6 UP32 ultimate_parent 1
#> 7 UP81 ultimate_parent 1
#> 8 UP269 ultimate_parent 1
#> 9 UP69 ultimate_parent 1
#> 10 UP3 ultimate_parent 1
#> # … with 206 more rows