fin

Documentation

Overview

Package fin is a library containing a collection of financial functions for time value of money (annuities), cash flow, interest rate conversions, bonds and depreciation calculations.

In the doc for most of the functions we state the equivalent Excel function.

The time value of money (TVM) functions simply are solutions for each one of the terms of the following equation:

pv(1+r)^n + pmt(1+r.type)((1+r)^n - 1)/r) + fv = 0

Solving for r (rate) is not possible analytically, so a solution is provided through the Newton-Raphson algorithm.

Index

• Constants
• func DaysDifference(date1 int64, date2 int64, basis int) int
• func DaysPerYear(year int, basis int) int
• func DepreciationFixedDeclining(cost float64, salvage float64, life int, period int, month int) (float64, error)
• func DepreciationSYD(cost float64, salvage float64, life int, per int) float64
• func DepreciationStraightLine(cost float64, salvage float64, life int) (float64, error)
• func DiscountRate(settlement int64, maturity int64, price float64, redemption float64, basis int) float64
• func EffectiveRate(nominal float64, numPeriods int) (float64, error)
• func FutureValue(rate float64, numPeriods int, pmt float64, pv float64, paymentType int) (fv float64, err error)
• func InterestPayment(rate float64, period int, numPeriods int, pv float64, fv float64, ...) (float64, error)
• func InternalRateOfReturn(values []float64, guess float64) (float64, error)
• func ModifiedInternalRateOfReturn(values []float64, financeRate float64, reinvestRate float64) (float64, error)
• func NetPresentValue(rate float64, values []float64) float64
• func NominalRate(effectiveRate float64, numPeriods int) (float64, error)
• func Payment(rate float64, numPeriods int, pv float64, fv float64, paymentType int) (pmt float64, err error)
• func Periods(rate float64, pmt float64, pv float64, fv float64, paymentType int) (numPeriods float64, err error)
• func PresentValue(rate float64, numPeriods int, pmt float64, fv float64, paymentType int) (pv float64, err error)
• func PriceDiscount(settlement int64, maturity int64, discount float64, redemption float64, ...) float64
• func PrincipalPayment(rate float64, period int, numPeriods int, pv float64, fv float64, ...) (float64, error)
• func Rate(numPeriods int, pmt float64, pv float64, fv float64, paymentType int, ...) (float64, error)
• func ScheduledInternalRateOfReturn(values []float64, dates []time.Time, guess float64) (float64, error)
• func ScheduledNetPresentValue(rate float64, values []float64, dates []time.Time) (float64, error)
• func TBillEquivalentYield(settlement int64, maturity int64, discount float64) (float64, error)
• func TBillPrice(settlement int64, maturity int64, discount float64) (float64, error)
• func TBillYield(settlement int64, maturity int64, price float64) (float64, error)

Constants

const (
	// US(NASD) 30/360
	CountNasd = iota
	// Actual/actual
	CountActualActual
	// Actual/360
	CountActual360
	// Actual/365
	CountActual365
	// European 30/360
	CountEuropean
)

These constants are used in the bonds functions (parameter "basis"), for specifying the basis for the type of day count:

const (
	// MaxIterations determines the maximum number of iterations performed by the Newton-Raphson algorithm.
	MaxIterations = 30
	// Precision determines how close to the solution the Newton-Raphson algorithm should arrive before stopping.
	Precision = 1E-6
)

const (
	PayEnd = iota
	PayBegin
)

These constants are used in the TVM functions (parameter "paymentType"). They determine whether payments occur at the end or at the beginning of each period:

Functions

func DaysDifference

func DaysDifference(date1 int64, date2 int64, basis int) int

DaysDifference returns the difference of days between two dates based on a daycount basis. Date1 and date2 are UNIX timestamps (seconds).

func DaysPerYear

func DaysPerYear(year int, basis int) int

DaysPerYear returns the number of days in the year based on a daycount basis.

func DepreciationFixedDeclining

func DepreciationFixedDeclining(cost float64, salvage float64, life int, period int, month int) (float64, error)

DepreciationFixedDeclining returns the depreciation of an asset using the fixed-declining balance method

Excel equivalent: DB

func DepreciationSYD

func DepreciationSYD(cost float64, salvage float64, life int, per int) float64

DepreciationSYD returns the depreciation for an asset in a given period using the sum-of-years' digits method

Excel equivalent: SYD

func DepreciationStraightLine

func DepreciationStraightLine(cost float64, salvage float64, life int) (float64, error)

DepreciationStraightLine returns the straight-line depreciation of an asset for each period

Excel equivalent: SLN

func DiscountRate

func DiscountRate(settlement int64, maturity int64, price float64, redemption float64, basis int) float64

DiscountRate returns the discount rate for a bond

settlement is the unix timestamp (seconds) for the settlement date

maturity is the unix timestamp (seconds) for the maturity date

price is the bond's price per $100 face value

redemption is the bond's redemption value per $100 face value

Excel equivalent: DISC

func EffectiveRate

func EffectiveRate(nominal float64, numPeriods int) (float64, error)

EffectiveRate returns the effective interest rate given the nominal rate and the number of compounding payments per year.

Excel equivalent: EFFECT

func FutureValue

func FutureValue(rate float64, numPeriods int, pmt float64, pv float64, paymentType int) (fv float64, err error)

FutureValue returns the Future Value of a cash flow with constant payments and interest rate (annuities).

Excel equivalent: FV

func InterestPayment

func InterestPayment(rate float64, period int, numPeriods int, pv float64, fv float64, paymentType int) (float64, error)

InterestPayment returns the interest payment for a given period for a cash flow with constant periodic payments (annuities)

Excel equivalent: IMPT

func InternalRateOfReturn

func InternalRateOfReturn(values []float64, guess float64) (float64, error)

InternalRateOfReturn returns the internal rate of return of a cash flow series. Guess is a guess for the rate, used as a starting point for the iterative algorithm.

Excel equivalent: IRR

func ModifiedInternalRateOfReturn

func ModifiedInternalRateOfReturn(values []float64, financeRate float64, reinvestRate float64) (float64, error)

ModifiedInternalRateOfReturn returns the internal rate of return of a cash flow series, considering both financial and reinvestment rates

financeRate is the rate on the money used in the cash flow.

reinvestRate is the rate received when reinvested

Excel equivalent: MIRR

func NetPresentValue

func NetPresentValue(rate float64, values []float64) float64

NetPresentValue returns the Net Present Value of a cash flow series given a discount rate

Excel equivalent: NPV

func NominalRate

func NominalRate(effectiveRate float64, numPeriods int) (float64, error)

NominalRate returns the nominal interest rate given the effective rate and the number of compounding payments per year.

Excel equivalent: NOMINAL

func Payment

func Payment(rate float64, numPeriods int, pv float64, fv float64, paymentType int) (pmt float64, err error)

Payment returns the constant payment (annuity) for a cash flow with a constant interest rate.

Excel equivalent: PMT

func Periods

func Periods(rate float64, pmt float64, pv float64, fv float64, paymentType int) (numPeriods float64, err error)

Periods returns the number of periods for a cash flow with constant periodic payments (annuities), and interest rate.

Excel equivalent: NPER

func PresentValue

func PresentValue(rate float64, numPeriods int, pmt float64, fv float64, paymentType int) (pv float64, err error)

PresentValue returns the Present Value of a cash flow with constant payments and interest rate (annuities).

Excel equivalent: PV

func PriceDiscount

func PriceDiscount(settlement int64, maturity int64, discount float64, redemption float64, basis int) float64

PriceDiscount returns the price per $100 face value of a discounted bond

settlement is the unix timestamp (seconds) for the settlement date

maturity is the unix timestamp (seconds) for the maturity date

discount is the bond's discount rate

redemption is the bond's redemption value per $100 face value

Excel equivalent: PRICEDISC

func PrincipalPayment

func PrincipalPayment(rate float64, period int, numPeriods int, pv float64, fv float64, paymentType int) (float64, error)

PrincipalPayment returns the principal payment for a given period for a cash flow with constant periodic payments (annuities)

Excel equivalent: PPMT

func Rate

func Rate(numPeriods int, pmt float64, pv float64, fv float64, paymentType int, guess float64) (float64, error)

Rate returns the periodic interest rate for a cash flow with constant periodic payments (annuities). Guess is a guess for the rate, used as a starting point for the iterative algorithm.

Excel equivalent: RATE

func ScheduledInternalRateOfReturn

func ScheduledInternalRateOfReturn(values []float64, dates []time.Time, guess float64) (float64, error)

ScheduledInternalRateOfReturn returns the internal rate of return of a scheduled cash flow series. Guess is a guess for the rate, used as a starting point for the iterative algorithm.

Excel equivalent: XIRR

func ScheduledNetPresentValue

func ScheduledNetPresentValue(rate float64, values []float64, dates []time.Time) (float64, error)

ScheduledNetPresentValue returns the Net Present Value of a scheduled cash flow series given a discount rate

Excel equivalent: XNPV

func TBillEquivalentYield

func TBillEquivalentYield(settlement int64, maturity int64, discount float64) (float64, error)

TBillEquivalentYield returns the bond-equivalent yield for a Treasury bill

settlement is the unix timestamp (seconds) for the settlement date

maturity is the unix timestamp (seconds) for the maturity date

discount is the T-Bill discount rate

Excel equivalent: TBILLEQ

func TBillPrice

func TBillPrice(settlement int64, maturity int64, discount float64) (float64, error)

TBillPrice returns the price per $100 face value for a Treasury bill

settlement is the unix timestamp (seconds) for the settlement date

maturity is the unix timestamp (seconds) for the maturity date

discount is the T-Bill discount rate

Excel equivalent: TBILLPRICE

func TBillYield

func TBillYield(settlement int64, maturity int64, price float64) (float64, error)

TBillYield returns the yield for a treasury bill

settlement is the unix timestamp (seconds) for the settlement date

maturity is the unix timestamp (seconds) for the maturity date

price is the TBill price per $100 face value

Excel equivalent: TBILLYIELD