agencyprice

Price callable bond using Agency OAS model

Syntax

Price = agencyprice(ZeroData,OAS,CouponRate,Settle,Maturity,Vol,CallDate)

Price = agencyprice(___,Name,Value)

Description

Price = agencyprice(ZeroData,OAS,CouponRate,Settle,Maturity,Vol,CallDate) computes the price for a callable bond, given OAS, using the Agency OAS model.

Price = agencyprice(___,Name,Value) specifies options using one or more name-value pair arguments in addition to the input arguments in the previous syntax.

Examples

Compute the Agency Price

This example shows how to compute the agency Price.

Settle = '20-Jan-2010';
ZeroRates = [.07 .164 .253 1.002 1.732 2.226 2.605 3.316 ...
3.474 4.188 4.902]'/100;
ZeroDates = daysadd(Settle,360*[.25 .5 1 2 3 4 5 7 10 20 30],1);
ZeroData = [ZeroDates ZeroRates];
 
Maturity = datetime(2013,12,30);
CouponRate = .022;
OAS = 6.53/10000;
Vol = .5117;
CallDate = datetime(2010,12,30);
Price = agencyprice(ZeroData, OAS, CouponRate, Settle, Maturity, Vol, CallDate)

Price = 
99.4212

Input Arguments

ZeroData — Zero curve

matrix

Zero curve, specified as an numRates-by-2 matrix where the first column is zero dates and the second column is the accompanying zero rates.

Data Types: double

OAS — Option-adjusted spreads

vector in decimals

Option-adjusted spreads, specified as an numBonds-by-1 vector expressed as a decimal (that is, 50 basis points is entered as .005).

Data Types: double

CouponRate — Coupon rates

vector in decimals

Coupon rates, specified as an numBonds-by-1 vector in decimals.

Data Types: double

Settle — Settlement date

datetime scalar | string scalar | date character vector

Settlement date, specified as a scalar datetime, string, or date character vector.

Note

The Settle date must be an identical settlement date for all the bonds and the zero curve.

To support existing code, agencyprice also accepts serial date numbers as inputs, but they are not recommended.

Maturity — Maturity date

datetime array | scalar array | date character vector

Maturity date, specified as a scalar string or character vector or numBonds-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, agencyprice also accepts serial date numbers as inputs, but they are not recommended.

Vol — Volatilities

vector in decimals

Volatilities specified as a scalar or an numBonds-by-1 vector in decimals. Vol is the volatility of interest rates corresponding to the time of the CallDate.

Data Types: double

CallDate — Call dates

datetime array | string array | date character vector

Call dates, specified as a scalar string or character vector or an numBonds-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, agencyprice also accepts serial date numbers as inputs, but they are not recommended.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: Price = agencyprice(ZeroData,OAS,CouponRate,Settle,Maturity,Vol,CallDate,'Basis',7,'Face',1000)

Basis — Day-count basis

0 (actual/actual) (default) | integer from 0 to 13

Day-count basis, specified as the comma-separated pair consisting of 'Basis' and a N-by-1 vector using the following values:

• 0 = actual/actual

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (PSA)

• 5 = 30/360 (ISDA)

• 6 = 30/360 (European)

• 7 = actual/365 (Japanese)

• 8 = actual/actual (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Data Types: double

CurveBasis — Curve basis

0 (actual/actual) (default) | integer from 0 to 13

Curve basis, specified as the comma-separated pair consisting of 'CurveBasis' and a N-by-1 vector using the following values:

• 0 = actual/actual

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (PSA)

• 5 = 30/360 (ISDA)

• 6 = 30/360 (European)

• 7 = actual/365 (Japanese)

• 8 = actual/actual (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Data Types: double

CurveCompounding — Compounding frequency of the zero curve

2 (semiannual) (default) | possible values include: –1, 0, 1, 2, 3, 4, 6, 12.

Compounding frequency of the zero curve, specified as the comma-separated pair consisting of 'CurveCompounding' and a N-by-1 vector using the supported values: –1, 0, 1, 2, 3, 4, 6, and 12.

Data Types: double

EndMonthRule — End-of-month rule flag

1 (in effect) (default) | nonnegative integer [0,1]

End-of-month rule flag, specified as the comma-separated pair consisting of 'EndMonthRule' and a nonnegative integer [0, 1] using a N-by-1 vector with date character vectors or a datetime array.

• 0 = Ignore rule, meaning that a payment date is always the same numerical day of the month.

• 1 = Set rule on, meaning that a payment date is always the last actual day of the month.

Data Types: logical

Face — face value of bond

100 (default) | vector

Face value of bond, specified as the comma-separated pair consisting of 'Face' and an N-by-1 vector of numeric values.

Data Types: double

FirstCouponDate — Irregular first coupon date

if you do not specify a FirstCouponDate, the cash flow payment dates are determined from other inputs (default) | datetime array | string array | date character vector

Irregular first coupon date, specified as the comma-separated pair consisting of 'FirstCouponDate' and a scalar string or character vector or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, agencyprice also accepts serial date numbers as inputs, but they are not recommended.

When FirstCouponDate and LastCouponDate are both specified, FirstCouponDate takes precedence in determining the coupon payment structure.

InterpMethod — Interpolation method

'linear' (default) | 'cubic','pchip'

Interpolation method, specified as the comma-separated pair consisting of 'InterpMethod' and a N-by-1 vector using a supported value. For more information on interpolation methods, see interp1.

Data Types: char

IssueDate — Bond issue date

if you do not specify an IssueDate, the cash flow payment dates are determined from other inputs (default) | datetime array | scalar array | date character vector

Bond issue date, specified as the comma-separated pair consisting of 'IssueDate' and a scalar string or character vector or an N-by-1 vector using a datetime array, string array, or date character vectors.

LastCouponDate — Irregular last coupon date

datetime array | string array | date character vector

Irregular last coupon date, specified as the comma-separated pair consisting of 'LastCouponDate' and a scalar string or character vector or an N-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, agencyprice also accepts serial date numbers as inputs, but they are not recommended.

In the absence of a specified FirstCouponDate, a specified LastCouponDate determines the coupon structure of the bond. The coupon structure of a bond is truncated at the LastCouponDate, regardless of where it falls, and is followed only by the bond's maturity cash flow date.

Period — Coupons per year

2 per year (default) | vector

Coupons per year, specified as the comma-separated pair consisting of 'Period' and an N-by-1 vector. Values for Period are 0, 1, 2, 3, 4, 6, and 12.

Data Types: double

StartDate — Forward starting date of payments

Settle date (default) | datetime array | string array | date character vector

Forward starting date of payments (the date from which a bond cash flow is considered), specified as the comma-separated pair consisting of 'StartDate' and a scalar string or character vector or an N-by-1 vector using a datetime array, string array, or date character vectors.

To support existing code, agencyprice also accepts serial date numbers as inputs, but they are not recommended.

If you do not specify StartDate, the effective start date is the Settle date.

Output Arguments

Price — Prices

matrix

Prices returned as an numBonds-by-1 matrix.

More About

Agency OAS Model

The BMA European Callable Securities Formula provides a standard methodology for computing price and option-adjusted spread for European Callable Securities (ECS).

References

[1] SIFMA, The BMA European Callable Securities Formula, https://www.sifma.org.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although agencyprice supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.