Rename decorator, update docstrings

pvdeg/decorators.py

@@ -4,7 +4,7 @@
 """
 
 
-def geospatial_result_type(value: bool, shape_names: list[str]) -> None:
+def geospatial_quick_shape(numeric_or_timeseries: bool, shape_names: list[str]) -> None:
     """
     Add an attribute to the functions that can be run with geospatial analysis.
     Strict typing is not enough for this purpose so we can view this attribute
@@ -33,10 +33,26 @@ def geospatial_result_type(value: bool, shape_names: list[str]) -> None:
 
     * Note: we cannot autotemplate functions with ambiguous return types that depend on runtime input,
     the function will need strictly return a timeseries or numeric but not one or the other.
+
+    Parameters:
+    -----------
+    numeric_or_timeseries: bool
+        indicate whether the function returns a single numeric/tuple of numerics
+        or a timeseries/tuple of timeseries. False when numeric, True when timeseries
+
+    shape_names: list[str]
+        list of return value names. These will become the xarray datavariable names in the output.
+
+    Modifies:
+    ---------
+    func.numeric_or_timeseries
+        sets to numeric_or_timeseries argument
+    func.shape_names
+        sets to shape_names argument
     """
 
     def decorator(func):
-        setattr(func, "numeric_or_timeseries", value)
+        setattr(func, "numeric_or_timeseries", numeric_or_timeseries)
         setattr(func, "shape_names", shape_names)
         return func
 

pvdeg/degradation.py

@@ -13,7 +13,7 @@
 from . import spectral
 from . import weather
 
-from pvdeg.decorators import geospatial_result_type
+from pvdeg.decorators import geospatial_quick_shape
 
 # TODO: Clean up all those functions and add gaps functionality
 
@@ -179,7 +179,7 @@ def _to_eq_vantHoff(temp, Tf=1.41):
     return Toeq
 
 
-@geospatial_result_type(0,["Iwa"])
+@geospatial_quick_shape(0,["Iwa"])
 def IwaVantHoff(
     weather_df: pd.DataFrame,
     meta: dict,

pvdeg/design.py

@@ -1,7 +1,7 @@
 """Collection of functions for PV module design considertations."""
 
 from . import humidity
-from pvdeg.decorators import geospatial_result_type
+from pvdeg.decorators import geospatial_quick_shape
 import pandas as pd
 
 
@@ -42,7 +42,7 @@ def edge_seal_ingress_rate(avg_psat):
     return k
 
 
-@geospatial_result_type(0, ["width"])
+@geospatial_quick_shape(0, ["width"])
 def edge_seal_width(
     weather_df: pd.DataFrame,
     meta: dict,

pvdeg/fatigue.py

@@ -2,7 +2,7 @@
 import pandas as pd
 from scipy.constants import convert_temperature
 from pvdeg import temperature
-from pvdeg.decorators import geospatial_result_type
+from pvdeg.decorators import geospatial_quick_shape
 
 
 def _avg_daily_temp_change(time_range, temp_cell):
@@ -98,7 +98,7 @@ def _times_over_reversal_number(temp_cell, reversal_temp):
     return num_changes_temp_hist
 
 
-@geospatial_result_type(0, ['damage'])
+@geospatial_quick_shape(0, ['damage'])
 def solder_fatigue(
     weather_df: pd.DataFrame,
     meta: dict,

pvdeg/geospatial.py

@@ -383,22 +383,27 @@ def zero_template(
 def auto_template(func: Callable, ds_gids: xr.Dataset) -> xr.Dataset:
     """
     Automatically create a template for a target function: `func`.
-    Only works on functions that have a strict return type. 
+    Only works on functions that have the `numeric_or_timeseries` and `shape_names` attributes.
+    These attributes are assigned at function definition with the `@geospatial_quick_shape` decorator.
+    
     Otherwise you will have to create your own template. 
     Don't worry, this is easy. See the Geospatial Templates Notebook 
     for more information. 
 
     examples:
+    ---------
+
     the function returns a numeric value
     >>> pvdeg.design.edge_seal_width
 
     the function returns a timeseries result
     >>> pvdeg.module.humidity
 
     counter example:
-    the function could either return a single numeric or a series based on changed in the input
-
-    Note: Only works on functions that use the `geospatial_result_type` decorator in the source code.
+    ----------------
+    the function could either return a single numeric or a series based on changed in 
+    the input. Because it does not have a known result shape we cannot determine the 
+    attributes required for autotemplating ahead of time. 
     """
 
     if not (hasattr(func, "numeric_or_timeseries") and hasattr(func, "shape_names")):
@@ -417,7 +422,6 @@ def auto_template(func: Callable, ds_gids: xr.Dataset) -> xr.Dataset:
 
     return template
 
-
 def plot_USA(
     xr_res, cmap="viridis", vmin=None, vmax=None, title=None, cb_title=None, fp=None
 ):

pvdeg/humidity.py

@@ -16,7 +16,7 @@
     weather
 )
 
-from pvdeg.decorators import geospatial_result_type
+from pvdeg.decorators import geospatial_quick_shape
 
 
 def _ambient(weather_df):
@@ -654,7 +654,7 @@ def backsheet(
     return backsheet
 
 
-@geospatial_result_type(1, ["RH_surface_outside", "RH_front_encap", "RH_back_encap", "RH_backsheet"])
+@geospatial_quick_shape(1, ["RH_surface_outside", "RH_front_encap", "RH_back_encap", "RH_backsheet"])
 def module(
     weather_df,
     meta,

pvdeg/letid.py

@@ -11,7 +11,7 @@
 
 
 from pvdeg import collection, utilities, standards, DATA_DIR
-from pvdeg.decorators import geospatial_result_type
+from pvdeg.decorators import geospatial_quick_shape
 
 
 def tau_now(tau_0, tau_deg, n_b):
@@ -871,7 +871,7 @@ def calc_injection_outdoors(results):
     return injection
 
 
-@geospatial_result_type(1, ["Temperature", "Injection", "NA", "NB", "NC", "tau", "Jsc", "Voc", "Isc", "FF", "Pmp", "Pmp_norm"])
+@geospatial_quick_shape(1, ["Temperature", "Injection", "NA", "NB", "NC", "tau", "Jsc", "Voc", "Isc", "FF", "Pmp", "Pmp_norm"])
 def calc_letid_outdoors(
     tau_0,
     tau_deg,

pvdeg/spectral.py

@@ -4,10 +4,10 @@
 
 import pvlib
 import pandas as pd
-from pvdeg.decorators import geospatial_result_type
+from pvdeg.decorators import geospatial_quick_shape
 
 
-@geospatial_result_type(
+@geospatial_quick_shape(
     1,
     [
         "apparent_zenith",
@@ -54,7 +54,7 @@ def solar_position(weather_df: pd.DataFrame, meta: dict) -> pd.DataFrame:
     return solar_position
 
 
-@geospatial_result_type(
+@geospatial_quick_shape(
     1,
     [
         "poa_global",

pvdeg/standards.py

@@ -16,10 +16,10 @@
 # from gaps import ProjectPoints
 
 from pvdeg import temperature, spectral, utilities, weather
-from pvdeg.decorators import geospatial_result_type
+from pvdeg.decorators import geospatial_quick_shape
 
 
-@geospatial_result_type(1, ["T_0", "T_inf", "poa"])
+@geospatial_quick_shape(1, ["T_0", "T_inf", "poa"])
 def eff_gap_parameters(
     weather_df=None,
     meta=None,
@@ -190,7 +190,7 @@ def eff_gap(T_0, T_inf, T_measured, T_ambient, poa, x_0=6.5, poa_min=400, t_amb_
     return x_eff
 
 
-@geospatial_result_type(0, ["x","T98_0", "T98_inf"]) # numeric result, with corresponding datavariable names
+@geospatial_quick_shape(0, ["x","T98_0", "T98_inf"]) # numeric result, with corresponding datavariable names
 def standoff(
     weather_df: pd.DataFrame = None,
     meta: dict = None,
@@ -418,7 +418,7 @@ def interpret_standoff(standoff_1=None, standoff_2=None):
     return Output
 
 
-@geospatial_result_type(0, ["T98"])
+@geospatial_quick_shape(0, ["T98"])
 def T98_estimate(
     weather_df=None,
     meta=None,

pvdeg/temperature.py

@@ -4,12 +4,12 @@
 
 import pvlib
 import pvdeg
-from pvdeg.decorators import geospatial_result_type
+from pvdeg.decorators import geospatial_quick_shape
 import pandas as pd
 from typing import Union
 
 
-@geospatial_result_type(1, ['module_temperature'])
+@geospatial_quick_shape(1, ['module_temperature'])
 def module(
     weather_df,
     meta,
@@ -100,7 +100,7 @@ def module(
     return module_temperature
 
 
-@geospatial_result_type(1, ["cell_temperature"])
+@geospatial_quick_shape(1, ["cell_temperature"])
 def cell(
     weather_df: pd.DataFrame,
     meta: dict,