added API and docstrings

docs/api/heavylight_Model.md

@@ -0,0 +1 @@
+::: heavylight.Model

docs/api/heavylight_Table.md

@@ -0,0 +1 @@
+::: heavylight.Model

mkdocs.yml

@@ -74,6 +74,8 @@ nav:
         - Introductory Guide: getting_started/intro_to_heavylight.ipynb
         - Heavylight Tables: getting_started/heavylight_tables.ipynb
     - API:
+        - Model: api/heavylight_Model.md
+        - Table: api/heavylight_Table.md
         - LightModel: api/lightmodel.md
     - Theory: 
         - Recursive life insurance: theory/recursive_life_insurance.ipynb

src/heavylight/heavylight.py

@@ -104,6 +104,12 @@ def __init__(self, *, do_run = None, proj_len:int = 0, **kwargs,):
             self.RunModel(proj_len)
 
     def RunModel(self, proj_len: int):
+        """
+        Run the model if not already run.
+
+        Parameters
+        ----------
+        - proj_len: length of projection to run"""
         if self._is_run:
             # TODO: replace this with ability to run further, but warn that earlier values not recalculated?
             raise ValueError("Run has already been completed.")
@@ -144,7 +150,12 @@ def _info(self):
             print(f"{name}: {func}")
 
     def ToDataFrame(self, param = 't'):
-        """return a pandas dataframe of all single parameter columns"""
+        """return a pandas dataframe of all single parameter columns
+        
+        Parameters
+        ----------
+        - param: parameter to filter on.  Default: `t`
+        """
         df = pd.DataFrame()
         for func in self._funcs:
             if self._funcs[func].has_one_param and self._funcs[func].param_names[0] == param:
@@ -157,4 +168,5 @@ def ToDataFrame(self, param = 't'):
 
     @property
     def df(self):
+        """return a pandas dataframe of all single parameter columns parameterised with `t`"""
         return self.ToDataFrame()

src/heavylight/heavytables.py

@@ -9,6 +9,7 @@
 # Each key column requires an input class which maps from the source datatype to an integer
 
 class IntegerLookup:
+    """An integer lookup - unsafe as doesn't check bounds"""
     def get(self, values):
         return values
 
@@ -25,6 +26,7 @@ def get(self, values):
         return values
 
 class BoundIntLookup:
+    """An integer lookup that clips to the lowest and highest keys"""
     def __init__(self, lower, upper):
         self.lower = int(lower)
         self.upper = int(upper)
@@ -33,6 +35,7 @@ def get(self, numpy_array):
         return np.clip(numpy_array, self.lower, self.upper)
 
 class StringLookup:
+    """A string lookup that include validation that the string match is exact"""
     def __init__(self, string_vals):
         self.string_vals = np.array(string_vals)
 
@@ -46,6 +49,7 @@ def get(self, keys):
         return np.searchsorted(self.string_vals, keys)          
 
 class BandLookup:
+    """A lookup that matches on bands, using the np.searchsorted function"""
     def __init__(self, upper_bounds, labels):
         """Inputs must be sorted"""
         self.upper_bounds = np.array(upper_bounds)
@@ -196,9 +200,8 @@ def get(self, *keys):
         return self._int_key_table.get_value(*int_keys)
 
     def __getitem__(self, keys):
-        # print(keys, type(keys))
         if not isinstance(keys, tuple):
-            keys = keys, #force to be a tuple
+            keys = keys,    #force to be a tuple
         return self.get(*keys)
 
     def __repr__(self):
@@ -236,11 +239,12 @@ def rectify(df: pd.DataFrame, fill=np.nan) -> pd.DataFrame:
 
     @classmethod
     def read_excel(cls, spreadsheet_path, sheet_name):
-        """Read in a table from an excel sheet"""
+        """Read in a table from an excel sheet, for more control pass in the dataframe using `__init__`"""
         df = pd.read_excel(spreadsheet_path, sheet_name=sheet_name)
         return cls(df)
 
     @classmethod
     def read_csv(cls, csv_path):
+        """Read in a table from an csv file, for more control pass in the dataframe using `__init__`"""
         df = pd.read_csv(csv_path)
         return cls(df)