inflationindex.hpp

Go to the documentation of this file.

/* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 
/*
 Copyright (C) 2007 Chris Kenyon
 Copyright (C) 2021 Ralf Konrad Eckel
 
 This file is part of QuantLib, a free-software/open-source library
 for financial quantitative analysts and developers - http://quantlib.org/
 
 QuantLib is free software: you can redistribute it and/or modify it
 under the terms of the QuantLib license.  You should have received a
 copy of the license along with this program; if not, please email
 <quantlib-dev@lists.sf.net>. The license is also available online at
 <http://quantlib.org/license.shtml>.
 
 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the license for more details.
*/
 
/*! \file inflationindex.hpp
    \brief base classes for inflation indexes
*/
 
#ifndef quantlib_inflation_index_hpp
#define quantlib_inflation_index_hpp
 
#include <ql/currency.hpp>
#include <ql/handle.hpp>
#include <ql/index.hpp>
#include <ql/indexes/region.hpp>
#include <ql/termstructures/inflationtermstructure.hpp>
 
namespace QuantLib {
 
    class ZeroInflationIndex;
    class YoYInflationIndex;
 
    struct CPI {
 
        //! when you observe an index, how do you interpolate between fixings?
        enum InterpolationType {
            AsIndex, //!< same interpolation as index
            Flat,    //!< flat from previous fixing
            Linear   //!< linearly between bracketing fixings
        };
 
        //! interpolated inflation fixing
        /*! \param index              The index whose fixing should be retrieved
            \param date               The date without lag; usually, the payment
                                      date for some inflation-based coupon.
            \param observationLag     The observation lag to be subtracted from the
                                      passed date; for instance, if the passed date is
                                      in May and the lag is three months, the inflation
                                      fixing from February (and March, in case of
                                      interpolation) will be observed.
            \param interpolationType  The interpolation type (flat or linear)
        */
        static Real laggedFixing(const ext::shared_ptr<ZeroInflationIndex>& index,
                                 const Date& date,
                                 const Period& observationLag,
                                 InterpolationType interpolationType);
 
 
        //! interpolated year-on-year inflation rate
        /*! \param index              The index whose fixing should be retrieved
            \param date               The date without lag; usually, the payment
                                      date for some inflation-based coupon.
            \param observationLag     The observation lag to be subtracted from the
                                      passed date; for instance, if the passed date is
                                      in May and the lag is three months, the year-on-year
                                      rate from February (and March, in case of
                                      interpolation) will be observed.
            \param interpolationType  The interpolation type (flat or linear)
        */
        static Real laggedYoYRate(const ext::shared_ptr<YoYInflationIndex>& index,
                                  const Date& date,
                                  const Period& observationLag,
                                  InterpolationType interpolationType);
    };
 
 
    //! Base class for inflation-rate indexes,
    class InflationIndex : public Index {
      public:
        InflationIndex(std::string familyName,
                       Region region,
                       bool revised,
                       Frequency frequency,
                       const Period& availabilitiyLag,
                       Currency currency);
 
        //! \name Index interface
        //@{
        std::string name() const override;
 
        /*! Inflation indices are not associated to a particular day,
            but to months or quarters.  Therefore, they do not have
            fixing calendars.  Since we're forced by the base `Index`
            interface to add one, this method returns a NullCalendar
            instance.
        */
        Calendar fixingCalendar() const override;
        bool isValidFixingDate(const Date&) const override { return true; }
 
        /*! Forecasting index values requires an inflation term
            structure, with a base date that is earlier than its asof
            date.  This must be so because indices are available only
            with a lag.  Usually, it makes sense for the base date to
            be the first day of the month of the last published
            fixing.
        */
        Real fixing(const Date& fixingDate, bool forecastTodaysFixing = false) const override = 0;
 
        //! returns a past fixing at the given date
        Real pastFixing(const Date& fixingDate) const override = 0;
 
        void addFixing(const Date& fixingDate, Rate fixing, bool forceOverwrite = false) override;
        //@}
 
        //! \name Inspectors
        //@{
        std::string familyName() const;
        Region region() const;
        bool revised() const;
        Frequency frequency() const;
        /*! The availability lag describes when the index might be
            available; for instance, the inflation value for January
            may only be available in April.  This doesn't mean that
            that inflation value is considered as the April fixing; it
            remains the January fixing, independently of the lag in
            availability.
        */
        Period availabilityLag() const;
        Currency currency() const;
        //@}
 
      protected:
        Date referenceDate_;
        std::string familyName_;
        Region region_;
        bool revised_;
        Frequency frequency_;
        Period availabilityLag_;
        Currency currency_;
 
      private:
        std::string name_;
    };
 
 
    //! Base class for zero inflation indices.
    class ZeroInflationIndex : public InflationIndex {
      public:
        ZeroInflationIndex(
            const std::string& familyName,
            const Region& region,
            bool revised,
            Frequency frequency,
            const Period& availabilityLag,
            const Currency& currency,
            Handle<ZeroInflationTermStructure> ts = {});
 
        //! \name Index interface
        //@{
        /*! \warning the forecastTodaysFixing parameter (required by
                     the Index interface) is currently ignored.
        */
        Real fixing(const Date& fixingDate, bool forecastTodaysFixing = false) const override;
        Real pastFixing(const Date& fixingDate) const override;
        //@}
        //! \name Other methods
        //@{
        Date lastFixingDate() const;
        Handle<ZeroInflationTermStructure> zeroInflationTermStructure() const;
        ext::shared_ptr<ZeroInflationIndex> clone(const Handle<ZeroInflationTermStructure>& h) const;
        bool needsForecast(const Date& fixingDate) const;
        //@}
      private:
        Real forecastFixing(const Date& fixingDate) const;
        Handle<ZeroInflationTermStructure> zeroInflation_;
    };
 
 
    //! Base class for year-on-year inflation indices.
    /*! These may be quoted indices published on, say, Bloomberg, or can be
        defined as the ratio of an index at different time points.
    */
    class YoYInflationIndex : public InflationIndex {
      public:
        //! \name Constructors
        //@{
        //! Constructor for year-on-year indices defined as a ratio.
        /*! An index build with this constructor won't store
            past fixings of its own; they will be calculated as a
            ratio from the past fixings stored in the underlying index.
        */
        explicit YoYInflationIndex(
            const ext::shared_ptr<ZeroInflationIndex>& underlyingIndex,
            Handle<YoYInflationTermStructure> ts = {});
 
        /*! \deprecated Use the similar overload without the interpolated parameter.
                        Deprecated in version 1.38.
        */
        [[deprecated("Use the similar overload without the interpolated parameter")]]
        YoYInflationIndex(
            const ext::shared_ptr<ZeroInflationIndex>& underlyingIndex,
            bool interpolated,
            Handle<YoYInflationTermStructure> ts = {});
 
        //! Constructor for quoted year-on-year indices.
        /*! An index built with this constructor needs its past
            fixings (i.e., the past year-on-year values) to be stored
            via the `addFixing` or `addFixings` method.
        */
        YoYInflationIndex(
            const std::string& familyName,
            const Region& region,
            bool revised,
            Frequency frequency,
            const Period& availabilityLag,
            const Currency& currency,
            Handle<YoYInflationTermStructure> ts = {});
 
        /*! \deprecated Use the similar overload without the interpolated parameter.
                        Deprecated in version 1.38.
        */
        [[deprecated("Use the similar overload without the interpolated parameter")]]
        YoYInflationIndex(
            const std::string& familyName,
            const Region& region,
            bool revised,
            bool interpolated,
            Frequency frequency,
            const Period& availabilityLag,
            const Currency& currency,
            Handle<YoYInflationTermStructure> ts = {});
        //@}
 
        //! \name Index interface
        //@{
        /*! \warning the forecastTodaysFixing parameter (required by
                     the Index interface) is currently ignored.
        */
        Rate fixing(const Date& fixingDate, bool forecastTodaysFixing = false) const override;
        Real pastFixing(const Date& fixingDate) const override;
        //@}
 
        //! \name Other methods
        //@{
        Date lastFixingDate() const;
        bool interpolated() const;
        bool ratio() const;
        ext::shared_ptr<ZeroInflationIndex> underlyingIndex() const;
        Handle<YoYInflationTermStructure> yoyInflationTermStructure() const;
 
        ext::shared_ptr<YoYInflationIndex> clone(const Handle<YoYInflationTermStructure>& h) const;
        bool needsForecast(const Date& fixingDate) const;
        //@}
 
      protected:
        bool interpolated_;
 
      private:
        Rate forecastFixing(const Date& fixingDate) const;
        bool ratio_;
        ext::shared_ptr<ZeroInflationIndex> underlyingIndex_;
        Handle<YoYInflationTermStructure> yoyInflation_;
    };
 
 
    namespace detail::CPI {
 
        // Returns either CPI::Flat or CPI::Linear depending on the combination of index and
        // CPI::InterpolationType.
        QuantLib::CPI::InterpolationType
        effectiveInterpolationType(const QuantLib::CPI::InterpolationType& type);
 
        QuantLib::CPI::InterpolationType
        effectiveInterpolationType(const QuantLib::CPI::InterpolationType& type,
                                   const ext::shared_ptr<YoYInflationIndex>& index);
 
        // checks whether the combination of index and CPI::InterpolationType results
        // effectively in CPI::Linear
        bool isInterpolated(const QuantLib::CPI::InterpolationType& type);
 
        bool isInterpolated(const QuantLib::CPI::InterpolationType& type,
                            const ext::shared_ptr<YoYInflationIndex>& index);
 
    }
 
 
    // inline
 
    inline std::string InflationIndex::name() const {
        return name_;
    }
 
    inline std::string InflationIndex::familyName() const {
        return familyName_;
    }
 
    inline Region InflationIndex::region() const {
        return region_;
    }
 
    inline bool InflationIndex::revised() const {
        return revised_;
    }
 
    inline Frequency InflationIndex::frequency() const {
        return frequency_;
    }
 
    inline Period InflationIndex::availabilityLag() const {
        return availabilityLag_;
    }
 
    inline Currency InflationIndex::currency() const {
        return currency_;
    }
 
    inline Handle<ZeroInflationTermStructure>
    ZeroInflationIndex::zeroInflationTermStructure() const {
        return zeroInflation_;
    }
 
    inline bool YoYInflationIndex::interpolated() const {
        return interpolated_;
    }
 
    inline bool YoYInflationIndex::ratio() const {
        return ratio_;
    }
 
    inline ext::shared_ptr<ZeroInflationIndex> YoYInflationIndex::underlyingIndex() const {
        return underlyingIndex_;
    }
 
    inline Handle<YoYInflationTermStructure>
    YoYInflationIndex::yoyInflationTermStructure() const {
        return yoyInflation_;
    }
 
}
 
#endif