BondIndex Class Reference

Bond Index. More...

#include <qle/indexes/bondindex.hpp>

Inheritance diagram for BondIndex:

Collaboration diagram for BondIndex:

Public Types
enum class	PriceQuoteMethod { PercentageOfPar , CurrencyPerUnit }

Public Member Functions
	BondIndex (const std::string &securityName, const bool dirty=false, const bool relative=true, const Calendar &fixingCalendar=NullCalendar(), const QuantLib::ext::shared_ptr< QuantLib::Bond > &bond=nullptr, const Handle< YieldTermStructure > &discountCurve=Handle< YieldTermStructure >(), const Handle< DefaultProbabilityTermStructure > &defaultCurve=Handle< DefaultProbabilityTermStructure >(), const Handle< Quote > &recoveryRate=Handle< Quote >(), const Handle< Quote > &securitySpread=Handle< Quote >(), const Handle< YieldTermStructure > &incomeCurve=Handle< YieldTermStructure >(), const bool conditionalOnSurvival=true, const Date &issueDate=Date(), const PriceQuoteMethod priceQuoteMethod=PriceQuoteMethod::PercentageOfPar, const double priceQuoteBaseValue=1.0, const bool isInflationLinked=false, const double bidAskAdjustment=0.0, const bool bondIssueDateFallback=false)
Index interface
std::string	name () const override
Calendar	fixingCalendar () const override
bool	isValidFixingDate (const Date &fixingDate) const override
Real	fixing (const Date &fixingDate, bool forecastTodaysFixing=false) const override
Observer interface
void	update () override
Fixing calculations
virtual Rate	forecastFixing (const Date &fixingDate) const
Rate	pastFixing (const Date &fixingDate) const

Inspectors
std::string	securityName_
bool	dirty_
bool	relative_
Calendar	fixingCalendar_
QuantLib::ext::shared_ptr< QuantLib::Bond >	bond_
Handle< YieldTermStructure >	discountCurve_
Handle< DefaultProbabilityTermStructure >	defaultCurve_
Handle< Quote >	recoveryRate_
Handle< Quote >	securitySpread_
Handle< YieldTermStructure >	incomeCurve_
bool	conditionalOnSurvival_
Date	issueDate_
PriceQuoteMethod	priceQuoteMethod_
double	priceQuoteBaseValue_
bool	isInflationLinked_
double	bidAskAdjustment_
QuantLib::ext::shared_ptr< DiscountingRiskyBondEngine >	vanillaBondEngine_
bool	bondIssueDateFallback_ = false
const std::string &	securityName () const
bool	dirty () const
bool	relative () const
QuantLib::ext::shared_ptr< QuantLib::Bond >	bond () const
Handle< YieldTermStructure >	discountCurve () const
Handle< DefaultProbabilityTermStructure >	defaultCurve () const
Handle< Quote >	recoveryRate () const
Handle< Quote >	securitySpread () const
Handle< YieldTermStructure >	incomeCurve () const
bool	conditionalOnSurvival () const
Date	issueDate () const
PriceQuoteMethod	priceQuoteMethod () const
double	priceQuoteBaseValue () const

Detailed Description

Bond Index.

Definition at line 46 of file bondindex.hpp.

Member Enumeration Documentation

PriceQuoteMethod

enum class PriceQuoteMethod

strong

Enumerator
PercentageOfPar
CurrencyPerUnit

Definition at line 48 of file bondindex.hpp.

{ PercentageOfPar, CurrencyPerUnit };

Constructor & Destructor Documentation

BondIndex()

BondIndex	(	const std::string &	securityName,
		const bool	dirty = false,
		const bool	relative = true,
		const Calendar &	fixingCalendar = NullCalendar(),
		const QuantLib::ext::shared_ptr< QuantLib::Bond > &	bond = nullptr,
		const Handle< YieldTermStructure > &	discountCurve = Handle<YieldTermStructure>(),
		const Handle< DefaultProbabilityTermStructure > &	defaultCurve = Handle<DefaultProbabilityTermStructure>(),
		const Handle< Quote > &	recoveryRate = Handle<Quote>(),
		const Handle< Quote > &	securitySpread = Handle<Quote>(),
		const Handle< YieldTermStructure > &	incomeCurve = Handle<YieldTermStructure>(),
		const bool	conditionalOnSurvival = true,
		const Date &	issueDate = Date(),
		const PriceQuoteMethod	priceQuoteMethod = PriceQuoteMethod::PercentageOfPar,
		const double	priceQuoteBaseValue = 1.0,
		const bool	isInflationLinked = false,
		const double	bidAskAdjustment = 0.0,
		const bool	bondIssueDateFallback = false
	)

The values that this index return are of the form

• 1.02 meaning 102% price clean or dirty (depending on the flag dirty in the ctor) i.e. the absolute bond clean or dirty NPV is divided by the current notional at the fixing date
• 10020 meaning an absolute NPV in terms of the current notional of the underlying bond at the fixing date, again clean or dirty depending on the flag dirty in the ctor, here the notional would be 10000

The first form is returned if the flag relative in the ctor is set to true, the second if this flag is set to false.

The fixing projection (fixingDate > today) assumes that the given bond is vanilla, i.e. its present value can be calculated by discounting the cashflows retrieved with Bond::cashflows().

If the bond has a pricing engine attached and today's fixing is projected, the pricing engine's result will be used. Otherwise today's fixing will be calculated as projected fixings for dates > today, i.e. by simply discounting the bond's cashflows.

If no bond is given, only historical fixings are returned by the index and only the clean price mode and relative price mode are supported respectively. Otherwise an exception is thrown whenever a fixing is requested from the index.

To compute projected fixings for dates > today, a discountCurve is required. The other quotes and curves are optional and default as follows:

• defaultCurve: defaults to zero hazard spread
• recoveryRate: defaults to zero
• securitySpread: defaults to zero
• incomCurve: defaults to the curve build as discountCurve + securitySpread

If conditionalOnSurvival is set to true, a projected fixing will be conditional on survival until the associated bond settlement date, otherwise it will include the default probability between today and the settlement date.

If priceQuoteMethod = CurrencyPerUnit, a fixing in the fixing history will be divided by priceQuoteBaseValue before returning it.

Definition at line 29 of file bondindex.cpp.

    : securityName_(securityName), dirty_(dirty), relative_(relative), fixingCalendar_(fixingCalendar), bond_(bond),
      discountCurve_(discountCurve), defaultCurve_(defaultCurve), recoveryRate_(recoveryRate),
      securitySpread_(securitySpread), incomeCurve_(incomeCurve), conditionalOnSurvival_(conditionalOnSurvival),
      issueDate_(issueDate), priceQuoteMethod_(priceQuoteMethod), priceQuoteBaseValue_(priceQuoteBaseValue),
      isInflationLinked_(isInflationLinked), bidAskAdjustment_(bidAskAdjustment),
      bondIssueDateFallback_(bondIssueDateFallback) {
 
    registerWith(Settings::instance().evaluationDate());
    registerWith(IndexManager::instance().notifier(BondIndex::name()));
    registerWith(bond_);
    registerWith(discountCurve_);
    registerWith(defaultCurve_);
    registerWith(recoveryRate_);
    registerWith(securitySpread_);
    registerWith(incomeCurve_);
 
    vanillaBondEngine_ = QuantLib::ext::make_shared<DiscountingRiskyBondEngine>(discountCurve, defaultCurve, recoveryRate,
                                                                        securitySpread, 6 * Months, boost::none);
}

Here is the call graph for this function:

Member Function Documentation

name()

std::string name ( ) const

override

Definition at line 57 of file bondindex.cpp.

{ return "BOND-" + securityName_; }

Here is the caller graph for this function:

fixingCalendar()

Calendar fixingCalendar ( ) const

override

Definition at line 59 of file bondindex.cpp.

{ return fixingCalendar_; }

Here is the caller graph for this function:

isValidFixingDate()

bool isValidFixingDate ( const Date &  fixingDate ) const

override

Definition at line 61 of file bondindex.cpp.

{ return fixingCalendar().isBusinessDay(d); }

Here is the call graph for this function:

Here is the caller graph for this function:

fixing()

Real fixing ( const Date &  fixingDate, bool  forecastTodaysFixing = false  ) const

override

Definition at line 65 of file bondindex.cpp.

                                                                              {
    //! this logic is the same as in InterestRateIndex
    QL_REQUIRE(isValidFixingDate(fixingDate), "Fixing date " << fixingDate << " is not valid for '" << name() << "'");
    Date today = Settings::instance().evaluationDate();
    if (fixingDate > today || (fixingDate == today && forecastTodaysFixing))
        return forecastFixing(fixingDate);
    Real adj = priceQuoteMethod_ == PriceQuoteMethod::CurrencyPerUnit ? 1.0 / priceQuoteBaseValue_ : 1.0;
    if (fixingDate < today || Settings::instance().enforcesTodaysHistoricFixings()) {
        // must have been fixed
        // do not catch exceptions
        Rate result = pastFixing(fixingDate);
        QL_REQUIRE(result != Null<Real>(), "Missing " << name() << " fixing for " << fixingDate);
        return result * adj;
    }
    try {
        // might have been fixed
        Rate result = pastFixing(fixingDate);
        if (result != Null<Real>())
            return result * adj;
        else
            ; // fall through and forecast
    } catch (Error&) {
        ; // fall through and forecast
    }
    return forecastFixing(fixingDate);
}

Here is the call graph for this function:

update()

void update ( )

override

Definition at line 63 of file bondindex.cpp.

{ notifyObservers(); }

forecastFixing()

Rate forecastFixing ( const Date &  fixingDate ) const

virtual

Reimplemented in BondFuturesIndex.

Definition at line 92 of file bondindex.cpp.

                                                           {
    Date today = Settings::instance().evaluationDate();
    QL_REQUIRE(fixingDate >= today,
               "BondIndex::forecastFixing(): fixingDate (" << fixingDate << ") must be >= today (" << today << ")");
    QL_REQUIRE(bond_, "BondIndex::forecastFixing(): bond required");
 
    // on today, try to get the dirty absolute price from the bond itself
 
    Real price = Null<Real>();
    if (fixingDate == today) {
        try {
            price = bond_->settlementValue();
        } catch (...) {
        }
    }
 
    // for future dates or if the above did not work, assume that the bond can be priced by
    // simply discounting its cashflows
 
    if (price == Null<Real>()) {
        auto res = vanillaBondEngine_->calculateNpv(bond_->settlementDate(fixingDate),
                                                    bond_->settlementDate(fixingDate), bond_->cashflows(), boost::none,
                                                    incomeCurve_, conditionalOnSurvival_, false);
        price = res.npv;
    }
 
    price += bidAskAdjustment_ * bond_->notional(fixingDate);
 
    if (!dirty_) {
        price -= bond_->accruedAmount(fixingDate) / 100.0 * bond_->notional(fixingDate);
    }
 
    if (relative_) {
        if (close_enough(bond_->notional(fixingDate), 0.0))
            price = 0.0;
        else
            price /= bond_->notional(fixingDate);
    }
 
    return price;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pastFixing()

Real pastFixing

(

const Date &

fixingDate

)

const

Definition at line 134 of file bondindex.cpp.

                                                       {
    QL_REQUIRE(isValidFixingDate(fixingDate), fixingDate << " is not a valid fixing date for '" << name() << "'");
 
    Date fd = (bondIssueDateFallback_ && fixingDate < issueDate_) ? issueDate_ : fixingDate;
 
    Real price = timeSeries()[fd] + bidAskAdjustment_;
    if (price == Null<Real>())
        return price;
    if (dirty_) {
        QL_REQUIRE(bond_, "BondIndex::pastFixing(): bond required for dirty prices");
        price += bond_->accruedAmount(fd) / 100.0;
    }
 
    if (isInflationLinked_) {
        price *= QuantExt::inflationLinkedBondQuoteFactor(bond_);
    }
 
    if (!relative_) {
        QL_REQUIRE(bond_, "BondIndex::pastFixing(): bond required for absolute prices");
        price *= bond_->notional(fd);
    }
    return price;
}

Here is the call graph for this function:

Here is the caller graph for this function:

securityName()

const std::string & securityName

(

)

const

Definition at line 122 of file bondindex.hpp.

{ return securityName_; }

Here is the caller graph for this function:

dirty()

bool dirty

(

)

const

Definition at line 123 of file bondindex.hpp.

{ return dirty_; }

Here is the caller graph for this function:

relative()

bool relative

(

)

const

Definition at line 124 of file bondindex.hpp.

{ return relative_; }

Here is the caller graph for this function:

bond()

QuantLib::ext::shared_ptr< QuantLib::Bond > bond

(

)

const

Definition at line 125 of file bondindex.hpp.

{ return bond_; }

Here is the caller graph for this function:

discountCurve()

Handle< YieldTermStructure > discountCurve

(

)

const

Definition at line 126 of file bondindex.hpp.

{ return discountCurve_; }

Here is the caller graph for this function:

defaultCurve()

Handle< DefaultProbabilityTermStructure > defaultCurve

(

)

const

Definition at line 127 of file bondindex.hpp.

{ return defaultCurve_; }

Here is the caller graph for this function:

recoveryRate()

Handle< Quote > recoveryRate

(

)

const

Definition at line 128 of file bondindex.hpp.

{ return recoveryRate_; }

Here is the caller graph for this function:

securitySpread()

Handle< Quote > securitySpread

(

)

const

Definition at line 129 of file bondindex.hpp.

{ return securitySpread_; }

Here is the caller graph for this function:

incomeCurve()

Handle< YieldTermStructure > incomeCurve

(

)

const

Definition at line 130 of file bondindex.hpp.

{ return incomeCurve_; }

Here is the caller graph for this function:

conditionalOnSurvival()

bool conditionalOnSurvival

(

)

const

Definition at line 131 of file bondindex.hpp.

{ return conditionalOnSurvival_; }

Here is the caller graph for this function:

issueDate()

Date issueDate

(

)

const

Definition at line 132 of file bondindex.hpp.

{ return issueDate_; }

priceQuoteMethod()

PriceQuoteMethod priceQuoteMethod

(

)

const

Definition at line 133 of file bondindex.hpp.

{ return priceQuoteMethod_; }

priceQuoteBaseValue()

double priceQuoteBaseValue

(

)

const

Definition at line 134 of file bondindex.hpp.

{ return priceQuoteBaseValue_; }

Member Data Documentation

securityName_

std::string securityName_

protected

Definition at line 138 of file bondindex.hpp.

dirty_

bool dirty_

protected

Definition at line 139 of file bondindex.hpp.

relative_

bool relative_

protected

Definition at line 139 of file bondindex.hpp.

fixingCalendar_

Calendar fixingCalendar_

protected

Definition at line 140 of file bondindex.hpp.

bond_

QuantLib::ext::shared_ptr<QuantLib::Bond> bond_

protected

Definition at line 141 of file bondindex.hpp.

discountCurve_

Handle<YieldTermStructure> discountCurve_

protected

Definition at line 142 of file bondindex.hpp.

defaultCurve_

Handle<DefaultProbabilityTermStructure> defaultCurve_

protected

Definition at line 143 of file bondindex.hpp.

recoveryRate_

Handle<Quote> recoveryRate_

protected

Definition at line 144 of file bondindex.hpp.

securitySpread_

Handle<Quote> securitySpread_

protected

Definition at line 145 of file bondindex.hpp.

incomeCurve_

Handle<YieldTermStructure> incomeCurve_

protected

Definition at line 146 of file bondindex.hpp.

conditionalOnSurvival_

bool conditionalOnSurvival_

protected

Definition at line 147 of file bondindex.hpp.

issueDate_

Date issueDate_

protected

Definition at line 148 of file bondindex.hpp.

priceQuoteMethod_

PriceQuoteMethod priceQuoteMethod_

protected

Definition at line 149 of file bondindex.hpp.

priceQuoteBaseValue_

double priceQuoteBaseValue_

protected

Definition at line 150 of file bondindex.hpp.

isInflationLinked_

bool isInflationLinked_

protected

Definition at line 151 of file bondindex.hpp.

bidAskAdjustment_

double bidAskAdjustment_

protected

Definition at line 152 of file bondindex.hpp.

vanillaBondEngine_

QuantLib::ext::shared_ptr<DiscountingRiskyBondEngine> vanillaBondEngine_

protected

Definition at line 153 of file bondindex.hpp.

bondIssueDateFallback_

bool bondIssueDateFallback_ = false

protected

Definition at line 154 of file bondindex.hpp.