CommodityAverageBasisPriceCurve< Interpolator > Class Template Reference

Commodity average basis price curve. More...

#include <qle/termstructures/commodityaveragebasispricecurve.hpp>

Inheritance diagram for CommodityAverageBasisPriceCurve< Interpolator >:

Collaboration diagram for CommodityAverageBasisPriceCurve< Interpolator >:

Public Member Functions
Constructors
	CommodityAverageBasisPriceCurve (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 > &index, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &baseFec, bool addBasis=true, 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_
QuantLib::Leg	baseLeg_
	The averaging 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::CommodityAverageBasisPriceCurve< Interpolator >

Commodity average 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. The base curve is averaged over the period defined the basis quote.

Definition at line 47 of file commodityaveragebasispricecurve.hpp.

Constructor & Destructor Documentation

CommodityAverageBasisPriceCurve()

CommodityAverageBasisPriceCurve	(	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 > &	index,
		const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &	baseFec,
		bool	addBasis = true,
		bool	priceAsHistFixing = true,
		const Interpolator &	interpolator = Interpolator()
	)

Curve constructed from dates and quotes.

Definition at line 119 of file commodityaveragebasispricecurve.hpp.

    : CommodityBasisPriceTermStructure(referenceDate, basisFec, index, baseFec, addBasis, 0, true, priceAsHistFixing),
      QuantLib::InterpolatedCurve<Interpolator>(interpolator), basisData_(basisData) {
    QL_REQUIRE(baseIndex_ != nullptr && !baseIndex_->priceCurve().empty(),
               "CommodityAverageBasisPriceCurve 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::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 strictly prior to the curve reference date.
    Date start = basisFec_->priorExpiry(false, 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);
 
    // Create the leg schedule using a vector of dates which are the successive basis contract expiry dates
    QL_REQUIRE(start < end, "Expected that the start date, " << io::iso_date(start)
                                                             << ", would be strictly less than the end date, "
                                                             << io::iso_date(end) << ".");
    vector<Date> expiries{ start + 1 * Days };
    vector<Time> scheduleTimes;
    while (start < end) {
        start = basisFec_->nextExpiry(true, start + 1 * Days);
        expiries.push_back(start);
        Time t = timeFromReference(start);
        // Only add to this->times_ if it is not already there. We can use dates_ for this check.
        if (find(dates_.begin(), dates_.end(), start) == dates_.end()) {
            this->times_.push_back(t);
            dates_.push_back(start);
        }
        scheduleTimes.push_back(t);
    }
    QL_REQUIRE(start == end, "Expected that the start date, " << io::iso_date(start) << ", to equal the end date, "
                                                              << io::iso_date(end)
                                                              << ", after creating the sequence of expiry dates.");
 
    // 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());
 
    // Populate the leg of cashflows.
    baseLeg_ = CommodityIndexedAverageLeg(Schedule(expiries), baseIndex_)
                   .withFutureExpiryCalculator(baseFec_)
                   .useFuturePrice(true)
                   .withQuantities(1.0);
    QL_REQUIRE(baseLeg_.size() == scheduleTimes.size(), "Unexpected number of averaging cashflows in the leg: "
                                                            << "got " << baseLeg_.size() << " but expected "
                                                            << scheduleTimes.size());
 
    // Populate the legIndexMap_
    for (Size i = 0; i < this->times_.size(); i++) {
        for (Size j = 0; j < scheduleTimes.size(); j++) {
 
            if (this->times_[i] < scheduleTimes[j] || close(this->times_[i], scheduleTimes[j])) {
                QL_REQUIRE(legIndexMap_.find(i) == legIndexMap_.end(),
                           "Should not already have a mapping for the " << ordinal(i) << " time.");
                legIndexMap_[i] = j;
                break;
            }
 
            if (j == scheduleTimes.size()) {
                QL_FAIL("Could not map the " << ordinal(i) << " time, " << this->times_[i] << ", to a cashflow.");
            }
        }
    }
 
    // 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 228 of file commodityaveragebasispricecurve.hpp.

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

performCalculations()

void performCalculations

override

Definition at line 232 of file commodityaveragebasispricecurve.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 = baseLeg_[legIndexMap_.at(i)]->amount();
 
        // 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 263 of file commodityaveragebasispricecurve.hpp.

                                                                                                        {
    return dates_.back();
}

Here is the caller graph for this function:

maxTime()

QuantLib::Time maxTime

override

Definition at line 267 of file commodityaveragebasispricecurve.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 271 of file commodityaveragebasispricecurve.hpp.

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

pillarDates()

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

overridevirtual

The pillar dates for the PriceTermStructure.

Implements PriceTermStructure.

Definition at line 276 of file commodityaveragebasispricecurve.hpp.

                                                                                         {
    return dates_;
}

currency()

const QuantLib::Currency & currency ( ) const

overridevirtual

The currency in which prices are expressed.

Implements PriceTermStructure.

Definition at line 82 of file commodityaveragebasispricecurve.hpp.

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

times()

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

(

)

const

Definition at line 87 of file commodityaveragebasispricecurve.hpp.

{ return this->times_; }

prices()

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

(

)

const

Definition at line 88 of file commodityaveragebasispricecurve.hpp.

{ return this->data_; }

priceImpl()

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

overrideprotectedvirtual

Price calculation.

Implements PriceTermStructure.

Definition at line 281 of file commodityaveragebasispricecurve.hpp.

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

Member Data Documentation

basisData_

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

private

Definition at line 98 of file commodityaveragebasispricecurve.hpp.

dates_

std::vector<QuantLib::Date> dates_

private

Definition at line 100 of file commodityaveragebasispricecurve.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 105 of file commodityaveragebasispricecurve.hpp.

basisValues_

std::vector<Real> basisValues_

mutableprivate

Definition at line 106 of file commodityaveragebasispricecurve.hpp.

basisInterpolation_

Interpolation basisInterpolation_

mutableprivate

Definition at line 107 of file commodityaveragebasispricecurve.hpp.

baseLeg_

QuantLib::Leg baseLeg_

private

The averaging cashflows will give the base curve prices.

Definition at line 110 of file commodityaveragebasispricecurve.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 115 of file commodityaveragebasispricecurve.hpp.