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].

\[\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:

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

  • value_prefix (str) – Base measurement name for column reconstruction (e.g., 'predicted_subsidence')

  • dt_col (str, default 'dt_col') – Name of temporal dimension column containing dt_values

  • q (list 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

  • spatial_cols (Tuple[str, str] | None)

Returns:

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

Return type:

pd.DataFrame

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')

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: - Maintains original spatial coordinates through operations - Handles missing quantiles per temporal value based on error - Preserves original data types for measurement values

See also

pandas.pivot_table

Base pandas function for reshaping

to_long_data_q

Inverse transformation function

gofast.analysis.validate_spatial_coordinates

Spatial validation

References