aggregate 2.0.0__tar.gz → 2.1.0__tar.gz

{aggregate-2.0.0/src/aggregate.egg-info → aggregate-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aggregate
-Version: 2.0.0
+Version: 2.1.0
 Summary: Tools for creating and working with aggregate probability distributions.
 Author-email: "Stephen J. Mildenhall" <mynl@me.com>
 Maintainer-email: "Stephen J. Mildenhall" <mynl@me.com>
@@ -61,7 +61,7 @@ Requires-Dist: datashader; extra == "viz"
 Requires-Dist: holoviews; extra == "viz"
 Requires-Dist: bokeh; extra == "viz"
 Provides-Extra: elt
-Requires-Dist: eltq>=2.13; extra == "elt"
+Requires-Dist: eltq>=2.15; extra == "elt"
 Provides-Extra: all
 Requires-Dist: aggregate[elt,massive,notebook,numba,viz]; extra == "all"
 Dynamic: license-file

{aggregate-2.0.0 → aggregate-2.1.0}/pyproject.toml

@@ -115,7 +115,7 @@ viz = [
 # import. A `uv sync` replaces a local eltq build with the published wheel, so
 # re-install a checkout after syncing to test an unreleased change.
 elt = [
-    "eltq>=2.13",
+    "eltq>=2.15",
 ]
 # Every user-facing extra in one shot. Self-referencing so the lists cannot
 # drift; deliberately excludes `dev` (docs build and test tooling).

{aggregate-2.0.0 → aggregate-2.1.0}/src/aggregate/__init__.py

@@ -61,7 +61,7 @@ __status__    = "beta"
 # The one place the version is written. A plain literal on purpose: setuptools
 # reads it statically for the wheel, and running code reports it live, so an
 # editable install never reports a stale number after a bump.
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 
 
 __doc__ = """

{aggregate-2.0.0 → aggregate-2.1.0}/src/aggregate/_aggregate.py

@@ -8477,8 +8477,7 @@ class Aggregate(HelpMixin, LabeledMixin, ProgramMixin):
             reins_view=reins_view)
 
     def calibrate_distortions(self, coc=None, *, lr=None, p=None, a=None,
-                              kind='lower',
-                              names=_pricing.DEFAULT_CALIBRATION_DISTORTIONS,
+                              kind='lower', names=None, extended=False,
                               reins_view=None):
         """Calibrate the standard pricing distortion set to a pricing target.
 
@@ -8505,6 +8504,12 @@ class Aggregate(HelpMixin, LabeledMixin, ProgramMixin):
             Asset level; snapped to the grid. Exactly one of ``p`` or ``a``.
         kind : {'lower', 'upper'}, optional
             VaR kind when ``p`` is provided. Default ``'lower'``.
+        names : sequence of str, optional
+            The distortion families to calibrate, in order. Default ``None``,
+            the standard set ``ccoc``, ``ph``, ``wang``, ``dual``, ``tvar``.
+        extended : bool, default False
+            Calibrate the extended set, the standard set with ``tsallis``
+            between ``wang`` and ``dual``. Raises ``ValueError`` with ``names``.
         reins_view : str, optional
             Which of a cession's distributions to calibrate on, one of
             :attr:`reins_views`. The default ``None`` is this aggregate's own
@@ -8515,8 +8520,8 @@ class Aggregate(HelpMixin, LabeledMixin, ProgramMixin):
         Returns
         -------
         CalibrationResult
-            Carrying ``distortion_df`` (one row per distortion in
-            ``[ccoc, ph, wang, dual, tvar]``), the shared one-row
+            Carrying ``distortion_df`` (one row per calibrated family, by
+            default ``[ccoc, ph, wang, dual, tvar]``), the shared one-row
             ``calibration_df`` target, the ``distortions`` themselves, and the
             inputs they were fitted at. The same three are stored on
             ``self.distortion_df`` / ``self.calibration_df`` /
@@ -8555,6 +8560,7 @@ class Aggregate(HelpMixin, LabeledMixin, ProgramMixin):
         """
         return _pricing.calibrate_distortions(self, coc, lr=lr, p=p, a=a,
                                               kind=kind, names=names,
+                                              extended=extended,
                                               reins_view=reins_view)
 
     def evaluate(self, P=None, *, p=None, a=None, names=None,
@@ -8564,7 +8570,7 @@ class Aggregate(HelpMixin, LabeledMixin, ProgramMixin):
         Pricing asks what the obligation is worth; evaluation asks how much
         stress the position you hold survives. Solves, per distortion family,
         for the shape at which the risk-adjusted margin reaches 0. The
-        breakeven ``gini_p`` is the family-agnostic acceptability index of
+        breakeven ``gini`` is the family-agnostic acceptability index of
         Cherny and Madan.
 
         Parameters
@@ -8601,7 +8607,7 @@ class Aggregate(HelpMixin, LabeledMixin, ProgramMixin):
             Carrying ``evaluation_df``, the panel: tidy (long) form,
             ``MultiIndex`` rows ``(Step, distortion)`` with ``Step`` this
             aggregate's name, and columns ``role`` / ``param_name`` /
-            ``param`` / ``gini_p`` / ``error`` / ``status``. ``role`` is
+            ``param`` / ``gini`` / ``error`` / ``status``. ``role`` is
             always ``'sell'`` here: an aggregate is an obligation written, so
             the position is held the way it is booked. The same shape
             :meth:`PnL.evaluate` and :meth:`Portfolio.evaluate` return, so

{aggregate-2.0.0 → aggregate-2.1.0}/src/aggregate/_loss_table.py

@@ -58,9 +58,9 @@ MAX_EXAMPLES = 5
 ELT_FORMS = {3: 'ELT3', 4: 'ELT4', 6: 'ELT6'}
 YELT_FORMS = {2: 'YELT2', 3: 'YELT3'}
 
-#: The oldest eltq with every function the ELT6 path calls; 2.13.0 added
-#: ``multiunit_moments``.
-ELTQ_MIN_VERSION = (2, 13, 0)
+#: The oldest eltq with every function the ELT6 path calls; 2.15.0 added
+#: ``density_arrays``, the severity's ``pdf``.
+ELTQ_MIN_VERSION = (2, 15, 0)
 
 #: Relative tolerance on the shared-event moment integration, eltq's
 #: ``multiunit_moments`` ``rtol`` on ``C_2`` and ``C_3``, under the Burke rule.

{aggregate-2.0.0 → aggregate-2.1.0}/src/aggregate/_pnl.py

@@ -3336,13 +3336,13 @@ class PnL(HelpMixin, LabeledMixin, ProgramMixin):
 
         A P&L is **evaluated, not priced**: you ask which distortion drives the
         risk-adjusted margin to zero, the breakeven stress the position
-        survives. The breakeven ``gini_p`` is the single family-agnostic
+        survives. The breakeven ``gini`` is the single family-agnostic
         acceptability index (Cherny & Madan).
 
         Every **margin row of the ledger** is evaluated, not just the grand
         result, so a tower reads as a story: the gross deal, each reinsurance
         layer as a position in its own right, and the running net after each
-        purchase. Reading a ``gini_p`` column down the ``net through ...`` rows
+        purchase. Reading a ``gini`` column down the ``net through ...`` rows
         is watching what buying cover does to the deal.
 
         A ceded layer is evaluated **from the seller's side** (:meth:`_row_role`
@@ -3351,7 +3351,7 @@ class PnL(HelpMixin, LabeledMixin, ProgramMixin):
         column says which rows those are: ``buy`` for a cession, ``sell`` for a
         book written, ``net`` for a running net or the grand result, which net
         the two against each other. That is what makes the panel a buy decision:
-        a layer whose ``gini_p`` sits **above** the ``net`` row immediately over
+        a layer whose ``gini`` sits **above** the ``net`` row immediately over
         it is priced above the holder's own acceptability, so buying it lowers
         the net, and one below it raises the net.
 
@@ -3373,7 +3373,7 @@ class PnL(HelpMixin, LabeledMixin, ProgramMixin):
         EvaluationResult
             Carrying ``evaluation_df``, the panel: tidy (long) form,
             ``MultiIndex`` rows ``(Step, distortion)`` and columns ``role`` /
-            ``param_name`` / ``param`` / ``gini_p`` / ``error`` / ``status``.
+            ``param_name`` / ``param`` / ``gini`` / ``error`` / ``status``.
             ``.unstack('distortion')`` on it gives the wide comparison view.
             ``premium`` on the result is ``None``: every ledger row carries
             its own consideration and no single number stands for them.

{aggregate-2.0.0 → aggregate-2.1.0}/src/aggregate/_portfolio.py

@@ -3563,8 +3563,7 @@ class Portfolio(HelpMixin, LabeledMixin, ProgramMixin):
         return _density.add_exa(self, df, unit_state)
 
     def calibrate_distortions(self, coc=None, *, lr=None, p=None, a=None,
-                              kind='lower',
-                              names=_pricing.DEFAULT_CALIBRATION_DISTORTIONS,
+                              kind='lower', names=None, extended=False,
                               reins_view=None):
         """
         Calibrate the standard pricing distortion set to a pricing target.
@@ -3587,6 +3586,12 @@ class Portfolio(HelpMixin, LabeledMixin, ProgramMixin):
             must be provided.
         kind : {'lower', 'upper'}, optional
             VaR kind when ``p`` is provided. Default ``'lower'``.
+        names : sequence of str, optional
+            The distortion families to calibrate, in order. Default ``None``,
+            the standard set ``ccoc``, ``ph``, ``wang``, ``dual``, ``tvar``.
+        extended : bool, default False
+            Calibrate the extended set, the standard set with ``tsallis``
+            between ``wang`` and ``dual``. Raises ``ValueError`` with ``names``.
         reins_view : str, optional
             Which of the book's reinsurance views to calibrate on, one of
             :attr:`reins_views` (``gross`` / ``ceded`` / ``net``). The default
@@ -3598,13 +3603,13 @@ class Portfolio(HelpMixin, LabeledMixin, ProgramMixin):
         -------
         CalibrationResult
             Carrying the per-distortion calibration receipt ``distortion_df``
-            (also stored on ``self.distortion_df``): one row per distortion in
-            ``[ccoc, ph, wang, dual, tvar]``, index named ``distortion`` (an
+            (also stored on ``self.distortion_df``): one row per calibrated
+            family, by default ``[ccoc, ph, wang, dual, tvar]``, index named ``distortion`` (an
             ordered categorical, canonical sort), columns
-            ``[param_name, param, error, gini_p, area]``. ``param`` is the raw
+            ``[param_name, param, error, gini, area]``. ``param`` is the raw
             shape (``param_name`` says what it is per family); ``error`` is the
-            premium miss; ``gini_p`` is the comparable normalised shape
-            ``= 2∫g−1 = p_equiv`` (TVaR-equivalent level); ``area = (gini_p+1)/2
+            premium miss; ``gini`` is the comparable normalised shape
+            ``= 2∫g−1 = p_equiv`` (TVaR-equivalent level); ``area = (gini+1)/2
             = ∫g``. The result also carries ``calibration_df``, the
             ``distortions``, the inputs, and the lazily computed allocation of
             the target across units (``pricing_df``).
@@ -3637,6 +3642,7 @@ class Portfolio(HelpMixin, LabeledMixin, ProgramMixin):
         """
         return _pricing.calibrate_distortions(self, coc, lr=lr, p=p, a=a,
                                               kind=kind, names=names,
+                                              extended=extended,
                                               reins_view=reins_view)
 
     def evaluate(self, P=None, *, unit='total', p=None, a=None, names=None,
@@ -3689,7 +3695,7 @@ class Portfolio(HelpMixin, LabeledMixin, ProgramMixin):
             Carrying ``evaluation_df``, the panel: tidy (long) form,
             ``MultiIndex`` rows ``(Step, distortion)``, one ``Step`` per
             evaluated unit, and columns ``role`` / ``param_name`` / ``param`` /
-            ``gini_p`` / ``error`` / ``status``. ``role`` is always ``'sell'``:
+            ``gini`` / ``error`` / ``status``. ``role`` is always ``'sell'``:
             every unit is an obligation written. With a ``reins_view`` each
             ``Step`` is suffixed by it, so panels for several views concatenate
             without collapsing.

{aggregate-2.0.0 → aggregate-2.1.0}/src/aggregate/_pricing.py

@@ -23,6 +23,9 @@ from .results import CalibrationResult
 
 # The standard pricing distortion set calibrated by ``calibrate_distortions``.
 DEFAULT_CALIBRATION_DISTORTIONS = ('ccoc', 'ph', 'wang', 'dual', 'tvar')
+# The standard set with ``tsallis`` in registry order, between ``wang`` and
+# ``dual``.
+EXTENDED_CALIBRATION_DISTORTIONS = ('ccoc', 'ph', 'wang', 'tsallis', 'dual', 'tvar')
 
 
 def guard_unbounded_anchor(obj, p, *, where):
@@ -702,12 +705,12 @@ def _calibration_frames(dists, coc, p_val, Fa, exa, P, a):
     for dname in names:
         dist = dists[dname]
         # param_name is the family's natural parameter ('a', 'lam', 'b', 'p');
-        # ccoc has none -> 'r'. gini_p = 2∫g - 1 (= p_equiv); area = ∫g.
-        rows.append([_param_name(dist), dist.shape, dist.error, dist.gini_p,
-                     (dist.gini_p + 1) / 2])
+        # ccoc has none -> 'r'. gini = 2∫g - 1 (= p_equiv); area = ∫g.
+        rows.append([_param_name(dist), dist.shape, dist.error, dist.gini,
+                     (dist.gini + 1) / 2])
     distortion_df = pd.DataFrame(
         rows,
-        columns=['param_name', 'param', 'error', 'gini_p', 'area'],
+        columns=['param_name', 'param', 'error', 'gini', 'area'],
         index=pd.CategoricalIndex(names, dtype=DISTORTION_DTYPE, name='distortion'),
     )
     calibration_df = complete_pentagon(
@@ -817,12 +820,18 @@ def _coc_from_lr(L, a, lr):
 
 
 def calibrate_distortions(obj, coc=None, *, lr=None, p=None, a=None,
-                          kind='lower',
-                          names=DEFAULT_CALIBRATION_DISTORTIONS,
+                          kind='lower', names=None, extended=False,
                           reins_view=None):
     """Calibrate the standard pricing distortion set to a pricing target on a
     single distribution (an ``Aggregate`` or a ``Portfolio`` total).
 
+    **The families** are ``names`` when given, and otherwise
+    :data:`DEFAULT_CALIBRATION_DISTORTIONS`, or
+    :data:`EXTENDED_CALIBRATION_DISTORTIONS` with ``extended=True``, which adds
+    ``tsallis`` between ``wang`` and ``dual``. ``names`` together with
+    ``extended=True`` raises ``ValueError``: the two choose the same thing, and
+    ignoring either would hide a mistake.
+
     Resolves the asset level ``a`` (from ``p`` or given), the expected loss
     ``exa = E[min(X, a)]`` and the premium target ``P`` (from ``coc`` via the
     ROE -> LR -> P inversion), then calls :meth:`Distortion.calibrate_set` once.
@@ -913,6 +922,13 @@ def calibrate_distortions(obj, coc=None, *, lr=None, p=None, a=None,
     artifact of the grid, so the reader means the loss ratio on the premium
     they are shown.
     """
+    if names is None:
+        names = (EXTENDED_CALIBRATION_DISTORTIONS if extended
+                 else DEFAULT_CALIBRATION_DISTORTIONS)
+    elif extended:
+        raise ValueError(
+            'calibrate_distortions takes names= or extended=True, not both: '
+            f'extended=True is the families {EXTENDED_CALIBRATION_DISTORTIONS}.')
     if (p is None) == (a is None):
         raise ValueError(
             'calibrate_distortions requires exactly one of p= (probability) '
@@ -1087,8 +1103,8 @@ EVAL_SIGN = {'sell': 1.0, 'buy': -1.0, 'net': 1.0}
 #: ``(step, family)``: ``param`` holds each family's own natural parameter, so
 #: it is a pure column only at this grain. ``role`` leads because it qualifies
 #: the whole row, naming whose position the parameters describe.
-#: ``area = (gini_p + 1) / 2`` is not carried, being a restatement of ``gini_p``.
-EVAL_COLS = ['role', 'param_name', 'param', 'gini_p', 'error', 'status']
+#: ``area = (gini + 1) / 2`` is not carried, being a restatement of ``gini``.
+EVAL_COLS = ['role', 'param_name', 'param', 'gini', 'error', 'status']
 
 
 def _eval_sign(role):
@@ -1118,7 +1134,7 @@ def evaluate_margin(gd, *, role='sell', names=None):
 
     Solves, per distortion family, for the shape at which the risk-adjusted
     margin reaches 0: the most stress the position survives. The breakeven
-    ``gini_p`` is the family-agnostic acceptability index.
+    ``gini`` is the family-agnostic acceptability index.
 
     Parameters
     ----------
@@ -1329,7 +1345,7 @@ def _evaluate_margin_arrays(x, p, bs, *, role='sell', names=None):
     rows = []
     for nm in names:
         d = dists[nm]
-        rows.append([role, _param_name(d), d.shape, d.gini_p, d.error, 'ok'])
+        rows.append([role, _param_name(d), d.shape, d.gini, d.error, 'ok'])
     return _eval_panel(rows, names)
 
 

{aggregate-2.0.0 → aggregate-2.1.0}/src/aggregate/_reinsurance.py

@@ -214,6 +214,73 @@ def make_ceder_netter(reins_list, debug=False):
         return ceder, netter
 
 
+def flat_run_end(reins_list, view, x, tol=1e-9):
+    """Right end of the stretch on which the net or ceded loss is constant at ``x``.
+
+    Parameters
+    ----------
+    reins_list : list of (share, limit, attach)
+        The program, validated as :func:`make_ceder_netter` validates it.
+    view : {'net', 'ceded'}
+        Which function of the subject loss.
+    x : float or array_like
+        Subject (gross) losses, nonnegative.
+    tol : float
+        Tolerance for joining two stretches that touch.
+
+    Returns
+    -------
+    numpy.ndarray
+        For each ``x``, :math:`r = \\sup\\{u : g(u) \\le g(x)\\}` with
+        :math:`g` the net or ceded function: the right end of the stretch of
+        constant :math:`g` containing ``x``, ``inf`` when :math:`g` stays
+        constant to infinity, and ``x`` itself where :math:`g` increases.
+
+    Notes
+    -----
+    With shares at most 100% and layers that do not overlap, both functions
+    are nondecreasing and piecewise linear, so :math:`\\{g(X) > g(x)\\} =
+    \\{X > r\\}` and :math:`\\Pr(g(X) > g(x)) = S(r)`. The net function is
+    constant across a layer placed at 100%. The ceded function is constant
+    below the first attachment, across a gap or a zero share layer, and above
+    the top of a finite program. Stretches that touch, such as two contiguous
+    layers at 100%, are joined. The stretches are read from the layer tuples
+    rather than from the knots of :func:`make_ceder_netter`, whose stand-in
+    for infinity loses the net function's value at an unlimited layer.
+    """
+    if view not in ('net', 'ceded'):
+        raise ValueError(f"view must be 'net' or 'ceded', not {view!r}")
+    _validate_reins_layers(reins_list)
+    flat = []
+    top = 0.0
+    for share, limit, attach in reins_list:
+        end = attach + limit
+        if view == 'net' and share >= 1:
+            flat.append((attach, end))
+        elif view == 'ceded':
+            if attach > top:
+                flat.append((top, attach))
+            if share <= 0:
+                flat.append((attach, end))
+        top = end
+    if view == 'ceded':
+        if not reins_list:
+            flat.append((0.0, np.inf))
+        elif np.isfinite(top):
+            flat.append((top, np.inf))
+    runs = []
+    for lo, hi in sorted(flat):
+        if runs and lo <= runs[-1][1] + tol:
+            runs[-1][1] = max(runs[-1][1], hi)
+        else:
+            runs.append([lo, hi])
+    x = np.asarray(x, dtype=float)
+    r = x.copy()
+    for lo, hi in runs:
+        r = np.where((x >= lo) & (x <= hi), np.maximum(r, hi), r)
+    return r
+
+
 # ====================================================================
 # Apply engine: ceder/netter convolution onto the model grid
 # ====================================================================