src.projection_entities.people.annuitants.Annuitants¶

class src.projection_entities.people.annuitants.Annuitants(time_steps: TimeSteps, data_sources: AnnuityDataSources)¶

One or more annuitants.

Inheritance Diagram

Variables & Properties

`primary_annuitant`	Returns the primary annuitant.
`secondary_annuitant`	Returns the secondary annuitant.
`data_sources`	Data sources to initialize projection values.
`annuitants`	List of annuitants
`t_q_x`	\({_t}q_x\) - Probability of death for the primary annuitant.
`t_q_y`	\({_t}q_y\) - Probability of death for the secondary annuitant.
`base_lapse_rate`	Base lapse rate.
`lapse_multiplier`	Base lapse rate multiplier.
`t_q_lapse`	\({_t}q_{lapse}\) - Final lapse rate.
`t_q_annuitization`	\({_t}q_{annuitization}\) - Annuitization rate.
`l_xy`	\(l_{xy}\) - Policy count - both alive.
`l_x_d_y`	\(l_{x}d_{y}\) - Policy count - only primary annuitant alive.
`l_y_d_x`	\(l_{y}d_{x}\) - Policy count - only secondary annuitant alive.
`d_xy`	\(d_{xy}\) - Policy count - both dead.
`d_lapse`	\(d_{lapse}\) - Policy count - lapsed.
`d_annuitization`	\(d_{annuitization}\) - Policy count - annuitized.

Methods

`__init__`(time_steps, data_sources)	Constructor method.
`update_decrements`()	Projects annuitants forward by one time step.
`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. Initializes a list of annuitants from the annuitants data source.

Parameters:

d_annuitization: ProjectionValue¶: \(d_{annuitization}\) - Policy count - annuitized.

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

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

l_x_d_y: ProjectionValue¶: \(l_{x}d_{y}\) - Policy count - only primary annuitant alive.

l_y_d_x: ProjectionValue¶: \(l_{y}d_{x}\) - Policy count - only secondary annuitant alive.

property primary_annuitant: Annuitant¶

Returns the primary annuitant. Primary annuitant is the youngest annuitant.

property secondary_annuitant: Annuitant | None¶

Returns the secondary annuitant. Secondary annuitant is the oldest annuitant. Returns None if there is no secondary annuitant.

t_q_annuitization: ProjectionValue¶: \({_t}q_{annuitization}\) - Annuitization rate.

t_q_x: ProjectionValue¶: \({_t}q_x\) - Probability of death for the primary annuitant.

t_q_y: ProjectionValue¶: \({_t}q_y\) - Probability of death for the secondary annuitant.

update_decrements() → None¶

Projects annuitants forward by one time step. Decrements are applied in the order of:

Annuitization

\[d_{annuitization_t} = d_{annuitization_{t - 1}} + \biggl(l_{xy_{t-1}} + l_{x}d_{y_{t-1}} + l_{y}d_{x_{t-1}}\biggr) \times {_t}q_{annuitization}\]
Lapse

\[d_{lapse_t} = d_{lapse_{t - 1}} + \biggl(l_{xy_{t-1}} + l_{x}d_{y_{t-1}} + l_{y}d_{x_{t-1}}\biggr) \times {_t}q_{lapse} \times (1 - {_t}q_{annuitization})\]
Mortality
1. Let policyholder behavior survivorship at time \(t\) be:
\[p_{pb_t} = (1 - {_t}q_{lapse}) \times (1 - {_t}q_{annuitization})\]
1. Then, at time \(t\):
\[ \begin{align}\begin{aligned}l_{xy_t} = l_{xy_{t-1}} \times (1 - {_t}q_x) \times (1 - {_t}q_y) \times p_{pb_t}\\l_{x}d_{y_t} = l_{x}d_{y_{t-1}} \times (1 - {_t}q_x) + \biggl(l_{x}d_{y_{t-1}} \times (1 - {_t}q_x) + l_{xy_{t-1}} \times {_t}q_y \times (1 - {_t}q_x)\biggr) \times p_{pb_t}\\l_{y}d_{x_t} = l_{y}d_{x_{t-1}} \times (1 - {_t}q_y) + \biggl(l_{y}d_{x_{t-1}} \times (1 - {_t}q_y) + l_{xy_{t-1}} \times {_t}q_x \times (1 - {_t}q_y)\biggr) \times p_{pb_t}\\d_{xy_t} = d_{xy_{t-1}} + \biggl(l_{xy_{t-1}} \times {_t}q_x \times {_t}q_y + l_{x}d_{y_{t-1}} \times {_t}q_x + l_{y}d_{x_{t-1}} \times {_t}q_y\biggr) \times p_{pb_t}\end{aligned}\end{align} \]

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.

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.