DisabilityTable#

DisabilityTable extends DecrementTable for disability incidence tables. The governing decrement is the inception rate \(i_x\), which represents the probability that an active life aged \(x\) becomes disabled within one year.

Important

Scope — incidence only. DisabilityTable exposes inception rates \(i_x\) and the standard decrement machinery (lx, tpx, modify_ix, …). It does not implement a full three-state Markov model: there are no recovery rates \(r_x\), no disabled-life mortality \(q_x^d\), and no enforcement of \(i_x + q_x \le 1\) when combined with a separate mortality table. For active-life decrements merged with mortality, use LifeTable.modify_qx with table_combination (see Modifying Decrements).

Table files for DisabilityTable are expected to carry \(i_x\) columns (prefixed ix_m, ix_f, or ix_u) and may include generational improvement factors following the same conventions as life tables.

See also

Table Taxonomy — Overview of all table types and decrement conventions.
Using Actuarial Tables — Loading and inspecting tables.
Modifying Decrements — Scaling, aggravated risk, and table_combination.
Mortality Improvement (MI) — Generational tables and improvement factors.

Bases: DecrementTable

Concrete implementation of DecrementTable for disability incidence tables.

DisabilityTable represents actuarial tables for disability incidence (\(i_x\)), where \(i_x\) denotes the probability of becoming disabled between ages \(x\) and \(x+1\). It provides all standard actuarial functions (lx, px, dx, tpx, tqx) but uses disability-specific nomenclature and blocks access to mortality-specific methods (qx, ox, ex).

Construction accepts scalar arguments for a single instance, or sequences for vectorial creation (families, scenarios, pricing grids). See __new__() for full dispatch details.

Parameters:

table_name (str, list, or tuple) – Name of one or more disability table files (without .ltk extension). A list or tuple enables multi-table vectorial creation.
sex (str or sequence of str) – Single sex ('m', 'f', 'u') or sequence for vectorial creation.
cohort (int, sequence of int, or None, optional) – Birth year(s) for generational tables. If None, loads a period table. Broadcast and zip-alignment rules match __new__().
unisex_blend (float, list of float, or None, optional) – Male weight for unisex blending in \([0, 1]\) (0.0 = all female, 1.0 = all male). A list is accepted in zip mode (cartesian=False) to assign a distinct blend to each instance; scalar sex='u' broadcasts to the list length. See __new__().
duration (int, 'ult', sequence, or None, optional) – Duration slice for select-ultimate tables. Pass an integer >= start_duration for a select column, 'ult' for the ultimate column, or None for non-select tables.
cartesian (bool, optional) – If True, create the full Cartesian product of all table_name, sex, cohort, and duration values. All table names must share the same generational structure and the same select structure. With cartesian=True, a unisex_blend sequence is allowed only when every sex value is 'u' (fifth cartesian axis). A scalar unisex_blend is replicated uniformly to all combinations where sex='u'. Default is False (zip/broadcast alignment).
return_dict (bool, optional) – If True, return a dict mapping TableKey to each DisabilityTable instance instead of a plain tuple. Default is False.

Returns:

Single DisabilityTable when sex is a scalar string, table_name is a bare string (not a list/tuple), cohort and duration are scalar or None, no sequence dimensions are provided, and return_dict=False. A tuple when any parameter is a sequence or cartesian=True and return_dict=False (including length-1 tuples). A dict keyed by TableKey when return_dict=True.

Return type:

DisabilityTable or tuple[DisabilityTable, …] or dict

Notes

DisabilityTable uses \(i_x\) (disability incidence) where LifeTable uses \(q_x\) (mortality).
All probability calculations (px, tpx, tqx) work identically to LifeTable.
Inherits the modification system via modify_ix().
Zip mode (default): table_name, sex, cohort, and duration are aligned element-wise (or broadcast when length is 1).
Cartesian mode (cartesian=True): every combination is created — suited to sensitivity grids and pricing studies, not sparse portfolio processing.
A ResourceWarning is emitted when more than 100 instances are created in a single constructor call.

Raises:

FileNotFoundError – If a table file does not exist in the actuarial tables directory.
ValueError – If the table is not a disability table; if cohort, sex, or duration sequences have incompatible lengths; if unisex_blend is out of \([0, 1]\) or provided when sex is not 'u'; if sex='u' and the table lacks a native unisex column while unisex_blend is None; if cartesian=True and table names mix generational and period tables or mix select and non-select tables; or if cartesian=True and unisex_blend is a sequence while sex contains any value other than 'u'.
TypeError – If cohort, duration, sex, or unisex_blend arguments have invalid types.
NotImplementedError – If qx(), ox(), ex(), or modify_qx() are called.

See also

DecrementTable: Abstract base class providing core decrement logic.
TableKey: Structured lookup key for return_dict=True results.
LifeTable: Mortality table implementation.
ExitTable: Exit/withdrawal table implementation.

Examples

>>> from lactuca import DisabilityTable, TableKey
>>> dt = DisabilityTable('DummySD2015Gen', sex='m', cohort=1970)
>>> dt.ix(40) >= 0.0
True
>>> # Zip mode: two sexes
>>> dt_m, dt_f = DisabilityTable('DummySD2015', ('m', 'f'))
>>> # Cartesian product: 2 sex × 2 cohorts → 4 instances
>>> tables = DisabilityTable(
...     'DummySD2015Gen', ('m', 'f'), cohort=[1970, 1980], cartesian=True
... )
>>> len(tables)
4
>>> # Dict return keyed by TableKey
>>> d = DisabilityTable('DummySD2015', ('m', 'f'), return_dict=True)
>>> dt_m = d[TableKey('DummySD2015', 'm')]

ex(x: object = None, m: Literal[1, 2, 3, 4, 6, 12, 14, 24, 26, 52, 365] = 1) → None#

Blocked method: not available for DisabilityTable.

Raises:: NotImplementedError – Always raised. Life expectancy (ex) is not applicable to disability tables.

Notes

Life expectancy is specific to mortality tables; use LifeTable instead.

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable('DummySD2015', sex='m')
>>> try:
...     dt.ex(40)
... except NotImplementedError:
...     pass

See also

LifeTable: Mortality table class with ex support.

ex_curtate(x: object = None) → None#

Blocked method: not available for DisabilityTable.

Raises:: NotImplementedError – Always raised. Curtate life expectancy is not applicable to disability tables.

Notes

Life expectancy is specific to mortality tables; use LifeTable instead.

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable('DummySD2015', sex='m')
>>> try:
...     dt.ex_curtate(40)
... except NotImplementedError:
...     pass

See also

LifeTable: Mortality table class with ex_curtate support.

ix(x: object = None, m: Literal[1, 2, 3, 4, 6, 12, 14, 24, 26, 52, 365] = 1) → object#

Return disability incidence probability at age x.

Computes the probability that an active life aged \(x\) becomes disabled before age \(x + 1/m\), using \(i_x = 1 - p_x\) where \(p_x\) is the probability of remaining active. For fractional periods, uses \(\ell_x\) interpolation.

Parameters:

x (float, int, sequence of float, NDArray[np.float64], or None, optional) – Entry age(s). Pandas and Polars Series are accepted. If None, returns the full incidence array for all integer ages 0 to \(\omega\).
m (PaymentFrequencyLiteral, optional) – Number of periods per year (1, 2, 3, 4, 6, 12, 14, 24, 26, 52, or 365). Default is 1.

Returns:

Disability incidence probability. Scalar when x is a scalar integer; array when x is a sequence or array. Rounded to config.decimals.ix.

Return type:

float or np.ndarray

Notes

For integer ages and m=1, returns the tabulated incidence rate \(i_x\).
For fractional ages or m>1, uses \(\ell_x\) interpolation: \(i_x = 1 - \frac{\ell_{x+1/m}}{\ell_x}\)
If x is None, returns the full rounded incidence array for all ages.
All results rounded to config.decimals.ix.
Consistent with international actuarial practice.

Raises:

ValueError – If any age in x is negative.
TypeError – If x is not numeric, or if m is not a scalar integer.

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable('DummySD2015Gen', sex='m', cohort=1970)
>>> dt.ix(40) >= 0.0
True
>>> bool(dt.ix(40, m=12) >= 0.0)
True
>>> vals = dt.ix([40, 45, 50])
>>> vals.shape
(3,)

See also

DecrementTable.px: Probability of not becoming disabled (complement of \(i_x\)).
DecrementTable.lx: Number of active lives at age \(x\).
DecrementTable.tqx: Probability of disability within t years.

modify_ix(modifications: ModifyDecrement) → None#

Apply modifications to disability incidence rates (ix).

This method allows actuarial adjustments to the base disability table, such as scaling rates, shifting ages, applying aggravated risk factors, or combining with other tables. All modifications are applied to a copy of the base rates and can be reset with reset_modifications().

Parameters:

modifications (dict) –

Dictionary specifying one or more modification operations. See ModifyDecrement TypedDict for supported keys:

’age_shift’int
Shift all ages by N years (drops first N ages).
’decrement_multiplier’float
Multiply all \(i_x\) values by a constant factor.
’decrement_geometric_increase’tuple[float, int]
Apply geometric growth to tail: (growth_rate, start_age).
’aggravated_risk’float
Apply aggravated risk transform: \(p_x \to p_x^{\text{factor}}\).
’table_combination’Union[DecrementTable, list, tuple]
Combine with an ExitTable (or list/tuple of ExitTables) using independent competitive risks (default) or UDD when combination_mode='udd'. DisabilityTable can only combine with ExitTable. Age alignment, host length, implicit zero beyond shorter tables, and rejection rules are identical to modify_qx() — see Modifying Decrements.
’combination_mode’'independent' or 'udd'
Optional actuarial assumption for table_combination; see modify_qx().

Raises:

ValueError – If modification parameters are invalid or produce non-actuarial results.
TypeError – If modification keys or values have incorrect types.

Notes

Modifications are applied in iteration order (dict order in Python 3.7+).
Combined tables must be compatible DecrementTable instances (typically ExitTable) with matching sex.
Final results are rounded to configured decimals (config.decimals.ix).
Non-accumulative: each call to modify_ix replaces any previous modification — it always restarts from the original unmodified base rates. To apply several operations together, pass all keys in a single dict. To run independent experiments without interference, call reset_modifications() between them.

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable("DummySD2015Gen", sex="m", cohort=1970)
>>> base = dt.ix(40)
>>> dt.modify_ix({"decrement_multiplier": 1.2})
>>> dt.ix(40) >= base
True

See also

DecrementTable.reset_modifications: Restore original base rates.

modify_qx(modifications=None) → None#

Blocked method: not available for DisabilityTable.

Raises:: NotImplementedError – Always raised. Use modify_ix() instead.

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable('DummySD2015', sex='m')
>>> try:
...     dt.modify_qx({'decrement_multiplier': 1.1})
... except NotImplementedError as exc:
...     'modify_ix' in str(exc)
True

See also

DisabilityTable.modify_ix: Apply actuarial modifications to disability incidence rates.

ox(x: object = None, m: Literal[1, 2, 3, 4, 6, 12, 14, 24, 26, 52, 365] = 1) → None#

Blocked method: not available for DisabilityTable.

Raises:: NotImplementedError – Always raised. Use ix() instead.

Notes

DisabilityTable does not support exit rates (ox).

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable('DummySD2015', sex='m')
>>> try:
...     dt.ox(40)
... except NotImplementedError as exc:
...     'ix' in str(exc)
True

See also

DisabilityTable.ix: Disability incidence probability.
ExitTable: Exit/withdrawal table class for exit rates.

qx(x: object = None, m: Literal[1, 2, 3, 4, 6, 12, 14, 24, 26, 52, 365] = 1) → None#

Blocked method: not available for DisabilityTable.

Raises:: NotImplementedError – Always raised. Use ix() instead.

Notes

DisabilityTable uses ix (disability incidence) instead of qx (mortality).

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable('DummySD2015', sex='m')
>>> try:
...     dt.qx(40)
... except NotImplementedError as exc:
...     'ix' in str(exc)
True

See also

DisabilityTable.ix: Disability incidence probability (replacement for \(q_x\)).

summary() → str#

Return a formatted summary of the disability table state and sample ix values.

Calls summary() for the common header block, then appends:

Decimals: ix=<n>
Sample ix values for the first and last 5 ages. When a modification is active, each line shows both the current and the original base value:
```
ix(40) = 0.00600 (original: 0.00500)
```
Without a modification the parenthetical is omitted.

Returns:: Multi-line summary string.
Return type:: str

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable("DummySD2015", sex="m")
>>> summary = dt.summary()
>>> "Decimals: ix=" in summary
True
>>> "Sample ix values (first 5):" in summary
True

See also

DecrementTable.reset_modifications: Restore base rates and clear modification state.
DisabilityTable.modify_ix: Apply modifications.

property decimals: _DecimalsConfig#

Access decimal precision settings for disability table actuarial functions.

This property provides convenient attribute-based access to global decimal precision configuration. All values are proxied dynamically from the Config singleton — no state is stored locally in the table instance. Commutation functions, mortality, life-expectancy, and exit-rate attributes are blocked and raise AttributeError.

Returns:

Decimal-precision proxy with attributes for disability-table actuarial columns. Available attributes:

ix : int — Disability incidence \(i_x\) precision
lx : int — Survival function \(\ell_x\) precision
dx : int — Decrements \(d_x\) precision
px : int — Survival probability \(p_x\) precision
tpx : int — Multi-year survival \({}_t p_x\) precision
tqx : int — Multi-year decrement \({}_t q_x\) precision

Return type:

object

Raises:

AttributeError – If accessing a blocked property: qx, ox, ex, Lx, Tx, Dx, Nx, Sx, Cx, Mx, Rx, annuities, or insurances.

Notes

Read-only proxy: self.decimals.xxx = value raises AttributeError by design; use Config().decimals.xxx = value to change precision globally.
Global scope: Changes to Config.decimals are immediately visible through all table instances.
For permanent changes, use Config().decimals.ix = value or Config().set('decimals_ix', value).

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable('DummySD2015', sex='m')
>>> isinstance(dt.decimals.ix, int)
True
>>> isinstance(dt.decimals.px, int)
True

See also

Config.decimals: Global decimal precision configuration.

property table_type: str#

Return the type identifier for this decrement table.

Returns:: Always returns ‘disability’ for DisabilityTable instances.
Return type:: str

Notes

Used for table identification and metadata display.
Immutable property; cannot be modified after instantiation.

Examples

>>> from lactuca import DisabilityTable
>>> dt = DisabilityTable('DummySD2015', sex='m')
>>> dt.table_type
'disability'

See also

DecrementTable: Base class providing core decrement logic.

DisabilityTable-specific members#

These members are defined on DisabilityTable itself and are not present on DecrementTable.

Actuarial methods#

`ix`	Return disability incidence probability at age x.

Modification#

modify_ix

Apply modifications to disability incidence rates (ix).

Inherited from DecrementTable#

The following members are inherited from DecrementTable. See the DecrementTable reference for full documentation of each member.

Note

qx, ox, ex, ex_curtate, and modify_qx are not available on DisabilityTable — the primary decrement is ix (disability incidence rate). Calling any of the blocked methods raises NotImplementedError.

Actuarial methods#

`lx`	Return lx values (number of lives at age x) for the specified age(s).
`px`	Return probability of surviving one period (px) at age x.
`tpx`	Return interval survival probability tpx for all (x, t) combinations.
`tqx`	Return interval death probability tqx for all (x, t) combinations.
`dx`	Return \(d_x\) values (number of decrements between ages \(x\) and \(x+1\)).

Modification#

`reset_modifications`	Restore decrement to the original base values and clear all caches.
`copy`	Return a deep copy of the instance.

Display#

`view_data`	Return the computed instance data, optionally excluding normalized padding rows.
`head`	Return the first n rows of the computed instance data.
`tail`	Return the last n rows of the computed instance data, always ending at w.

State#

`sex`	Current sex used for calculations.
`cohort`	Current cohort (year of birth) for generational tables.
`duration`	Return the current policy duration for select or non-select tables.
`unisex_blend`	Male weight used to blend male/female rates into unisex rates.
`w`	Current upper age limit (omega), accounting for modifications.
`modified`	True if a modification is currently active on this table.
`modifications_applied`	List of modification descriptors applied in the current call.
`is_select`	Return True if the underlying table is a select-ultimate table.
`metadata_pending`	True when required metadata has not yet been supplied via configure() or setters.

Deferred construction#

`configure`	Configure table metadata atomically with a single rebuild.
`batch_update`	Context manager to batch multiple setter assignments into one rebuild.

Table metadata#

`table_name`	Name of the underlying actuarial table.
`table`	Access the underlying TableSource instance with table data and metadata.
`generational`	Whether the table includes cohort-based improvement factors.
`base_year`	Base year for generational improvement.
`omega`	Original terminal age from metadata (immutable).
`start_age`	Minimum defined age in the original table.
`description`	Human-readable table description from metadata.
`valid_sexes`	Valid sexes for this table (e.g. `['m', 'f']`).
`sex_independent`	Whether rates are identical for both sexes.
`generational_formula_type`	Generational improvement formula type.
`select`	Whether this is a select-ultimate table.
`select_period`	Select period in years.
`select_improvement_diagonal`	Calendar-year index for generational improvement on select columns.
`start_duration`	Minimum integer duration.
`mi_by_duration`	Whether improvement factors are stored by policy duration.
`mi_structure`	Mortality improvement column layout tag.
`grid_years`	Projection calendar years for year-indexed MI tables.
`file_name`	Basename of the loaded table file.
`file_path`	Absolute path to the loaded table file.
`data`	Raw underlying table data (all columns, all sexes).
`metadata`	Raw metadata dictionary from the table file.