diff --git a/docs/source/_autosummary/pvdeg.geospatial.plot_sparse_analysis_land.rst b/docs/source/_autosummary/pvdeg.geospatial.plot_sparse_analysis_land.rst new file mode 100644 index 0000000..16e8a98 --- /dev/null +++ b/docs/source/_autosummary/pvdeg.geospatial.plot_sparse_analysis_land.rst @@ -0,0 +1,6 @@ +pvdeg.geospatial.plot\_sparse\_analysis\_land +============================================= + +.. currentmodule:: pvdeg.geospatial + +.. autofunction:: plot_sparse_analysis_land \ No newline at end of file diff --git a/docs/source/_autosummary/pvdeg.geospatial.rst b/docs/source/_autosummary/pvdeg.geospatial.rst index 4524da2..159523f 100644 --- a/docs/source/_autosummary/pvdeg.geospatial.rst +++ b/docs/source/_autosummary/pvdeg.geospatial.rst @@ -34,6 +34,7 @@ pvdeg.geospatial pvdeg.geospatial.plot_Europe pvdeg.geospatial.plot_USA pvdeg.geospatial.plot_sparse_analysis + pvdeg.geospatial.plot_sparse_analysis_land pvdeg.geospatial.start_dask pvdeg.geospatial.template_parameters pvdeg.geospatial.zero_template @@ -157,6 +158,13 @@ pvdeg.geospatial .. minigallery:: pvdeg.geospatial.plot_sparse_analysis :add-heading: + .. autofunction:: plot_sparse_analysis_land + + .. _sphx_glr_backref_pvdeg.geospatial.plot_sparse_analysis_land: + + .. minigallery:: pvdeg.geospatial.plot_sparse_analysis_land + :add-heading: + .. autofunction:: start_dask .. _sphx_glr_backref_pvdeg.geospatial.start_dask: diff --git a/docs/source/_autosummary/pvdeg.utilities.linear_normalize.rst b/docs/source/_autosummary/pvdeg.utilities.linear_normalize.rst new file mode 100644 index 0000000..8fae071 --- /dev/null +++ b/docs/source/_autosummary/pvdeg.utilities.linear_normalize.rst @@ -0,0 +1,6 @@ +pvdeg.utilities.linear\_normalize +================================= + +.. currentmodule:: pvdeg.utilities + +.. autofunction:: linear_normalize \ No newline at end of file diff --git a/docs/source/_autosummary/pvdeg.utilities.merge_sparse.rst b/docs/source/_autosummary/pvdeg.utilities.merge_sparse.rst new file mode 100644 index 0000000..9da49b5 --- /dev/null +++ b/docs/source/_autosummary/pvdeg.utilities.merge_sparse.rst @@ -0,0 +1,6 @@ +pvdeg.utilities.merge\_sparse +============================= + +.. currentmodule:: pvdeg.utilities + +.. autofunction:: merge_sparse \ No newline at end of file diff --git a/docs/source/_autosummary/pvdeg.utilities.rst b/docs/source/_autosummary/pvdeg.utilities.rst index fe0b340..d769d53 100644 --- a/docs/source/_autosummary/pvdeg.utilities.rst +++ b/docs/source/_autosummary/pvdeg.utilities.rst @@ -26,6 +26,8 @@ pvdeg.utilities pvdeg.utilities.get_kinetics pvdeg.utilities.get_state_bbox pvdeg.utilities.gid_downsampling + pvdeg.utilities.linear_normalize + pvdeg.utilities.merge_sparse pvdeg.utilities.meta_as_dict pvdeg.utilities.new_id pvdeg.utilities.nrel_kestrel_check @@ -100,6 +102,20 @@ pvdeg.utilities .. minigallery:: pvdeg.utilities.gid_downsampling :add-heading: + .. autofunction:: linear_normalize + + .. _sphx_glr_backref_pvdeg.utilities.linear_normalize: + + .. minigallery:: pvdeg.utilities.linear_normalize + :add-heading: + + .. autofunction:: merge_sparse + + .. _sphx_glr_backref_pvdeg.utilities.merge_sparse: + + .. minigallery:: pvdeg.utilities.merge_sparse + :add-heading: + .. autofunction:: meta_as_dict .. _sphx_glr_backref_pvdeg.utilities.meta_as_dict: diff --git a/docs/source/whatsnew/index.rst b/docs/source/whatsnew/index.rst index 78b3536..b1070d6 100644 --- a/docs/source/whatsnew/index.rst +++ b/docs/source/whatsnew/index.rst @@ -5,6 +5,8 @@ What's New PVDegradationTools (pvdeg) change log: +.. include:: releases/v0.4.3.rst +.. include:: releases/v0.4.2.rst .. include:: releases/v0.4.1.rst .. include:: releases/v0.4.0.rst .. include:: releases/v0.3.3.rst diff --git a/docs/source/whatsnew/releases/v0.4.2.rst b/docs/source/whatsnew/releases/v0.4.2.rst index 597e551..1c7c30b 100644 --- a/docs/source/whatsnew/releases/v0.4.2.rst +++ b/docs/source/whatsnew/releases/v0.4.2.rst @@ -4,11 +4,11 @@ v0.4.2 (2024-09-13) Bug Fixes --------- -* Remove duplicate gid's from `pvdeg.geospatial.elevation_stochastic_downselection` +* Remove duplicate gid's from ``pvdeg.geospatial.elevation_stochastic_downselection`` Tests ----- -* Added a test for Xmin in `test_standards.py` and removed dependency on pvgis. +* Added a test for Xmin in ``test_standards.py`` and removed dependency on pvgis. Contributors ~~~~~~~~~~~~ diff --git a/docs/source/whatsnew/releases/v0.4.3.rst b/docs/source/whatsnew/releases/v0.4.3.rst new file mode 100644 index 0000000..0ae9f13 --- /dev/null +++ b/docs/source/whatsnew/releases/v0.4.3.rst @@ -0,0 +1,10 @@ +v0.4.3 (2024-11-1) +======================= + +Enhancements +------------- +``pvdeg.geospatial.analysis`` implements autotemplating. No need to specify a template for common ``pvdeg`` functions during analysis. Manually creating and providing templates is still an option. Docstrings updated with examples. + +Contributors +~~~~~~~~~~~~ +* Tobin Ford (:ghuser:`tobin-ford`) diff --git a/pvdeg/geospatial.py b/pvdeg/geospatial.py index c9cb0d2..1e015fc 100644 --- a/pvdeg/geospatial.py +++ b/pvdeg/geospatial.py @@ -190,7 +190,12 @@ def calc_block(weather_ds_block, future_meta_df, func, func_kwargs): def analysis(weather_ds, meta_df, func, template=None, **func_kwargs): """ - Applies a function to each gid of a weather dataset. + Applies a function to each gid of a weather dataset. `analysis` will attempt to create a template using `geospatial.auto_template`. + If this process fails you will have to provide a geospatial template to the template argument. + + ValueError: cannot be autotemplated. create a template manually with `geospatial.output_template` + + Parameters ---------- @@ -212,8 +217,10 @@ def analysis(weather_ds, meta_df, func, template=None, **func_kwargs): """ if template is None: - param = template_parameters(func) - template = output_template(weather_ds, **param) + template = auto_template( + func=func, + ds_gids=weather_ds + ) # future_meta_df = client.scatter(meta_df) kwargs = {"func": func, "future_meta_df": meta_df, "func_kwargs": func_kwargs} @@ -241,7 +248,11 @@ def analysis(weather_ds, meta_df, func, template=None, **func_kwargs): def output_template( - ds_gids, shapes, attrs=dict(), global_attrs=dict(), add_dims=dict() + ds_gids: xr.Dataset, + shapes: dict, + attrs=dict(), + global_attrs=dict(), + add_dims=dict() ): """ Generates a xarray template for output data. Output variables and @@ -249,6 +260,31 @@ def output_template( The dimension length are derived from the input data. Additonal output dimensions can be defined with the add_dims argument. + Examples + -------- + Providing the shapes dictionary can be confusing. Here is what the `shapes` dictionary should look like for `pvdeg.standards.standoff`. + Refer to the docstring, the function will have one result per location so the only dimension for each return value is "gid", a geospatial ID number. + + .. code-block:: python + shapes = { + "x": ("gid",), + "T98_inf": ("gid",), + "T98_0": ("gid",), + } + + **Note: The dimensions are stored in a tuple, this this why all of the parenthesis have commas after the single string, otherwise python will interpret the value as a string.** + + This is what the shapes dictinoary should look like for `pvdeg.humidity.module`. Refering to the docstring, + we can see that the function will return a timeseries result for each location. This means we need dimensions of "gid" and "time". + + .. code-block:: python + shapes = { + "RH_surface_outside": ("gid", "time"), + "RH_front_encap": ("gid", "time"), + "RH_back_encap": ("gid", "time"), + "RH_backsheet": ("gid", "time"), + } + Parameters ---------- ds_gids : xarray.Dataset @@ -290,9 +326,8 @@ def output_template( return output_template -# we should be able to get rid of this with the new autotemplating function and decorator -# this is helpful for users so we should move it to a section in the documenation, -# discuss with group +# This has been replaced with pvdeg.geospatial.auto_templates inside of pvdeg.geospatial.analysis. +# it is here for completeness. it can be removed. def template_parameters(func): """ Output parameters for xarray template. @@ -417,11 +452,10 @@ def auto_template(func: Callable, ds_gids: xr.Dataset) -> xr.Dataset: 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. + Otherwise you will have to create your own template using `geospatial.output_template`. + See the Geospatial Templates Notebook for more information. - examples: + Examples --------- the function returns a numeric value @@ -430,11 +464,24 @@ def auto_template(func: Callable, ds_gids: xr.Dataset) -> xr.Dataset: the function returns a timeseries result >>> pvdeg.module.humidity - counter example: + Counter example: ---------------- 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. + + Parameters + ---------- + func: callable + function to create template from. This will raise an error if the function was not declared with the `@geospatial_quick_shape` decorator. + ds_gids : xarray.Dataset + Dataset containing the gids and their associated dimensions. (geospatial weather dataset) + Dataset should already be chunked. + + Returns + ------- + output_template : xarray.Dataset + Template for output data. """ if not (hasattr(func, "numeric_or_timeseries") and hasattr(func, "shape_names")):