check_inputs

yohou.utils.validation.check_inputs(y, X_actual)

Validate that target and feature DataFrames have consistent time intervals.

Ensures all input DataFrames (target y and exogenous features X_actual) have the same uniform time interval. This is required for proper alignment in forecasting operations.

Parameters

Name	Type	Description	Default
y	DataFrame	Target time series with "time" column.	required
X_actual	DataFrame or None	Exogenous feature time series with "time" column, or None.	required

Returns

Type	Description
str	The common time interval shared by all provided DataFrames (e.g., "1d", "1mo").

Raises

Type	Description
ValueError	If any DataFrame has inconsistent intervals internally, or if the intervals don't match across DataFrames.

Examples

>>> import polars as pl
>>> from datetime import datetime
>>> time_index = pl.datetime_range(
...     start=datetime(2020, 1, 1), end=datetime(2020, 1, 5), interval="1d", eager=True
... )
>>> y = pl.DataFrame({"time": time_index, "sales": [100, 110, 120, 130, 140]})
>>> X_actual = pl.DataFrame({"time": time_index, "holiday": [0, 0, 1, 0, 0]})
>>> interval = check_inputs(y, X_actual)
>>> interval
'1d'

See Also

• check_interval_consistency : Validates single DataFrame intervals
• validate_column_names : Validates column names don't misuse __ separator

Source Code

View on GitHub

Show/Hide source

def check_inputs(y: pl.DataFrame, X_actual: pl.DataFrame | None) -> str:
    """Validate that target and feature DataFrames have consistent time intervals.

    Ensures all input DataFrames (target y and exogenous features X_actual) have the same
    uniform time interval. This is required for proper alignment in forecasting
    operations.

    Parameters
    ----------
    y : pl.DataFrame
        Target time series with "time" column.

    X_actual : pl.DataFrame or None
        Exogenous feature time series with "time" column, or None.

    Returns
    -------
    str
        The common time interval shared by all provided DataFrames (e.g., "1d", "1mo").

    Raises
    ------
    ValueError
        If any DataFrame has inconsistent intervals internally, or if the intervals
        don't match across DataFrames.

    Examples
    --------
    >>> import polars as pl
    >>> from datetime import datetime
    >>> time_index = pl.datetime_range(
    ...     start=datetime(2020, 1, 1), end=datetime(2020, 1, 5), interval="1d", eager=True
    ... )
    >>> y = pl.DataFrame({"time": time_index, "sales": [100, 110, 120, 130, 140]})
    >>> X_actual = pl.DataFrame({"time": time_index, "holiday": [0, 0, 1, 0, 0]})
    >>> interval = check_inputs(y, X_actual)
    >>> interval
    '1d'

    See Also
    --------
    - [`check_interval_consistency`][yohou.utils.validation.check_interval_consistency] : Validates single DataFrame intervals
    - [`validate_column_names`][yohou.utils.validation.validate_column_names] : Validates column names don't misuse __ separator

    """
    # Validate column names first
    validate_column_names(y)
    if X_actual is not None:
        validate_column_names(X_actual)

    y_interval = check_interval_consistency(y)
    if X_actual is not None:
        X_interval = check_interval_consistency(X_actual)

        if X_interval != y_interval:
            raise ValueError(
                f"Time interval mismatch: y has interval {y_interval}, but X_actual has interval "
                f"{X_interval}. All inputs must have the same time interval."
            )

    return y_interval