Feature/split out resources

docs/examples_overview.md

@@ -43,7 +43,7 @@ No manual setup is required - all necessary input files will be automatically ge
 
 ## Additional Resource Downloading and Upsampling Examples
 
-Examples are provided in the `examples/inputs/` folder demonstrating how to download wind and solar data using the `hercules.resource.wind_solar_resource_downloader` module and upsample wind data using the `hercules.resource.upsample_wind_data` module to create inputs for Hercules simulations.
+Examples are provided in the `examples/inputs/` folder demonstrating how to download wind and solar data using the `hercules.resource.nsrdb_downloader`, `hercules.resource.wtk_downloader`, and `hercules.resource.openmeteo_downloader` modules and upsample wind data using the `hercules.resource.upsample_wind_data` module to create inputs for Hercules simulations.
 
 - [03: Download NSRDB and WIND Toolkit Solar and Wind Data](../examples/inputs/03_download_small_nsrdb_wtk_solar_wind_example.py) - Downloads a subset of solar and wind data for a small grid of locations for a single year from the NSRDB and WIND Toolkit datasets, respectively
 - [04: Download and Upsample WIND Toolkit Wind Data](../examples/inputs/04_download_and_upsample_wtk_wind_example.py) - Downloads wind speed and direction for a small grid of locations for a single year from the WIND Toolkit dataset, then spatially interpolates the data at specific wind turbine locations and temporally upsamples the times series with added turbulence

docs/resource_downloading.md

@@ -1,16 +1,16 @@
 # Solar and Wind Resource Downloading and Upsampling
 
-Functions are provided in the `hercules.resource.wind_solar_resource_downloading` module for downloading solar and wind time series data so they can be used as inputs to Hercules simulations. The `hercules.resource.upsample_wind_data` module is used to spatially interpolate downloaded wind data at specific wind turbine locations and temporally upsample the data.
+Functions are provided in the `hercules.resource.nsrdb_downloader`, `hercules.resource.wtk_downloader`, and `hercules.resource.openmeteo_downloader` modules for downloading solar and wind time series data so they can be used as inputs to Hercules simulations. The `hercules.resource.upsample_wind_data` module is used to spatially interpolate downloaded wind data at specific wind turbine locations and temporally upsample the data.
 
 ## Overview
 
-The `hercules.resource.wind_solar_resource_downloading` module contains functions for downloading solar data from the [National Solar Radiation Database (NSRDB)](https://nsrdb.nrel.gov), wind data from the [Wind Integration National Dataset (WIND) Toolkit](https://www.nrel.gov/grid/wind-toolkit), and solar and wind data from [Open-Meteo](https://open-meteo.com).
+The `hercules.resource.nsrdb_downloader`, `hercules.resource.wtk_downloader`, and `hercules.resource.openmeteo_downloader` modules contain functions for downloading solar data from the [National Solar Radiation Database (NSRDB)](https://nsrdb.nrel.gov), wind data from the [Wind Integration National Dataset (WIND) Toolkit](https://www.nrel.gov/grid/wind-toolkit), and solar and wind data from [Open-Meteo](https://open-meteo.com), respectively.
 
 For downloaded wind data, the `hercules.resource.upsample_wind_data` module can be used to spatially interpolate the data at specific wind turbine locations and temporally upsample the data to represent realistic turbulent wind speeds. The downloaded and upsampled data can be saved as `.feather` files and used as inputs to Hercules simulations.
 
 ## Solar and Wind Resource Downloading Module
 
-This section describes the functions for downloading solar and wind resource data in the `hercules.resource.wind_solar_resource_downloading` module.
+This section describes the functions for downloading solar and wind resource data in the `hercules.resource.nsrdb_downloader`, `hercules.resource.wtk_downloader`, and `hercules.resource.openmeteo_downloader` modules.
 
 ### API Key
 
@@ -41,8 +41,8 @@ Arguments to the `download_nsrdb_data` function used to specify the data to down
 - `start_date`: If `year` is not used, the specific start date for which data are requested.
 - `end_date`: If `year` is not used, the specific end date for which data are requested.
 - `variables`: List of variables to download. Defaults to ["ghi", "dni", "dhi", "wind_speed", "air_temperature"].
-- `nsrdb_dataset_path`:  Path name of NSRDB dataset. Available datasets are described [here](https://developer.nrel.gov/docs/solar/nsrdb/) and path names can be identified [here](https://data.openei.org/s3_viewer?bucket=nrel-pds-nsrdb). Defaults to the GOES Conus v4.0.0 dataset: "/nrel/nsrdb/GOES/conus/v4.0.0".
-- `nsrdb_filename_prefix`: File name prefix for the NSRDB HDF5 files in the format "{nsrdb_filename_prefix}_{year}.h5". Information about file names can be found [here](https://data.openei.org/s3_viewer?bucket=nrel-pds-nsrdb). Defaults to "nsrdb_conus".
+- `nsrdb_dataset_path`:  Path name of NSRDB dataset. Available datasets are described [here](https://developer.nlr.gov/docs/solar/nsrdb/) and path names can be identified [here](https://data.openei.org/s3_viewer?bucket=nrel-pds-nsrdb). You can see also identify path names of datasets directly by following the directions on [this page](https://github.com/NatLabRockies/rex/tree/main/examples/HSDS), as datasets on the NLR HPC may be named differenctly than the AWS site. Defaults to the GOES Conus v4.0.0 dataset: "/nrel/nsrdb/GOES/conus/v4.0.0".
+- `nsrdb_filename_prefix`: File name prefix for the NSRDB HDF5 files in the format "{nsrdb_filename_prefix}{year}.h5". Information about file names can be found [here](https://data.openei.org/s3_viewer?bucket=nrel-pds-nsrdb). Defaults to "nsrdb_conus_".
 - `coord_delta`: Coordinate delta for bounding box defining grid of points for which data are requested. Bounding box is defined as target_lat +/- coord_delta and target_lon +/- coord_delta. Defaults to 0.1 degrees.
 
 ### WIND Toolkit Wind Data
@@ -75,7 +75,7 @@ Arguments to the `download_openmeteo_data` function used to specify the data to
 
 ## Wind Data Upsampling Module
 
-After downloading wind data from WIND Toolkit or Open-Meteo, the `hercules.resource.upsample_wind_data` module can be used to spatially interpolate wind speeds and directions from the grid of downloaded points to specific wind turbine locations. The spatially interpolated wind speeds and directions are then upsampled to the desired temporal resolution and realistic turbulence is added to the wind speed time series. The upsampled data are then saved in the format used for wind inputs to Hercules simulations.
+After downloading wind data from `hercules.resource.wtk_downloader` or `hercules.resource.openmeteo_downloader`, the `hercules.resource.upsample_wind_data` module can be used to spatially interpolate wind speeds and directions from the grid of downloaded points to specific wind turbine locations. The spatially interpolated wind speeds and directions are then upsampled to the desired temporal resolution and realistic turbulence is added to the wind speed time series. The upsampled data are then saved in the format used for wind inputs to Hercules simulations.
 
 ### Spatial Interpolation Overview
 
@@ -98,9 +98,9 @@ Note that in the current implementation, independent stochastic turbulence is ge
 The function `upsample_wind_data` is used to perform the above-mentioned steps and return the upsampled wind speeds and directions at each upsampled location as a pandas DataFrame, which is also saved as a `.feather` file.
 
 Arguments to the `upsample_wind_data` function used to specify the upsampling are as follows:
-- `ws_data_filepath`: Filepath to the `.feather` file containing raw downloaded wind speed data saved by the `download_wtk_data` or `download_openmeteo_data` functions in the `wind_solar_resource_downloading` module.
-- `wd_data_filepath`: Filepath to the `.feather` file containing raw downloaded wind direction data saved by the `download_wtk_data` or `download_openmeteo_data` functions in the `wind_solar_resource_downloading` module.
-- `coords_filepath`: Filepath to the `.feather` file containing the coordinates corresponding to the downloaded wind data saved by the `download_wtk_data` or `download_openmeteo_data` functions in the `wind_solar_resource_downloading` module.
+- `ws_data_filepath`: Filepath to the `.feather` file containing raw downloaded wind speed data saved by the `download_wtk_data` function in `hercules.resource.wtk_downloader` or the `download_openmeteo_data` function in `hercules.resource.openmeteo_downloader`.
+- `wd_data_filepath`: Filepath to the `.feather` file containing raw downloaded wind direction data saved by the `download_wtk_data` function in `hercules.resource.wtk_downloader` or the `download_openmeteo_data` function in `hercules.resource.openmeteo_downloader`.
+- `coords_filepath`: Filepath to the `.feather` file containing the coordinates corresponding to the downloaded wind data saved by the `download_wtk_data` function in `hercules.resource.wtk_downloader` or the `download_openmeteo_data` function in `hercules.resource.openmeteo_downloader`.
 - `x_locs_upsample`: The "x" (Easting) locations of the desired upsampled locations (e.g., corresponding to turbine locations) relative to the provided origin coordinates in meters.
 - `y_locs_upsample`: The "y" (Northing) locations of the desired upsampled locations (e.g., corresponding to turbine locations) relative to the provided origin coordinates in meters.
 - `origin_lat`: The "origin" latitude corresponding to a `y_locs_upsample` location of 0.

examples/inputs/03_download_small_nsrdb_wtk_solar_wind_example.py

@@ -15,10 +15,7 @@
 import os
 import sys
 
-from hercules.resource.wind_solar_resource_downloader import (
-    download_nsrdb_data,
-    download_wtk_data,
-)
+import hercules.resource as resource
 from matplotlib import pyplot as plt
 
 sys.path.append(".")
@@ -30,7 +27,9 @@ def run_small_example():
     # ARM Southern Great Plains coordinates
     target_lat = 36.607322
     target_lon = -97.487643
-    year = 2020
+    # Use 2022 for solar because the NSRDB TMY dataset only includes 2022-2024 data,
+    #   and we want to demonstrate using a non-default dataset.
+    year_solar = 2022
 
     # Create data directory
     data_dir = "data/small_wtk_nsrdb_example"
@@ -42,12 +41,13 @@ def run_small_example():
 
     # Download a small sample of NSRDB data with plotting
     try:
-        nsrdb_data = download_nsrdb_data(
+        nsrdb_data = resource.nsrdb_downloader.download_nsrdb_data(
             target_lat=target_lat,
             target_lon=target_lon,
-            year=year,
+            year=year_solar,
             variables=["ghi"],  # Just one variable
-            nsrdb_dataset_path="/nrel/nsrdb/conus",  # Demonstrating using a non-default dataset
+            nsrdb_dataset_path="/nrel/nsrdb/GOES/tmy/v4.0.0",  # Using a non-default dataset
+            nsrdb_filename_prefix="nsrdb_tmy-",  # Downloading a typical meteorological year dataset
             coord_delta=0.05,  # Small area
             output_dir=data_dir,
             filename_prefix="nsrdb_small_example",
@@ -70,11 +70,14 @@ def run_small_example():
     print("=" * 60)
 
     # Download a small sample of WTK data with plotting
+    # Use 2020 for wind because WTK data is only avaialable 2018-2020
+    year_wind = 2020
+
     try:
-        wtk_data = download_wtk_data(
+        wtk_data = resource.wtk_downloader.download_wtk_data(
             target_lat=target_lat,
             target_lon=target_lon,
-            year=year,
+            year=year_wind,
             variables=["windspeed_100m"],  # Just one variable
             coord_delta=0.05,  # Small area
             output_dir=data_dir,

examples/inputs/04_download_and_upsample_wtk_wind_example.py

@@ -21,7 +21,7 @@
 import pandas as pd
 import utm
 from hercules.resource.upsample_wind_data import upsample_wind_data
-from hercules.resource.wind_solar_resource_downloader import download_wtk_data
+from hercules.resource.wtk_downloader import download_wtk_data
 from matplotlib import pyplot as plt
 
 sys.path.append(".")

examples/inputs/05_download_small_openmeteo_solar_wind_example.py

@@ -6,9 +6,7 @@
 import sys
 
 import numpy as np
-from hercules.resource.wind_solar_resource_downloader import (
-    download_openmeteo_data,
-)
+from hercules.resource.openmeteo_downloader import download_openmeteo_data
 from matplotlib import pyplot as plt
 
 sys.path.append(".")

examples/inputs/06_download_and_upsample_openmeteo_wind_example.py

@@ -10,10 +10,8 @@
 import numpy as np
 import pandas as pd
 import utm
+from hercules.resource.openmeteo_downloader import download_openmeteo_data
 from hercules.resource.upsample_wind_data import upsample_wind_data
-from hercules.resource.wind_solar_resource_downloader import (
-    download_openmeteo_data,
-)
 from matplotlib import pyplot as plt
 
 sys.path.append(".")

hercules/resource/__init__.py

@@ -0,0 +1,28 @@
+"""Resource downloading and processing utilities for Hercules.
+
+This subpackage contains modules for downloading and processing wind and
+solar resource data from multiple sources (NSRDB, WTK, Open-Meteo) and
+for upsampling wind data for use in Hercules simulations.
+"""
+
+from .nsrdb_downloader import download_nsrdb_data
+from .openmeteo_downloader import download_openmeteo_data
+from .resource_utilities import (
+    get_variable_colormap,
+    get_variable_label,
+    plot_spatial_map,
+    plot_timeseries,
+)
+from .upsample_wind_data import upsample_wind_data
+from .wtk_downloader import download_wtk_data
+
+__all__ = [
+    "download_nsrdb_data",
+    "download_wtk_data",
+    "download_openmeteo_data",
+    "plot_timeseries",
+    "plot_spatial_map",
+    "get_variable_label",
+    "get_variable_colormap",
+    "upsample_wind_data",
+]