kdiagram.utils.pivot_forecasts_long¶

kdiagram.utils.pivot_forecasts_long(df, qlow_cols, q50_cols, qup_cols, horizon_labels=None, id_vars=None)[source]¶

Reshapes multi-horizon forecast data from wide to long format.

This is a powerful data wrangling utility that transforms a DataFrame with separate columns for each horizon’s quantiles (e.g., ‘q10_2023’, ‘q50_2023’, ‘q10_2024’, ‘q50_2024’) into a “long” format DataFrame. The resulting table has dedicated columns for ‘horizon’, ‘q_low’, ‘q_median’, and ‘q_high’, which is often a more convenient structure for plotting and analysis.

Parameters:

dfpd.DataFrame: The input DataFrame in wide format.
qlow_colslist of str: List of column names for the lower quantile, one for each forecast horizon, in order.
q50_colslist of str: List of column names for the median quantile, in the same horizon order.
qup_colslist of str: List of column names for the upper quantile, in the same horizon order.
horizon_labelslist of str, optional: Custom labels for each forecast horizon. If not provided, generic labels like ‘H1’, ‘H2’ will be generated. The length must match the number of quantile columns.
id_varsstr or list of str, optional: Identifier column(s) to keep in the long-format DataFrame (e.g., a location or sample ID). These columns will be repeated for each horizon.

Returns:

pd.DataFrame: The reshaped DataFrame in long format.

Raises:

ValueError: If the lengths of the quantile column lists or the horizon_labels are inconsistent.

Parameters:

df (DataFrame)
qlow_cols (list[str])
q50_cols (list[str])
qup_cols (list[str])
horizon_labels (list[str] | None)
id_vars (str | list[str] | None)

Return type:

DataFrame

See also

pandas.melt: The underlying pandas function for unpivoting.
plot_horizon_metrics: A plot that benefits from this data format.

Examples

>>> import pandas as pd
>>> from kdiagram.utils.forecast_utils import pivot_forecasts_long
>>>
>>> # Create a sample wide-format DataFrame
>>> df_wide = pd.DataFrame({
...     'location_id': ['A', 'B'],
...     'q10_2023': [10, 12], 'q50_2023': [15, 18], 'q90_2023': [20, 24],
...     'q10_2024': [12, 14], 'q50_2024': [18, 21], 'q90_2024': [24, 28],
... })
>>>
>>> # Reshape the data
>>> df_long = pivot_forecasts_long(
...     df_wide,
...     qlow_cols=['q10_2023', 'q10_2024'],
...     q50_cols=['q50_2023', 'q50_2024'],
...     qup_cols=['q90_2023', 'q90_2024'],
...     horizon_labels=['Year 2023', 'Year 2024'],
...     id_vars='location_id'
... )
>>> print(df_long)
  location_id    horizon  q_low  q_median  q_high
0           A  Year 2023     10        15      20
1           B  Year 2023     12        18      24
2           A  Year 2024     12        18      24
3           B  Year 2024     14        21      28