CommodityBasisPriceCurve< Interpolator > Class Template Reference

Commodity basis price curve. More...

#include <qle/termstructures/commoditybasispricecurve.hpp>

Inheritance diagram for CommodityBasisPriceCurve< Interpolator >:

Collaboration diagram for CommodityBasisPriceCurve< Interpolator >:

Public Member Functions
Constructors
	CommodityBasisPriceCurve (const QuantLib::Date &referenceDate, const std::map< QuantLib::Date, QuantLib::Handle< QuantLib::Quote > > &basisData, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &basisFec, const QuantLib::ext::shared_ptr< CommodityIndex > &baseIndex, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &baseFec, bool addBasis=true, QuantLib::Size monthOffset=0, bool priceAsHistFixing=true, const Interpolator &interpolator=Interpolator())
	Curve constructed from dates and quotes. More...
Observer interface
void	update () override
LazyObject interface
void	performCalculations () const override
TermStructure interface
QuantLib::Date	maxDate () const override
QuantLib::Time	maxTime () const override
PriceTermStructure interface
QuantLib::Time	minTime () const override
	The minimum time for which the curve can return values. More...
std::vector< QuantLib::Date >	pillarDates () const override
	The pillar dates for the PriceTermStructure. More...
const QuantLib::Currency &	currency () const override
	The currency in which prices are expressed. More...
Inspectors
const std::vector< QuantLib::Time > &	times () const
const std::vector< QuantLib::Real > &	prices () const
Public Member Functions inherited from CommodityBasisPriceTermStructure
	CommodityBasisPriceTermStructure (const QuantLib::Date &referenceDate, const QuantLib::Calendar &cal, const QuantLib::DayCounter &dc, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &basisFec, const QuantLib::ext::shared_ptr< CommodityIndex > &baseIndex, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &baseFec, bool addBasis=true, QuantLib::Size monthOffset=0, bool averagingBaseCashflow=false, bool priceAsHistoricalFixing=true)
	CommodityBasisPriceTermStructure (const QuantLib::Date &referenceDate, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &basisFec, const QuantLib::ext::shared_ptr< CommodityIndex > &baseIndex, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &baseFec, bool addBasis=true, QuantLib::Size monthOffset=0, bool averagingBaseCashflow=false, bool priceAsHistoricalFixing=true)
const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &	basisFutureExpiryCalculator () const
	Inspectors. More...
const QuantLib::ext::shared_ptr< CommodityIndex > &	baseIndex () const
const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &	baseFutureExpiryCalculator () const
bool	addBasis () const
bool	averagingBaseCashflow () const
bool	priceAsHistoricalFixing () const
QuantLib::Size	monthOffset () const
Public Member Functions inherited from PriceTermStructure
	PriceTermStructure (const QuantLib::DayCounter &dc=QuantLib::DayCounter())
	PriceTermStructure (const QuantLib::Date &referenceDate, const QuantLib::Calendar &cal=QuantLib::Calendar(), const QuantLib::DayCounter &dc=QuantLib::DayCounter())
	PriceTermStructure (QuantLib::Natural settlementDays, const QuantLib::Calendar &cal, const QuantLib::DayCounter &dc=QuantLib::DayCounter())
QuantLib::Real	price (QuantLib::Time t, bool extrapolate=false) const
QuantLib::Real	price (const QuantLib::Date &d, bool extrapolate=false) const
void	update () override

PriceTermStructure implementation
std::map< QuantLib::Date, QuantLib::Handle< QuantLib::Quote > >	basisData_
std::vector< QuantLib::Date >	dates_
std::vector< Time >	basisTimes_
std::vector< Real >	basisValues_
Interpolation	basisInterpolation_
std::map< QuantLib::Date, QuantLib::ext::shared_ptr< CashFlow > >	baseLeg_
	The commodity cashflows will give the base curve prices. More...
std::map< QuantLib::Size, QuantLib::Size >	legIndexMap_
QuantLib::Real	priceImpl (QuantLib::Time t) const override
	Price calculation. More...

Additional Inherited Members
Protected Member Functions inherited from PriceTermStructure
void	checkRange (QuantLib::Time t, bool extrapolate) const
	Extra time range check for minimum time, then calls TermStructure::checkRange. More...
Protected Attributes inherited from CommodityBasisPriceTermStructure
QuantLib::ext::shared_ptr< FutureExpiryCalculator >	basisFec_
QuantLib::ext::shared_ptr< CommodityIndex >	baseIndex_
QuantLib::ext::shared_ptr< FutureExpiryCalculator >	baseFec_
bool	addBasis_
QuantLib::Size	monthOffset_
bool	averagingBaseCashflow_
bool	priceAsHistoricalFixing_

Detailed Description

template<class Interpolator>
class QuantExt::CommodityBasisPriceCurve< Interpolator >

Commodity basis price curve.

Class representing an outright commodity price curve created from a base price curve and a collection of basis quotes that are added to or subtracted from the base curve. This class is intended to be used only for commodity future basis price curves.

There is an assumption in the curve construction that the frequency of the base future contract is the same as the frequency of the basis future contract. In other words, if the base future contract is monthly then the basis future contract is monthly for example.

Definition at line 53 of file commoditybasispricecurve.hpp.

Constructor & Destructor Documentation

CommodityBasisPriceCurve()

CommodityBasisPriceCurve	(	const QuantLib::Date &	referenceDate,
		const std::map< QuantLib::Date, QuantLib::Handle< QuantLib::Quote > > &	basisData,
		const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &	basisFec,
		const QuantLib::ext::shared_ptr< CommodityIndex > &	baseIndex,
		const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &	baseFec,
		bool	addBasis = true,
		QuantLib::Size	monthOffset = 0,
		bool	priceAsHistFixing = true,
		const Interpolator &	interpolator = Interpolator()
	)

Curve constructed from dates and quotes.

Definition at line 125 of file commoditybasispricecurve.hpp.

    : CommodityBasisPriceTermStructure(referenceDate, basisFec, baseIndex, baseFec, addBasis, monthOffset, false,
                                       priceAsHistFixing),
      QuantLib::InterpolatedCurve<Interpolator>(interpolator), basisData_(basisData) {
    QL_REQUIRE(baseIndex != nullptr && !baseIndex->priceCurve().empty(),
               "CommodityBasisPriceCurve requires baseIndex with priceCurve");
    using QuantLib::Date;
    using QuantLib::Schedule;
    using QuantLib::io::iso_date;
    using QuantLib::io::ordinal;
    using std::distance;
    using std::find;
    using std::max;
    using std::min;
    using std::sort;
    using std::vector;
 
    // Observe the quotes
    for (auto it = basisData_.cbegin(); it != basisData_.cend();) {
        if (it->first < referenceDate) {
            // If the basis quote's date is before the reference date, remove it.
            basisData_.erase(it++);
        } else {
            // Otherwise, process the basis quote
            dates_.push_back(it->first);
            basisTimes_.push_back(timeFromReference(it->first));
            if (addBasis_)
                basisValues_.push_back(it->second->value());
            else
                basisValues_.push_back(-it->second->value());
            registerWith(it->second);
            ++it;
        }
    }
 
    // Set up the interpolation to be used on the basis
    basisInterpolation_ = interpolator.interpolate(basisTimes_.begin(), basisTimes_.end(), basisValues_.begin());
 
    // Initialise this curve's times with the basis pillars. We will add more pillars below.
    this->times_ = basisTimes_;
 
    // Get the first basis contract expiry date on or after the curve reference date.
    Date basisExpiry = basisFec_->nextExpiry(true, referenceDate);
 
    // Get the first basis contract expiry date on or after the max date. Here, max date is defined as the maximum of
    // 1) last pillar date of base price curve and 2) basis curve data.
    Date maxDate = max(baseIndex_->priceCurve()->maxDate(), basisData_.rbegin()->first);
    Date end = basisFec_->nextExpiry(true, maxDate);
 
    // Populate the base cashflows.
    while (basisExpiry <= end) {
        Date basisContractDate = basisFec_->contractDate(basisExpiry);
        basisContractDate = Date(1, basisContractDate.month(), basisContractDate.year()) - monthOffset_ * Months;
        Date periodStart = basisContractDate - monthOffset_ * Months;
        Date periodEnd = (periodStart + 1 * Months) - 1 * Days;
        baseLeg_[basisExpiry] = makeCommodityCashflowForBasisFuture(
            periodStart, periodEnd, baseIndex_, baseFec_, averagingBaseCashflow_);
 
        // Only add to this->times_ if it is not already there. We can use dates_ for this check.
        if (find(dates_.begin(), dates_.end(), basisExpiry) == dates_.end()) {
            this->times_.push_back(timeFromReference(basisExpiry));
            dates_.push_back(basisExpiry);
        }
 
        basisExpiry = basisFec_->nextExpiry(true, basisExpiry + 1 * Days);
    }
 
    // Sort the times and dates vector and ensure no duplicates in the times vector.
    sort(this->times_.begin(), this->times_.end());
    sort(dates_.begin(), dates_.end());
    auto it = unique(this->times_.begin(), this->times_.end(), [](double s, double t) { return close(s, t); });
    QL_REQUIRE(it == this->times_.end(), "Unexpected duplicate time, " << *it << ", in the times vector.");
    this->data_.resize(this->times_.size());
 
    // Set up the underlying interpolation on times_ and data_
    QuantLib::InterpolatedCurve<Interpolator>::setupInterpolation();
}

Here is the call graph for this function:

Member Function Documentation

update()

void update

override

Definition at line 207 of file commoditybasispricecurve.hpp.

{ QuantLib::LazyObject::update(); }

performCalculations()

void performCalculations

override

Definition at line 209 of file commoditybasispricecurve.hpp.

                                                                                                     {
 
    // Update the basis interpolation object
    Size basisIdx = 0;
    for (const auto& kv : basisData_) {
        basisValues_[basisIdx] = addBasis_ ? kv.second->value() : -kv.second->value();
        basisIdx++;
    }
    basisInterpolation_.update();
 
    // Update this curve's interpolation
    for (Size i = 0; i < this->times_.size(); i++) {
 
        Real baseValue = 0.0;
        auto it = baseLeg_.find(dates_[i]);
        if (it != baseLeg_.end()) {
            // If we have associated the basis date with a base cashflow.
            baseValue = it->second->amount();
        } else {
            // If we didn't associate the basis date with a base cashflow, just ask the base pts at t. This will have
            // happened if the basis date that was passed in was not a basis contract expiry date wrt basisFec_.
            baseValue = baseIndex_->priceCurve()->price(this->times_[i], true);
        }
 
        // Get the basis with flat extrapolation
        Real basis = 0.0;
        if (this->times_[i] < basisTimes_.front()) {
            basis = basisValues_.front();
        } else if (this->times_[i] > basisTimes_.back()) {
            basis = basisValues_.back();
        } else {
            basis = basisInterpolation_(this->times_[i], true);
        }
 
        // Update the outright value
        this->data_[i] = baseValue + basis;
    }
    this->interpolation_.update();
}

maxDate()

QuantLib::Date maxDate

override

Definition at line 249 of file commoditybasispricecurve.hpp.

                                                                                                 {
    return dates_.back();
}

Here is the caller graph for this function:

maxTime()

QuantLib::Time maxTime

override

Definition at line 253 of file commoditybasispricecurve.hpp.

                                                                                                 {
    return this->times_.back();
}

minTime()

QuantLib::Time minTime

overridevirtual

The minimum time for which the curve can return values.

Reimplemented from PriceTermStructure.

Definition at line 257 of file commoditybasispricecurve.hpp.

                                                                                                 {
    return this->times_.front();
}

pillarDates()

std::vector< QuantLib::Date > pillarDates ( ) const

overridevirtual

The pillar dates for the PriceTermStructure.

Implements PriceTermStructure.

Definition at line 261 of file commoditybasispricecurve.hpp.

                                                                                                                {
    return dates_;
}

currency()

const QuantLib::Currency & currency ( ) const

overridevirtual

The currency in which prices are expressed.

Implements PriceTermStructure.

Definition at line 89 of file commoditybasispricecurve.hpp.

{ return baseIndex_->priceCurve()->currency(); }

times()

const std::vector< QuantLib::Time > & times

(

)

const

Definition at line 94 of file commoditybasispricecurve.hpp.

{ return this->times_; }

prices()

const std::vector< QuantLib::Real > & prices

(

)

const

Definition at line 95 of file commoditybasispricecurve.hpp.

{ return this->data_; }

priceImpl()

QuantLib::Real priceImpl ( QuantLib::Time  ) const

overrideprotectedvirtual

Price calculation.

Implements PriceTermStructure.

Definition at line 265 of file commoditybasispricecurve.hpp.

                                                                                                                 {
    calculate();
    return this->interpolation_(t, true);
}

Member Data Documentation

basisData_

std::map<QuantLib::Date, QuantLib::Handle<QuantLib::Quote> > basisData_

private

Definition at line 105 of file commoditybasispricecurve.hpp.

dates_

std::vector<QuantLib::Date> dates_

private

Definition at line 106 of file commoditybasispricecurve.hpp.

basisTimes_

std::vector<Time> basisTimes_

mutableprivate

Interpolator used for interpolating the basis if needed. Basis interpolation uses the same interpolator as the curve itself. A second template parameter could be added for this in future if it needs to be relaxed.

Definition at line 111 of file commoditybasispricecurve.hpp.

basisValues_

std::vector<Real> basisValues_

mutableprivate

Definition at line 112 of file commoditybasispricecurve.hpp.

basisInterpolation_

Interpolation basisInterpolation_

mutableprivate

Definition at line 113 of file commoditybasispricecurve.hpp.

baseLeg_

std::map<QuantLib::Date, QuantLib::ext::shared_ptr<CashFlow> > baseLeg_

private

The commodity cashflows will give the base curve prices.

Definition at line 116 of file commoditybasispricecurve.hpp.

legIndexMap_

std::map<QuantLib::Size, QuantLib::Size> legIndexMap_

private

Map where the key is the index of a time in the times_ vector and the value is the index of the cashflow in the baseLeg_ to associate with that time.

Definition at line 121 of file commoditybasispricecurve.hpp.