loan_calculator package

Submodules

loan_calculator.interest_rate module

class loan_calculator.interest_rate.InterestRateType[source]

Bases: enum.Enum

An enumeration.

annual = 'annual'
daily = 'daily'
monthly = 'monthly'
quarterly = 'quarterly'
semiannual = 'semiannual'
class loan_calculator.interest_rate.YearSizeType[source]

Bases: enum.IntEnum

An enumeration.

banker = 360
commercial = 365
loan_calculator.interest_rate.convert_to_daily_interest_rate(interest_rate_aliquot, interest_rate_type=<InterestRateType.daily: 'daily'>, year_size=<YearSizeType.commercial: 365>)[source]

“Convert aliquots from a given rate to a daily interest rate.

This function will convert an aliquot from a given rate (as in InterestRateType) to a daily interest rate, since “a day” is the default unit time adopted for financial modelling in this library. It is also important to note that the proper conversion of rates depends on the size of a year in days.

interest_rate_aliquot: float, required
Aliquot to be converted to a daily interest rate aliquot.
interest_rate_type: InterestRateType, optional
The type of rate in which the input aliquot is capitalized (default: InterestRateType.daily).
year_size: YearSizeType, optional
A year size is necessary since monthly, quarterly and semiannual rates are relative to an annum (default YearSizeType.commercial).
float
Aliquot as a daily interest rate.
TypeError
If the interest_rate_type is none one of the enumerated in InterestRateType.

loan_calculator.irr module

loan_calculator.irr.approximate_irr(net_principal, returns, return_days, daily_interest_rate)[source]

Approximate the internal return rate of a series of returns.

Use a Newton-Raphson solver implementation to approximate the IRR for the given loan parameters.

Let \(s_\circ\) be a net principal (i.e., a principal with eventual taxes and fees properly deduced), \(r_1,r_2\ldots,r_k\) a sequence of returns and \(n_1,n_2,\ldots,n_k\) the due days for these returns. The internal return rate \(c\) is then defined as the least positive root of the polynomial

\[f(X) = s_\circ X^{n_k} - r_1 X^{n_k-n_1} - \cdots - r_{k-1} X^{n_k-n_{k-1}} - r_k\]

on the real unknown

\[X = 1 + c.\]

The derivative of \(f\) is given by

\[f^\prime (X) = n_k s_\circ X^{n_k - 1} - \sum_{i=1}^{k-1} (n_k - n_i) r_i X^{n_k - n_i - 1}.\]

The polynomial \(f\) and its derivative derivative \(f^\prime\) are implemented as Python callables and passed to the Newton-Raphson search implementation with the daily interest rate as initial approximation for the IRR.

net_principal: float, required
The principal used as reference to evaluate the irr, i.e., this is the amount of money which is, from the perspective of the borrower, affected by the irr.
returns: list, required
List of expected returns or due payments.
return_days: list, required
List of number of days since the loan was granted until each expected return.
daily_interest_rate: float, required
Loan’s daily interest rate (for the grossed up principal), used as the start point for the approximation of the IRR.
loan_calculator.irr.newton_raphson_solver(target_function, target_function_derivative, initial_point, maximum_relative_error=1e-10, max_iterations=100)[source]

Numerical solver based on Newton-Raphson approximation method.

The Newton-Raphson method allows algorithmic approximation for the root of a differentiable function, given its derivative and an initial point at which this derivative does not vanish.

Let \(f:\left[a,b\right]\longrightarrow\mathbb{R}\) a differentiable function, \(f^{\prime}\) its derivative function and \(x_0\in\left[a,b\right]\). A root of \(f\) is then iteratively approximated by the recurrence

\[x_n := x_{n-1} - \frac{f(x_{n-1})}{f^{\prime}(x_{n-1})}, n\geq 1.\]

The relative error associated with the \(n\)-th iteration of the recurrence above is defined as

\[e_n := | \frac{x_n - x_{n-1}}{x_{n-1}} |, n \geq 1.\]

The approximation stops if either \(e_n\) > maximum_relative_error or \(n\) > max_iterations.

loan_calculator.irr.return_polynomial_derivative_factory(net_principal, returns, return_days)[source]

Factory for a callable implementing point evaluation of the derivative of the return polynomial for the given parameters.

The return polynomial for a loan with net principal \(s_\circ\), returns \(r_1,r_2,\ldots,r_k\) to be paid \(n_1,n_2,\ldots,n_k\) days after the loan is granted, respectively, is given by

\[f(c) = s_\circ (1 + c)^{n_k} - r_1 (1 + c)^{n_k-n_1} - \cdots - r_{k-1} (1 + c)^{n_k-n_{k-1}} - r_k.\]

Therefore, the derivative of \(f(c)\) is given by

\[f^\prime (c) = n_k s_\circ (1 + c)^{n_k - 1} - \sum_{i=1}^{k-1} (n_k - n_i) r_i (1 + c)^{n_k - n_i - 1}.\]
net_principal : float, required
The net principal of a grossed up loan.
returns : list of floats, required
Due payments that completely pay off the grossed up principal when respectively applied for the given return days.
return_days : list of ints, required
List with the number of days since the taxable event (which is usually a “loan granted” event) happened.
Callable
Python callable implementing the return polynomial for the given parameters
loan_calculator.irr.return_polynomial_factory(net_principal, returns, return_days)[source]

Factory for a callable with point evaluation of the return polynomial.

The return polynomial for a loan with net principal \(s_\circ\), returns \(r_1,r_2,\ldots,r_k\) to be paid \(n_1,n_2,\ldots,n_k\) days after the loan is granted, respectively, is given by

\[f(c) = s_\circ (1 + c)^{n_k} - r_1 (1 + c)^{n_k-n_1} - \cdots - r_{k-1} (1 + c)^{n_k-n_{k-1}} - r_k.\]

This function builds and returns a callable implementing such polynomial.

net_principal : float, required
The net principal of a grossed up loan.
returns : list of floats, required
Due payments that completely pay off the grossed up principal when respectively applied for the given return days.
return_days : list of ints, required
List with the number of days since the taxable event (which is usually a “loan granted” event) happened.
Callable
Python callable implementing the return polynomial for the given parameters

loan_calculator.loan module

class loan_calculator.loan.Loan(principal, annual_interest_rate, start_date, return_dates, year_size=<YearSizeType.commercial: 365>, grace_period=0, amortization_schedule_type='progressive-price-schedule')[source]

Bases: object

Loan.

principal : float, required
The loan’s principal.
annual_interest_rate : float, required
The loan’s annual interest rate.
start_date : date, required
The loan’s reference date. This date is usually the one when the borrower signed the loan’s contract.
return_dates : list, required
List of date objects with the expected return dates. These dates are usually contractually agreed.
year_size : int, optional
The reference year size for converting from annual to daily interest rates. (default 365)
grace_period : int, optional
The number of days for which the principal is not affected by the capitalization process. (default 0)
amortization_schedule_type : str, optional
A discriminator string indicating the amortization schedule to be adopted. The available schedules are progressive_price_schedule, regressive_price_schedule, constant_amortization_schedule. (default AmortizationScheduleType.progressive_price_schedule.value).
amortization_function
amortizations
balance
due_payments
interest_payments
return_days
total_amortization
total_interest
total_paid

loan_calculator.pmt module

loan_calculator.pmt.constant_return_pmt(principal, daily_interest_rate, return_days)[source]

Calculate the PMT (payment value) for the given parameters.

If \(s\) is the principal, \(d\) is the daily interest rate and \((n_1,\ldots,n_k)\) is the vector with the number of days since the start reference date, then the PMT is given by

\[\mathrm{PMT}\ (s, d, (n_1,\ldots,n_k)) = \frac{s}{\sum\frac{1}{(1+d)^{n_j}}},\]

where the sum is taken for \(j,1\leq j\leq k\).

principal : float, required
The value which should be fully paid by consecutive payments with value returned by this function.
daily_interest_rate : float, required
The daily rate at which the principal grows over time.
return_days : list, required
List of integers representing the numbers of days since the start reference date.

The required payment value for the given parameters.

loan_calculator.projection module

class loan_calculator.projection.Projection(loan, projection_dates, grossup_type=<GrossupType.iof: 'iof'>, *args)[source]

Bases: object

Project loan grossup for given projection dates.

The grossup of a loan is dependent of a reference data, usually interpreted as the associated taxable event date

projected_irrs
projected_principals

loan_calculator.utils module

loan_calculator.utils.display_summary(loan, reference_date=None)[source]

Display a legible summary of a loan.

loan : Loan, required
Loan to be displayed.
reference_date : date, optional
Date object with the date to consider as reference when calculating the values of the column day in the function’s output. (default None)

Module contents

Loan Calculator

class loan_calculator.Loan(principal, annual_interest_rate, start_date, return_dates, year_size=<YearSizeType.commercial: 365>, grace_period=0, amortization_schedule_type='progressive-price-schedule')[source]

Bases: object

Loan.

principal : float, required
The loan’s principal.
annual_interest_rate : float, required
The loan’s annual interest rate.
start_date : date, required
The loan’s reference date. This date is usually the one when the borrower signed the loan’s contract.
return_dates : list, required
List of date objects with the expected return dates. These dates are usually contractually agreed.
year_size : int, optional
The reference year size for converting from annual to daily interest rates. (default 365)
grace_period : int, optional
The number of days for which the principal is not affected by the capitalization process. (default 0)
amortization_schedule_type : str, optional
A discriminator string indicating the amortization schedule to be adopted. The available schedules are progressive_price_schedule, regressive_price_schedule, constant_amortization_schedule. (default AmortizationScheduleType.progressive_price_schedule.value).
amortization_function
amortizations
balance
due_payments
interest_payments
return_days
total_amortization
total_interest
total_paid
class loan_calculator.IofGrossup(base_loan, reference_date, daily_iof_aliquot=8.2e-05, complementary_iof_aliquot=0.0038, service_fee_aliquot=0.0)[source]

Bases: loan_calculator.grossup.base.BaseGrossup

Implement grossup based on IOF tax and linear service fee.

The mathematical model for this grossup is given by

\[s - \sum_{i=1}^k A(n_i-n_d,d,s)\min((n_i-n_d)I^*,1\frac{1}{2}\%) - sI^{**} - gs = s_\circ\]

where

  • \(s\) is the grossed up principal,
  • \(s_\circ\) is the net principal,
  • \(d\) is the daily interest rate,
  • \(n_d\) is the number of days in the grace period,
  • \(n_i\) is the number of days since the contract start,
  • \(A(n_i,n_d,d,s)\) is the amortization for the given parameters,
  • \(I^{*}\) is the reduced IOF tax aliquot,
  • \(I^{**}\) is the complementary IOF tax aliquot, and
  • \(g\) is the service fee aliquot.
reference_date : date, required
The date the loan’s net principal is made available.
daily_iof_aliquot : float, optional
Reduced IOF tax aliquot. The amortizations are the tax calculation basis and the aliquot is incident in proportion to the number of days since the taxable event. The IOF taxes over the amortization are summed up this aggregated value is the due tax over the amortizations. (Default 0.000082)
complementary_iof_aliquot : float, optional
Complementary IOF tax aliquot. The tax calculation basis is the principal. (Default 0.0038)
service_fee_aliquot : float, optional
Aliquot applied over the principal and is meant to model the service fee. (Default 0.0)
grossup(loan, reference_date, daily_iof_aliquot, complementary_iof_aliquot, service_fee_aliquot)[source]
class loan_calculator.Projection(loan, projection_dates, grossup_type=<GrossupType.iof: 'iof'>, *args)[source]

Bases: object

Project loan grossup for given projection dates.

The grossup of a loan is dependent of a reference data, usually interpreted as the associated taxable event date

projected_irrs
projected_principals
class loan_calculator.AmortizationScheduleType[source]

Bases: enum.Enum

An enumeration.

constant_amortization_schedule = 'constant-amortization-schedule'
progressive_price_schedule = 'progressive-price-schedule'
regressive_price_schedule = 'regressive-price-schedule'
class loan_calculator.GrossupType[source]

Bases: enum.Enum

An enumeration.

iof = 'iof'
loan_calculator.convert_to_daily_interest_rate(interest_rate_aliquot, interest_rate_type=<InterestRateType.daily: 'daily'>, year_size=<YearSizeType.commercial: 365>)[source]

“Convert aliquots from a given rate to a daily interest rate.

This function will convert an aliquot from a given rate (as in InterestRateType) to a daily interest rate, since “a day” is the default unit time adopted for financial modelling in this library. It is also important to note that the proper conversion of rates depends on the size of a year in days.

interest_rate_aliquot: float, required
Aliquot to be converted to a daily interest rate aliquot.
interest_rate_type: InterestRateType, optional
The type of rate in which the input aliquot is capitalized (default: InterestRateType.daily).
year_size: YearSizeType, optional
A year size is necessary since monthly, quarterly and semiannual rates are relative to an annum (default YearSizeType.commercial).
float
Aliquot as a daily interest rate.
TypeError
If the interest_rate_type is none one of the enumerated in InterestRateType.
class loan_calculator.InterestRateType[source]

Bases: enum.Enum

An enumeration.

annual = 'annual'
daily = 'daily'
monthly = 'monthly'
quarterly = 'quarterly'
semiannual = 'semiannual'
loan_calculator.display_summary(loan, reference_date=None)[source]

Display a legible summary of a loan.

loan : Loan, required
Loan to be displayed.
reference_date : date, optional
Date object with the date to consider as reference when calculating the values of the column day in the function’s output. (default None)
class loan_calculator.YearSizeType[source]

Bases: enum.IntEnum

An enumeration.

banker = 360
commercial = 365