pvlib.clearsky.detect_clearsky

pvlib.clearsky.detect_clearsky(measured, clearsky, times, window_length, mean_diff=75, max_diff=75, lower_line_length=-5, upper_line_length=10, var_diff=0.005, slope_dev=8, max_iterations=20, return_components=False)[source]

Detects clear sky times according to the algorithm developed by Reno and Hansen for GHI measurements [1]. The algorithm was designed and validated for analyzing GHI time series only. Users may attempt to apply it to other types of time series data using different filter settings, but should be skeptical of the results.

The algorithm detects clear sky times by comparing statistics for a measured time series and an expected clearsky time series. Statistics are calculated using a sliding time window (e.g., 10 minutes). An iterative algorithm identifies clear periods, uses the identified periods to estimate bias in the clearsky data, scales the clearsky data and repeats.

Clear times are identified by meeting 5 criteria. Default values for these thresholds are appropriate for 10 minute windows of 1 minute GHI data.

Parameters:
measured : array or Series

Time series of measured values.

clearsky : array or Series

Time series of the expected clearsky values.

times : DatetimeIndex

Times of measured and clearsky values.

window_length : int

Length of sliding time window in minutes. Must be greater than 2 periods.

mean_diff : float, default 75

Threshold value for agreement between mean values of measured and clearsky in each interval, see Eq. 6 in [1].

max_diff : float, default 75

Threshold value for agreement between maxima of measured and clearsky values in each interval, see Eq. 7 in [1].

lower_line_length : float, default -5

Lower limit of line length criterion from Eq. 8 in [1]. Criterion satisfied when lower_line_length < line length difference < upper_line_length

upper_line_length : float, default 10

Upper limit of line length criterion from Eq. 8 in [1].

var_diff : float, default 0.005

Threshold value in Hz for the agreement between normalized standard deviations of rate of change in irradiance, see Eqs. 9 through 11 in [1].

slope_dev : float, default 8

Threshold value for agreement between the largest magnitude of change in successive values, see Eqs. 12 through 14 in [1].

max_iterations : int, default 20

Maximum number of times to apply a different scaling factor to the clearsky and redetermine clear_samples. Must be 1 or larger.

return_components : bool, default False

Controls if additional output should be returned. See below.

Returns:
clear_samples : array or Series

Boolean array or Series of whether or not the given time is clear. Return type is the same as the input type.

components : OrderedDict, optional

Dict of arrays of whether or not the given time window is clear for each condition. Only provided if return_components is True.

alpha : scalar, optional

Scaling factor applied to the clearsky_ghi to obtain the detected clear_samples. Only provided if return_components is True.

Notes

Initial implementation in MATLAB by Matthew Reno. Modifications for computational efficiency by Joshua Patrick and Curtis Martin. Ported to Python by Will Holmgren, Tony Lorenzo, and Cliff Hansen.

Differences from MATLAB version:

  • no support for unequal times
  • automatically determines sample_interval
  • requires a reference clear sky series instead calculating one from a user supplied location and UTCoffset
  • parameters are controllable via keyword arguments
  • option to return individual test components and clearsky scaling parameter

References

[1] Reno, M.J. and C.W. Hansen, “Identification of periods of clear sky irradiance in time series of GHI measurements” Renewable Energy, v90, p. 520-531, 2016.