Borrowing Classes

PeriodicBorrowing

class cred.PeriodicBorrowing(start_date, end_date, freq, initial_principal, first_reg_start=None, year_frac=<function actual360>, calc_convention=<function unadjusted>, pmt_convention=<function unadjusted>, holiday_calendar=None, desc=None, prepayment=None)

Abstract class for debt with regular, periodic principal and interest periods. Superclass for FixedRateBorrowing.

Parameters:
  • start_date (datetime-like) – Borrowing start date
  • end_date (datetime-like) – Borrowing end date
  • freq (Monthly, dateutil.relativedelta.relativedelta) – Interest period frequency. Using the Monthly offset is recommended to automatically recognize end of month roll dates appropriately.
  • initial_principal – Initial principal amount of the borrowing
  • first_reg_start (datetime-like, optional(default=None)) – Start date of first regular interest period. If None (default), will be the same as the start_date.
  • year_frac (function) – Function that takes two dates and returns the year fraction between them. Bound to Borrowing.year_frac. Default function is cred.interest.actual360. Use cred.interest.thrity360 for NASD 30 / 360 day count.
  • calc_convention (function, optional(default=cred.businessdays.unadjusted)) – Business day adjustment method for interest calculation dates. Function that takes a date as its first argument and a list of holidays as its second argument and returns the adjusted date. See cred.businessdays.following, preceding, and modified_following. Assigned to `adjust_calc_date’.
  • pmt_convention (function, optional(default=cred.businessdays.unadjusted)) – Business day adjustment method for payment dates. Function that takes a date as its first argument and a list of holidays as its second argument and returns the adjusted date. See cred.businessdays.following, preceding, and modified_following. Assigned to `adjust_pmt_date’.
  • holiday_calendar (pandas.tseries.holiday.AbstractHolidayCalendar, optional(default=None)) – Payment holidays to use in adjusting payment dates. Defaults to None.
  • desc (int, str, optional(default=None)) – Optional borrowing description.
  • prepayment (BasePrepayment, optional(default=None)) – Optional BasePrepayment subclass that defines prepayment terms and calculates prepayment costs.
accrued_interest(dt, include_dt=False)

Returns the amount of interest accrued from the start of the interest period in which dt falls to dt. By default, calculates interest from and including the period start date to but excluding dt. Set include_dt=True to include interest accrued through and including dt.

bop_principal(period)

Returns the beginning of interest period principal balance for the InterestPeriod argument.

date_index(dt, inc_period_end=False)

Returns the index of the period that contains the date argument. Default is inclusive of period start dates and exclusive of end dates. Dates prior to the borrowing start date or after the latest of the borrowing end date or final payment date raise and index error.

Parameters:
  • dt (datetime-like) – Look-up date
  • inc_period_end (bool) – Determines whether roll dates are included in the ending or starting period. Be default, end dates are considered the start date for the next period and are not included.
Returns:

Return type:

int

date_period(dt, inc_period_end=False)

Returns the period that date falls inside. Default is inclusive of period start date and exclusive of end date. Dates prior to the borrowing start date or after the max(borrowing end date, final payment date) raise and index error.

Parameters:
  • dt (datetime-like) – Look-up date
  • inc_period_end (bool optional(default=False)) – Determines whether roll dates are included in the ending or starting period. Be default, end dates are considered the start date for the next period and are not included.
Returns:

Return type:

InterestPeriod

eop_principal(period)

Period beginning balance less the period principal payment.

interest_payment(period)

Calculates the interest payment for the period as the year fraction from the period’s start date to end date (using the borrowing’s year_frac method) times the period’s interest_rate property times the period’s bop_principal property.

Parameters:period (InterestPeriod) – PeriodicBorrowing uses InterestPeriod class periods.
Returns:
Return type:float
outstanding_principal(dt, include_dt=False)

Returns the clean amount not including any accrued interest. The outstanding amount contemplates payment dates rather than period end dates, so the balance is not reduced by any amortization until the payment date occurs.

Returns None for dates prior to the start date, and returns the last period’s beginning balance less principal payment for any date equal or greater than the final payment date.

See repayment_amount for total cost to repay including any prepayment premiums.

Parameters:
  • dt (datetime-like) – As-of date
  • include_dt (bool, optional(default=False)) – Indicates whether to include principal payments due on dt
Returns:

Return type:

float

payments(first_dt=None, last_dt=None, pmt_dt=False)

Returns a list of list of (date, payment_amount) for all payments from first_dt to last_dt inclusive. If pmt_dt=False, then dates will correspond to scheduled period end dates. pmt_dt=True will evaluate and return dates based on their adjusted payment dates.

Passing first_dt or last_dt as None will return payments from the first period or through the last period respectively. Passing both as None will return payments for the entire term of the borrowing.

Parameters:
  • first_dt (datetime-like, optional(default=None)) – First payment date, inclusive
  • last_dt (datetime-like, optional(default=None)) – Last payment date, inclusive
  • pmt_dt (bool) – Whether to evaluate dates based on scheduled period end dates or adjusted period payment dates
Returns:

Return type:

list((date, float))

period_end_date(i)

Returns end period calculation end date for period with index i. Returns None for indexes greater than then number of interest periods in the loan.

period_payment(period)

Returns the sum of the period’s interest and principal payments.

period_start_date(i)

Returns the calculation start date for period with index i.

pmt_date(i)

Returns the payment date for period with index i.

principal_payment(period)

Returns the principal payment for the period. By default this assumings interest only unless overridden by a subclass (e.g. FixedRateBorrowing).

repayment_amount(dt)

Required repayment amount including any prepayment premiums as defined by the prepayment object. See borrowing.outstanding_principal for clean balance.

schedule()

Returns the borrowing’s cash flow schedule as a pandas.DataFrame.

set_period_values(period)

Called for each period after it is initialized to set the period’s values. Calculating period values may rely on previously set values for that period (e.g. see interest payment), so order matters.

PeriodicBorrowing and its subclasses use InterestPeriod which should have a start date, end date, payment date, beginning period principal, interest payment, and principal payments.

unpaid_amount(dt, interest=True, princ=True, include_dt=False)

Returns the total unpaid interest and/or principal, if any. Specifically, returns the amount of interest to be paid on the payment date if dt is greater than or equal to the period end date but less than (or less than or equal to if include_dt=True) the period payment date and/or any scheduled principal payments if dt is between the period end date and payment date.

By default, does not include any payments due on dt.

Parameters:
  • dt (datetime-like) – Date of evaluation
  • interest (bool) – Include unpaid interest if True
  • princ (bool) – Include unpaid principal if True
  • include_dt (bool) – Include amounts scheduled to be paid on dt

FixedRateBorrowing

class cred.FixedRateBorrowing(start_date, end_date, freq, initial_principal, coupon, amort_periods=None, io_periods=0, **kwargs)

PeriodicBorrowing subclass for fixed rate borrowings.

Parameters:
  • start_date (datetime-like) – Borrowing start date
  • end_date (datetime-like) – Borrowing end date
  • freq (dateutil.relativedelta.relativedelta) – Interest period frequency
  • initial_principal – Initial principal amount of the borrowing
  • coupon (float) – Coupon rate
  • amort_periods (int, object, optional(default=None)) –

    If None (default), will be calculated as interest only.

    If amort_periods is a single number n, then will calculate principal payments based on a fully amortizing schedule over n periods of length freq with constant principal and interest payments (e.g. 360 where freq=relativedelta(months=1) will calculate 30 year amortization with constant monthly payments.

    If amort_periods is an object, it must implement __getitem__ and must have length at least greater than or equal to the number of periods. Custom amortization schedules can be provided this way, for example using lists or pandas.Series objects with amortization amount for period i at index i. Note that custom amortizations schedules should include the balloon payment as well.

  • io_periods (int, optional(default=0)) – If amort_periods is a number (i.e. amortization with constant principal and interest payments), then defines the leading number of full interest only periods. Calculated from the first_reg_start date, so any leading stub periods are ignored.
  • **kwargs – Keyword arguments passed to superclass (PeriodicBorrowing) initialization. Ex. desc for borrowing description, year_frac for day count convention, pmt_convention for business day adjustment, first_reg_start, etc.
principal_payment(period)

Returns the principal payment for the period. By default this assumings interest only unless overridden by a subclass (e.g. FixedRateBorrowing).