spotforecast2 0.0.1__py3-none-any.whl

spotforecast2/preprocessing/split.py

@@ -0,0 +1,139 @@
+import pandas as pd
+
+
+def split_abs_train_val_test(
+    data: pd.DataFrame,
+    end_train: pd.Timestamp,
+    end_validation: pd.Timestamp,
+    verbose: bool = False,
+) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """Splits a time series DataFrame into training, validation, and test sets based on absolute timestamps.
+
+    Args:
+        data (pd.DataFrame): The time series data with a DateTimeIndex.
+        end_train (pd.Timestamp): The end date for the training set.
+        end_validation (pd.Timestamp): The end date for the validation set.
+
+    Returns:
+        tuple: A tuple containing:
+            - data_train (pd.DataFrame): The training set.
+            - data_val (pd.DataFrame): The validation set.
+            - data_test (pd.DataFrame): The test set.
+
+    Examples:
+        >>> from spotforecast2.data.fetch_data import fetch_data
+        >>> from spotforecast2.preprocessing.split import split_train_val_test
+        >>> data = fetch_data()
+        >>> end_train = pd.Timestamp('2020-12-31 23:00:00')
+        >>> end_validation = pd.Timestamp('2021-06-30 23:00:00')
+        >>> data_train, data_val, data_test = split_train_val_test(
+        ...     data,
+        ...     end_train=end_train,
+        ...     end_validation=end_validation,
+        ...     verbose=True
+        ... )
+    """
+    data = data.copy()
+    start_date = data.index.min()
+    end_date = data.index.max()
+    if verbose:
+        print(f"Start date: {start_date}")
+        print(f"End date: {end_date}")
+    data_train = data.loc[:end_train, :].copy()
+    data_val = data.loc[end_train:end_validation, :].copy()
+    data_test = data.loc[end_validation:, :].copy()
+
+    if verbose:
+        print(
+            f"Train: {data_train.index.min()} --- {data_train.index.max()}  (n={len(data_train)})"
+        )
+        print(
+            f"Val: {data_val.index.min()} --- {data_val.index.max()}  (n={len(data_val)})"
+        )
+        print(
+            f"Test: {data_test.index.min()} --- {data_test.index.max()}  (n={len(data_test)})"
+        )
+
+    return data_train, data_val, data_test
+
+
+def split_rel_train_val_test(
+    data: pd.DataFrame,
+    perc_train: float,
+    perc_val: float,
+    verbose: bool = False,
+) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """Splits a time series DataFrame into training, validation, and test sets by percentages.
+
+    The test percentage is computed as 1 - perc_train - perc_val.
+    Sizes are rounded to ensure the splits sum to the full dataset size.
+
+    Args:
+        data (pd.DataFrame): The time series data with a DateTimeIndex.
+        perc_train (float): Fraction of data used for training.
+        perc_val (float): Fraction of data used for validation.
+        verbose (bool): Whether to print additional information.
+
+    Returns:
+        tuple: A tuple containing:
+            - data_train (pd.DataFrame): The training set.
+            - data_val (pd.DataFrame): The validation set.
+            - data_test (pd.DataFrame): The test set.
+
+    Examples:
+        >>> from spotforecast2.data.fetch_data import fetch_data
+        >>> from spotforecast2.preprocessing.split import split_rel_train_val_test
+        >>> data = fetch_data()
+        >>> data_train, data_val, data_test = split_rel_train_val_test(
+        ...     data,
+        ...     perc_train=0.7,
+        ...     perc_val=0.2,
+        ...     verbose=True
+        ... )
+    """
+    data = data.copy()
+    if data.shape[0] == 0:
+        raise ValueError("Input data is empty.")
+    if not (0 <= perc_train <= 1) or not (0 <= perc_val <= 1):
+        raise ValueError("perc_train and perc_val must be between 0 and 1 (inclusive).")
+
+    perc_test = 1 - perc_train - perc_val
+    if verbose:
+        print(
+            f"Splitting data into train/val/test with percentages: "
+            f"{perc_train:.4%} / {perc_val:.4%} / {perc_test:.4%}"
+        )
+    if round(perc_test, 10) < 0.0:
+        print(
+            f"Splitting data into train/val/test with percentages: "
+            f"{perc_train:.4%} / {perc_val:.4%} / {perc_test:.4%}"
+        )
+        raise ValueError(
+            "perc_train and perc_val must sum to 1 or less to leave room for a test set."
+        )
+
+    n_total = len(data)
+    n_train = int(round(n_total * perc_train))
+    n_val = int(round(n_total * perc_val))
+    n_test = n_total - n_train - n_val
+
+    if n_test < 0:
+        n_test = 0
+        n_val = n_total - n_train
+    if n_val < 0:
+        n_val = 0
+        n_train = n_total
+
+    end_train_idx = n_train
+    end_val_idx = n_train + n_val
+
+    data_train = data.iloc[:end_train_idx, :].copy()
+    data_val = data.iloc[end_train_idx:end_val_idx, :].copy()
+    data_test = data.iloc[end_val_idx:, :].copy()
+
+    if verbose:
+        print(f"Train size: {len(data_train)} ({len(data_train) / n_total:.2%})")
+        print(f"Val size: {len(data_val)} ({len(data_val) / n_total:.2%})")
+        print(f"Test size: {len(data_test)} ({len(data_test) / n_total:.2%})")
+
+    return data_train, data_val, data_test

spotforecast2/utils/__init__.py

@@ -0,0 +1,43 @@
+"""Utility functions for spotforecast."""
+
+from spotforecast2.utils.validation import (
+    check_y,
+    check_exog,
+    get_exog_dtypes,
+    check_interval,
+    MissingValuesWarning,
+    DataTypeWarning,
+    check_exog_dtypes,
+    check_predict_input,
+)
+from spotforecast2.utils.data_transform import (
+    input_to_frame,
+    expand_index,
+    transform_dataframe,
+)
+from spotforecast2.utils.forecaster_config import (
+    initialize_lags,
+    initialize_weights,
+    check_select_fit_kwargs,
+)
+from spotforecast2.utils.convert_to_utc import convert_to_utc
+from spotforecast2.utils.generate_holiday import create_holiday_df
+
+__all__ = [
+    "check_y",
+    "check_exog",
+    "get_exog_dtypes",
+    "check_interval",
+    "MissingValuesWarning",
+    "DataTypeWarning",
+    "input_to_frame",
+    "initialize_lags",
+    "expand_index",
+    "initialize_weights",
+    "check_select_fit_kwargs",
+    "check_exog_dtypes",
+    "check_predict_input",
+    "transform_dataframe",
+    "convert_to_utc",
+    "create_holiday_df",
+]

spotforecast2/utils/convert_to_utc.py

@@ -0,0 +1,44 @@
+"""Utility functions for timezone conversion."""
+
+from typing import Optional
+import pandas as pd
+
+
+def convert_to_utc(df: pd.DataFrame, timezone: Optional[str]) -> pd.DataFrame:
+    """Convert DataFrame index timezone to UTC.
+
+    Args:
+        df: DataFrame with DatetimeIndex.
+        timezone: Optional timezone string. Required if index has no timezone.
+
+    Returns:
+        DataFrame with UTC timezone index.
+
+    Raises:
+        ValueError: If index is not DatetimeIndex or has no timezone and
+            timezone is None.
+
+    Examples:
+        >>> from spotforecast2.utils.convert_to_utc import convert_to_utc
+        >>> df = pd.DataFrame({"value": [1, 2, 3]}, index=pd.to_datetime(["2022-01-01", "2022-01-02", "2022-01-03"]))
+        >>> convert_to_utc(df, "Europe/Berlin")
+                   value
+        2022-01-01 00:00:00+01:00
+        2022-01-02 00:00:00+01:00
+        2022-01-03 00:00:00+01:00
+    """
+    if not isinstance(df.index, pd.DatetimeIndex):
+        raise ValueError(
+            "No DatetimeIndex found. Please specify the time column via 'index_col'"
+        )
+    if df.index.tz is None:
+        if timezone is not None:
+            df.index = df.index.tz_localize(timezone)
+        else:
+            raise ValueError(
+                "Index has no timezone information. Please provide a timezone."
+            )
+
+    df.index = df.index.tz_convert("UTC")
+
+    return df

spotforecast2/utils/data_transform.py

@@ -0,0 +1,208 @@
+"""
+Data transformation utilities for time series forecasting.
+
+This module provides functions for normalizing and transforming data formats.
+"""
+
+from typing import Union
+import numpy as np
+import pandas as pd
+
+
+def input_to_frame(
+    data: Union[pd.Series, pd.DataFrame], input_name: str
+) -> pd.DataFrame:
+    """
+    Convert input data to a pandas DataFrame.
+
+    This function ensures consistent DataFrame format for internal processing.
+    If data is already a DataFrame, it's returned as-is. If it's a Series,
+    it's converted to a single-column DataFrame.
+
+    Args:
+        data: Input data as pandas Series or DataFrame.
+        input_name: Name of the input data type. Accepted values are:
+            - 'y': Target time series
+            - 'last_window': Last window for prediction
+            - 'exog': Exogenous variables
+
+    Returns:
+        DataFrame version of the input data. For Series input, uses the series
+        name if available, otherwise uses a default name based on input_name.
+
+    Examples:
+        >>> import pandas as pd
+        >>> from spotforecast2.utils.data_transform import input_to_frame
+        >>>
+        >>> # Series with name
+        >>> y = pd.Series([1, 2, 3], name="sales")
+        >>> df = input_to_frame(y, input_name="y")
+        >>> df.columns.tolist()
+        ['sales']
+        >>>
+        >>> # Series without name (uses default)
+        >>> y_no_name = pd.Series([1, 2, 3])
+        >>> df = input_to_frame(y_no_name, input_name="y")
+        >>> df.columns.tolist()
+        ['y']
+        >>>
+        >>> # DataFrame (returned as-is)
+        >>> df_input = pd.DataFrame({"temp": [20, 21], "humidity": [50, 55]})
+        >>> df_output = input_to_frame(df_input, input_name="exog")
+        >>> df_output.columns.tolist()
+        ['temp', 'humidity']
+        >>>
+        >>> # Exog series without name
+        >>> exog = pd.Series([10, 20, 30])
+        >>> df_exog = input_to_frame(exog, input_name="exog")
+        >>> df_exog.columns.tolist()
+        ['exog']
+    """
+    output_col_name = {"y": "y", "last_window": "y", "exog": "exog"}
+
+    if isinstance(data, pd.Series):
+        data = data.to_frame(
+            name=data.name if data.name is not None else output_col_name[input_name]
+        )
+
+    return data
+
+
+def expand_index(index: Union[pd.Index, None], steps: int) -> pd.Index:
+    """
+    Create a new index extending from the end of the original index.
+
+    This function generates future indices for forecasting by extending the time
+    series index by a specified number of steps. Handles both DatetimeIndex and
+    RangeIndex appropriately.
+
+    Args:
+        index: Original pandas Index (DatetimeIndex or RangeIndex). If None,
+            creates a RangeIndex starting from 0.
+        steps: Number of future steps to generate.
+
+    Returns:
+        New pandas Index with `steps` future periods.
+
+    Raises:
+        TypeError: If steps is not an integer, or if index is neither DatetimeIndex
+            nor RangeIndex.
+
+    Examples:
+        >>> import pandas as pd
+        >>> from spotforecast2.utils.data_transform import expand_index
+        >>>
+        >>> # DatetimeIndex
+        >>> dates = pd.date_range("2023-01-01", periods=5, freq="D")
+        >>> new_index = expand_index(dates, 3)
+        >>> new_index
+        DatetimeIndex(['2023-01-06', '2023-01-07', '2023-01-08'], dtype='datetime64[ns]', freq='D')
+        >>>
+        >>> # RangeIndex
+        >>> range_idx = pd.RangeIndex(start=0, stop=10)
+        >>> new_index = expand_index(range_idx, 5)
+        >>> new_index
+        RangeIndex(start=10, stop=15, step=1)
+        >>>
+        >>> # None index (creates new RangeIndex)
+        >>> new_index = expand_index(None, 3)
+        >>> new_index
+        RangeIndex(start=0, stop=3, step=1)
+        >>>
+        >>> # Invalid: steps not an integer
+        >>> try:
+        ...     expand_index(dates, 3.5)
+        ... except TypeError as e:
+        ...     print("Error: steps must be an integer")
+        Error: steps must be an integer
+    """
+    if not isinstance(steps, (int, np.integer)):
+        raise TypeError(f"`steps` must be an integer. Got {type(steps)}.")
+
+    # Convert numpy integer to Python int if needed
+    if isinstance(steps, np.integer):
+        steps = int(steps)
+
+    if isinstance(index, pd.Index):
+        if isinstance(index, pd.DatetimeIndex):
+            new_index = pd.date_range(
+                start=index[-1] + index.freq, periods=steps, freq=index.freq
+            )
+        elif isinstance(index, pd.RangeIndex):
+            new_index = pd.RangeIndex(start=index[-1] + 1, stop=index[-1] + 1 + steps)
+        else:
+            raise TypeError(
+                "Argument `index` must be a pandas DatetimeIndex or RangeIndex."
+            )
+    else:
+        new_index = pd.RangeIndex(start=0, stop=steps)
+
+    return new_index
+
+
+def transform_dataframe(
+    df: pd.DataFrame,
+    transformer: object,
+    fit: bool = False,
+    inverse_transform: bool = False,
+) -> pd.DataFrame:
+    """
+    Transform raw values of pandas DataFrame with a scikit-learn alike
+    transformer, preprocessor or ColumnTransformer.
+
+    The transformer used must have the following methods: fit, transform,
+    fit_transform and inverse_transform. ColumnTransformers are not allowed
+    since they do not have inverse_transform method.
+
+    Args:
+        df: DataFrame to be transformed.
+        transformer: Scikit-learn alike transformer, preprocessor, or ColumnTransformer.
+            Must implement fit, transform, fit_transform and inverse_transform.
+        fit: Train the transformer before applying it. Defaults to False.
+        inverse_transform: Transform back the data to the original representation.
+            This is not available when using transformers of class
+            scikit-learn ColumnTransformers. Defaults to False.
+
+    Returns:
+        Transformed DataFrame.
+
+    Raises:
+        TypeError: If df is not a pandas DataFrame.
+        ValueError: If inverse_transform is requested for ColumnTransformer.
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError(f"`df` argument must be a pandas DataFrame. Got {type(df)}")
+
+    if transformer is None:
+        return df
+
+    # Check for ColumnTransformer by class name to avoid importing sklearn
+    is_column_transformer = type(
+        transformer
+    ).__name__ == "ColumnTransformer" or hasattr(transformer, "transformers")
+
+    if inverse_transform and is_column_transformer:
+        raise ValueError(
+            "`inverse_transform` is not available when using ColumnTransformers."
+        )
+
+    if not inverse_transform:
+        if fit:
+            values_transformed = transformer.fit_transform(df)
+        else:
+            values_transformed = transformer.transform(df)
+    else:
+        values_transformed = transformer.inverse_transform(df)
+
+    if hasattr(values_transformed, "toarray"):
+        # If the returned values are in sparse matrix format, it is converted to dense
+        values_transformed = values_transformed.toarray()
+
+    if isinstance(values_transformed, pd.DataFrame):
+        df_transformed = values_transformed
+    else:
+        df_transformed = pd.DataFrame(
+            values_transformed, index=df.index, columns=df.columns
+        )
+
+    return df_transformed