pvlib.clearsky.detect_clearsky

pvlib.clearsky.detect_clearsky(measured, clearsky, times=None, infer_limits=False, window_length=10, 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)

Detects clear sky times using the algorithm developed by Reno and Hansen.

The algorithm [1] was designed and validated for analyzing GHI time series. Jordan and Hansen [2] extended the algorithm to plane-of-array (POA) irradiance measurements.

The algorithm [1] 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 five criteria. Default values for these thresholds are appropriate for 10 minute windows of 1 minute GHI data. For data at longer intervals, it is recommended to set infer_limits=True to use the thresholds from [2].

For POA data, clearsky must be on the same plane as measured.

Parameters:

• measured (array or Series) – Time series of measured GHI. [W/m2]

• clearsky (array or Series) – Time series of the expected clearsky GHI. [W/m2]

• times (DatetimeIndex, optional) – Times of measured and clearsky values. If not specified, the index of measured will be used.

• infer_limits (bool, default False) – If True, does not use passed in kwargs (or defaults), but instead interpolates these values from Table 1 in [2].

• window_length (int, default 10) – Length of sliding time window in minutes. Each window must contain at least three data points.

• mean_diff (float, default 75) – Threshold value for agreement between mean values of measured and clearsky in each interval, see Eq. 6 in [1]. [W/m2]

• max_diff (float, default 75) – Threshold value for agreement between maxima of measured and clearsky values in each interval, see Eq. 7 in [1]. [W/m2]

• lower_line_length (float, default -5) – Lower limit of line length criterion from Eq. 8 in [1].

• 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 clearsky to obtain the detected clear_samples. Only provided if return_components is True.

Raises:

• ValueError – If measured is not a Series and times is not provided.

• ValueError – If a window contains less than three data points.

• ValueError – If the measured data is not sufficient to fill a window.

• NotImplementedError – If timestamps are not equally spaced.

References

[1] (1,2)

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.

[2] (1,2,3)

Jordan, D.C. and C. Hansen, “Clear-sky detection for PV degradation analysis using multiple regression”, Renewable Energy, v209, p. 393-400, 2023. DOI: 10.1016/j.renene.2023.04.035

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

• uses centered windows (Matlab function uses left-aligned windows)