RECENT POSTS

Modeling assets with QuantLib

Feb 13, 2022

What’s the best strategy to model assets with modelx?

You may have heard about QuantLib, an open-source library for modeling financial instruments. This post is about exploring QuantLib to see how QuantLib can be leveraged for modeling a bond portfolio with modelx. A sample model is also developed and explained.

About QuantLib

QuantLib Logo

First, here’s a brief introduction to QuantLib for those who don’t know much about it. As mentioned earlier, QuantLib is an open-source library for financial instrument valuation. It has been around for more than 20 years, and probably the most recognized open source library in the area of quantitative finance. Here’re some facts about QuantLib:

  • QuantLib itself is written in C++, but it’s available in Python through a Python binding library.
  • QuantLib contains many classes that represents types of financial instruments.
  • QuantLib takes full advantage of the object-oriented paradigm.
  • The class hierarchy is highly organized. For example click “Inheritance diagram for Instrument:” on this page. The diagram is a graphical representation of the hierarchy. All the instrument models inherit from Instrument.
  • QuantLib implements its own caching mechanism, similar to modelx. Observer, Observable and LazyObject in the diagram above are for implementing the mechanism.

QuantLib vs. actuarial models

Life insurance policies are a kind on financial instruments, so you would expect that objects in QuantLib would look a lot like life actuarial models. However, the QuantLib objects are designed in a pretty different manner. The most noticeable difference is in handling time.

Actuarial models do not usually model the exact dates of cashflows. This is because insurance claims and surrender payouts are contingent on insured’s death or policyholder’s behavior, so the exact payment dates are unknown. Instead, actuarial models define projection steps, discrete points in time based on a regular pattern, such as at the end of each calendar month, or at the end of each fiscal year, regardless of the timing of actual cashflows.

On the other hand, QuantLib treats dates and time periods very precisely. In QuantLib, for each trade, the number of settlement days needs to be specified, which is the number of days between the tarde date and the delivery date of the trade. Other examples of QuantLib’s precise time treatment are day count conventions, business days and calendars.

Unlike actuarial models, QuantLib does not define projection steps that apply to the cashflows of all instruments. The cashflows of a financial instrument is represented by a vector of Cashflow objects, and each Cashflow is essentially a pair of the exact date and the amount of the cashflow.

Modeling a bond portfolio in modelx using QuantLib

Despite the differences, QuantLib is still a powerful tool to model assets for actuarial applications. To demonstrate how QuantLib integrates with modelx, a sample model is developed. The sample model models a portfolio of fixed rate bonds, generates cashflows and calculates the market value of the portfolio.

Here’s a brief summary on how the model is structured.

  • The model reads 1000 records of sample bond data from a spreadsheet. The bond data is generated by a Jupyter notebook using random numbers. The data is stored in the model as a pandas DataFrame named bond_data.

  • date_init holds a valuation date as a string. The dates cells defines projection steps by returning points in time as QuantLib’s Date objects. The valuation date is set to January 1, 2022. The length of a projection step is annual.

  • fixed_rate_bond returns a QuantLib’s FixedRateBond object representing a bond specified by the given bond ID.

  • The cashflows cells returns a vector of the cashflows of the selected bond. The cashflows falling in each projection period defined by dates are aggregated.

  • cashflows_total returns a vector of the aggregated cashflows of the entire bond portfolio.

  • Risk-free yield data is also read from a spreadsheet in the model and stored as a DataFrame named zero_curve. riskfree_curve constructs and returns a QuantLib’s ZeroCurve object.

  • market_values returns a list of the market values of the bonds. The market value of each bond is calculated using the cleanPrice method by discounting the cashflows of the bond by the risk-free rates plus the bond’s credit spread.

  • z_spread_recalc is for checking the calculation of the market value of a selected bond, by reproducing the z-spread from the market value and the risk free curve.

The video shows the model opened in Spyder with the modelx plugin and the following values are examined.

  • bond_data
  • cashflows for the 1 bond ID.
  • z_spread_recalc for the 1 bond ID. Note 0.0304 matches the input in bond_data.
  • cashflow_total
  • market_values

The sample model and the Jupyter notebook for the sample generation are attached below.

The models calculates the cashflows and market values of the 1000 bonds almost instantly. The sample model shows how well QuantLib integrates with modelx, and indicates that modelx can be an optimal tool for developing full-fledged ALM models.

References