Conventions
Across all of them:- Cash inflows are positive and outflows are negative.
- Interest rates are entered and returned as decimals (
0.08, not8%). periods_per_yearandcompounds_per_yeardefault to12; a value less than 1 returns aParameter out of rangeerror.beginning_of_periodisfalsefor end-of-period (the default) ortruefor beginning-of-period.
Value and period units
The time-value-of-money and amortization functions accept units on their value and period arguments, with these rules:- Values —
present_value,future_value, andpaymentmay each be a currency value (375000 USD) or a plain scalar (375000). Within a single call they must all be the same kind. A value of0is the exception: it is accepted for any of these arguments regardless of the others. - Periods —
periodsmay be a time value (30 yr) or a scalar. A time value is converted to a number of periods by converting it to years and multiplying byperiods_per_year. A scalar is used as the number of periods unchanged. - Solving for periods — when
periods()solves for the number of periods, its return type mirrors the value arguments. Ifpresent_value,future_value, andpaymentare currency values, the result is a time value in years (the period count divided byperiods_per_year). If they are scalars, the result is a bare scalar count of periods. Seeperiods.
Time value of money
The five core functions each solve for one variable given the others. Each accepts the optional tailperiods_per_year; compounds_per_year; beginning_of_period. periods of 0 returns a result of 0.
Present value [pv]
Future value [fv]
Payment [pmt]
Interest rate [rate]
Number of periods [periods]
periods() returns a bare scalar count. With currency values, it returns a time value in years — the period count divided by periods_per_year — because the result carries the period unit rather than a dimensionless count.
periods_per_year at its default of 12, the first call returns the count in periods (months) and the second returns it in years (94.2355 periods / 12 periods per year = 7.853 yr).
To recover a scalar count from a currency-valued call, convert the result to the unit that matches one period and strip it with unitvalue. At the default of 12 periods per year, one period is a month, so convert to "mo":
"mo" form is exact only because periods_per_year is 12. For any other cadence, recover the count by converting to years and multiplying by periods_per_year — unitvalue(periods(...); "yr") * periods_per_year — which holds regardless of how many periods fall in a year.
Recovering the count matters when a downstream calculation multiplies it by a currency amount: a yr-typed count raises input.incompatible_units (“Cannot multiply Currency and Time”), while the recovered scalar count multiplies cleanly.
Amortization
These analyze a loan or investment over its schedule. They follow the same value and period unit rules as the functions above, and thebegin and end arguments follow the same rule as periods — a time value is converted to periods, a scalar is used unchanged. In addition, a fractional begin or end is reduced to its integer part (1.5 → 1, 11.3 → 11).
Each function also accepts a final positive_result argument: set it to true to always report the result as a positive number. periods of 0 returns 0 (or, for amortization, an empty table).
End balance [endbal]
end.
Follows the shared conventions and value and period units; see Amortization for the period and positive_result rules.
Principal paid [prnpaid]
begin to period end, inclusive.
Follows the shared conventions and value and period units; see Amortization for the period and positive_result rules.
Interest paid [intpaid]
begin to period end, inclusive.
Follows the shared conventions and value and period units; see Amortization for the period and positive_result rules.
Amortization table [amortization]
begin to end, inclusive. Each row is one period; its four columns are, in order, the payment, the principal paid, the interest paid, and the end balance.
To chart how a payment splits between principal and interest across the schedule, slice those two columns with columns: columns(schedule; 2; 3) returns a two-column table ready to show as a bar chart. A single column is taken the same way — column(schedule; 4) is the end-balance curve.
Follows the shared conventions and value and period units; see Amortization for the period and positive_result rules.
Uniform and single payment series
These take aninterest_rate per compounding period and a number of periods. uspv() calculates the present value of a series of 1 payments. sppv() calculates the present value of 1.
Because the rate is per period, divide an annual rate by the number of compounding periods per year — for a 6% annual rate compounding monthly, pass 0.06 / 12. The rate is a decimal, so you can also write it as rate / 100 or rate%.
Interest rate conversion
effrate converts a nominal rate to an effective annual rate; nomrate does the reverse. A compounds_per_year of 0 denotes continuous compounding; a negative value returns a Parameter out of range error. Both take and return decimals.
Cash flow analysis
Each takes atable of cash flows (inflows positive, outflows negative). For npv, nfv, nus, mirr, and profindex, the rate is annual by default — divide it by the number of compounding periods per year to use a periodic rate.
irr finds the rate at which the cash flows’ net present value is zero. A meaningful result requires the cash flows to change sign at least once; when they change sign more than once, more than one rate can satisfy NPV = 0. mirr takes a finance interest_rate and a reinvestment risk_rate.