## kernels.ConventionalCandidate


Settings held fixed when a candidate is refitted at successive dates.


Usage

``` python
kernels.ConventionalCandidate(
    method="cl",
    history_periods=None,
    average="volume",
    drop_high=0,
    drop_low=0,
    exclude=(),
    expected_loss_ratio=None,
    decay=None,
    horizon=None,
    unsupported_factor="raise",
    exhausted_exclusions="raise",
    zero_cells="observed",
    preserve=1,
    drop_above=None,
    drop_below=None,
    exclude_valuations=(),
    trim_ties="origin",
    n_iters=1,
    trend=0.0,
    tail=None
)
```


`history_periods` selects the most recent usable paired origins at EACH age (under `zero_cells="missing"`, the most recent paired origins, a pair left out for a zero cell keeping its place, as chainladder-python counts them). `exclude` identifies link ratios by (origin, FROM development lag in months). `horizon` is the final development lag in months, with no tail beyond it; omitted, it is the deepest observed age of this particular fit. Replays require an explicit horizon to keep the target fixed through time.

`zero_cells` says what a cumulative of exactly zero is. `"observed"` (the default) keeps it as data: the link ratio INTO a zero is 0 and is used, and the link ratio OUT of a zero is undefined and left out with reason `"undefined_ratio"`. `"missing"` follows chainladder-python, which stores a zero cell as missing: a link ratio is used only when neither of its two cells is zero, and both the link into a zero and the link out of it are left out with reason `"zero_cell"`. A zero on an origin's latest diagonal is still its latest amount under either rule, so its chain-ladder ultimate is 0 (chainladder-python leaves that ultimate missing instead).

The link-ratio options (`history_periods`, `exclude`, `exclude_valuations`, `drop_above`, `drop_below`, `drop_high`, `drop_low`, `preserve`, `trim_ties`, `exhausted_exclusions` and `zero_cells`) are checked and applied by `kernels.links`, whose docstring gives the order they run in; [link_rules](kernels.ConventionalCandidate.md#ibnr.kernels.ConventionalCandidate.link_rules) holds them as one `~ibnr.kernels.links.LinkRules`. `drop_high` and `drop_low` are counts, and `True` is stored as 1. `trim_ties` defaults to `"origin"`, the tie rule of 0.7.2. `average` may also be `"regression"`.

`n_iters` (`"bf"` and `"gcc"` only) is the number of Benktander iterations: 1 is the method itself, and each further one uses the last ultimate as the a priori ultimate, at most `MAX_N_ITERS` (10,000). `trend` (`"gcc"` only) is an annual rate: each origin's losses are moved to the valuation date's level by `(1 + trend)` a year from the end of the origin period before the loss ratios are pooled, and each pooled ratio is brought back to its origin's level after.

`tail` (a `~ibnr.kernels.tail.TailSpec`) extends the pattern past the last observed age: the link factors are estimated first, the tail is applied to them (replacing the links from its attachment age on, when that is before the last age), and every origin's development to ultimate then includes the tail factor, the oldest origin's too. Chain ladder, Bornhuetter-Ferguson, Benktander and Cape Cod all read it through the pattern. A tail cannot be combined with `horizon`, and its `sigma` and `std_err` are Mack settings, refused here.


## Parameter Attributes


`method: str = ``"cl"`  

`history_periods: int | None = None`  

`average: str = ``"volume"`  

`drop_high: int = ``0`  

`drop_low: int = ``0`  

`exclude: tuple[tuple[dt.date, int], …] = ()`\  

`expected_loss_ratio: float | None = None`  

`decay: float | None = None`  

`horizon: int | None = None`  

`unsupported_factor: str = ``"raise"`  

`exhausted_exclusions: str = ``"raise"`  

`zero_cells: str = ``"observed"`  

`preserve: int = ``1`  

`drop_above: float | None = None`  

`drop_below: float | None = None`  

`exclude_valuations: tuple[dt.date, …] = ()`\  

`trim_ties: str = ``"origin"`  

`n_iters: int = ``1`  

`trend: float = ``0.0`  

`tail: TailSpec | None = None`  


## Attributes

| Name | Description |
|----|----|
| [link_rules](#link_rules) | The link-ratio options as one `~ibnr.kernels.links.LinkRules`. |

------------------------------------------------------------------------


#### link_rules


The link-ratio options as one `~ibnr.kernels.links.LinkRules`.


`link_rules: LinkRules`


Built when read rather than stored, so `vars(candidate)` holds the fields alone and `ConventionalCandidate(**vars(candidate))` works.
