# pvlib.clearsky.detect_clearsky¶

pvlib.clearsky.detect_clearsky(measured, clearsky, times=None, 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)[source]

Detects clear sky times according to the algorithm developed by Reno and Hansen for GHI measurements. The algorithm 1 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 GHI. [W/m2]

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

• times (DatetimeIndex or None, default None.) – Times of measured and clearsky values. If None the index of measured will be used.

• window_length (int, default 10) – 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]. [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]. 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.

Raises

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.

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)