docs: add Triangle shape/empty/compute examples (#704)

chainladder/core/base.py

@@ -60,6 +60,26 @@
 
     @property
     def shape(self):
+        """The 4-D shape of the Triangle: ``(index, columns, origin, development)``.
+
+        Examples
+        --------
+        A single-triangle sample such as RAA has one index and one column.
+
+        .. testsetup::
+
+            import chainladder as cl
+
+        .. testcode::
+
+            print(cl.load_sample('raa').shape)
+            print(cl.load_sample('clrd').shape)
+
+        .. testoutput::
+
+            (1, 1, 10, 10)
+            (775, 6, 10, 10)
+        """
         return self.values.shape
 
     @property
@@ -69,6 +89,24 @@
         Returns ``'empty'`` for a Triangle instantiated without data
         (e.g. ``cl.Triangle()``), ``'single'`` for a Triangle holding a
         single triangle, and ``'multi'`` for a multidimensional Triangle.
+
+        Examples
+        --------
+        .. testsetup::
+
+            import chainladder as cl
+
+        .. testcode::
+
+            print(cl.Triangle().dimensionality)
+            print(cl.load_sample('raa').dimensionality)
+            print(cl.load_sample('clrd').dimensionality)
+
+        .. testoutput::
+
+            empty
+            single
+            multi
         """
         return self._dimensionality
 
@@ -79,6 +117,22 @@
         Mirrors ``pandas.DataFrame.empty``. Returns ``True`` for a Triangle
         instantiated without data (e.g. ``cl.Triangle()``), whose ``values``
         have not been populated, and ``False`` otherwise.
+
+        Examples
+        --------
+        .. testsetup::
+
+            import chainladder as cl
+
+        .. testcode::
+
+            print(cl.Triangle().empty)
+            print(cl.load_sample('raa').empty)
+
+        .. testoutput::
+
+            True
+            False
         """
         return self._dimensionality == "empty"
 
@@ -166,7 +220,7 @@
             columns: list
     ):
         """Summarize dataframe to the level specified in axes"""
         if type(data) != pd.DataFrame:
             # A non-pandas input that reaches this branch is a Dask dataframe.
             # Only the Dask backend is deprecated, so gate the warning on the
             # data's module rather than warning for every pandas subclass that
@@ -367,6 +421,31 @@
         """Given the current triangle shape and valuation, it determines the
         appropriate placement of NANs in the triangle for future valuations.
         This becomes useful when managing array arithmetic.
+
+        Examples
+        --------
+        Observed cells are ``1`` and future valuations are missing.
+
+        .. testsetup::
+
+            import chainladder as cl
+
+        .. testcode::
+
+            print(cl.load_sample('raa').nan_triangle)
+
+        .. testoutput::
+
+            [[ 1.  1.  1.  1.  1.  1.  1.  1.  1.  1.]
+             [ 1.  1.  1.  1.  1.  1.  1.  1.  1. nan]
+             [ 1.  1.  1.  1.  1.  1.  1.  1. nan nan]
+             [ 1.  1.  1.  1.  1.  1.  1. nan nan nan]
+             [ 1.  1.  1.  1.  1.  1. nan nan nan nan]
+             [ 1.  1.  1.  1.  1. nan nan nan nan nan]
+             [ 1.  1.  1.  1. nan nan nan nan nan nan]
+             [ 1.  1.  1. nan nan nan nan nan nan nan]
+             [ 1.  1. nan nan nan nan nan nan nan nan]
+             [ 1. nan nan nan nan nan nan nan nan nan]]
         """
         xp = self.get_array_module()
         if self.is_pattern or self.is_ultimate:
@@ -401,7 +480,7 @@
             target: Series = target_field
             # If the target field is a period, convert to timestamp. period_end is a boolean that if true,
             # means that the timestamp should be the end of the period.
             if type(target.iloc[0]) == pd.Period:
                 return target.dt.to_timestamp(how={1: "e", 0: "s"}[period_end])
         else:
             datetime_arg: np.ndarray = target_field.unique()
@@ -527,6 +606,29 @@
         -------
             The backend module. For example, if the backend is numpy, it will return the "np" that you
             would get if you ran the statement, "import numpy as np".
+
+        Examples
+        --------
+        The returned module is the same object as ``numpy`` or ``sparse``,
+        matching the Triangle's ``array_backend``.
+
+        .. testsetup::
+
+            import chainladder as cl
+
+        .. testcode::
+
+            import numpy as np
+            import sparse as sp
+
+            raa = cl.load_sample('raa')
+            print(raa.get_array_module() is np)
+            print(raa.set_backend('sparse').get_array_module() is sp)
+
+        .. testoutput::
+
+            True
+            True
         """
 
         backend: str = (
@@ -666,6 +768,17 @@
         Returns
         -------
         Triangle
+
+        Examples
+        --------
+        Numpy- and sparse-backed Triangles are already materialized.
+        ``compute`` exists to realize a lazy dask array. The dask backend is
+        deprecated and optional, so that path is shown as a code sample:
+
+        .. code-block:: python
+
+            tri = cl.load_sample('raa').set_backend('dask')
+            tri = tri.compute()
         """
         if hasattr(self.values, "chunks"):
             obj = self.copy()

docs/_templates/autosummary/class_inherited.rst

@@ -2,8 +2,11 @@
 
 .. currentmodule:: {{ module }}
 
+{% set documented_attrs = ['shape', 'empty', 'dimensionality', 'nan_triangle'] %}
+{% set hidden_attrs = attributes | reject('in', documented_attrs) | list %}
+
 .. autoclass:: {{ objname }}
    :members:
    :inherited-members:
    :undoc-members:
-   :exclude-members: set_fit_request, set_predict_request, set_score_request, set_transform_request, {{ attributes | join(', ') }}
+   :exclude-members: set_fit_request, set_predict_request, set_score_request, set_transform_request{% if hidden_attrs %}, {{ hidden_attrs | join(', ') }}{% endif %}