Documentation: https://hsbc.github.io/pyratings/
Source Code: https://github.com/hsbc/pyratings/
Do you work in the investment industry? Do you work with fixed income instruments, such as bonds and credit securities? Then you are probably concerned with credit ratings, too?
This Python library will be useful for portfolio managers, credit analysts, as well as anybody who is working with credit ratings. It provides functions, which will be helpful in order to work with ratings in a professional and efficient way.
Do you need to compute the average credit rating of an investment portfolio? Do you need to compute the worst rating for individual securities', given these securities have ratings attached from more than one rating agency? Do you need to compute the Weighted Average Rating Factor (WARF)?
If yes, you might want to take a look at pyratings and its offerings in the credit ratings space.
pyratings offers the following capabilities:
pyratings supports long-term ratings as well as short-term ratings. Currently, the following rating agencies will be supported:
pyratings is listed on pypi. Make sure to have Python 3.9+ installed on your machine.
Using pip:
pip install pyratings
Using pdm:
pdm add pyratings
Using poetry:
poetry add pyratings
Here are some very basic code snippets to get you up and running.
Sometimes, a rating has a credit watch or an outlook attached to it. In order to work with this rating, it is usually necessary to get rid of it.
>>> import pyratings as rtg
>>> rtg.get_pure_ratings("AA- *+")
"AA-"
Cleaning a pandas datraframe, which comprises several securities with ratings from S&P and Fitch:
>>> import numpy as np
>>> import pandas as pd
>>> import pyratings as rtg
>>> rtg_df = pd.DataFrame(
... data={
... "rtg_SP": [
... "BB+ *-",
... "BBB *+",
... np.nan,
... "AA- (Developing)",
... np.nan,
... "CCC+ (CwPositive)",
... "BB+u",
... ],
... "rtg_Fitch": [
... "BB+ *-",
... "BBB *+",
... np.nan,
... "AA- (Developing)",
... np.nan,
... "CCC+ (CwPositive)",
... "BB+u",
... ],
... },
... )
>>> rtg_df
rtg_SP rtg_Fitch
0 BB+ *- BB+ *-
1 BBB *+ BBB *+
2 NaN NaN
3 AA- (Developing) AA- (Developing)
4 NaN NaN
5 CCC+ (CwPositive) CCC+ (CwPositive)
6 BB+u BB+u
# Get rid of all the noise.
>>> rtg.get_pure_ratings(rtg_df)
rtg_SP_clean rtg_Fitch_clean
0 BB+ BB+
1 BBB BBB
2 NaN NaN
3 AA- AA-
4 NaN NaN
5 CCC+ CCC+
6 BB+ BB+
It is quite common that an individual credit security has been rated by several credit agencies. In this case, you may want to compute the best or worst rating.
>>> import pandas as pd
>>> import pyratings as rtg
>>> ratings_df = pd.DataFrame(
... data=(
... {
... "rating_S&P": ['AAA', 'AA-', 'AA+', 'BB-', 'C'],
... "rating_Moody": ['Aa1', 'Aa3', 'Aa2', 'Ba3', 'Ca'],
... "rating_Fitch": ['AA-', 'AA-', 'AA-', 'B+', 'C'],
... }
... )
... )
>>> ratings_df
rating_S&P rating_Moody rating_Fitch
0 AAA Aa1 AA-
1 AA- Aa3 AA-
2 AA+ Aa2 AA-
3 BB- Ba3 B+
4 C Ca C
# Return a pd.Series with the worst ratings.
>>> rtg.get_worst_ratings(
... ratings_df, rating_provider_input=["S&P", "Moody", "Fitch"]
... )
0 AA-
1 AA-
2 AA-
3 B+
4 C
Name: worst_rtg, dtype: object
To work with ratings, it's sometimes necessary to translate human-readable ratings into numerical rating scores and vice versa. pyratings offers a number of functions on that front.
The documentation shows
in detail how pyratings translates human-readable ratings into numerical rating
scores.
Here's an example how to translate a pandas series from ratings to scores and vice
versa.
>>> import pandas as pd
>>> import pyratings as rtg
>>> ratings_series = pd.Series(
... data=["Baa1", "C", "NR", "WD", "D", "B1", "SD"], name='Moody'
... )
>>> scores_series = rtg.get_scores_from_ratings(
... ratings=ratings_series, rating_provider="Moody's", tenor="long-term"
... )
>>> scores_series
0 8.0
1 21.0
2 NaN
3 NaN
4 22.0
5 14.0
6 22.0
Name: rtg_score_Moody, dtype: float64
# Translate these rating scores back, but this time use DBRS' rating scale
>>> rtg.get_ratings_from_scores(
... rating_scores=scores_series, rating_provider="DBRS", tenor="long-term"
... )
0 BBBH
1 C
2 NaN
3 NaN
4 D
5 BH
6 D
Name: rtg_DBRS, dtype: object
If you need help or have any questions, the first step should be to take a look at the docs. If you can't find an answer, please open an issue on GitHub, or send an email to opensource@hsbc.de. The subject line should contain '#pyratings'
We very much welcome contributions! Before you begin, please read our contributing guideliens.
Thanks to
This project is licensed under the Apache 2.0 License – please see the LICENSE file.