tf_quant_finance.rates.hagan_west.monotone_convex.interpolate_forward_rate

Last updated: 2023-03-16.

tf_quant_finance.rates.hagan_west.monotone_convex.interpolate_forward_rate#

View source

Interpolates instantaneous forward rate to supplied times .

tf_quant_finance.rates.hagan_west.monotone_convex.interpolate_forward_rate(
    interpolation_times, reference_times, yields=None, discrete_forwards=None,
    validate_args=False, dtype=None, name=None
)

Applies the Hagan West procedure to interpolate either a zero coupon yield curve or a discrete forward curve to a given set of times to compute the instantaneous forward rate for those times.

A zero coupon yield curve is specified by a set of times and the yields on zero coupon bonds expiring at those times. A discrete forward rate curve specifies the interest rate that applies between two times in the future as seen from the current time. The relation between the two sets of curve is as follows. Suppose the yields on zero coupon bonds expiring at times [t_1, ..., t_n] are [r_1, ..., r_n], then the forward rate between time [t_i, t_{i+1}] is denoted f(0; t_i, t_{i+1}) and given by

  f(0; t_i, t_{i+1}) = (r_{i+1} t_{i+1} - r_i t_i) / (t_{i+1} - t_i)

This function uses the Hagan West algorithm to perform the interpolation. This scheme interpolates on the forward curve. If yields are specified instead of discrete_forwards then they are first converted to the discrete forwards before interpolation. For more details on the interpolation procedure, see Ref. [1].

Example#

  dtype = np.float64
  # Market data.
  reference_times = np.array([1.0, 2.0, 3.0, 4,0, 5.0], dtype=dtype)
  yields = np.array([2.75, 4.0, 4.75, 5.0, 4.75], dtype=dtype) / 100

  # Times for which the interpolated values are required.
  interpolation_times = np.array([0.3, 1.3, 2.1, 4.5], dtype=dtype)
  interpolated_forwards = interpolate_forward_rates(
      interpolation_times,
      reference_times=reference_times,
      yields=yields)

  # Produces: [0.0229375, 0.05010625, 0.0609, 0.03625].

References:#

[1]: Patrick Hagan & Graeme West. Methods for Constructing a Yield Curve. Wilmott Magazine, pp. 70-81. May 2008.

Args:#

  • interpolation_times: Non-negative rank 1 Tensor of any size. The times for which the interpolation has to be performed.

  • reference_times: Strictly positive rank 1 Tensor of real dtype containing increasing values. The expiry times of the underlying zero coupon bonds.

  • yields: Optional rank 1 Tensor of the same shape and dtype as reference_times, if supplied. The yield rate of zero coupon bonds expiring at the corresponding time in the reference_times. Either this argument or the discrete_forwards must be supplied (but not both). Default value: None.

  • discrete_forwards: Optional rank 1 Tensor of the same shape and dtype as reference_times, if supplied. The ith component of the Tensor is the forward rate that applies between reference_times[i-1] and reference_times[i] for i>0 and between time 0 and reference_times[0] for i=0. Either this argument or the yields must be specified (but not both). Default value: None.

  • validate_args: Python bool. If true, adds control dependencies to check that the times are bounded by the reference_times. Default value: False

  • dtype: tf.Dtype to use when converting arguments to Tensors. If not supplied, the default Tensorflow conversion will take place. Note that this argument does not do any casting. Default value: None.

  • name: Python str name prefixed to Ops created by this class. Default value: None which is mapped to the default name ‘interpolate_forward_rate’.

Returns:#

  • interpolated_forwards: Rank 1 Tensor of the same size and dtype as the interpolation_times. The interpolated instantaneous forwards at the interpolation_times.

Raises:#

ValueError if neither yields nor discrete_forwards are specified or if both are specified.

Contents