Home

Awesome

pyratings — Working with credit ratings, professionally and efficiently

img img img img img img

Documentation: https://hsbc.github.io/pyratings/

Source Code: https://github.com/hsbc/pyratings/

What is it all about?

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.

Table of contents

What has pyratings to offer and how might it help you?

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:

How to install pyratings?

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

Getting started with pyratings

Here are some very basic code snippets to get you up and running.

Cleaning ratings

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+

Consolidating ratings

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

Translating ratings

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.<br> 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

Support

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'

Contributing

We very much welcome contributions! Before you begin, please read our contributing guideliens.

Acknowledgements

Thanks to

License

This project is licensed under the Apache 2.0 License – please see the LICENSE file.