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)
-
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'¶
-
-
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)