Financial Toolbox    

SIA Default Parameter Values

To illustrate the use of default values in SIA-compliant functions, consider the cfdates function, which computes actual cash flow payment dates for a portfolio of fixed income securities regardless of whether the first and/or last coupon periods are normal, long, or short.

The complete calling syntax with the full input argument list is

while the minimal calling syntax requires only settlement and maturity dates

Single Bond Example

As an example, suppose you have a bond with these characteristics

Note that Period, Basis, and EndMonthRule are set to their default values, and IssueDate, FirstCouponDate, and LastCouponDate are set to NaN.

Formally, a NaN is an IEEE arithmetic standard for Not-a-Number and is used to indicate the result of an undefined operation (e.g., zero divided by zero). However, NaN is also a very convenient placeholder. In the SIA functions of the Financial Toolbox, NaN indicates the presence of a nonapplicable value. It tells the SIA fixed-income functions to ignore the input value and apply the default. Setting IssueDate, FirstCouponDate, and LastCouponDate to NaN in this example tells cfdates to assume that the bond has been issued prior to settlement and that no odd first or last coupon periods exist.

Having set these values, all these calls to cfdates produce the same result.

Thus, leaving a particular input unspecified has the same effect as passing an empty matrix ([]) or passing a NaN - all three tell cfdates (and other SIA-compliant functions) to use the default value for a particular input parameter.

Bond Portfolio Example

Since the previous example included only a single bond, there was no difference between passing an empty matrix or passing a NaN for an optional input argument. For a portfolio of bonds, however, using NaN as a placeholder is the only way to specify default acceptance for some bonds while explicitly setting nondefault values for the remaining bonds in the portfolio.

Now suppose you have a portfolio of two bonds.

These calls to cfdates all set the coupon period to its default value (Period = 2) for both bonds.

The first two calls explicitly set Period = 2. Since Maturity is a 2-by-1 vector of maturity dates, cfdates knows you have a two-bond portfolio.

The first call specifies a single (i.e., scalar) 2 for Period. Passing a scalar tells cfdates to apply the scalar-valued input to all bonds in the portfolio. This is an example of implicit scalar-expansion. Note that the settlement date has been implicit scalar-expanded as well.

The second call also applies the default coupon period by explicitly passing a two-element vector of 2's. The third call passes an empty matrix, which cfdates interprets as an invalid period, for which the default value will be used. The fourth call is similar, except that a NaN has been passed. The fifth call passes two NaN's, and has the same effect as the third. The last call passes the minimal input set.

Finally, consider the following calls to cfdates for the same two-bond portfolio.

The first call explicitly sets Period = 4 for the first bond and implicitly sets the default Period = 2 for the second bond. The second call has the same effect as the first but explicitly sets the periodicity for both bonds.

The optional input Period has been used for illustrative purpose only. The default-handling process illustrated in the examples applies to any of the optional input arguments.


  SIA Framework SIA Coupon Date Calculations