The PolicyAttrs Space#

Policy attributes and policy values.

This Space holds policy attributes and policy-level values used by Projection and its base spaces.

The main role of this Space is to associate product specs sourced from InputData with the model points held in policy_data(), and to expose the resulting per-policy values as 1-D numpy arrays whose layout matches the rows of policy_data. Callers therefore index into them with the integer policy index idx.

The Cells fall into two groups by their data source:

Model point attributes, such as product(), issue_age() and sum_assured(), read a column directly from policy_data() and convert it to a NumPy array.
Product-level values, such as int_rate(), table_id() and load_acq_sa_param1(), look up a column in product_spec() keyed by product attributes (e.g. Product, PolType, Gen) and reindex it onto the rows of policy_data before converting it to a NumPy array. These Cells are typically used to build the loadings and rates consumed by gross_prem_rate().

Both groups end with the same array-conversion step. The reindexing and conversion are performed by helper Cells inherited from the Utilities base Space:

map_to_policies() reindexes a Series keyed by lookup columns onto the rows of policy_data, so the result has one entry per policy.
pandas_to_array() then converts that Series into a NumPy array when return_array is True (the default). When return_array is False the pandas object is passed through unchanged, which is convenient for inspection and debugging.

The two pipelines are illustrated below:

        graph LR
    A1["policy_data()['col']<br/>pandas Series<br/>indexed by Policy"]
    A2["product_spec(name)<br/>pandas Series keyed by<br/>(Product, PolType, Gen)"]
    A2 --> B["map_to_policies<br/>reindex onto<br/>policy_data rows"]
    A1 --> C["pandas_to_array<br/>convert when<br/>return_array=True"]
    B --> C
    C --> D["1-D NumPy array<br/>indexed by policy idx"]

For example, issue_age() is implemented as pandas_to_array(input_data.policy_data()['IssueAge']) (top branch), while load_acq_sa_param1() is implemented as pandas_to_array(map_to_policies(input_data.product_spec('LoadAcqSAParam1'))) (bottom branch).

The steps can also be executed individually on a console, which is useful for inspecting the intermediate pandas objects:

>>> pol = m.PolicyAttrs

>>> # Model-point attribute: pick a column from policy_data
>>> s = pol.input_data.policy_data()['IssueAge']
>>> s.head()
Policy
1    30
2    30
3    31
4    31
5    32
Name: IssueAge, dtype: int64
>>> len(s)
300

>>> # Convert to a 1-D NumPy array (return_array is True)
>>> pol.pandas_to_array(s)
array([30, 30, 31, ..., 78, 79, 79])

>>> # Product-level value: look up a column in product_spec
>>> ps = pol.input_data.product_spec('LoadAcqSAParam1')
>>> ps
Product
TERM    0.00
WL      0.02
ENDW    0.02
Name: LoadAcqSAParam1, dtype: float64

>>> # Reindex onto the rows of policy_data
>>> mapped = pol.map_to_policies(ps)
>>> mapped.head()
Policy
1    0.0
2    0.0
3    0.0
4    0.0
5    0.0
Name: LoadAcqSAParam1, dtype: float64
>>> len(mapped)
300

>>> # Convert to a 1-D NumPy array
>>> pol.pandas_to_array(mapped)
array([0.  , 0.  , 0.  , ..., 0.02, 0.02, 0.02])

Composing these calls is exactly what issue_age() and load_acq_sa_param1() return.

Parameters and References#

input_data#: Alias for InputData. Per-policy attributes are read from the PolicyData range in input.xlsx via policy_data(), and product specs from product_spec().

prem_term#: Alias for policy_term().

Inherited helpers

Inherited from Utilities:

Cells Summary#

Policy Attributes#

Model point attributes read directly from policy_data() for each policy.

`product`()	Per-policy product type as a `ProductID` code.
`policy_type`()	Per-policy policy type from the `PolType` column of `policy_data()`.
`sex`()	Per-policy sex as a `SexID` code.
`issue_age`()	Per-policy issue age in years.
`prem_freq`()	Per-policy premium payment frequency (number of payments per year).
`policy_term`()	Per-policy policy term in years.
`policy_count`()	Per-policy number of policies in the model point.
`sum_assured`()	Per-policy sum assured.
`gen`()	Per-policy generation (cohort) identifier.
`channel`()	Per-policy distribution channel.
`duration`()	Per-policy elapsed policy duration in years.

Product Bases#

Per-policy interest rate and mortality table identifiers, selected by rate basis (premium or valuation).

`int_rate`(basis)	Interest Rate
`table_id`(basis)	Mortality Table ID

Loadings#

Per-policy acquisition and maintenance loadings used by gross_prem_rate(), together with the raw ProductSpecTable parameters they are built from.

`load_acq_sa`()	Acquisition Loading per Sum Assured
`load_acq_sa_param1`()	Per-policy `LoadAcqSAParam1` parameter from `ProductSpecTable`.
`load_acq_sa_param2`()	Per-policy `LoadAcqSAParam2` parameter from `ProductSpecTable`.
`load_maint_prem`()	Maintenance Loading per Gross Premium
`load_maint_prem_param1`()	Per-policy `LoadMaintPremParam1` parameter from `ProductSpecTable`.
`load_maint_prem_param2`()	Per-policy `LoadMaintPremParam2` parameter from `ProductSpecTable`.
`load_maint_prem_waiver_prem`()	Maintenance Loading per Gross Premium for Premium Waiver
`load_maint_sa`()	Maintenance Loading per Sum Assured during Premium Payment
`load_maint_sa2`()	Maintenance Loading per Sum Assured during Premium Payment

Surrender Charges#

The per-policy initial surrender charge rate and the raw ProductSpecTable parameters it is built from.

`init_surr_charge`()	Initial Surrender Charge Rate
`surr_charge_param1`()	Per-policy `SurrChargeParam1` parameter from `ProductSpecTable`.
`surr_charge_param2`()	Per-policy `SurrChargeParam2` parameter from `ProductSpecTable`.

Misc#

Placeholder cells reserved for future use.

Warning

gross_prem_table(), reserve_rate() and uern_prem_rate() are placeholders that currently return None and are to be implemented.

`gross_prem_table`()	Gross premium table
`reserve_rate`()	Valuation Reserve Rate per Sum Assured
`uern_prem_rate`()	Unearned Premium Rate

Cells Descriptions#

product()[source]#: Per-policy product type as a ProductID code.

policy_type()[source]#: Per-policy policy type from the PolType column of policy_data().

sex()[source]#: Per-policy sex as a SexID code.

issue_age()[source]#: Per-policy issue age in years.

prem_freq()[source]#: Per-policy premium payment frequency (number of payments per year).

policy_term()[source]#: Per-policy policy term in years.

policy_count()[source]#: Per-policy number of policies in the model point.

sum_assured()[source]#: Per-policy sum assured.

gen()[source]#: Per-policy generation (cohort) identifier.

channel()[source]#: Per-policy distribution channel.

duration()[source]#: Per-policy elapsed policy duration in years.

int_rate(basis)[source]#: Interest Rate

table_id(basis)[source]#: Mortality Table ID

load_acq_sa()[source]#: Acquisition Loading per Sum Assured

load_acq_sa_param1()[source]#: Per-policy LoadAcqSAParam1 parameter from ProductSpecTable.

load_acq_sa_param2()[source]#: Per-policy LoadAcqSAParam2 parameter from ProductSpecTable.

load_maint_prem()[source]#: Maintenance Loading per Gross Premium

load_maint_prem_param1()[source]#: Per-policy LoadMaintPremParam1 parameter from ProductSpecTable.

load_maint_prem_param2()[source]#: Per-policy LoadMaintPremParam2 parameter from ProductSpecTable.

load_maint_prem_waiver_prem()[source]#: Maintenance Loading per Gross Premium for Premium Waiver

load_maint_sa()[source]#: Maintenance Loading per Sum Assured during Premium Payment

load_maint_sa2()[source]#: Maintenance Loading per Sum Assured during Premium Payment

init_surr_charge()[source]#: Initial Surrender Charge Rate

surr_charge_param1()[source]#: Per-policy SurrChargeParam1 parameter from ProductSpecTable.

surr_charge_param2()[source]#: Per-policy SurrChargeParam2 parameter from ProductSpecTable.

gross_prem_table()[source]#: Gross premium table

reserve_rate()[source]#: Valuation Reserve Rate per Sum Assured

uern_prem_rate()[source]#: Unearned Premium Rate