BucketedDistribution Class Reference

Represents a bucketed probability distibution. More...

#include <qle/math/bucketeddistribution.hpp>

Collaboration diagram for BucketedDistribution:

Public Member Functions
	BucketedDistribution ()
	Default constructor. More...
	BucketedDistribution (QuantLib::Real min, QuantLib::Real max, QuantLib::Size numberBuckets)
	Build a default initial distribution from min and max and numberBuckets. More...
	BucketedDistribution (QuantLib::Real min, QuantLib::Real max, QuantLib::Size numberBuckets, QuantLib::Real initialValue)
	BucketedDistribution (const std::vector< QuantLib::Real > &buckets, const std::vector< QuantLib::Real > &initialProbabilities, const std::vector< QuantLib::Real > &initialPoints)
	Explicitly specify the initial distribution. More...
	BucketedDistribution (const BucketedDistribution &other)
	Copy constructor. More...
void	add (const DiscreteDistribution &distribution)
	Update the bucketed distribution by adding a discrete distribution. More...
const std::vector< QuantLib::Real > &	buckets () const
	Return the buckets of the distribution. More...
const std::vector< QuantLib::Real > &	probabilities () const
	Get the probabilities. More...
std::vector< QuantLib::Real > &	probabilities ()
	Set the probabilities. More...
const std::vector< QuantLib::Real > &	points () const
	Return the points of the distribution. More...
Size	numberBuckets () const
	Return the number of buckets in the distribution. More...
std::vector< QuantLib::Real >	cumulativeProbabilities () const
	Return the cumulative probabilities of the distribution. More...
std::vector< QuantLib::Real >	complementaryProbabilities () const
	Return 1.0 minus the cumulative probabilities of the distribution. More...
void	applyShift (QuantLib::Real shift)
	Shift all buckets and points by an additive shift. More...
void	applyFactor (QuantLib::Real factor)
	Shift all buckets and points by a multiplicative factor. More...
Real	cumulativeProbability (QuantLib::Real x) const
	Return cumulative probability at point x using linear interpolation. More...
Real	inverseCumulativeProbability (QuantLib::Real p) const
	Return inverse cumulative probability given a probability p using linear interpolation. More...
BucketedDistribution &	operator+= (const BucketedDistribution &other)
	Utility functions. More...
DiscreteDistribution	createDiscrete () const
	Create a DiscreteDistribution from a BucketedDistribution with discrete points at midpoints of the buckets. More...
void	erase (QuantLib::Size n)
	Erase the first n buckets from the distribution. More...
QuantLib::Size	bucket (QuantLib::Real value) const
	Returns the index of the bucket containing value. More...

Private Member Functions
void	init (QuantLib::Real min, QuantLib::Real max, QuantLib::Size numberBuckets)
	Common code used in the constructor. More...

Private Attributes
std::vector< QuantLib::Real >	buckets_
	Vector of numbers denoting buckets of distribution. More...
std::vector< QuantLib::Real >	probabilities_
	Vector of numbers denoting probabilities in each bucket. More...
std::vector< QuantLib::Real >	points_
std::vector< QuantLib::Real >	previousProbabilities_
std::vector< QuantLib::Real >	previousPoints_

Static Private Attributes
static const QuantLib::Real	minProbability_ = 0.00000001

Detailed Description

Represents a bucketed probability distibution.

Definition at line 35 of file bucketeddistribution.hpp.

Constructor & Destructor Documentation

BucketedDistribution() [1/5]

BucketedDistribution

(

)

Default constructor.

Definition at line 38 of file bucketeddistribution.hpp.

{}

BucketedDistribution() [2/5]

BucketedDistribution	(	QuantLib::Real	min,
		QuantLib::Real	max,
		QuantLib::Size	numberBuckets
	)

Build a default initial distribution from min and max and numberBuckets.

BucketedDistribution() [3/5]

BucketedDistribution	(	QuantLib::Real	min,
		QuantLib::Real	max,
		QuantLib::Size	numberBuckets,
		QuantLib::Real	initialValue
	)

Build a default initial distribution from min and max and numberBuckets and set all probabilities to initialValue

BucketedDistribution() [4/5]

BucketedDistribution	(	const std::vector< QuantLib::Real > &	buckets,
		const std::vector< QuantLib::Real > &	initialProbabilities,
		const std::vector< QuantLib::Real > &	initialPoints
	)

Explicitly specify the initial distribution.

BucketedDistribution() [5/5]

BucketedDistribution

(

const BucketedDistribution &

other

)

Copy constructor.

Definition at line 71 of file bucketeddistribution.cpp.

    : buckets_(other.buckets_), probabilities_(other.probabilities_), points_(other.points_),
      previousProbabilities_(other.previousProbabilities_), previousPoints_(other.previousPoints_) {}

Member Function Documentation

add()

void add

(

const DiscreteDistribution &

distribution

)

Update the bucketed distribution by adding a discrete distribution.

Definition at line 77 of file bucketeddistribution.cpp.

                                                                       {
 
    // Update the distribution with the values provided
    previousProbabilities_ = probabilities_;
    previousPoints_ = points_;
    vector<Real> tempPoints(points_.size(), 0.0);
    vector<Real> tempProbabilities = previousProbabilities_;
    vector<bool> bucketsChanged(points_.size(), false);
 
    for (Size i = 0; i < buckets_.size() - 1; i++) {
        // Skip buckets that have no probability of being occupied
        if (previousProbabilities_[i] >= minProbability_) {
            // Update buckets reachable from ith bucket
            for (Size j = 0; j < distribution.size(); j++) {
                Distributionpair pair = distribution.get(j);
                Real transitionPoint = previousPoints_[i] + pair.x_;
                Real transitionProbability = previousProbabilities_[i] * pair.y_;
 
                // Find in which bucket transitionPoint lies
                QL_REQUIRE(buckets_[0] <= transitionPoint && transitionPoint <= buckets_.back(),
                           "Value, " << transitionPoint << ", is out of range of buckets: (" << buckets_[0] << ", "
                                     << buckets_.back() << ")");
 
                // Either transition to a higher bucket or stay in the same bucket
                if (transitionPoint >= buckets_[i + 1]) {
                    Size bucketIndex = 0;
                    vector<Real>::const_iterator it =
                        upper_bound(buckets_.begin() + i + 1, buckets_.end(), transitionPoint);
                    if (it == buckets_.end()) {
                        // If here, must be equal to upper end of last bucket
                        bucketIndex = buckets_.size() - 2;
                    } else {
                        bucketIndex = it - buckets_.begin() - 1;
                    }
 
                    // Update probability if moved to different bucket
                    probabilities_[i] -= transitionProbability;
                    probabilities_[bucketIndex] += transitionProbability;
                    // Update temp points (divide again in separate loop below)
                    tempPoints[bucketIndex] += transitionPoint * transitionProbability;
                    tempProbabilities[bucketIndex] += transitionProbability;
                    bucketsChanged[bucketIndex] = true;
                } else {
                    // If bucket does not change, do not update probability but shift
                    // the conditional expectation i.e. point in bucket
                    points_[i] += pair.x_ * pair.y_;
                }
            }
        }
    }
 
    // If the probability of being in bucket is non-zero and the bucket has been hit by
    // the addition of the distribution above, update the conditional expectation (i.e. points_)
    for (Size i = 0; i < buckets_.size() - 1; i++) {
        if (tempProbabilities[i] > minProbability_ && bucketsChanged[i]) {
            points_[i] = (previousProbabilities_[i] * points_[i] + tempPoints[i]) / tempProbabilities[i];
        }
    }
}

Here is the call graph for this function:

buckets()

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

(

)

const

Return the buckets of the distribution.

Definition at line 55 of file bucketeddistribution.hpp.

{ return buckets_; }

Here is the caller graph for this function:

probabilities() [1/2]

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

(

)

const

Get the probabilities.

Definition at line 57 of file bucketeddistribution.hpp.

{ return probabilities_; }

Here is the caller graph for this function:

probabilities() [2/2]

std::vector< QuantLib::Real > & probabilities

(

)

Set the probabilities.

Definition at line 59 of file bucketeddistribution.hpp.

{ return probabilities_; }

points()

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

(

)

const

Return the points of the distribution.

Definition at line 61 of file bucketeddistribution.hpp.

{ return points_; }

Here is the caller graph for this function:

numberBuckets()

Size numberBuckets

(

)

const

Return the number of buckets in the distribution.

Definition at line 63 of file bucketeddistribution.hpp.

{ return buckets_.size() - 1; }

Here is the caller graph for this function:

cumulativeProbabilities()

vector< Real > cumulativeProbabilities

(

)

const

Return the cumulative probabilities of the distribution.

Definition at line 167 of file bucketeddistribution.cpp.

                                                                 {
    vector<Real> cumulativeProbabilities(buckets_.size(), 0.0);
    cumulativeProbabilities[0] = 0.0;
    // Calculate running sum i.e. probability that <= endpoint of each bucket
    transform(probabilities_.begin(), probabilities_.end(), cumulativeProbabilities.begin(),
              cumulativeProbabilities.begin() + 1, plus<Real>());
    return cumulativeProbabilities;
}

Here is the call graph for this function:

Here is the caller graph for this function:

complementaryProbabilities()

vector< Real > complementaryProbabilities

(

)

const

Return 1.0 minus the cumulative probabilities of the distribution.

Definition at line 176 of file bucketeddistribution.cpp.

                                                                    {
    vector<Real> probabilities = cumulativeProbabilities();
    // transform(probabilities.begin(), probabilities.end(), probabilities.begin(), std::bind1st(minus<Real>(), 1.0));
    transform(probabilities.begin(), probabilities.end(), probabilities.begin(), [](const Real x) { return x - 1.0; });
    return probabilities;
}

Here is the call graph for this function:

applyShift()

void applyShift

(

QuantLib::Real

shift

)

Shift all buckets and points by an additive shift.

Definition at line 183 of file bucketeddistribution.cpp.

                                                {
    // transform(buckets_.begin(), buckets_.end(), buckets_.begin(), std::bind1st(plus<Real>(), shift));
    transform(buckets_.begin(), buckets_.end(), buckets_.begin(), [shift](const Real x) { return x + shift; });
    // transform(points_.begin(), points_.end(), points_.begin(), std::bind1st(plus<Real>(), shift));
    transform(points_.begin(), points_.end(), points_.begin(), [shift](const Real x) { return x + shift; });
    // transform(previousPoints_.begin(), previousPoints_.end(), previousPoints_.begin(), std::bind1st(plus<Real>(),
    // shift));
    transform(previousPoints_.begin(), previousPoints_.end(), previousPoints_.begin(),
              [shift](const Real x) { return x + shift; });
}

applyFactor()

void applyFactor

(

QuantLib::Real

factor

)

Shift all buckets and points by a multiplicative factor.

Definition at line 194 of file bucketeddistribution.cpp.

                                                  {
    // If factor is negative, reverse everything before scaling so buckets are still ascending
    if (factor < 0.0) {
        reverse(buckets_.begin(), buckets_.end());
        reverse(points_.begin(), points_.end());
        reverse(previousPoints_.begin(), previousPoints_.end());
        reverse(probabilities_.begin(), probabilities_.end());
        reverse(previousProbabilities_.begin(), previousProbabilities_.end());
    }
    // transform(buckets_.begin(), buckets_.end(), buckets_.begin(), std::bind1st(multiplies<Real>(), factor));
    transform(buckets_.begin(), buckets_.end(), buckets_.begin(), [factor](const Real x) { return x * factor; });
    // transform(points_.begin(), points_.end(), points_.begin(), std::bind1st(multiplies<Real>(), factor));
    transform(points_.begin(), points_.end(), points_.begin(), [factor](const Real x) { return x * factor; });
    // transform(previousPoints_.begin(), previousPoints_.end(), previousPoints_.begin(),
    // std::bind1st(multiplies<Real>(), factor));
    transform(previousPoints_.begin(), previousPoints_.end(), previousPoints_.begin(),
              [factor](const Real x) { return x * factor; });
}

cumulativeProbability()

Real cumulativeProbability

(

QuantLib::Real

x

)

const

Return cumulative probability at point x using linear interpolation.

Definition at line 213 of file bucketeddistribution.cpp.

                                                             {
    vector<Real> probabilities = cumulativeProbabilities();
    vector<Real>::const_iterator it = lower_bound(buckets_.begin(), buckets_.end(), x);
    // If x > upper end of last bucket
    if (it == buckets_.end())
        return 1.0;
    // If x <= lower end of first bucket
    if (it == buckets_.begin())
        return 0.0;
    // If x is in range of buckets
    Size index = it - buckets_.begin();
    return probabilities[index - 1] + (x - buckets_[index - 1]) * (probabilities[index] - probabilities[index - 1]) /
                                          (buckets_[index] - buckets_[index - 1]);
}

Here is the call graph for this function:

inverseCumulativeProbability()

Real inverseCumulativeProbability

(

QuantLib::Real

p

)

const

Return inverse cumulative probability given a probability p using linear interpolation.

Definition at line 228 of file bucketeddistribution.cpp.

                                                                    {
    QL_REQUIRE(0 <= p && p <= 1.0, "Probability must be between 0 and 1");
    vector<Real> probabilities = cumulativeProbabilities();
    vector<Real>::const_iterator it = lower_bound(probabilities.begin(), probabilities.end(), p);
    // If p > last cumulative probability (shouldn't happen since p <= 1.0)
    if (it == probabilities.end())
        return buckets_.back();
    // If p <= first cumulative probability (shouldn't happen since p >= 0.0)
    if (it == probabilities.begin())
        return buckets_.front();
    // If p is in the range of probabilities
    Size index = it - probabilities.begin();
    return buckets_[index - 1] + (p - probabilities[index - 1]) * (buckets_[index] - buckets_[index - 1]) /
                                     (probabilities[index] - probabilities[index - 1]);
}

Here is the call graph for this function:

operator+=()

BucketedDistribution & operator+=

(

const BucketedDistribution &

other

)

Utility functions.

Definition at line 244 of file bucketeddistribution.cpp.

                                                                                        {
 
    QL_REQUIRE(buckets_.size() - 1 == other.numberBuckets(), "Distributions must have same number of buckets to sum");
 
    bool bucketsEqual = equal(buckets_.begin(), buckets_.end(), other.buckets().begin(),
                              static_cast<bool (*)(Real, Real)>(&close_enough));
    QL_REQUIRE(bucketsEqual, "Distributions must have the same buckets to sum");
 
    transform(probabilities_.begin(), probabilities_.end(), other.probabilities().begin(), probabilities_.begin(),
              plus<Real>());
 
    return *this;
}

Here is the call graph for this function:

createDiscrete()

DiscreteDistribution createDiscrete

(

)

const

Create a DiscreteDistribution from a BucketedDistribution with discrete points at midpoints of the buckets.

Definition at line 258 of file bucketeddistribution.cpp.

                                                                {
    // Create a vector containing midpoint of each bucket
    vector<Real> midpoints(probabilities_.size(), 0.0);
    transform(buckets_.begin(), buckets_.end() - 1, buckets_.begin() + 1, midpoints.begin(), plus<Real>());
    // transform(midpoints.begin(), midpoints.end(), midpoints.begin(), std::bind2nd(divides<Real>(), 2.0));
    transform(midpoints.begin(), midpoints.end(), midpoints.begin(),
              [](const Real x) { return x / 2.0; }); // IS THIS CORRECT?!?
 
    return DiscreteDistribution(midpoints, probabilities_);
}

erase()

void erase

(

QuantLib::Size

n

)

Erase the first n buckets from the distribution.

Warning:

This may invalidate the distribution if the buckets erased do not have negligible probability.

Definition at line 269 of file bucketeddistribution.cpp.

                                       {
    QL_REQUIRE(n < numberBuckets(), "There are not enough buckets to erase");
    buckets_.erase(buckets_.begin(), buckets_.begin() + n);
    probabilities_.erase(probabilities_.begin(), probabilities_.begin() + n);
    points_.erase(points_.begin(), points_.begin() + n);
    previousProbabilities_.erase(previousProbabilities_.begin(), previousProbabilities_.begin() + n);
    previousPoints_.erase(previousPoints_.begin(), previousPoints_.begin() + n);
}

Here is the call graph for this function:

bucket()

Size bucket

(

QuantLib::Real

value

)

const

Returns the index of the bucket containing value.

Definition at line 137 of file bucketeddistribution.cpp.

                                                  {
 
    QL_REQUIRE(buckets_[0] <= value && value <= buckets_.back(), "Value, " << value << ", is out of range of buckets: ("
                                                                           << buckets_[0] << ", " << buckets_.back()
                                                                           << ")");
 
    vector<Real>::const_iterator it = upper_bound(buckets_.begin(), buckets_.end(), value);
    if (it == buckets_.end()) {
        // If here, must be equal to upper end of last bucket
        return buckets_.size() - 2;
    }
    return it - buckets_.begin() - 1;
}

init()

void init ( QuantLib::Real  min, QuantLib::Real  max, QuantLib::Size  numberBuckets  )

private

Common code used in the constructor.

Definition at line 151 of file bucketeddistribution.cpp.

                                                                      {
    // Initial checks
    QL_REQUIRE(buckets_.size() >= 3, "There should be at least two buckets for the distribution");
    QL_REQUIRE(max > min, "Max should be strictly greater than min");
 
    // Divide [min, max] into equally sized buckets
    Real bucketSize = (max - min) / numberBuckets;
    for (Size i = 0; i < buckets_.size(); ++i) {
        buckets_[i] = min + i * bucketSize;
    }
 
    // Initially set points to lower end of buckets
    copy(buckets_.begin(), buckets_.end() - 1, points_.begin());
    previousPoints_ = points_;
}

Here is the call graph for this function:

Member Data Documentation

buckets_

std::vector<QuantLib::Real> buckets_

private

Vector of numbers denoting buckets of distribution.

Definition at line 91 of file bucketeddistribution.hpp.

probabilities_

std::vector<QuantLib::Real> probabilities_

private

Vector of numbers denoting probabilities in each bucket.

Definition at line 93 of file bucketeddistribution.hpp.

points_

std::vector<QuantLib::Real> points_

private

Definition at line 94 of file bucketeddistribution.hpp.

previousProbabilities_

std::vector<QuantLib::Real> previousProbabilities_

private

Definition at line 95 of file bucketeddistribution.hpp.

previousPoints_

std::vector<QuantLib::Real> previousPoints_

private

Definition at line 96 of file bucketeddistribution.hpp.

minProbability_

const Real minProbability_ = 0.00000001

staticprivate

Definition at line 99 of file bucketeddistribution.hpp.