Financial functions

financialInternalRateOfReturn

Calculates the Internal Rate of Return (IRR) for a series of cash flows occurring at regular intervals. IRR is the discount rate at which the Net Present Value (NPV) equals zero.

IRR attempts to solve the following equation:

$$\sum_{i=0}^n \frac{cashflow_i}{(1 + irr)^i} = 0$$

Syntax

Arguments

• cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Type: Array of numeric values (Int8, Int16, Int32, Int64, Float32, Float64).
• guess — Optional initial guess (constant value) for the internal rate of return. Default: 0.1. Type: Float32|Float64.

Returned value

• Returns the internal rate of return as a Float64 value.
• Returns NaN if:
  • The calculation cannot converge
  • Input array is empty or has only one element
  • All cash flows are zero
  • Other calculation errors occur

Examples

Basic usage:

With initial guess:

Notes

• The function uses Newton-Raphson and TOMS748 methods for finding the root.
• At least one cash flow must be negative and one must be positive for a meaningful IRR calculation.

financialInternalRateOfReturnExtended

Calculates the Extended Internal Rate of Return (XIRR) for a series of cash flows occurring at irregular intervals. XIRR is the discount rate at which the net present value (NPV) of all cash flows equals zero.

XIRR attempts to solve the following equation (example for ACT_365F):

$$\sum_{i=0}^n \frac{cashflow_i}{(1 + rate)^{(date_i - date_0)/365}} = 0$$

Syntax

Arguments

• cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Type: Array of numeric values (Int8, Int16, Int32, Int64, Float32, Float64).
• dates — Array of dates corresponding to each cash flow. Must be sorted in ascending order with unique values. Type: Array of Date or Date32.
• guess — Optional initial guess (constant value) for the internal rate of return. Default: 0.1. Type: Float32|Float64.
• daycount — Optional day count convention. Supported values:
  • 'ACT_365F' (default) — Actual/365 Fixed
  • 'ACT_365_25' — Actual/365.25

Returned value

• Returns the internal rate of return as a Float64 value.
• Returns NaN if:
  • The calculation cannot converge
  • Input arrays are empty or have only one element
  • All cash flows are zero
  • Dates are not sorted or not unique
  • Other calculation errors occur

Examples

Basic usage:

Using different day count convention:

Notes

• The function uses Newton-Raphson and TOMS748 methods for finding the root.
• The dates array must be sorted in ascending order with unique values.

financialNetPresentValueExtended

Calculates the Extended Net Present Value (XNPV) for a series of cash flows occurring at irregular intervals. XNPV considers the specific timing of each cash flow when calculating present value.

XNPV equation for ACT_365F:

$$XNPV=\sum_{i=1}^n \frac{cashflow_i}{(1 + rate)^{(date_i - date_0)/365}}$$

Syntax

Arguments

• rate — The discount rate to apply. Type: Float64.
• cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Must contain at least one positive and one negative value. Type: Array of numeric values (Int8, Int16, Int32, Int64, Float32, Float64).
• dates — Array of dates corresponding to each cash flow. Must have the same size as cashflows array. Type: Array of Date or Date32.
• daycount — Optional day count convention. Supported values:
  • 'ACT_365F' (default) — Actual/365 Fixed
  • 'ACT_365_25' — Actual/365.25

Returned value

• Returns the net present value as a Float64 value.

Examples

Basic usage:

Using different day count convention:

financialNetPresentValue

Calculates the Net Present Value (NPV) of a series of cash flows assuming equal time intervals between each cash flow.

Default variant:

$$\sum_{i=0}^{N-1} \frac{values_i}{(1 + rate)^i}$$

Variant with start_from_zero set to False (Excel style):

$$\sum_{i=1}^{N} \frac{values_i}{(1 + rate)^i}$$

Syntax

Arguments

• rate — The discount rate to apply. Type: Float64.
• cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Type: Array of numeric values (Int8, Int16, Int32, Int64, Float32, Float64).
• start_from_zero — Optional boolean parameter indicating whether to start the NPV calculation from period 0 (true) or period 1 (false). Default: true.

Returned value

• Returns the net present value as a Float64 value.

Examples

Basic usage:

With start_from_zero = false (Excel compatibility mode):

Notes

• When start_from_zero = true, the first cash flow is discounted by (1 + rate)^0, which equals 1
• When start_from_zero = false, the first cash flow is discounted by (1 + rate)^1, matching Excel's NPV function behavior