SPACING

This function verifies the time intervals between consecutive timestamps in a series.

It returns True when the difference between one timestamp and the preceding one exactly matches the specified pandas frequency string (e.g., ‘15min’ or ‘1H’). This is used to identify irregular logging intervals or data gaps.

Excel Usage

=SPACING(times, freq)

times (list[list], required): Timestamps in ISO8601 format.
freq (str, required): Expected interval between samples as a pandas frequency string (e.g. ‘15min’).

Returns (list[list]): 2D list of booleans (True if spacing matches), or an error string.

Example 1: Check regular 1-hour spacing

Inputs:

times	freq
2024-01-01T00:00:00Z	1H
2024-01-01T01:00:00Z
2024-01-01T02:00:00Z

Excel formula:

=SPACING({"2024-01-01T00:00:00Z";"2024-01-01T01:00:00Z";"2024-01-01T02:00:00Z"}, "1H")

Expected output:

Result
true
true
true

Example 2: Identify mismatch in irregular timestamp spacing

Inputs:

times	freq
2024-01-01T00:00:00Z	1H
2024-01-01T01:00:00Z
2024-01-01T03:00:00Z

Excel formula:

=SPACING({"2024-01-01T00:00:00Z";"2024-01-01T01:00:00Z";"2024-01-01T03:00:00Z"}, "1H")

Expected output:

Result
true
true
false

Example 3: Handle a scalar timestamp input

Inputs:

times	freq
2024-01-01T00:00:00Z	1H

Excel formula:

=SPACING("2024-01-01T00:00:00Z", "1H")

Expected output:

true

Example 4: Validate regular 15-minute intervals

Inputs:

times	freq
2024-01-01T00:00:00Z	15min
2024-01-01T00:15:00Z
2024-01-01T00:30:00Z
2024-01-01T00:45:00Z

Excel formula:

=SPACING({"2024-01-01T00:00:00Z";"2024-01-01T00:15:00Z";"2024-01-01T00:30:00Z";"2024-01-01T00:45:00Z"}, "15min")

Expected output:

Result
true
true
true
true

Python Code

Show Code

import pandas as pd
from pvanalytics.quality.time import spacing as result_func

def spacing(times, freq):
    """
    Check that the spacing between timestamps conforms to an expected frequency.

    See: https://pvanalytics.readthedocs.io/en/stable/generated/pvanalytics.quality.time.spacing.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        times (list[list]): Timestamps in ISO8601 format.
        freq (str): Expected interval between samples as a pandas frequency string (e.g. '15min').

    Returns:
        list[list]: 2D list of booleans (True if spacing matches), or an error string.
    """
    try:
        def flatten_str(data):
            if not isinstance(data, list): return [str(data)]
            return [str(val) for row in data for val in (row if isinstance(row, list) else [row]) if val != ""]

        time_list = flatten_str(times)

        if len(time_list) == 0:
            return "Error: input array cannot be empty"

        dt_idx = pd.DatetimeIndex(time_list)

        f = str(freq).strip()
        if not f:
            return "Error: freq must be provided"

        res = result_func(dt_idx, freq=f)

        return [[bool(v)] for v in res]
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

times *

Timestamps in ISO8601 format.

freq *

Expected interval between samples as a pandas frequency string (e.g. '15min').