annuity {jrvFinance}

Present Value of Annuity and Related Functions

Description

Functions to compute present value and future value of annuities, to find instalment given the present value or future value. Can also find the rate or the number of periods given other parameters.

Usage

annuity.pv(
  rate,
  n.periods = Inf,
  instalment = 1,
  terminal.payment = 0,
  immediate.start = FALSE,
  cf.freq = 1,
  comp.freq = 1
)

annuity.fv(
  rate,
  n.periods = Inf,
  instalment = 1,
  terminal.payment = 0,
  immediate.start = FALSE,
  cf.freq = 1,
  comp.freq = 1
)

annuity.instalment(
  rate,
  n.periods = Inf,
  pv = if (missing(fv)) 1 else 0,
  fv = 0,
  terminal.payment = 0,
  immediate.start = FALSE,
  cf.freq = 1,
  comp.freq = 1
)

annuity.periods(
  rate,
  instalment = 1,
  pv = if (missing(fv)) 1 else 0,
  fv = 0,
  terminal.payment = 0,
  immediate.start = FALSE,
  cf.freq = 1,
  comp.freq = 1,
  round2int.digits = 3
)

annuity.rate(
  n.periods = Inf,
  instalment = 1,
  pv = if (missing(fv)) 1 else 0,
  fv = 0,
  terminal.payment = 0,
  immediate.start = FALSE,
  cf.freq = 1,
  comp.freq = 1
)

annuity.instalment.breakup(
  rate,
  n.periods = Inf,
  pv = 1,
  immediate.start = FALSE,
  cf.freq = 1,
  comp.freq = 1,
  period.no = 1
)

Arguments

rate

The interest rate in decimal (0.10 or 10e-2 for 10%)

n.periods

The number of periods in the annuity.

instalment

The instalment (cash flow) per period.

terminal.payment

Any cash flow at the end of the annuity. For example, a bullet repayment at maturity of the unamortized principal.

immediate.start

Logical variable which is TRUE for immediate annuities (the first instalment is due immediately) and FALSE for deferred annuities (the first instalment is due at the end of the first period).

cf.freq

Frequency of annuity payments: 1 for annual, 2 for semi-annual, 12 for monthly.

comp.freq

Frequency of compounding of interest rates: 1 for annual, 2 for semi-annual, 12 for monthly, Inf for continuous compounding.

pv

The present value of all the cash flows including the terminal payment.

fv

The future value (at the end of the annuity) of all the cash flows including the terminal payment.

round2int.digits

Used only in annuity.periods. If the computed number of periods is an integer when rounded to round2int.digits, then the rounded integer value is returned. With the default value of 3, 9.9996 is returned as 10, but 9.9994 and 9.39999999 are returned without any rounding.

period.no

Used only in annuity.instalment.breakup. This is the period for which the instalment needs to be broken up into principal and interest parts.

Details

These functions are based on the Present Value relationship:

pv = fv \cdot df = terminal.payment \cdot df + \frac{instalment (1 - df)}{r}

where df = (1 + r)^{-n.periods} is the n.periods discount factor and r is the per period interest rate computed using rate, cf.freq and comp.freq.

It is intended that only one of pv or fv is used in any function call, but internally the functions use pv + fv \cdot df as the LHS of the present value relationship under the assumption that only of the two is non zero.

The function annuity.instalment.breakup regards the annuity as a repayment of a loan equal to pv plus the present value of terminal.payment. The instalment paid in period period.no is broken up into the principal repayment (amortization) and interest components.

Value

For most functions, the return value is one of the arguments described above. For example annuity.pv returns pv. The only exception is annuity.instalment.breakup. This returns a list with the following components:

opening.principal

The principal balance at the beginning of the period

closing.principal

The principal balance at the end of the period

interest.part

The portion of the instalment which represents interest

principal.part

The portion of the instalment which represents principal repayment

Author(s)

Prof. Jayanth R. Varma [e-mail]