com.webcab.ejb.finance.bonds
Interface DurationConvexity

All Superinterfaces:

EJBObject, Remote

public interface DurationConvexity

extends EJBObject

Within this Enterprise JavaBean we provide methods for the evaluation and application of the duration and convexity of a bond. The duration can be thought of the weighted average of the times when payments are made. The convexity is the rate of change with which the duration changes with respect to the underlying price.

The notion of duration pays an important role in the hedging and risk analysis of interest bearing investments. These methods are widely applicable but have the drawback that they assume that the interest rate curve which the asset under consideration depends on may only undergo small parallel shifts. In such an instance the duration pays such an important role because the change in a bonds price will be equal to the duration multiplied by the size of the parallel shift in the yield curve.

The notion of convexity allows us to refine "duration" based methods. In particular, the convexity can be viewed as being the coefficient of the second term within the Taylor expansion of the function which expresses the percentage change in the bonds price with respect to the yield. Hence, whereas the duration measures the linear component of the interest rate risk the convexity measures the two term in the Taylor expansion which is the first non-linear component of the interest rate risk. Therefore, convexity allows us to hedge the most significant component of the nonlinear components of a bonds risk.

Method Summary

double	bondPriceChange(double duration, double convexity, double yieldChange) Estimates the percentage change of the bond portfolio's value for a given (absolute) change of the yield.
double	convexity(double yield, double[] coupons, Date evaluationDate, Date[] dateOfCoupons, double principleSum, Date maturityDate, BusinessCalendar businessCalendar) Evaluates the convexity of a bond.
double	convexity(double yield, double[] coupons, double[] time2Coupons, double principleSum, double maturity) Evaluates the convexity of a bond.
double	duration(double yield, double[] payments, Date evaluationDate, Date[] paymentDates, double principleSum, Date maturityDate, BusinessCalendar businessCalendar) Evaluates the duration of a bond with a continuous interest yield where the cash flows (or payments) made in terms of amount and time of payment are known.
double	duration(double yield, double[] payments, double[] time2Payments, double principleSum, double maturity) Evaluates the duration of a bond with a continuous interest yield where the cash flows (or payments) made in terms of amount and time of payment are known.
double	durationHedgeRatio(double futuresPrice, double duration, double forwardValue, double durationPort) Evaluates the duration-hedge ratio of an interest rate dependent asset such as a bond portfolio or a money market security.
double	durationOfPortfolio(double[] duration, double[] weightOfBond) Returns the duration of a portfolio of bonds when the duration and weight of each bond within the portfolio is known.
double	durationOfPortfolioValue(double[] duration, double[] valueOfBond) Returns the duration (in monetary terms) of a bond portfolio when the duration and value of each bond within the portfolio is known.
double	percentagePriceChange(double deltaYield, double duration) Returns the percentage change of the bonds price by a small parallel shift of the interest rate curve which the bonds depends on.
double	percentagePriceChange(double deltaYield, double[] duration, double[] valueOfBond) Return the percentage change in a bond portfolio's value for a small parallel shift of all the interest rate curves which the bonds within the portfolio depend on.
double	percentagePriceChange(double duration, double annualYield, double deltaYield) Evaluates the percentage price change in a bond portfolio's value when the (annual) interest rates (expressed in decimal format) experience a small parallel shift.
double	percentagePriceChange(double duration, double yield, int periodsCompoundedOver, double deltaYield) Evaluates the percentage change in a bond portfolios value when interest rates experience a small parallel shift.
double	priceOfBond(double yield, double[] coupons, Date evaluationDate, Date[] dateOfCoupons, double principleSum, Date maturityDate, BusinessCalendar businessCalendar) This method evaluates the price of a bond via the relationship between its yield and cash flows.
double	priceOfBond(double yield, double[] coupons, double[] time2Coupons, double principleSum, double maturity) This method evaluates the price of a bond via the relationship between its yield and cash flows.
double[]	weightOfBonds(double[] valueOfBond) Evaluates the weights of the individual bonds within a bond portfolio and returns the result as an array of weights where the n-th term of the array corresponds to the weight of the n-th member of the portfolio.

Methods inherited from interface javax.ejb.EJBObject

getEJBHome, getHandle, getPrimaryKey, isIdentical, remove

Method Detail

priceOfBond

public double priceOfBond(double yield,
                          double[] coupons,
                          Date evaluationDate,
                          Date[] dateOfCoupons,
                          double principleSum,
                          Date maturityDate,
                          BusinessCalendar businessCalendar)
                   throws DurationConvexityDemoException,
                          RemoteException

This method evaluates the price of a bond via the relationship between its yield and cash flows.

Parameters:

yield - the continuously compounded yield which the bond pays expressed in decimal format (i.e. 1 percent = 0.01)

coupons - an array where the first term is the first coupon payment and the second term is the second coupon payment and so on

principleSum - the principle sum of the bond which will be repaid at maturity

evaluationDate - the date when the price of the bond is evaluated.

dateOfCoupons - an array of dates where the first term corresponds to the date of the first coupon payment, the second term to the second coupon payment and so on...

maturityDate - the date when the bond matures

businessCalendar - The instance of a BusinessCalendar interface implementation. Specify null to select the London business calendar.

DurationConvexityDemoException

RemoteException

priceOfBond

public double priceOfBond(double yield,
                          double[] coupons,
                          double[] time2Coupons,
                          double principleSum,
                          double maturity)
                   throws DurationConvexityDemoException,
                          RemoteException

This method evaluates the price of a bond via the relationship between its yield and cash flows.

Parameters:

yield - the continuously compounded yield which the bond pays expressed in decimal format (i.e. 1 percent = 0.01)

coupons - an array where the first term is the first coupon payment and the second term is the second coupon payment and so on

time2Coupons - an array of doubles where the first element represents the time until the first coupon payment is made, the second the time until the second coupon payment is made and so on

principleSum - the principle sum of the bond which will be repaid at maturity

maturity - the time in years until the bond matures

DurationConvexityDemoException

RemoteException

duration

public double duration(double yield,
                       double[] payments,
                       Date evaluationDate,
                       Date[] paymentDates,
                       double principleSum,
                       Date maturityDate,
                       BusinessCalendar businessCalendar)
                throws DurationConvexityDemoException,
                       RemoteException

Evaluates the duration of a bond with a continuous interest yield where the cash flows (or payments) made in terms of amount and time of payment are known.

Parameters:

yield - the continuous compounded yield paid by the bond expressed in decimal format (i.e. 1 percent = 0.01)

payments - an array of doubles where the first element represents the first payment from the bond, the second the second payment and so on.

principleSum - the principle sum paid by the bond at maturity

evaluationDate - the date on which the duration of the bond is evaluated

paymentDates - an array of dates where the first term corresponds to the first payment date and the second payment date corresponds to the second payment and so on...

maturityDate - the date when the bond matures

businessCalendar - The instance of a BusinessCalendar interface implementation. Specify null to select the London business calendar.

DurationConvexityDemoException

RemoteException

duration

public double duration(double yield,
                       double[] payments,
                       double[] time2Payments,
                       double principleSum,
                       double maturity)
                throws DurationConvexityDemoException,
                       RemoteException

Evaluates the duration of a bond with a continuous interest yield where the cash flows (or payments) made in terms of amount and time of payment are known.

Parameters:

yield - the continuous compounded yield paid by the bond expressed in decimal format (i.e. 1 percent = 0.01)

payments - an array of doubles where the first element represents the first payment from the bond, the second the second payment and so on.

time2Payments - an array of doubles where the first element represents the time in years until the first payment is made, the second the time in years until the second payment is made and so on

principleSum - the principle sum paid by the bond at maturity

maturity - the time in years until the bond matures

DurationConvexityDemoException

RemoteException

percentagePriceChange

public double percentagePriceChange(double deltaYield,
                                    double duration)
                             throws DurationConvexityDemoException,
                                    RemoteException

Returns the percentage change of the bonds price by a small parallel shift of the interest rate curve which the bonds depends on. Note that the returned percentage change is expressed in decimal format (i.e. 1 percent = 0.01).

Parameters:

deltaYield - the small parallel shift (in absolute terms) of the interest rate curve. That is, if the implied 3 month yield is 3.5 percent, and the 6 month yield is 3.7 percent then a parallel shift of 0.1, would result in a 3 month yield of 3.6 percent and a 6 month yield of 3.8 percent.

duration - the duration of the bond

DurationConvexityDemoException

RemoteException

weightOfBonds

public double[] weightOfBonds(double[] valueOfBond)
                       throws DurationConvexityDemoException,
                              RemoteException

Evaluates the weights of the individual bonds within a bond portfolio and returns the result as an array of weights where the n-th term of the array corresponds to the weight of the n-th member of the portfolio.

Parameters:

valueOfBond - an array where the first element corresponds to the value of the first bond within the portfolio and the second element corresponds to the value of the second bond and so on.

DurationConvexityDemoException

RemoteException

durationOfPortfolio

public double durationOfPortfolio(double[] duration,
                                  double[] weightOfBond)
                           throws DurationConvexityDemoException,
                                  RemoteException

Returns the duration of a portfolio of bonds when the duration and weight of each bond within the portfolio is known.

Parameters:

duration - an array where the first term is the duration of the first element of the portfolio and second term is the duration of the second term and so on...

weightOfBond - an array where the first element corresponds to the weight of the first element within the portfolio and the second term corresponds to the weight of the second element within the portfolio and so on...

DurationConvexityDemoException

RemoteException

See Also:

weightOfBonds - Use this method to find the weights of the bonds within a portfolio, duration - Use this method to find the duration of each member of the portfolio

durationOfPortfolioValue

public double durationOfPortfolioValue(double[] duration,
                                       double[] valueOfBond)
                                throws DurationConvexityDemoException,
                                       RemoteException

Returns the duration (in monetary terms) of a bond portfolio when the duration and value of each bond within the portfolio is known.

Parameters:

valueOfBond - an array where the first term is the value of the first bond within the portfolio and the second term is the value of the second bond within the portfolio and on so...

DurationConvexityDemoException

RemoteException

See Also:

duration - Use this method to find the duration of each member of the portfolio

percentagePriceChange

public double percentagePriceChange(double deltaYield,
                                    double[] duration,
                                    double[] valueOfBond)
                             throws DurationConvexityDemoException,
                                    RemoteException

Return the percentage change in a bond portfolio's value for a small parallel shift of all the interest rate curves which the bonds within the portfolio depend on. The percentage change of the portfolio is returned in decimal format (i.e. 1 percent = 0.01).

Parameters:

deltaYield - the small parallel shift (in absolute terms) of the interest rate curve.

duration - an array where the first value is the duration of the first bond within the portfolio and the second term is the duration of the second bond within the portfolio and so on

valueOfBond - an array where the first term corresponds to the value of the first bond within the portfolio and the second term corresponds to the weight of the second term within the portfolio and so on

DurationConvexityDemoException

RemoteException

See Also:

duration - Use in order to evaluate the duration of each bond within the portfolio.

percentagePriceChange

public double percentagePriceChange(double duration,
                                    double annualYield,
                                    double deltaYield)
                             throws DurationConvexityDemoException,
                                    RemoteException

Evaluates the percentage price change in a bond portfolio's value when the (annual) interest rates (expressed in decimal format) experience a small parallel shift.

Parameters:

duration - the duration of the bond portfolio

annualYield - the annual yield of the bond portfolio expressed in decimal format (i.e. 1 percent = 0.01)

deltaYield - the small parallel shift in the bond portfolios yield, expressed in decimal format

DurationConvexityDemoException

RemoteException

See Also:

durationOfPortfolio - Use in order to evaluate the duration of the portfolio.

percentagePriceChange

public double percentagePriceChange(double duration,
                                    double yield,
                                    int periodsCompoundedOver,
                                    double deltaYield)
                             throws DurationConvexityDemoException,
                                    RemoteException

Evaluates the percentage change in a bond portfolios value when interest rates experience a small parallel shift. Note, that here the yield is quoted with a compounding frequency of `periodsCompoundedOver' times a year.

Parameters:

duration - the duration of the bond portfolio

yield - the yield of the bond portfolio compounded `periodsCompoundedOver' time a year

periodsCompoundedOver - the number of time periods per annum which the yield is compounded over

deltaYield - the small parallel shift in the bond portfolios yield, expressed in decimal format

DurationConvexityDemoException

RemoteException

convexity

public double convexity(double yield,
                        double[] coupons,
                        Date evaluationDate,
                        Date[] dateOfCoupons,
                        double principleSum,
                        Date maturityDate,
                        BusinessCalendar businessCalendar)
                 throws DurationConvexityDemoException,
                        RemoteException

Evaluates the convexity of a bond.

Parameters:

yield - the continuously compounded yield of the bond portfolio expressed in decimal format (i.e. 1 percent = 0.01)

coupons - an array of doubles where the first term corresponds to the amount paid by the next coupon paid by the bond, the second term corresponds to the coupon after that and so on

principleSum - the principle sum paid at the maturity of the bond

evaluationDate - the date when the convexity of the bond is evaluated.

dateOfCoupons - an array of dates where the first term corresponds to the date of the first coupon payment and the second term corresponds to the date of second coupon payment and so on...

maturityDate - the date when the bond matures

businessCalendar - The instance of a BusinessCalendar interface implementation. Specify null to select the London business calendar.

DurationConvexityDemoException

RemoteException

convexity

public double convexity(double yield,
                        double[] coupons,
                        double[] time2Coupons,
                        double principleSum,
                        double maturity)
                 throws DurationConvexityDemoException,
                        RemoteException

Evaluates the convexity of a bond.

Parameters:

yield - the continuously compounded yield of the bond portfolio expressed in decimal format (i.e. 1 percent = 0.01)

coupons - an array of doubles where the first term corresponds to the amount paid by the next coupon paid by the bond, the second term corresponds to the coupon after that and so on

time2Coupons - an array where the first element is the time in years until the first coupon payment, the second term is the time (in years) until the second coupon payment and so on

principleSum - the principle sum paid at the maturity of the bond

maturity - the time (in years) until the bond matures

DurationConvexityDemoException

RemoteException

bondPriceChange

public double bondPriceChange(double duration,
                              double convexity,
                              double yieldChange)
                       throws DurationConvexityDemoException,
                              RemoteException

Estimates the percentage change of the bond portfolio's value for a given (absolute) change of the yield. This approach using the duration and convexity to estimate the change of a bond portfolios value to changes of the yield is more accurate than duration only approach.

Parameters:

duration - the duration of the bond portfolio

convexity - the convexity of the bond portfolio

yieldChange - the change (in absolute terms) in the yield of the bond portfolio

DurationConvexityDemoException

RemoteException

See Also:

convexity, duration

durationHedgeRatio

public double durationHedgeRatio(double futuresPrice,
                                 double duration,
                                 double forwardValue,
                                 double durationPort)
                          throws DurationConvexityDemoException,
                                 RemoteException

Evaluates the duration-hedge ratio of an interest rate dependent asset such as a bond portfolio or a money market security. The hedge ratio returns the number if relevant interest rate future contracts which need to be brought (or sold) in order to hedge against price changes resulting from small parallel shifts of the interest rate curve.

Parameters:

futuresPrice - the contract price of the interest rate futures contract

duration - the duration of the asset underlying the futures contract at the maturity of the futures contract

forwardValue - the forward value of the portfolio being hedged at the maturity of the hedge

durationPort - the duration of the portfolio at the maturity of the hedge

DurationConvexityDemoException

RemoteException