check_groups

yohou.utils.validation.check_groups(fitted_panel_groups, requested_panel_groups)

Validate and normalize panel group names for forecaster operations.

Validates that requested panel groups exist in the fitted forecaster and returns the normalized list of groups to use.

Parameters

Name	Type	Description	Default
fitted_panel_groups	list of str or None	Panel group names from fitted forecaster (groups_). None indicates the forecaster was fitted on global (non-panel) data.	required
requested_panel_groups	list of str or None	Panel group names requested for operation. If None, all fitted panel groups will be used.	required

Returns

Type	Description
list of str or None	Validated panel group names to use for the operation. None for global (non-panel) data.

Raises

Type	Description
ValueError	If requested_panel_groups is provided but forecaster was fitted on global data, or if any requested panel group was not present during fit.

Examples

>>> # Global data: no panel groups
>>> result = check_groups(fitted_panel_groups=None, requested_panel_groups=None)
>>> result is None
True

>>> # Panel data: use all fitted groups
>>> check_groups(fitted_panel_groups=["sales", "inventory"], requested_panel_groups=None)
['sales', 'inventory']

>>> # Panel data: validate specific groups
>>> check_groups(fitted_panel_groups=["sales", "inventory"], requested_panel_groups=["sales"])
['sales']

See Also

• check_groups_exist : Validate requested panel groups exist (deprecated).
• check_panel_groups_match : Validate y and X_actual have matching panel groups.
• inspect_panel : Detect panel groups in a DataFrame.

Source Code

View on GitHub

Show/Hide source

def check_groups(
    fitted_panel_groups: list[str] | None,
    requested_panel_groups: list[str] | None,
) -> list[str] | None:
    """Validate and normalize panel group names for forecaster operations.

    Validates that requested panel groups exist in the fitted forecaster and
    returns the normalized list of groups to use.

    Parameters
    ----------
    fitted_panel_groups : list of str or None
        Panel group names from fitted forecaster (groups_).
        None indicates the forecaster was fitted on global (non-panel) data.

    requested_panel_groups : list of str or None
        Panel group names requested for operation.
        If None, all fitted panel groups will be used.

    Returns
    -------
    list of str or None
        Validated panel group names to use for the operation.
        None for global (non-panel) data.

    Raises
    ------
    ValueError
        If requested_panel_groups is provided but forecaster was fitted on global data,
        or if any requested panel group was not present during fit.

    Examples
    --------
    >>> # Global data: no panel groups
    >>> result = check_groups(fitted_panel_groups=None, requested_panel_groups=None)
    >>> result is None
    True

    >>> # Panel data: use all fitted groups
    >>> check_groups(fitted_panel_groups=["sales", "inventory"], requested_panel_groups=None)
    ['sales', 'inventory']

    >>> # Panel data: validate specific groups
    >>> check_groups(fitted_panel_groups=["sales", "inventory"], requested_panel_groups=["sales"])
    ['sales']

    See Also
    --------
    - [`check_groups_exist`][yohou.utils.validation.check_groups_exist] : Validate requested panel groups exist (deprecated).
    - [`check_panel_groups_match`][yohou.utils.validation.check_panel_groups_match] : Validate y and X_actual have matching panel groups.
    - [`inspect_panel`][yohou.utils.panel.inspect_panel] : Detect panel groups in a DataFrame.

    """
    # If no groups requested, use all fitted groups
    if requested_panel_groups is None:
        return fitted_panel_groups

    # Validate that requested groups are compatible with fitted state
    if fitted_panel_groups is None:
        raise ValueError("The forecaster was fitted on global data, but `groups` were provided.")

    # Check that all requested groups exist in fitted groups
    missing_groups = set(requested_panel_groups) - set(fitted_panel_groups)
    if missing_groups:
        raise ValueError(
            f"Panel group(s) {sorted(missing_groups)} not found in fitted forecaster. "
            f"Available groups: {sorted(fitted_panel_groups)}."
        )

    return requested_panel_groups