Datasets

skforecast.datasets.fetch_dataset

fetch_dataset(
    name,
    version=None,
    raw=False,
    kwargs_read=None,
    verbose=True,
)

Fetch a dataset from the skforecast-datasets repository.

Parameters:

Name	Type	Description	Default
name	str	Name of the dataset to fetch.	required
version	(str, int)	Deprecated since version 0.27.0, it has no effect and will be removed in version 0.29.0. Datasets are always fetched from the main branch of skforecast-datasets.	None
raw	bool	If True, the raw dataset is fetched. If False, the preprocessed dataset is fetched: the column with the date/time is set as index, converted to datetime and sorted. When the dates are unique, the frequency of the dataset is set with asfreq (rows with NaN are introduced for missing dates, with a MissingValuesWarning).	False
kwargs_read	dict	Kwargs to pass to pandas pd.read_csv or pd.read_parquet function depending on the dataset file type.	None
verbose	bool	If True, print information about the dataset.	True

Returns:

Name	Type	Description
df	pandas DataFrame	Dataset.

Notes

Datasets with several series in long format (one row per series and date, see their description in show_datasets_info) have repeated dates in the index, so no frequency is set and the rows are sorted by date, keeping the order of the series within each date. Use reshape_series_long_to_dict (after reset_index, it needs the dates as a column) or pivot_table to get one series per key or column.

Source code in skforecast/datasets/datasets.py

def fetch_dataset(
    name: str,
    version: str | int | None = None,
    raw: bool = False,
    kwargs_read: dict | None = None,
    verbose: bool = True
) -> pd.DataFrame:
    """
    Fetch a dataset from the skforecast-datasets repository.

    Parameters
    ----------
    name : str
        Name of the dataset to fetch.
    version : str, int, default None
        **Deprecated** since version 0.27.0, it has no effect and will be removed
        in version 0.29.0. Datasets are always fetched from the main branch of
        skforecast-datasets.
    raw : bool, default False
        If `True`, the raw dataset is fetched. If `False`, the preprocessed
        dataset is fetched: the column with the date/time is set as index,
        converted to datetime and sorted. When the dates are unique, the
        frequency of the dataset is set with `asfreq` (rows with NaN are
        introduced for missing dates, with a `MissingValuesWarning`).
    kwargs_read : dict, default None
        Kwargs to pass to pandas `pd.read_csv` or `pd.read_parquet` function
        depending on the dataset file type.
    verbose : bool, default True
        If `True`, print information about the dataset.

    Returns
    -------
    df : pandas DataFrame
        Dataset.

    Notes
    -----
    Datasets with several series in long format (one row per series and date,
    see their description in `show_datasets_info`) have repeated dates in the
    index, so no frequency is set and the rows are sorted by date, keeping the
    order of the series within each date. Use `reshape_series_long_to_dict`
    (after `reset_index`, it needs the dates as a column) or `pivot_table` to
    get one series per key or column.

    """

    _warn_deprecated_version(version)
    kwargs_read = kwargs_read or {}

    if name not in datasets:
        raise ValueError(
            f"Dataset '{name}' not found. "
            f"Available datasets are: {sorted(datasets)}"
        )

    file_type = datasets[name]['file_type']
    if file_type not in ('csv', 'parquet'):
        raise ValueError(
            f"Unknown file type '{file_type}' for dataset '{name}'. "
            f"Supported file types are 'csv' and 'parquet'."
        )

    url = datasets[name]['url']
    if '{version}' in url:
        url = url.format(version='main')

    if file_type == 'csv':
        kwargs_read = {'sep': datasets[name]['sep'], **kwargs_read}
        try:
            df = pd.read_csv(url, **kwargs_read)
        except Exception as e:
            raise ValueError(
                f"Error reading dataset '{name}' from {url}: {str(e)}."
            ) from e
    elif file_type == 'parquet':
        try:
            df = pd.read_parquet(url, **kwargs_read)
        except ImportError as e:
            raise ImportError(
                f"Reading dataset '{name}' requires pyarrow or fastparquet: "
                f"pip install pyarrow. Original error: {e}"
            ) from e
        except Exception as e:
            raise ValueError(
                f"Error reading dataset '{name}' from {url}: {str(e)}."
            ) from e
        # pyarrow keeps the memory used while reading in its pool. Returning it
        # to the OS lets the preprocessing of large datasets (e.g. m5) fit in
        # memory.
        try:
            import pyarrow as pa
            pa.default_memory_pool().release_unused()
        except ImportError:
            pass

    if not raw:
        n_inserted = n_dropped = 0
        try:
            index_col = datasets[name]['index_col']
            freq = datasets[name]['freq']
            date_format = datasets[name]['date_format']
            if df.index.name != index_col:
                # Unlike `set_index`, `pop` does not copy the whole DataFrame
                df.index = df.pop(index_col)
            df.index = pd.to_datetime(df.index, format=date_format)
            if df.index.is_unique:
                index_before = df.index
                df = df.asfreq(freq)
                n_inserted = len(df.index.difference(index_before))
                n_dropped = len(index_before.difference(df.index))
            if not df.index.is_monotonic_increasing:
                # Stable, to keep the order of the series of long-format datasets
                # within each date
                df = df.sort_index(kind='stable')
        except Exception as e:
            warnings.warn(
                f"Could not preprocess dataset '{name}': {e}",
                stacklevel=2
            )

        # Outside the `try`, so that a warning turned into an error is not
        # reported as a preprocessing failure
        if n_inserted > 0:
            warnings.warn(
                f"Dataset '{name}' has {n_inserted} missing dates for frequency "
                f"'{freq}'. Rows with NaN values have been introduced after "
                f"setting the frequency.",
                MissingValuesWarning,
                stacklevel=2
            )
        if n_dropped > 0:
            warnings.warn(
                f"{n_dropped} rows of dataset '{name}' are not aligned with "
                f"frequency '{freq}' and have been dropped after setting the "
                f"frequency. The frequency of the dataset may be wrong, use "
                f"`raw=True` to get the original data.",
                stacklevel=2
            )

    if verbose:
        _print_dataset_info(name, shape=df.shape)

    return df

skforecast.datasets.load_demo_dataset

load_demo_dataset(version=None, verbose=True)

Load demo data set with monthly expenditure ($AUD) on corticosteroid drugs that the Australian health system had between 1991 and 2008. Obtained from the book: Forecasting: Principles and Practice by Rob J Hyndman and George Athanasopoulos. Index is set to datetime with monthly frequency and sorted.

Parameters:

Name	Type	Description	Default
version	(str, int)	Deprecated since version 0.27.0, it has no effect and will be removed in version 0.29.0. Datasets are always fetched from the main branch of skforecast-datasets.	None
verbose	bool	If True, print information about the dataset.	True

Returns:

Name	Type	Description
y	pandas Series	Dataset.

Source code in skforecast/datasets/datasets.py

def load_demo_dataset(
    version: str | int | None = None,
    verbose: bool = True
) -> pd.Series:
    """
    Load demo data set with monthly expenditure ($AUD) on corticosteroid drugs that
    the Australian health system had between 1991 and 2008. Obtained from the book:
    Forecasting: Principles and Practice by Rob J Hyndman and George Athanasopoulos.
    Index is set to datetime with monthly frequency and sorted.

    Parameters
    ----------
    version : str, int, default None
        **Deprecated** since version 0.27.0, it has no effect and will be removed
        in version 0.29.0. Datasets are always fetched from the main branch of
        skforecast-datasets.
    verbose : bool, default True
        If `True`, print information about the dataset.

    Returns
    -------
    y : pandas Series
        Dataset.

    """

    _warn_deprecated_version(version)

    # `version` is not passed, so the deprecation warning is raised only once
    y = fetch_dataset('h2o', raw=False, verbose=False)['x']
    y = y.rename('y')
    y.index.name = 'datetime'

    if verbose:
        _print_dataset_info('h2o', shape=y.shape)

    return y

skforecast.datasets.show_datasets_info

show_datasets_info(datasets_names=None, version=None)

Print information about available datasets. If datasets_names is provided, only information about those datasets will be printed.

Parameters:

Name	Type	Description	Default
datasets_names	(str, list)	Name or list of names of the datasets to display information about. If None, information about all datasets will be displayed.	None
version	(str, int)	Deprecated since version 0.27.0, it has no effect and will be removed in version 0.29.0. Datasets are always fetched from the main branch of skforecast-datasets.	None

Returns:

Type	Description
None

Source code in skforecast/datasets/datasets.py

def show_datasets_info(
    datasets_names: str | list[str] | None = None,
    version: str | int | None = None
) -> None:
    """
    Print information about available datasets. If `datasets_names` is provided,
    only information about those datasets will be printed.

    Parameters
    ----------
    datasets_names : str, list, default None
        Name or list of names of the datasets to display information about. If
        None, information about all datasets will be displayed.
    version : str, int, default None
        **Deprecated** since version 0.27.0, it has no effect and will be removed
        in version 0.29.0. Datasets are always fetched from the main branch of
        skforecast-datasets.

    Returns
    -------
    None

    """

    _warn_deprecated_version(version)
    if datasets_names is None:
        datasets_names = sorted(datasets)
    elif isinstance(datasets_names, str):
        datasets_names = [datasets_names]
    else:
        datasets_names = list(datasets_names)

    for dataset_name in datasets_names:
        if dataset_name in datasets:
            _print_dataset_info(dataset_name)
        else:
            print(
                f"Dataset '{dataset_name}' not available. Set argument "
                f"`datasets_names` to None to see all available datasets."
            )