Irradiance sphinx documentation

docs/examples/clearsky-limits-irradiance.py

@@ -0,0 +1,84 @@
+"""
+Clearsky Limits for Irradiance Data
+===================================
+
+Checking the clearsky limits of irradiance data.
+"""
+
+# %%
+# Identifying and filtering out invalid irradiance data is a
+# useful way to reduce noise during analysis. In this example,
+# we use :py:func:`pvanalytics.quality.irradiance.clearsky_limits`
+# to identify irradiance values that do not exceed
+# a limit based on a clear-sky model. For this example we will
+# use GHI data from the RMIS weather system located on the NREL campus in CO.
+
+import pvanalytics
+from pvanalytics.quality.irradiance import clearsky_limits
+from pvanalytics.features.daytime import power_or_irradiance
+import pvlib
+import matplotlib.pyplot as plt
+import pandas as pd
+import pathlib
+
+# %%
+# First, read in data from the RMIS NREL system. This data set contains
+# 5-minute right-aligned POA, GHI, DNI, DHI, and GNI measurements,
+# but only the GHI is relevant here.
+
+pvanalytics_dir = pathlib.Path(pvanalytics.__file__).parent
+rmis_file = pvanalytics_dir / 'data' / 'irradiance_RMIS_NREL.csv'
+data = pd.read_csv(rmis_file, index_col=0, parse_dates=True)
+freq = '5T'
+# Make the datetime index tz-aware.
+data.index = data.index.tz_localize("Etc/GMT+7")
+
+
+# %%
+# Now model clear-sky irradiance for the location and times of the
+# measured data. You can do this using
+# :py:meth:`pvlib.location.Location.get_clearsky`, using the lat-long
+# coordinates associated the RMIS NREL system.
+
+location = pvlib.location.Location(39.7407, -105.1686)
+clearsky = location.get_clearsky(data.index)
+
+# %%
+# Use :py:func:`pvanalytics.quality.irradiance.clearsky_limits`.
+# Here, we check GHI data in field 'irradiance_ghi__7981'.
+# :py:func:`pvanalytics.quality.irradiance.clearsky_limits`
+# returns a mask that identifies data that falls between
+# lower and upper limits. The defaults (used here)
+# are upper bound of 110% of clear-sky GHI, and
+# no lower bound.
+
+clearsky_limit_mask = clearsky_limits(data['irradiance_ghi__7981'],
+                                      clearsky['ghi'])
+
+
+# %%
+# Mask nighttime values in the GHI time series using the
+# :py:func:`pvanalytics.features.daytime.power_or_irradiance` function.
+# We will then remove nighttime values from the GHI time series.
+
+day_night_mask = power_or_irradiance(series=data['irradiance_ghi__7981'],
+                                     freq=freq)
+
+# %%
+# Plot the 'irradiance_ghi__7981' data stream and its associated clearsky GHI
+# data stream. Mask the GHI time series by its clearsky_limit_mask for daytime
+# periods.
+# Please note that a simple Ineichen model with static monthly turbidities
+# isn't always accurate, as in this case. Other models that may provide better
+# clear-sky estimates include McClear or PSM3.
+data['irradiance_ghi__7981'].plot()
+clearsky['ghi'].plot()
+data.loc[clearsky_limit_mask & day_night_mask][
+    'irradiance_ghi__7981'].plot(ls='', marker='.')
+plt.legend(labels=["RMIS GHI", "Clearsky GHI",
+                   "Under Clearsky Limit"],
+           loc="upper left")
+plt.xlabel("Date")
+plt.ylabel("GHI (W/m^2)")
+plt.tight_layout()
+plt.show()

docs/examples/daily-insolation-limits-irradiance.py

@@ -0,0 +1,69 @@
+"""
+Clearsky Limits for Daily Insolation
+====================================
+
+Checking the clearsky limits for daily insolation data.
+"""
+
+# %%
+# Identifying and filtering out invalid irradiance data is a
+# useful way to reduce noise during analysis. In this example,
+# we use :py:func:`pvanalytics.quality.irradiance.daily_insolation_limits`
+# to determine when the daily insolation lies between a minimum
+# and a maximum value. Irradiance measurements and clear-sky
+# irradiance on each day are integrated with the trapezoid rule
+# to calculate daily insolation. For this example we will use data
+# from the RMIS weather system located on the NREL campus
+# in Colorado, USA.
+
+import pvanalytics
+from pvanalytics.quality.irradiance import daily_insolation_limits
+import pvlib
+import matplotlib.pyplot as plt
+import pandas as pd
+import pathlib
+
+# %%
+# First, read in data from the RMIS NREL system. This data set contains
+# 5-minute right-aligned data. It includes POA, GHI,
+# DNI, DHI, and GNI measurements.
+
+pvanalytics_dir = pathlib.Path(pvanalytics.__file__).parent
+rmis_file = pvanalytics_dir / 'data' / 'irradiance_RMIS_NREL.csv'
+data = pd.read_csv(rmis_file, index_col=0, parse_dates=True)
+# Make the datetime index tz-aware.
+data.index = data.index.tz_localize("Etc/GMT+7")
+
+# %%
+# Now model clear-sky irradiance for the location and times of the
+# measured data:
+location = pvlib.location.Location(39.7407, -105.1686)
+clearsky = location.get_clearsky(data.index)
+
+# %%
+# Use :py:func:`pvanalytics.quality.irradiance.daily_insolation_limits`
+# to identify if the daily insolation lies between a minimum
+# and a maximum value. Here, we check GHI irradiance field
+# 'irradiance_ghi__7981'.
+# :py:func:`pvanalytics.quality.irradiance.daily_insolation_limits`
+# returns a mask that identifies data that falls between
+# lower and upper limits. The defaults (used here)
+# are upper bound of 125% of clear-sky daily insolation,
+# and lower bound of 40% of clear-sky daily insolation.
+
+daily_insolation_mask = daily_insolation_limits(data['irradiance_ghi__7981'],
+                                                clearsky['ghi'])
+
+# %%
+# Plot the 'irradiance_ghi__7981' data stream and its associated clearsky GHI
+# data stream. Mask the GHI time series by its daily_insolation_mask.
+data['irradiance_ghi__7981'].plot()
+clearsky['ghi'].plot()
+data.loc[daily_insolation_mask, 'irradiance_ghi__7981'].plot(ls='', marker='.')
+plt.legend(labels=["RMIS GHI", "Clearsky GHI",
+                   "Within Daily Insolation Limit"],
+           loc="upper left")
+plt.xlabel("Date")
+plt.ylabel("GHI (W/m^2)")
+plt.tight_layout()
+plt.show()

docs/examples/qcrad-consistency-irradiance.py

@@ -0,0 +1,88 @@
+"""
+QCrad Consistency for Irradiance Data
+=====================================
+
+Check consistency of GHI, DHI and DNI using QCRad criteria.
+"""
+
+# %%
+# Identifying and filtering out invalid irradiance data is a
+# useful way to reduce noise during analysis. In this example,
+# we use
+# :py:func:`pvanalytics.quality.irradiance.check_irradiance_consistency_qcrad`
+# to check the consistency of GHI, DHI and DNI data using QCRad criteria.
+# For this example we will use data from the RMIS weather system located
+# on the NREL campus in Colorado, USA.
+
+
+import pvanalytics
+from pvanalytics.quality.irradiance import check_irradiance_consistency_qcrad
+import pvlib
+import matplotlib.pyplot as plt
+import pandas as pd
+import pathlib
+
+# %%
+# First, read in data from the RMIS NREL system. This data set contains
+# 5-minute right-aligned data. It includes POA, GHI,
+# DNI, DHI, and GNI measurements.
+
+pvanalytics_dir = pathlib.Path(pvanalytics.__file__).parent
+rmis_file = pvanalytics_dir / 'data' / 'irradiance_RMIS_NREL.csv'
+data = pd.read_csv(rmis_file, index_col=0, parse_dates=True)
+
+# %%
+# Now generate solar zenith estimates for the location,
+# based on the data's time zone and site latitude-longitude
+# coordinates.
+latitude = 39.742
+longitude = -105.18
+time_zone = "Etc/GMT+7"
+data = data.tz_localize(time_zone)
+solar_position = pvlib.solarposition.get_solarposition(data.index,
+                                                       latitude,
+                                                       longitude)
+
+# %%
+# Use
+# :py:func:`pvanalytics.quality.irradiance.check_irradiance_consistency_qcrad`
+# to generate the QCRAD consistency mask.
+
+qcrad_consistency_mask = check_irradiance_consistency_qcrad(
+    solar_zenith=solar_position['zenith'],
+    ghi=data['irradiance_ghi__7981'],
+    dhi=data['irradiance_dhi__7983'],
+    dni=data['irradiance_dni__7982'])
+
+
+# %%
+# Plot the GHI, DHI, and DNI data streams with the QCRAD
+# consistency mask overlay. This mask applies to all 3 data streams.
+fig = data[['irradiance_ghi__7981', 'irradiance_dhi__7983',
+            'irradiance_dni__7982']].plot()
+# Highlight periods where the QCRAD consistency mask is True
+fig.fill_between(data.index, fig.get_ylim()[0], fig.get_ylim()[1],
+                 where=qcrad_consistency_mask[0], alpha=0.4)
+fig.legend(labels=["RMIS GHI", "RMIS DHI", "RMIS DNI", "QCRAD Consistent"],
+           loc="upper center")
+plt.xlabel("Date")
+plt.ylabel("Irradiance (W/m^2)")
+plt.tight_layout()
+plt.show()
+
+# %%
+# Plot the GHI, DHI, and DNI data streams with the diffuse
+# ratio limit mask overlay. This mask is true when the
+# DHI / GHI ratio passes the limit test.
+fig = data[['irradiance_ghi__7981', 'irradiance_dhi__7983',
+            'irradiance_dni__7982']].plot()
+# Highlight periods where the GHI ratio passes the limit test
+fig.fill_between(data.index, fig.get_ylim()[0], fig.get_ylim()[1],
+                 where=qcrad_consistency_mask[1], alpha=0.4)
+fig.legend(labels=["RMIS GHI", "RMIS DHI", "RMIS DNI",
+                   "Within Diffuse Ratio Limit"],
+           loc="upper center")
+plt.xlabel("Date")
+plt.ylabel("Irradiance (W/m^2)")
+plt.tight_layout()
+plt.show()

docs/examples/qcrad-limits-irradiance.py

@@ -0,0 +1,97 @@
+"""
+QCrad Limits for Irradiance Data
+================================
+
+Test for physical limits on GHI, DHI or DNI using the QCRad criteria.
+"""
+
+# %%
+# Identifying and filtering out invalid irradiance data is a
+# useful way to reduce noise during analysis. In this example,
+# we use
+# :py:func:`pvanalytics.quality.irradiance.check_irradiance_limits_qcrad`
+# to test for physical limits on GHI, DHI or DNI using the QCRad criteria.
+# For this example we will use data from the RMIS weather system located
+# on the NREL campus in Colorado, USA.
+
+import pvanalytics
+from pvanalytics.quality.irradiance import check_irradiance_limits_qcrad
+import pvlib
+import matplotlib.pyplot as plt
+import pandas as pd
+import pathlib
+
+# %%
+# First, read in data from the RMIS NREL system. This data set contains
+# 5-minute right-aligned data. It includes POA, GHI,
+# DNI, DHI, and GNI measurements.
+
+pvanalytics_dir = pathlib.Path(pvanalytics.__file__).parent
+rmis_file = pvanalytics_dir / 'data' / 'irradiance_RMIS_NREL.csv'
+data = pd.read_csv(rmis_file, index_col=0, parse_dates=True)
+
+# %%
+# Now generate solar zenith estimates for the location,
+# based on the data's time zone and site latitude-longitude
+# coordinates. This is done using the
+# :py:func:`pvlib.solarposition.get_solarposition` function.
+latitude = 39.742
+longitude = -105.18
+time_zone = "Etc/GMT+7"
+data = data.tz_localize(time_zone)
+solar_position = pvlib.solarposition.get_solarposition(data.index,
+                                                       latitude,
+                                                       longitude)
+
+# %%
+# Generate the estimated extraterrestrial radiation for the time series,
+# referred to as dni_extra. This is done using the
+# :py:func:`pvlib.irradiance.get_extra_radiation` function.
+dni_extra = pvlib.irradiance.get_extra_radiation(data.index)
+
+# %%
+# Use :py:func:`pvanalytics.quality.irradiance.check_irradiance_limits_qcrad`
+# to generate the QCRAD irradiance limit mask
+
+qcrad_limit_mask = check_irradiance_limits_qcrad(
+    solar_zenith=solar_position['zenith'],
+    dni_extra=dni_extra,
+    ghi=data['irradiance_ghi__7981'],
+    dhi=data['irradiance_dhi__7983'],
+    dni=data['irradiance_dni__7982'])
+
+# %%
+# Plot the 'irradiance_ghi__7981' data stream with its associated QCRAD limit
+# mask.
+data['irradiance_ghi__7981'].plot()
+data.loc[qcrad_limit_mask[0], 'irradiance_ghi__7981'].plot(ls='', marker='.')
+plt.legend(labels=["RMIS GHI", "Within QCRAD Limits"],
+           loc="upper left")
+plt.xlabel("Date")
+plt.ylabel("GHI (W/m^2)")
+plt.tight_layout()
+plt.show()
+
+# %%
+# Plot the 'irradiance_dhi__7983 data stream with its associated QCRAD limit
+# mask.
+data['irradiance_dhi__7983'].plot()
+data.loc[qcrad_limit_mask[1], 'irradiance_dhi__7983'].plot(ls='', marker='.')
+plt.legend(labels=["RMIS DHI", "Within QCRAD Limits"],
+           loc="upper left")
+plt.xlabel("Date")
+plt.ylabel("DHI (W/m^2)")
+plt.tight_layout()
+plt.show()
+
+# %%
+# Plot the 'irradiance_dni__7982' data stream with its associated QCRAD limit
+# mask.
+data['irradiance_dni__7982'].plot()
+data.loc[qcrad_limit_mask[2], 'irradiance_dni__7982'].plot(ls='', marker='.')
+plt.legend(labels=["RMIS DNI", "Within QCRAD Limits"],
+           loc="upper left")
+plt.xlabel("Date")
+plt.ylabel("DNI (W/m^2)")
+plt.tight_layout()
+plt.show()

docs/whatsnew/0.1.2.rst

@@ -38,6 +38,12 @@ Documentation
 * Added examples for the pvanalytics.features.daytime module,
   including :py:func:`pvanalytics.features.daytime.power_or_irradiance`
   (:issue:`133`, :pull:`139`)
+* Added examples for the pvanalytics.quality.irradiance module,
+  including :py:func:`pvanalytics.quality.irradiance.clearsky_limits`,
+  :py:func:`pvanalytics.quality.irradiance.daily_insolation_limits`,
+  :py:func:`pvanalytics.quality.irradiance.check_irradiance_consistency_qcrad`,
+  and :py:func:`pvanalytics.quality.irradiance.check_irradiance_limits_qcrad`
+  (:issue:`133`, :pull:`140`)
 
 
 Contributors