- Function SecurityPeriodicDuration(SettlementDate, MaturityDate, ParValue, Redemption, Frequency, CouponRate, Yield, Basis)
SecurityPeriodicDuration
The function SecurityPeriodicDuration
returns the Macauley duration
of a security that pays interest at the end of each coupon period.
Duration is defined as the weighted average of time it takes to receive
a positive cash flow. The present values of the cash flows are used as
weights. The duration can be used as a measure of a bond price’s
response to changes in yield.
SecurityPeriodicDuration(
SettlementDate, ! (input) scalar string expression
MaturityDate, ! (input) scalar string expression
ParValue, ! (input) numerical expression
Redemption, ! (input) numerical expression
Frequency, ! (input) numerical expression
CouponRate, ! (input) numerical expression
Yield, ! (input) numerical expression
[Basis] ! (optional) numerical expression
)
Arguments
- SettlementDate
The date of settlement of the security. SettlementDate must be in date format.
- MaturityDate
The date of maturity of the security. MaturityDate must also be in date format and must be a date after SettlementDate.
- ParValue
The starting value of the security at issue date. ParValue must be a positive real number.
- Redemption
The amount repaid for the security at the maturity date. Redemption must be a positive real number.
- Frequency
The number of coupon payments in one year. Frequency must be 1 (annual), 2 (semi-annual) or 4 (quarterly).
- CouponRate
The annual interest rate of the security as a percentage of the par value. CouponRate must be a nonnegative real number.
- Yield
The yield of the security. Yield must be a nonnegative real number.
- Basis
The day-count basis method to be used. The default is 1.
Return Value
The function
SecurityPeriodicDuration
returns the Macauley duration of a security that pays interest at the end of each coupon period. Duration is defined as the weighted average of the time it takes to receive a positive cash flow.
Equation
The Macauley duration \(D\) is computed through the equation
\[D = \frac{ \displaystyle \left(N-1+ \frac{f_{SN}}{f_{PN}}\right) \frac{R}{\left(1 + \frac{r_y}{f}\right)^{N-1+\frac{f_{SN}}{f_{PN}}}} + \sum_{i=1}^N \left(i-1+ \frac{f_{SN}}{f_{PN}}\right) \frac{v_{\textit{par}}\frac{r_c}{f}}{\left(1 + \frac{r_y}{f}\right)^{i-1+\frac{f_{SN}}{f_{PN}}}} } { \displaystyle \frac{R}{\left(1 + \frac{r_y}{f}\right)^{N-1+\frac{f_{SN}}{f_{PN}}}} + \sum_{i=1}^N \frac{v_{\textit{par}}\frac{r_c}{f}}{\left(1 + \frac{r_y}{f}\right)^{i-1+\frac{f_{SN}}{f_{PN}}}} }\]where all other variables have the same interpretation as in the general equations for securities with multiple coupons.
Note
This function can be used in an objective function or constraint and the input parameters ParValue, Redemption, CouponRate, and Yield can be used as a variable.
The function
SecurityPeriodicDuration
is similar to the Excel function DURATION <https://support.microsoft.com/en-us/office/duration-function-b254ea57-eadc-4602-a86a-c8e369334038>_.
Example
The code:
_p_spd := SecurityPeriodicDuration(
SettlementDate : "2024-01-01",
MaturityDate : "2044-01-01",
ParValue : 100,
Redemption : 100,
Frequency : 1,
CouponRate : 0.08,
Yield : 0.08,
Basis : 1);
block where single_column_display := 1, listing_number_precision := 6 ;
display _p_spd ;
endblock ;
Results in:
_p_spd := 10.603599 ;