Package tvm

August 29, 2016

Type Package
Title Time Value of Money Functions
Version 0.3.0
Author Juan Manuel Truppia
Maintainer Juan Manuel Truppia <jmtruppia@gmail.com>
Description Functions for managing cashflows and interest rate curves.
License MIT + file LICENSE
Depends R (>= 3.1.0)
Suggests testthat, knitr
Imports ggplot2, reshape2
VignetteBuilder knitr
NeedsCompilation no
Repository CRAN
Date/Publication 2015-08-21 07:38:59

R topics documented:
adjust_disc . .
cashflow . . . .
cft . . . . . . .
disc_cf . . . . .
find_rate . . . .
irr . . . . . . .
loan . . . . . .
npv . . . . . .
plot.rate_curve
pmt . . . . . .
rate . . . . . .
rate_curve . . .
rem . . . . . .
tvm . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
1

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

2
2
3
3
4
4
5
5
6
7
7
8
9
9

cashflow
xirr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
xnpv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
[.rate_curve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Index

adjust_disc

12

Adjusts the discount factors by a spread

Description
Adjusts the discount factors by a spread
Usage
adjust_disc(fd, spread)
Arguments
fd

vector of discount factors used to discount cashflows in 1:length(fd) periods

spread

effective spread

Examples
adjust_disc(fd = c(0.99, 0.98), spread = 0.01)

cashflow

Get the cashflow for a loan

Description
Returns the cashflow for the loan, excluding the initial inflow for the loan taker
Usage
cashflow(l)
Arguments
l

The loan

Examples
l <- loan(rate = 0.05, maturity = 10, amt = 100, type = "bullet")
cashflow(l)

cft

cft

Calculates the Total Financial Cost (CFT)

Description
This is the IRR of the loans cashflow, after adding all the extra costs
Usage
cft(amt, maturity, rate, up_fee = 0, per_fee = 0)
Arguments
amt
maturity
rate
up_fee
per_fee

The amount of the loan

The maturity of the loan
The loan rate, in effective rate
The fee that the loan taker pays upfront
The fee that the loan payer pays every period

Details
It is assumed that the loan has monthly payments The CFT is returned as an effective rate of periodicty equal to that of the maturity and the rate The interest is calculated over amt + fee
Examples
cft(amt = 100, maturity = 10, rate = 0.05, up_fee = 1, per_fee = 0.1)

disc_cf

Value of a discounted cashflow

Description
Value of a discounted cashflow
Usage
disc_cf(fd, cf)
Arguments
fd
cf

The discount factor vector

The cashflow

Examples
disc_cf(fd = c(1, 0.99, 0.98, 0.97), cf = c(1, -0.3, -0.4, -0.6))

irr

find_rate

Find the rate for a loan given the discount factors

Description
Thru a root finding process, this function finds the rate that corresponds to a given set of discount
factors, as for the loan to have the same present value discounted with the discount factors or with
that constant rate
Usage
find_rate(m, d, loan_type, interval = c(1e-06, 2), tol = 1e-08)
Arguments
m
d
loan_type
interval
tol

The maturity of the loan

The discount factor vector
One of the loan types
The interval for the root finding process
The tolerance for the root finding process

Examples
find_rate(m = 3, d = c(0.99, 0.98, 0.97), loan_type = "bullet")

irr

The IRR is returned as an effective rate with periodicity equal to that

of the cashflow

Description
Internal Rate of Return of a periodic cashflow (IRR)
Usage
irr(cf, ts = seq(from = 0, by = 1, along.with = cf), interval = c(-1, 10),
...)
Arguments
cf
ts
interval
...

The cashflow
The times on which the cashflow ocurrs. It is assumed that cf[idx] happens at
moment ts[idx]
A length 2 vector that indicates the root finding algorithm where to search for
the irr
Other arguments to be passed on to uniroot

loan

Examples
irr(cf = c(-1, 0.5, 0.9), ts = c(0, 1, 3))

loan

Creates an instance of a loan class

Description
Creates an instance of a loan class
Usage
loan(rate, maturity, amt, type, grace_int = 0, grace_amort = grace_int)
Arguments
rate

The periodic effective rate of the loan

maturity

The maturity of the loan, measured in the same units as the periodicity of the
rate

amt

The amount loaned

type

The type of loan. Available types are c("bullet","french","german")

grace_int

The number of periods that the loan doesnt pay interest and capitalizes it. Leave
in 0 for zero loans

grace_amort

The number of periods that the loan doesnt amortize

Examples
loan(rate = 0.05, maturity = 10, amt = 100, type = "bullet")

npv

Net Present Value of a periodic cashflow (NPV)

Description
Net Present Value of a periodic cashflow (NPV)
Usage
npv(i, cf, ts = seq(from = 0, by = 1, along.with = cf))

plot.rate_curve

Arguments
i

The rate used to discount the cashflow. It must be effective and with a periodicity
that matches that of the cashflow

cf

The cashflow

ts

The times on which the cashflow ocurrs. It is assumed that cf[idx] happens at
moment ts[idx]. If empty, assumes that cf[idx] happens at period idx - 1

Value
The net present value at
Examples
npv(i = 0.01, cf = c(-1, 0.5, 0.9), ts = c(0, 1, 3))

plot.rate_curve

Plots a rate curve

Description
Plots a rate curve
Usage
## S3 method for class 'rate_curve'
plot(x, rate_type = NULL, ...)
Arguments
x

The rate curve

rate_type

The rate types to plot, in c("french","fut","german","zero_eff","zero_nom","swap")

...

Other arguments (unused)

Examples
r <- rate_curve(rates = c(0.1, 0.2, 0.3), rate_type = "zero_eff")
plot(r)
## Not run:
plot(r, rate_type = "german")
plot(r, rate_type = c("french", "german"))
## End(Not run)

pmt

pmt

The value of the payment of a loan with constant payments (french type
amortization)

Description
The value of the payment of a loan with constant payments (french type amortization)
Usage
pmt(amt, maturity, rate)
Arguments
amt
maturity
rate

The amount of the loan

The maturity of the loan
The rate of the loan

Details
The periodicity of the maturity and the rate must match, and this will be the periodicity of the
payments
Examples
pmt(amt = 100, maturity = 10, rate = 0.05)

rate

The rate of a loan with constant payments (french type amortization)

Description
The rate of a loan with constant payments (french type amortization)
Usage
rate(amt, maturity, pmt, extrema = c(1e-04, 1e+09), tol = 1e-04)
Arguments
amt
maturity
pmt
extrema
tol

The amount of the loan

The maturity of the loan
The payments of the loan
Vector of length 2 that has the minimum and maximum value to search for the
rate
The tolerance to use in the root finding algorithm

rate_curve

Details
The periodicity of the maturity and the payment must match, and this will be the periodicity of the
rate (which is returned as an effective rate)
Examples
rate(amt = 100, maturity = 10, pmt = 15)

rate_curve

Creates a rate curve instance

Description
Creates a rate curve instance
Usage
rate_curve(rates = NULL, rate_type = "zero_eff", pers = 1:length(rates),
fun_d = NULL, fun_r = NULL, knots = seq.int(from = 1, to = max(pers), by
= 1), functor = function(x, y) splinefun(x = x, y = y, method = "monoH.FC"))
Arguments
rates
rate_type
pers
fun_d
fun_r
knots
functor

A rate vector
The rate type. Must be on of c("fut", "zero_nom", "zero_eff", "swap")
The periods the rates correspond to
A discount factor function. fun_d(x) returns the discount factor for time x, vectorized on x
A rate function. fun_r(x) returns the EPR for time x, vectorized on x
The nodes used to bootstrap the rates. This is a mandatory argument if a rate
function or discount function is provided
A function with parameters x and y, that returns a function used to interpolate

Note
Currently a rate curve can only be built from one of the following sources
1. A discount factor function
2. A rate function and a rate type from the following types: "fut", "zero_nom", "zero_eff" or
"swap"
3. A rate vector, a pers vector and a rate type as before
Examples
rate_curve(rates = c(0.1, 0.2, 0.3), rate_type = "zero_eff")
rate_curve(fun_r = function(x) rep_len(0.1, length(x)), rate_type = "swap", knots = 1:12)
rate_curve(fun_d = function(x) 1 / (1 + x), knots = 1:12)

rem

rem

Remaining capital in a loan

Description
The amount that has to be repayed at each moment in a loan, at the end of the period
Usage
rem(cf, amt, r)
Arguments
cf

The cashflow of the loan, not including the initial inflow for the loan taker

amt

The original amount of the loan

The periodic rate of the loan

Examples
rem(cf = rep_len(0.4, 4), amt = 1, r = 0.2)

tvm

tvm

Description
Functions for managing cashflows and interest rate curves.

xirr

The IRR is returned as an effective anual rate

Description
Internal Rate of Return of an irregular cashflow (IRR)
Usage
xirr(cf, d, interval = c(-1, 10), ...)

10

[.rate_curve

Arguments
cf

The cashflow

The dates when each cashflow occurs. Same length as the cashflow

interval

A length 2 vector that indicates the root finding algorithm where to search for
the irr

...

Other arguments to be passed on to uniroot

Examples
xirr(cf = c(-1, 1.5), d = Sys.Date() + c(0, 365))

xnpv

Net Present Value of an irregular cashflow (NPV)

Description
Net Present Value of an irregular cashflow (NPV)
Usage
xnpv(i, cf, d)
Arguments
i

The rate used to discount the cashflow. It must be an effective anual rate (EAR)

cf

The cashflow

The dates when each cashflow occurs. Same length as the cashflow

Examples
xnpv(i = 0.01, cf = c(-1, 0.5, 0.9), d = as.Date(c("2015-01-01", "2015-02-15", "2015-04-10")))

[.rate_curve

Returns a particular rate or rates from a curve

Description
Returns a particular rate or rates from a curve
Usage
## S3 method for class 'rate_curve'
r[rate_type = "zero_eff", x = NULL]

[.rate_curve

11

Arguments
r

The rate_curve object

rate_type

The rate type

The points in time to return

Value
If x is NULL, then returns a rate function of rate_type type. Else, it returns the rates of rate_type
type and corresponding to time x
Examples
r <- rate_curve(rates = c(0.1, 0.2, 0.3), rate_type = "zero_eff")
r["zero_eff"]
r["swap",c(1.5, 2)]

Index
[.rate_curve, 10
adjust_disc, 2
cashflow, 2
cft, 3
disc_cf, 3
find_rate, 4
irr, 4
loan, 5
npv, 5
plot.rate_curve, 6
pmt, 7
rate, 7
rate_curve, 8
rem, 9
tvm, 9
tvm-package (tvm), 9
xirr, 9
xnpv, 10

12