src.projection_entities.products.annuity.base_contract.BaseContract¶

class src.projection_entities.products.annuity.base_contract.BaseContract(time_steps: TimeSteps, data_sources: AnnuityDataSources)¶

Base contract for an annuity product.

Inheritance Diagram

Variables & Properties

`primary_annuitant`	Convenience property to get the primary annuitant.
`data_sources`	Data sources to initialize projection values.
`annuitants`	List of annuitants under the base contract.
`accounts`	List of accounts opened under the base contract.
`riders`	List of riders attached to the base contract.
`quarterversaries`	List of quarterversaries within one time step.
`monthiversaries`	List of monthiversaries within one time step.
`anniversaries`	List of anniversaries within one time step.
`premium_new`	New premiums received.
`premium_cumulative`	Cumulative premiums received.
`interest_credited`	Interest credited.
`gmdb_charge`	GMDB rider charge.
`gmwb_charge`	GMWB rider charge.
`withdrawal`	Withdrawals taken.
`account_value`	Account value.
`surrender_charge`	Point-in-time surrender charge.
`cash_surrender_value`	Point-in-time cash surrender value.

Methods

`__init__`(time_steps, data_sources)	Constructor method.
`age_contract`()	Scans current time step for `monthiversaries`, `quarterversaries`, and `anniversaries` using `get_xversaries()`.
`assess_charge`(charge_amount, charge_account_name)	Applies a charge to a specific charge account, pro-rata across all sub-accounts, using
`assess_charges`()	Loops through each rider and calls the rider's `process_charge` method.
`credit_interest`()	Projects interest credited for a single time step by looping through each sub-account and calling the
`process_premiums`()	Processes premiums paid for a single time step by looping through each sub-account and calling the
`process_withdrawal`(withdrawal_amount)	Applies a withdrawal pro-rata across all sub-accounts, using
`process_withdrawals`()	Processes GMWB withdrawals by calling each GMWB rider's `process_withdrawal()` method.
`update_cash_surrender_value`()	Updates the surrender charge for each sub-account, using `update_surrender_charge()`.
`update_gmdb_naar`()	Updates GMDB Net Amount At Risk (NAAR) by calling each GMDB rider's `update_net_amount_at_risk()` method.
`write_projection_values`(output_file_path)	Writes all `ProjectionValue` attributes in this projection entity to a CSV file.
`write_projection_values_recursively`(...)	Convenience method that writes `ProjectionValue` attributes for itself, as well as any nested `ProjectionEntity` attributes.

Details

__init__(time_steps: TimeSteps, data_sources: AnnuityDataSources)¶

Constructor method. Creates an annuity contract, along with sibling Projection Entities:

Riders
Annuitants
Sub-accounts

Parameters:

time_steps – Projection-wide timekeeping object.
data_sources – Annuity data sources.

account_value: ProjectionValue¶: Account value.

accounts: List[Account]¶: List of accounts opened under the base contract.

age_contract() → None¶

Scans current time step for monthiversaries, quarterversaries, and anniversaries using get_xversaries().

Returns:: Nothing.

anniversaries: ProjectionValue¶: List of anniversaries within one time step.

annuitants: Annuitants¶: List of annuitants under the base contract.

assess_charge(charge_amount: ProjectionValue, charge_account_name: str) → None¶

Applies a charge to a specific charge account, pro-rata across all sub-accounts, using process_charge().
Updates account_value to reflect charge.
Calls update_cash_surrender_value() to recalculate cash surrender value.

Parameters:

charge_amount – Dollar amount of charge.
charge_account_name – Charge account name.

Returns:

Nothing.

assess_charges() → None¶

Loops through each rider and calls the rider’s process_charge method. Depending on the rider, this could be:

GMWB process_charge()
GMDB process_charge()

Returns:: Nothing.

cash_surrender_value: ProjectionValue¶: Point-in-time cash surrender value.

credit_interest() → None¶

Projects interest credited for a single time step by looping through each sub-account and calling the sub-account’s credit_interest() method.
Updates account_value and interest_credited to reflect interest earned and credited to the account value.
Calls update_cash_surrender_value() to recalculate cash surrender value.

Returns:: Nothing.

data_sources: AnnuityDataSources¶: Data sources to initialize projection values.

gmdb_charge: ProjectionValue¶: GMDB rider charge.

gmwb_charge: ProjectionValue¶: GMWB rider charge.

init_t: date¶: Initial time step. Marks when this entity first came into existence.

interest_credited: ProjectionValue¶: Interest credited.

monthiversaries: ProjectionValue¶: List of monthiversaries within one time step.

premium_cumulative: ProjectionValue¶: Cumulative premiums received.

premium_new: ProjectionValue¶: New premiums received.

property primary_annuitant: Annuitant¶

Convenience property to get the primary annuitant. Links to primary_annuitant.

Returns:: Primary annuitant.

process_premiums() → None¶

Processes premiums paid for a single time step by looping through each sub-account and calling the sub-account’s process_premiums() method.
Instantiates new sub-accounts, adding them to accounts.
Updates premium_new, premium_cumulative, and account_value for new premiums.
Calls update_cash_surrender_value() to recalculate cash surrender value.

Returns:: Nothing.

process_withdrawal(withdrawal_amount: ProjectionValue) → None¶

Applies a withdrawal pro-rata across all sub-accounts, using process_withdrawal().
Updates account_value to reflect withdrawal.
Calls update_cash_surrender_value() to recalculate cash surrender value.

Parameters:: withdrawal_amount – Withdrawal amount.
Returns:: Nothing.

process_withdrawals() → None¶

Processes GMWB withdrawals by calling each GMWB rider’s process_withdrawal() method.

Returns:: Nothing.

quarterversaries: ProjectionValue¶: List of quarterversaries within one time step.

riders: List[Gmwb | GmdbRop | GmdbRav | GmdbMav]¶: List of riders attached to the base contract.

surrender_charge: ProjectionValue¶: Point-in-time surrender charge.

time_steps: TimeSteps¶: Projection-wide timekeeping object.

update_cash_surrender_value() → None¶

Updates the surrender charge for each sub-account, using update_surrender_charge().

Once surrender charges are updated, calculates the aggregate surrender charge and cash surrender value.

Returns:: Nothing.

update_gmdb_naar() → None¶

Updates GMDB Net Amount At Risk (NAAR) by calling each GMDB rider’s update_net_amount_at_risk() method.

Returns:: Nothing.

withdrawal: ProjectionValue¶: Withdrawals taken.

write_projection_values(output_file_path: str) → None¶

Writes all ProjectionValue attributes in this projection entity to a CSV file. Existing file will be overwritten.

Parameters:: output_file_path – Output file path.
Returns:: Nothing.

write_projection_values_recursively(output_file_path: str) → None¶

Convenience method that writes ProjectionValue attributes for itself, as well as any nested ProjectionEntity attributes.

This function behaves recursively, writing output for all nested projection entities no matter how deeply they are nested.

Parameters:: output_file_path – Output file path
Returns:: Nothing.