kdiagram.utils.pivot_q_data

kdiagram.utils.pivot_q_data(df, value_prefix, dt_col='dt_col', q=None, spatial_cols=None, error='raise', verbose=0)[source]

Convert long-format DataFrame with quantile columns back to wide format with temporal quantile measurements.

Reconstructs columns following the pattern {value_prefix}_{dt_value}_q{quantile} from separated temporal and quantile dimensions. Inverse operation of to_long_data_q [1].

(1)\[\mathbf{L}_{p \times k} \rightarrow \mathbf{W}_{m \times n}\]

where:

  • \(p\) = Long format row count

  • \(k\) = Spatial cols + temporal + quantile columns

  • \(m\) = \(p / t\) (t = unique temporal values)

  • \(n\) = Spatial cols + \(t \times q\) quantile columns

Parameters:
dfpd.DataFrame

Long-format DataFrame containing: - Spatial columns (e.g., 'lon', 'lat') - Temporal column (dt_col) - Quantile columns ({value_prefix}_q{quantile})

value_prefixstr

Base measurement name for column reconstruction (e.g., 'predicted_subsidence')

dt_colstr, default=’dt_col’

Name of temporal dimension column containing dt_values

qlist of float/str, optional

Specific quantiles to include in output. If None, uses all detected quantiles in columns

error{‘raise’, ‘warn’, ‘ignore’}, default=’raise’

Handling for missing components: - 'raise': ValueError on missing data - 'warn': Warning with partial DataFrame - 'ignore': Return partial DataFrame silently

verbose{0, 1, 2, 3, 4, 5}, default=0

Detail level for processing messages: - 0: Silent - 1: Basic progress - 2: Column detection details - 3: Quantile validation - 4: Pivoting steps - 5: Full shape transitions

Returns:
pd.DataFrame

Wide-format DataFrame with columns: - Spatial columns - {value_prefix}_{dt_value}_q{quantile} columns

Parameters:
Return type:

DataFrame

See also

pandas.pivot_table

Base pandas function for reshaping

Notes

  1. Column requirements:

    • Must contain exactly one temporal column (dt_col)

    • Quantile columns must follow {prefix}_q{quantile} pattern

    • Spatial columns must be unique per location

  2. Pivoting logic [2]:

    • Maintains original spatial coordinates through operations

    • Handles missing quantiles per temporal value based on error

    • Preserves original data types for measurement values

References

[1]

VanderPlas, J. (2016). “Python Data Science Handbook”. O’Reilly Media, Inc.

[2]

McKinney, W. (2013). “Python for Data Analysis”. O’Reilly Media, Inc.

Examples

>>> from kdiagram.utils.q_utils import pivot_q_data
>>> long_df = pd.DataFrame({
...     'lon': [-118.25, -118.25, -118.3],
...     'lat': [34.05, 34.05, 34.1],
...     'year': [2022, 2023, 2022],
...     'subs_q0.1': [1.2, 1.7, 1.3],
...     'subs_q0.5': [1.5, 1.9, 1.6]
... })
>>> wide_df = pivot_q_data(long_df, 'subs', dt_col='year')
>>> wide_df.columns
Index(['lon', 'lat', 'subs_2022_q0.1', 'subs_2022_q0.5',
       'subs_2023_q0.1', 'subs_2023_q0.5'], dtype='object')