Merge branch 'development' into Documentation

Author: tobin-ford

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

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:

docs/source/_autosummary/pvdeg.utilities.display_json.rst

@@ -0,0 +1,6 @@
+pvdeg.utilities.display\_json
+=============================
+
+.. currentmodule:: pvdeg.utilities
+
+.. autofunction:: display_json

docs/source/_autosummary/pvdeg.utilities.linear_normalize.rst

@@ -0,0 +1,6 @@
+pvdeg.utilities.linear\_normalize
+=================================
+
+.. currentmodule:: pvdeg.utilities
+
+.. autofunction:: linear_normalize

docs/source/_autosummary/pvdeg.utilities.merge_sparse.rst

@@ -0,0 +1,6 @@
+pvdeg.utilities.merge\_sparse
+=============================
+
+.. currentmodule:: pvdeg.utilities
+
+.. autofunction:: merge_sparse

docs/source/_autosummary/pvdeg.utilities.read_material.rst

@@ -0,0 +1,6 @@
+pvdeg.utilities.read\_material
+==============================
+
+.. currentmodule:: pvdeg.utilities
+
+.. autofunction:: read_material

docs/source/_autosummary/pvdeg.utilities.rst

@@ -21,17 +21,22 @@ pvdeg.utilities
 
       pvdeg.utilities.compare_templates
       pvdeg.utilities.convert_tmy
+      pvdeg.utilities.display_json
       pvdeg.utilities.fix_metadata
       pvdeg.utilities.geospatial_from_csv
       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
       pvdeg.utilities.quantile_df
+      pvdeg.utilities.read_material
       pvdeg.utilities.remove_scenario_filetrees
       pvdeg.utilities.restore_gids
+      pvdeg.utilities.search_json
       pvdeg.utilities.strip_normalize_tmy
       pvdeg.utilities.tilt_azimuth_scan
       pvdeg.utilities.ts_gid_df
@@ -65,6 +70,13 @@ pvdeg.utilities
    .. minigallery:: pvdeg.utilities.convert_tmy
        :add-heading:
 
+   .. autofunction:: display_json
+
+   .. _sphx_glr_backref_pvdeg.utilities.display_json:
+
+   .. minigallery:: pvdeg.utilities.display_json
+       :add-heading:
+
    .. autofunction:: fix_metadata
 
    .. _sphx_glr_backref_pvdeg.utilities.fix_metadata:
@@ -100,6 +112,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:
@@ -128,6 +154,13 @@ pvdeg.utilities
    .. minigallery:: pvdeg.utilities.quantile_df
        :add-heading:
 
+   .. autofunction:: read_material
+
+   .. _sphx_glr_backref_pvdeg.utilities.read_material:
+
+   .. minigallery:: pvdeg.utilities.read_material
+       :add-heading:
+
    .. autofunction:: remove_scenario_filetrees
 
    .. _sphx_glr_backref_pvdeg.utilities.remove_scenario_filetrees:
@@ -142,6 +175,13 @@ pvdeg.utilities
    .. minigallery:: pvdeg.utilities.restore_gids
        :add-heading:
 
+   .. autofunction:: search_json
+
+   .. _sphx_glr_backref_pvdeg.utilities.search_json:
+
+   .. minigallery:: pvdeg.utilities.search_json
+       :add-heading:
+
    .. autofunction:: strip_normalize_tmy
 
    .. _sphx_glr_backref_pvdeg.utilities.strip_normalize_tmy:

docs/source/_autosummary/pvdeg.utilities.search_json.rst

@@ -0,0 +1,6 @@
+pvdeg.utilities.search\_json
+============================
+
+.. currentmodule:: pvdeg.utilities
+
+.. autofunction:: search_json

docs/source/whatsnew/index.rst

@@ -4,7 +4,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

docs/source/whatsnew/releases/v0.4.2.rst

@@ -13,4 +13,4 @@ Tests
 Contributors
 ~~~~~~~~~~~~
 * Martin Springer (:ghuser:`martin-springer`)
-* Aidan Wesley (:ghuser:`AidanWesley``)
+* Aidan Wesley (:ghuser:`AidanWesley``)

docs/source/whatsnew/releases/v0.4.3.rst

@@ -0,0 +1,14 @@
+v0.4.3 (2024-10-10)
+===================
+
+Enhancements
+------------
+Suite of utility functions to facilitate accessing material parameter json files.
+
+* ``pvdeg.utilities.read_material`` creates a public api to replace the private ``pvdeg.untility._read_material`` function (to be deprecated soon)  
+* ``pvdeg.utilities.search_json`` to search jsons and identify keys for desired materials.  
+* ``pvdeg.utilities.display_json`` to view 2 level jsons in Jupyter Notebooks using HTML.  
+
+Contributors
+-----------
+* Tobin Ford (:ghuser:`tobin-ford`)

pvdeg/temperature.py

@@ -196,7 +196,7 @@ def cell(
     Calculate the PV cell temperature using PVLIB
     Currently this only supports the SAPM temperature model.
 
-    Parameters:
+    Parameters
     -----------
     weather_df : (pd.dataframe)
         Data Frame with minimum requirements of 'temp_air' and 'wind_speed'
@@ -304,7 +304,7 @@ def temperature(
     Calculate the PV cell or module temperature using PVLIB
     Current supports the following temperature models:
 
-    Parameters:
+    Parameters
     -----------
     cell_or_mod : (str)
         choose to calculate the cell or module temperature. Use
@@ -347,12 +347,12 @@ def temperature(
         keyword argument dictionary used for the pvlib temperature model calculation.
         See https://pvlib-python.readthedocs.io/en/stable/reference/pv_modeling/temperature.html for more.
 
-    Return:
+    Return
     -------
     temp_cell : pandas.DataFrame
         This is the temperature of the cell in a module at every time step.[°C]
 
-    References:
+    References
     -----------
     R. Rabbani, M. Zeeshan, "Exploring the suitability of MERRA-2 reanalysis data for wind energy
         estimation, analysis of wind characteristics and energy potential assessment for selected

pvdeg/utilities.py

@@ -13,6 +13,15 @@
 from subprocess import run
 import cartopy.feature as cfeature
 
+
+# A mapping to simplify access to files stored in `pvdeg/data`
+pvdeg_datafiles = { 
+    "AApermeation": os.path.join(DATA_DIR, "AApermeation.json"),
+    "H2Opermeation": os.path.join(DATA_DIR, "H2Opermeation.json"),
+    "O2permeation": os.path.join(DATA_DIR, "O2permeation.json"),
+}
+
+
 def gid_downsampling(meta, n):
     """
     Downsample the NSRDB GID grid by a factor of n
@@ -492,8 +501,7 @@ def convert_tmy(file_in, file_out="h5_from_tmy.h5"):
         )
 
 
-# previously: fname="materials.json"
-# add control over what parameters (O2, H2, AA)?
+### DEPRECATE ###
 def _read_material(name, fname="O2permeation.json"):
     """
     read a material from materials.json and return the parameter dictionary
@@ -1337,4 +1345,138 @@ def merge_sparse(files: list[str])->xr.Dataset:
         for var in ds.data_vars:
             merged_ds[var].values[np.ix_(lat_inds, lon_inds)] = ds[var].values
 
-    return merged_ds
+    return merged_ds
+
+def display_json(
+    pvdeg_file: str = None, 
+    fp: str = None, 
+    ) -> None:
+    """
+    Interactively view a 2 level JSON file in a JupyterNotebook
+
+    Parameters:
+    ------------
+    pvdeg_file: str
+        keyword for material json file in `pvdeg/data`. Options:
+        >>> "AApermeation", "H2Opermeation", "O2permeation"
+    fp: str
+        file path to material parameters json with same schema as material parameters json files in `pvdeg/data`.  `pvdeg_file` will override `fp` if both are provided.
+    """
+    from IPython.display import display, HTML
+
+    if pvdeg_file:
+        try:
+            fp = pvdeg_datafiles[pvdeg_file]
+        except KeyError:
+            raise KeyError(f"{pvdeg_file} does not exist in pvdeg/data. Options are {pvdeg_datafiles.keys()}")
+
+    with open(fp, 'r') as file:
+        data = json.load(file)
+
+    def json_to_html(data):
+        json_str = json.dumps(data, indent=2)
+        for key in data.keys():
+            json_str = json_str.replace(f'"{key}":', f'<span style="color: plum;">"{key}":</span>')
+        
+        indented_html = '<br>'.join([' ' * 4 + line for line in json_str.splitlines()])
+        return f'<pre style="color: white; background-color: black; padding: 10px; border-radius: 5px;">{indented_html}</pre>'
+
+    html = f'<h2 style="color: white;">JSON Output at fp: {fp}</h2><div>'
+    for key, value in data.items():
+        html += (
+            f'<div>'
+            f'<strong style="color: white;">{key}:</strong> '
+            f'<span onclick="this.nextElementSibling.style.display = this.nextElementSibling.style.display === \'none\' ? \'block\' : \'none\'" style="cursor: pointer; color: white;">&#9660;</span>'
+            f'<div style="display: none;">{json_to_html(value)}</div>'
+            f'</div>'
+        )
+    html += '</div>'
+
+    # Display the HTML
+    display(HTML(html))
+
+
+def search_json(
+    pvdeg_file: str = None, 
+    fp: str = None, 
+    name_or_alias: str = None,
+    )-> str:
+    """
+    Search through a 2 level JSON with arbitrary key names for subkeys with matching attributes of name or alias.
+
+    Parameters
+    ------------
+    pvdeg_file: str
+        keyword for material json file in `pvdeg/data`. Options:
+        >>> "AApermeation", "H2Opermeation", "O2permeation"
+    fp: str
+        file path to material parameters json with same schema as material parameters json files in `pvdeg/data`. `pvdeg_file` will override `fp` if both are provided.
+    name_or_alias: str
+        searches for matching subkey value in either `name` or `alias` attributes. exits on the first matching instance.
+
+    Returns
+    ---------
+    jsonkey: str
+        arbitrary key from json that owns the matching subattribute of `name` or `alias`.
+    """
+
+    if pvdeg_file:
+        try:
+            fp = pvdeg_datafiles[pvdeg_file]
+        except KeyError:
+            raise KeyError(rf"{pvdeg_file} does not exist in pvdeg/data. Options are {pvdeg_datafiles.keys()}")
+
+    with open(fp, "r") as file:
+        data = json.load(file)
+
+    for key, subdict in data.items():
+        if "name" in subdict and "alias" in subdict:
+            if (subdict["name"] == name_or_alias or subdict["alias"] == name_or_alias):
+                return key
+
+    raise ValueError(rf"name_or_alias: {name_or_alias} not in JSON at {os.path(fp)}")
+
+def read_material(
+    pvdeg_file: str = None, 
+    fp: str = None, 
+    key: str = None,
+    parameters: list[str] = None,
+)-> dict:
+    """
+    Read material parameters from a `pvdeg/data` file or JSON file path.
+
+    Parameters
+    -----------
+    pvdeg_file: str
+        keyword for material json file in `pvdeg/data`. Options:
+        >>> "AApermeation", "H2Opermeation", "O2permeation"
+    fp: str
+        file path to material parameters json with same schema as material parameters json files in `pvdeg/data`. `pvdeg_file` will override `fp` if both are provided.
+    key: str
+        key corresponding to specific material in the file. In the pvdeg files these have arbitrary names. Inspect the files or use `display_json` or `search_json` to identify the key for desired material.
+    parameters: list[str]
+        parameters to grab from the file at index key. If none, will grab all items at index key. the elements in parameters must match the keys in the json exactly or the output value for the specific key/parameter in the retunred dict will be `None`.
+
+    Returns
+    --------
+    material: dict
+        dictionary of material parameters from the seleted file at the index key.
+    """
+
+    # these live in the `pvdeg/data` folder
+    if pvdeg_file:
+        try:
+            fp = pvdeg_datafiles[pvdeg_file]
+        except KeyError:
+            raise KeyError(f"{pvdeg_file} does not exist in pvdeg/data. Options are {pvdeg_datafiles.keys()}")
+
+    with open(fp, "r") as file:
+        data = json.load(file)
+
+    # take subdict from file
+    material_dict = data[key] 
+    
+    if parameters:
+        material_dict = {k: material_dict.get(k, None) for k in parameters} 
+
+    return material_dict

pyproject.toml

@@ -67,6 +67,7 @@ docs = [
     "nbsphinx",
     "sphinx_toggleprompt",
     "pydata_sphinx_theme",
+    "mistune==3.0.0",
 ]
 test = [
     "pytest",