financecalculator2025.future_value

Functions

future_value(principal, annual_rate, n_periods[, ...])

Calculates the future value of an investment with optional monthly contributions.

Module Contents

financecalculator2025.future_value.future_value(principal, annual_rate, n_periods, contribution=0)[source]

Calculates the future value of an investment with optional monthly contributions.

Parameters:

  • principal (float) – The initial investment (positive value) or loan (negative value).

  • annual_rate (float) – Annual interest rate (as a percentage, e.g., 5 for 5%).

  • n_periods (int) – Total number of periods (in months).

  • contribution (float, optional) – Payment made per period (monthly contributions). Defaults to 0 if not provided. A negative contribution indicates withdrawals.

Returns:

A DataFrame containing the following columns:

  • ’Future Value’: The future value of the investment, including contributions.

  • ’Principal’: The initial investment.

  • ’Contributions’: Total amount contributed over the investment period.

  • ’Interest Earned’: The total interest earned from the investment.

Return type:

pandas.DataFrame

Raises:

  • TypeError – If any of principal, annual_rate, n_periods, or contribution is not a float or int.

  • ValueError – If n_periods is not positive. If annual_rate is negative.

Warning

UserWarning

If annual_rate is 0, the future value will be equal to the principal plus contributions. If annual_rate is unusually low (<1), indicating the user may have entered a percentage instead of a decimal. If n_periods is unusually low (<6), suggesting the user may have entered years instead of months.

Examples

>>> future_value(principal=1000, annual_rate=5, n_periods=120, contribution=100)