|
math-php
|
General references on financial functions and formulas: More...
Static Public Member Functions | |
| static | pmt (float $rate, int $periods, float $present_value, float $future_value=0, bool $beginning=false) |
| Financial payment for a loan or annuity with compound interest. More... | |
| static | ipmt (float $rate, int $period, int $periods, float $present_value, float $future_value=0, bool $beginning=false) |
| Interest on a financial payment for a loan or annuity with compound interest. More... | |
| static | ppmt (float $rate, int $period, int $periods, float $present_value, float $future_value=0, bool $beginning=false) |
| Principle on a financial payment for a loan or annuity with compound interest. More... | |
| static | periods (float $rate, float $payment, float $present_value, float $future_value, bool $beginning=false) |
| Number of payment periods of an annuity. More... | |
| static | aer (float $nominal, int $periods) |
| Annual Equivalent Rate (AER) of an annual percentage rate (APR). More... | |
| static | nominal (float $aer, int $periods) |
| Annual Nominal Rate of an annual effective rate (AER). More... | |
| static | fv (float $rate, int $periods, float $payment, float $present_value, bool $beginning=false) |
| Future value for a loan or annuity with compound interest. More... | |
| static | pv (float $rate, int $periods, float $payment, float $future_value, bool $beginning=false) |
| Present value for a loan or annuity with compound interest. More... | |
| static | npv (float $rate, array $values) |
| Net present value of cash flows. More... | |
| static | rate (float $periods, float $payment, float $present_value, float $future_value, bool $beginning=false, float $initial_guess=0.1) |
| Interest rate per period of an Annuity. More... | |
| static | irr (array $values, float $initial_guess=0.1) |
| Internal rate of return. More... | |
| static | mirr (array $values, float $finance_rate, float $reinvestment_rate) |
| Modified internal rate of return. More... | |
| static | payback (array $values, float $rate=0.0) |
| Discounted Payback of an investment. More... | |
| static | profitabilityIndex (array $values, float $rate) |
| Profitability Index. More... | |
Public Attributes | |
| const | EPSILON = 1e-6 |
| Floating-point range near zero to consider insignificant. | |
General references on financial functions and formulas:
|
static |
Annual Equivalent Rate (AER) of an annual percentage rate (APR).
The effective yearly rate of an annual percentage rate when the annual percentage rate is compounded periodically within the year.
Same as the =EFFECT() function in most spreadsheet software.
The formula: https://en.wikipedia.org/wiki/Effective_interest_rate
/ i \ ᴺ
AER = | 1 + - | - 1 \ n /
Examples: The AER of APR 3.5% interest compounded monthly. aer(0.035, 12)
| float | $nominal | |
| int | $periods |
|
static |
Future value for a loan or annuity with compound interest.
Same as the =FV() function in most spreadsheet software.
The basic future-value formula derivation: https://en.wikipedia.org/wiki/Future_value
PMT*((1+r)ᴺ - 1)
FV = -PV*(1+r)ᴺ - -------------— r
The (1+r*when) factor adjusts the payment to the beginning or end of the period. In the common case of a payment at the end of a period, the factor is 1 and reduces to the formula above. Setting when=1 computes an "annuity due" with an immediate payment.
Examples: The future value in 5 years on a 30-year fixed mortgage note of $265000 at 3.5% interest paid at the end of every month. This is how much loan principle would be outstanding: fv(0.035/12, 5*12, 1189.97, -265000, false)
The present_value is negative indicating money borrowed for the mortgage, whereas payment is positive, indicating money that will be paid to the mortgage.
| float | $rate | |
| int | $periods | |
| float | $payment | |
| float | $present_value | |
| bool | $beginning | adjust the payment to the beginning or end of the period |
|
static |
Interest on a financial payment for a loan or annuity with compound interest.
Determines the interest payment at a particular period of the annuity. For a typical loan paid down to zero, the amount of interest and principle paid throughout the lifetime of the loan will change, with the interest portion of the payment decreasing over time as the loan principle decreases.
Same as the =IPMT() function in most spreadsheet software.
See the PMT function for derivation of the formula. For IPMT, we have the payment equal to the interest portion and principle portion of the payment:
PMT = IPMT + PPMT
The interest portion IPMT on a regular annuity can be calculated by computing the future value of the annuity for the prior period and computing the compound interest for one period:
IPMT = FV(p=n-1) * rate
For an "annuity due" where payment is at the start of the period, period=1 has no interest portion of the payment because no time has elapsed for compounding. To compute the interest portion of the payment, the future value of 2 periods back needs to be computed, as the definition of a period is different, giving:
IPMT = (FV(p=n-2) - PMT) * rate
By thinking of the future value at period 0 instead of the present value, the given formulas are computed.
Example of regular annuity and annuity due for a loan of $10.00 paid back in 3 periods. Although the principle payments are equal, the total payment and interest portion are lower with the annuity due because a principle payment is made immediately.
Regular Annuity | Annuity Due
Period FV PMT IPMT PPMT | PMT IPMT PPMT 0 -10.00 | 1 -6.83 -3.67 -0.50 -3.17 | -3.50 0.00 -3.50 2 -3.50 -3.67 -0.34 -3.33 | -3.50 -0.33 -3.17
| 3 0.00 -3.67 -0.17 -3.50 | -3.50 -0.17 -3.33 |
|---|---|
| SUM -11.01 -1.01 -10.00 | -10.50 -0.50 -10.00 |
Examples: The interest on a payment on a 30-year fixed mortgage note of $265000 at 3.5% interest paid at the end of every month, looking at the first payment: ipmt(0.035/12, 1, 30*12, 265000, 0, false)
| float | $rate | |
| int | $period | |
| int | $periods | |
| float | $present_value | |
| float | $future_value | |
| bool | $beginning | adjust the payment to the beginning or end of the period |
|
static |
Internal rate of return.
Periodic rate of return that would provide a net-present value (NPV) of 0.
Same as =IRR formula in most spreadsheet software.
Reference: https://en.wikipedia.org/wiki/Internal_rate_of_return
Examples: The rate of return of an initial investment of $100 with returns of $50, $40, and $30: irr([-100, 50, 40, 30])
Solves for NPV=0 using Newton's Method.
| array | $values | |
| float | $initial_guess |
|
static |
Modified internal rate of return.
Rate of return that discounts outflows (investments) at the financing rate, and reinvests inflows with an expected rate of return.
Same as =MIRR formula in most spreadsheet software.
The formula derivation: https://en.wikipedia.org/wiki/Modified_internal_rate_of_return
_____________________________ n/ FV(re-invested cash inflows)
Examples: The rate of return of an initial investment of $100 at 5% financing with returns of $50, $40, and $30 reinvested at 10%: mirr([-100, 50, 40, 30], 0.05, 0.10)
| array | $values | |
| float | $finance_rate | |
| float | $reinvestment_rate |
|
static |
Annual Nominal Rate of an annual effective rate (AER).
The nominal yearly rate of an annual effective rate when the annual effective rate is compounded periodically within the year.
Same as the =NOMINAL() function in most spreadsheet software.
See: https://en.wikipedia.org/wiki/Nominal_interest_rate
/ 1/N \
NOMINAL = | (AER + 1) -1 | * N \ /
Examples: The nominal rate of AER 3.557% interest compounded monthly. nominal(0.03557, 12)
| float | $aer | |
| int | $periods |
|
static |
Net present value of cash flows.
Cash flows are periodic starting from an initial time and with a uniform discount rate.
Similar to the =NPV() function in most spreadsheet software, except the initial (usually negative) cash flow at time 0 is given as the first element of the array rather than subtracted. For example, spreadsheet: =NPV(0.01, 100, 200, 300, 400) - 1000 is done as MathPHP::npv(0.01, [-1000, 100, 200, 300, 400])
The basic net-present-value formula derivation: https://en.wikipedia.org/wiki/Net_present_value
n Rt Σ -----— t=0 (1 / r)ᵗ
Examples: The net present value of 5 yearly cash flows after an initial $1000 investment with a 3% discount rate: npv(0.03, [-1000, 100, 500, 300, 700, 700])
| float | $rate | |
| array | $values |
|
static |
Discounted Payback of an investment.
The number of periods to recoup cash outlays of an investment.
This is commonly used with discount rate=0 as simple payback period, but it is not a real financial measurement when it doesn't consider the discount rate. Even with a discount rate, it doesn't consider the cost of capital or re-investment of returns.
Avoid this when possible. Consider NPV, MIRR, IRR, and other financial functions.
Reference: https://en.wikipedia.org/wiki/Payback_period
The result is given assuming cash flows are continous throughout a period. To compute payback in terms of whole periods, use ceil() on the result.
An investment could reach its payback period before future cash outlays occur. The payback period returned is defined to be the final point at which the sum of returns becomes positive.
Examples: The payback period of an investment with a $1,000 investment and future returns of $100, $200, $300, $400, $500: payback([-1000, 100, 200, 300, 400, 500])
The discounted payback period of an investment with a $1,000 investment, future returns of $100, $200, $300, $400, $500, and a discount rate of 0.10: payback([-1000, 100, 200, 300, 400, 500], 0.1)
| array | $values | |
| float | $rate |
|
static |
Number of payment periods of an annuity.
Solves for the number of periods in the annuity formula.
Same as the =NPER() function in most spreadsheet software.
Solving the basic annuity formula for number of periods:
log(PMT + PV*r) n = -----------------— log(1 + r)
The (1+r*when) factor adjusts the payment to the beginning or end of the period. In the common case of a payment at the end of a period, the factor is 1 and reduces to the formula above. Setting when=1 computes an "annuity due" with an immediate payment.
Examples: The number of periods of a $475000 mortgage with interest rate 3.5% and monthly payment of $2132.96 paid in full: nper(0.035/12, -2132.96, 475000, 0)
| float | $rate | |
| float | $payment | |
| float | $present_value | |
| float | $future_value | |
| bool | $beginning | adjust the payment to the beginning or end of the period |
|
static |
Financial payment for a loan or annuity with compound interest.
Determines the periodic payment amount for a given interest rate, principal, targeted payment goal, life of the annuity as number of payments, and whether the payments are made at the start or end of each payment period.
Same as the =PMT() function in most spreadsheet software.
The basic monthly payment formula derivation: https://en.wikipedia.org/wiki/Mortgage_calculator#Monthly_payment_formula
rP(1+r)ᴺ
PMT = -----— (1+r)ᴺ-1
The formula is adjusted to allow targeting any future value rather than 0. The 1/(1+r*when) factor adjusts the payment to the beginning or end of the period. In the common case of a payment at the end of a period, the factor is 1 and reduces to the formula above. Setting when=1 computes an "annuity due" with an immediate payment.
Examples: The payment on a 30-year fixed mortgage note of $265000 at 3.5% interest paid at the end of every month. pmt(0.035/12, 30*12, 265000, 0, false)
The payment on a 30-year fixed mortgage note of $265000 at 3.5% interest needed to half the principal in half in 5 years: pmt(0.035/12, 5*12, 265000, 265000/2, false)
The weekly payment into a savings account with 1% interest rate and current balance of $1500 needed to reach $10000 after 3 years: pmt(0.01/52, 3*52, -1500, 10000, false) The present_value is negative indicating money put into the savings account, whereas future_value is positive, indicating money that will be withdrawn from the account. Similarly, the payment value is negative
How much money can be withdrawn at the end of every quarter from an account with $1000000 earning 4% so the money lasts 20 years: pmt(0.04/4, 20*4, 1000000, 0, false)
| float | $rate | |
| int | $periods | |
| float | $present_value | |
| float | $future_value | |
| bool | $beginning | adjust the payment to the beginning or end of the period |
|
static |
Principle on a financial payment for a loan or annuity with compound interest.
Determines the principle payment at a particular period of the annuity. For a typical loan paid down to zero, the amount of interest and principle paid throughout the lifetime of the loan will change, with the principle portion of the payment increasing over time as the loan principle decreases.
Same as the =PPMT() function in most spreadsheet software.
See the PMT function for derivation of the formula. See the IPMT function for derivation and use of PMT, IPMT, and PPMT.
With derivations for PMT and IPMT, we simply compute:
PPMT = PMT - IPMT
Examples: The principle on a payment on a 30-year fixed mortgage note of $265000 at 3.5% interest paid at the end of every month, looking at the first payment: ppmt(0.035/12, 1, 30*12, 265000, 0, false)
| float | $rate | |
| int | $period | |
| int | $periods | |
| float | $present_value | |
| float | $future_value | |
| bool | $beginning | adjust the payment to the beginning or end of the period |
|
static |
Profitability Index.
The Profitability Index, also referred to as Profit Investment Ratio (PIR) and Value Investment Ratio (VIR), is a comparison of discounted cash inflows to discounted cash outflows. It can be used as a decision criteria of an investment, using larger than 1 to choose an investment, and less than 1 to pass.
The formula derivation: https://en.wikipedia.org/wiki/Profitability_index
PV(cash outflows)
The formula is usually stated in terms of the initial investmest, but it is generalized here to discount all future outflows.
Examples: The profitability index of an initial $100 investment with future returns of $50, $50, $50 with a 10% discount rate: profitabilityIndex([-100, 50, 50, 50], 0.10)
| array | $values | |
| float | $rate |
|
static |
Present value for a loan or annuity with compound interest.
Same as the =PV() function in most spreadsheet software.
The basic present-value formula derivation: https://en.wikipedia.org/wiki/Present_value
PMT*((1+r)ᴺ - 1)
PV = -FV - -------------—
(1 + r)ᴺ
The (1+r*when) factor adjusts the payment to the beginning or end of the period. In the common case of a payment at the end of a period, the factor is 1 and reduces to the formula above. Setting when=1 computes an "annuity due" with an immediate payment.
Examples: The present value of a band's $1000 face value paid in 5 year's time with a constant discount rate of 3.5% compounded monthly: pv(0.035/12, 5*12, 0, -1000, false)
The present value of a $1000 5-year bond that pays a fixed 7% ($70) coupon at the end of each year with a discount rate of 5%: pv(0.5, 5, -70, -1000, false)
The payment and future_value is negative indicating money paid out.
| float | $rate | |
| int | $periods | |
| float | $payment | |
| float | $future_value | |
| bool | $beginning | adjust the payment to the beginning or end of the period |
|
static |
Interest rate per period of an Annuity.
Same as the =RATE() formula in most spreadsheet software.
The basic rate formula derivation is to solve for the future value taking into account the present value: https://en.wikipedia.org/wiki/Future_value
((1+r)ᴺ - 1)
FV + PV*(1+r)ᴺ + PMT * ---------— = 0 r The (1+r*when) factor adjusts the payment to the beginning or end of the period. In the common case of a payment at the end of a period, the factor is 1 and reduces to the formula above. Setting when=1 computes an "annuity due" with an immediate payment.
Not all solutions for the rate have real-value solutions or converge. In these cases, NAN is returned.
| float | $periods | |
| float | $payment | |
| float | $present_value | |
| float | $future_value | |
| bool | $beginning | |
| float | $initial_guess |
1.8.13