Docs/issue 704 tailconstant examples

chainladder/tails/constant.py

@@ -43,6 +43,83 @@ class TailConstant(TailBase):
     --------
     TailCurve
 
+    Examples
+    --------
+
+    Applying a 5% tail factor to the RAA sample triangle. The ``tail_``
+    attribute returns the point estimate of the tail at the latest maturity,
+    while ``ldf_`` and ``cdf_`` are extended to include the tail.
+
+    .. testsetup::
+
+        import chainladder as cl
+
+    .. testcode::
+
+        raa = cl.load_sample('raa')
+        dev = cl.Development().fit_transform(raa)
+        tail = cl.TailConstant(tail=1.05).fit(dev)
+        print(tail.tail_)
+
+    .. testoutput::
+
+               120-Ult
+        (All)     1.05
+
+    .. testcode::
+
+        print(tail.cdf_)
+
+    .. testoutput::
+
+                 12-Ult    24-Ult    36-Ult    48-Ult    60-Ult    72-Ult   84-Ult    96-Ult   108-Ult  120-Ult  132-Ult
+        (All)  9.366246  3.122749  1.923441  1.513462  1.291708  1.160163  1.11347  1.077625  1.059677     1.05  1.02538
+
+    Using ``decay`` to control how the tail factor is distributed across
+    future development periods. A higher ``decay`` rate retains more of the
+    tail factor in the immediately following development period rather than
+    spreading it out evenly. Compare the ``120-132`` and ``132-144`` LDFs
+    below against the default ``decay=0.5``.
+
+    .. testcode::
+
+        tail = cl.TailConstant(tail=1.10, decay=0.75).fit(dev)
+        print(tail.ldf_)
+
+    .. testoutput::
+
+                  12-24     24-36     36-48     48-60     60-72     72-84     84-96    96-108   108-120   120-132   132-144
+        (All)  2.999359  1.623523  1.270888  1.171675  1.113385  1.041935  1.033264  1.016936  1.009217  1.023512  1.074731
+
+    Using ``attachment_age`` to attach the tail at an earlier development age
+    than the latest available. Below, the tail is attached at age 72 instead
+    of the default 120, so ages 84 onward are filled with the decayed tail
+    factors rather than the original LDFs.
+
+    .. testcode::
+
+        tail = cl.TailConstant(tail=1.05, attachment_age=72).fit(dev)
+        print(tail.cdf_)
+
+    .. testoutput::
+
+                 12-Ult    24-Ult  36-Ult    48-Ult    60-Ult  72-Ult   84-Ult    96-Ult  108-Ult   120-Ult   132-Ult
+        (All)  8.476874  2.826229  1.7408  1.369751  1.169054    1.05  1.02538  1.013216  1.00717  1.004156  1.002652
+
+    Using ``projection_period`` to extend the ``ldf_`` and ``cdf_`` vectors
+    further beyond the latest available development age. Below, the projection
+    is extended by 36 months instead of the default 12, adding two extra
+    development columns to ``cdf_``.
+
+    .. testcode::
+
+        tail = cl.TailConstant(tail=1.05, projection_period=36).fit(dev)
+        print(tail.cdf_)
+
+    .. testoutput::
+
+                 12-Ult    24-Ult    36-Ult    48-Ult    60-Ult    72-Ult   84-Ult    96-Ult   108-Ult  120-Ult  132-Ult   144-Ult  156-Ult
+        (All)  9.366246  3.122749  1.923441  1.513462  1.291708  1.160163  1.11347  1.077625  1.059677     1.05  1.02538  1.013216  1.00717
     """
 
     def __init__(self, tail=1.0, decay=0.5, attachment_age=None, projection_period=12):