From 2d0284aed5fcbdabd67ebe38980788eab358d537 Mon Sep 17 00:00:00 2001 From: Lewis Fogden Date: Sun, 28 Apr 2024 18:52:33 +0100 Subject: [PATCH] added API and docstrings --- docs/api/heavylight_Model.md | 1 + docs/api/heavylight_Table.md | 1 + mkdocs.yml | 2 ++ src/heavylight/heavylight.py | 14 +++++++++++++- src/heavylight/heavytables.py | 10 +++++++--- 5 files changed, 24 insertions(+), 4 deletions(-) create mode 100644 docs/api/heavylight_Model.md create mode 100644 docs/api/heavylight_Table.md diff --git a/docs/api/heavylight_Model.md b/docs/api/heavylight_Model.md new file mode 100644 index 0000000..0489de1 --- /dev/null +++ b/docs/api/heavylight_Model.md @@ -0,0 +1 @@ +::: heavylight.Model \ No newline at end of file diff --git a/docs/api/heavylight_Table.md b/docs/api/heavylight_Table.md new file mode 100644 index 0000000..0489de1 --- /dev/null +++ b/docs/api/heavylight_Table.md @@ -0,0 +1 @@ +::: heavylight.Model \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 252dc63..c5e0f41 100644 --- a/mkdocs.yml +++ b/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 diff --git a/src/heavylight/heavylight.py b/src/heavylight/heavylight.py index 5e936b8..127b3fa 100644 --- a/src/heavylight/heavylight.py +++ b/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() \ No newline at end of file diff --git a/src/heavylight/heavytables.py b/src/heavylight/heavytables.py index a90c0cd..e989395 100644 --- a/src/heavylight/heavytables.py +++ b/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)