pvanalytics.quality.time.shifts_ruptures

pvanalytics.quality.time.shifts_ruptures(event_times, reference_times, period_min=2, shift_min=15, round_up_from=None, prediction_penalty=13)

Identify time shifts using the ruptures library.

Compares the event time in the expected time zone (reference_times) with the actual event time in event_times.

The Pelt changepoint detection method is applied to the difference between event_times and reference_times. For each period between change points the mode of the difference is rounded to a multiple of shift_min and returned as the time-shift for all days in that period.

Parameters

  • event_times (Series) – Time of an event in minutes since midnight. Should be a time series of integers with a single value per day. Typically the time mid-way between sunrise and sunset.

  • reference_times (Series) – Time of event in minutes since midnight for each day in the expected timezone. For example, passing solar transit time in a fixed offset time zone can be used to detect daylight savings shifts when it is unknown whether or not event_times is in a fixed offset time zone.

  • period_min (int, default 2) –

    Minimum number of days between shifts. Must be less than or equal to the number of days in event_times. [days]

    Increasing this parameter will make the result less sensitive to transient shifts. For example if your intent is to find and correct daylight savings time shifts passing period_min=60 can give good results while excluding shorter periods that appear shifted.

  • shift_min (int, default 15) – Minimum shift amount in minutes. All shifts are rounded to a multiple of shift_min. [minutes]

  • round_up_from (int, optional) – The number of minutes greater than a multiple of shift_min for a shift to be rounded up. If a shift is less than round_up_from then it will be rounded towards 0. If not specified then the shift will be rounded up from shift_min // 2. Using a larger value will effectively make the shift detection more conservative as small variations will tend to be rounded to zero. [minutes]

  • prediction_penalty (int, default 13) – Penalty used in assessing change points. See :py:method:`ruptures.detection.Pelt.predict` for more information.

Returns

  • shifted (Series) – Boolean series indicating whether there appears to be a time shift on that day.

  • shift_amount (Series) – Time shift in minutes for each day in event_times. These times can be used to shift the data into the same time zone as reference_times.

Raises

ValueError – If the number of days in event_times is less than period_min.

Notes

Timestamped data from monitored PV systems may not always be localized to a consistent timezone. In some cases, data is timestamped with local time that may or may not be adjusted for daylight savings time transitions. This function helps detect issues of this sort, by detecting points where the time of some daily event (e.g. solar noon) changes significantly with respect to a reference time for the event. If the data’s timestamps have not been adjusted for daylight savings transitions, the time of day at solar noon will change by roughly 60 minutes in the days before and after the transition.

To use this changepoint detection method to determine if your data’s timestamps involve daylight savings transitions, first reduce your PV system data (irradiance or power) to a daily time series, with each point being the observed midday time in minutes. For example, if sunrise and sunset are inferred from the PV system data, the midday time can be inferred as the average of each day’s sunrise and sunset time of day. To establish the expected midday time, calculate solar transit time in time of day. This function detects shifts in the difference between the observed and expected midday times, and returns (here I’m unclear what is being returned)

Derived from the PVFleets QA project.