check_panel_internal_consistency¶

def check_panel_internal_consistency(df: pl.DataFrame, df_name: str = "DataFrame") -> None:
    """Validate that all panel groups in a DataFrame have the same local column structure.

    For panel data with multiple groups (e.g., store_1__sales, store_2__sales),
    this checks that all groups have identical local column names.

    Parameters
    ----------
    df : pl.DataFrame
        DataFrame to validate. Must have "time" column.
    df_name : str, default="DataFrame"
        Name of DataFrame in error message (e.g., "y", "X_actual", "y_pred").

    Raises
    ------
    ValueError
        If panel groups have mismatched local column structures.

    Examples
    --------
    >>> import polars as pl
    >>> from datetime import datetime
    >>> # Valid panel data - both groups have same local columns
    >>> df = pl.DataFrame({
    ...     "time": [datetime(2020, 1, 1), datetime(2020, 1, 2)],
    ...     "store_1__sales": [10, 20],
    ...     "store_2__sales": [30, 40],
    ... })
    >>> check_panel_internal_consistency(df, "y")  # No error

    >>> # Invalid - group "store_1" has local column "sales" but group
    >>> # "store_2" has local column "revenue"
    >>> df_bad = pl.DataFrame({
    ...     "time": [datetime(2020, 1, 1)],
    ...     "store_1__sales": [10],
    ...     "store_2__revenue": [100],
    ... })
    >>> check_panel_internal_consistency(df_bad, "y")  # doctest: +SKIP
    Traceback (most recent call last):
        ...
    ValueError: Panel structure mismatch in y...

    See Also
    --------
    - [`check_panel_groups_match`][yohou.utils.validation.check_panel_groups_match] : Validate y and X_actual have matching panel groups.
    - [`check_groups`][yohou.utils.validation.check_groups] : Validate panel group names for forecaster operations.
    - [`inspect_panel`][yohou.utils.panel.inspect_panel] : Detect panel groups in a DataFrame.

    """
    _, groups = inspect_panel(df)
    if not groups:
        return  # No panel data, nothing to check

    # Get reference group (first one)
    ref_grp = next(iter(groups))
    ref_cols = sorted(c.split("__", 1)[1] for c in groups[ref_grp])

    # Check all other groups match reference
    for grp, cols in groups.items():
        curr_cols = sorted(c.split("__", 1)[1] for c in cols)
        if curr_cols != ref_cols:
            raise ValueError(
                f"Panel structure mismatch in `{df_name}`. Group '{ref_grp}' has local "
                f"columns {ref_cols}, but group '{grp}' has {curr_cols}."
            )