kdiagram.utils.build_q_column_names¶

kdiagram.utils.build_q_column_names(df, quantiles, value_prefix=None, dt_value=None, strict_match=True)[source]¶

Generate and validate quantile column names following naming conventions.

Parameters:

df (pd.DataFrame) – Target DataFrame containing potential quantile columns
quantiles (list of float/str) – Quantile values to search for (0 < q < 1). Accepts: - Float values (e.g., 0.25) - String representations (e.g., “25%”)
value_prefix (str, optional) – Column name prefix for structured naming. If None, looks for unprefixed columns.
dt_value (list of str/int, optional) – Temporal identifiers for time-aware quantiles. Converts all values to strings.
strict_match (bool, default True) – Matching strategy: - True: Requires exact column name matches - False: Uses regex pattern matching for flexible detection

Returns:

Valid column names found in the DataFrame matching the quantile naming pattern.

Return type:

list

Notes

Constructs column names using the pattern:

\[\begin{split}\text{col_name} = \begin{cases} \text{value_prefix}\_\text{date}\_q\text{quantile} & \text{if both prefix and date exist} \\ \text{value_prefix}\_q\text{quantile} & \text{if only prefix exists} \\ \text{date}\_q\text{quantile} & \text{if only date exists} \\ q\text{quantile} & \text{otherwise} \end{cases}\end{split}\]

Examples

>>> from kdiagram.utils.diagnose_q import build_q_column_names
>>> import pandas as pd

# Basic usage with prefix >>> df = pd.DataFrame(columns=[‘price_q0.25’, ‘price_2023_q0.5’]) >>> build_q_column_names(df, [0.25, 0.5], ‘price’) # if strict_match ts [‘price_q0.25’, ‘price_2023_q0.5’]

# Date-filtered search >>> build_q_column_names(df, [0.5], ‘price’, dt_value=[‘2023’]) [‘price_2023_q0.5’]

# Unprefixed columns >>> df = pd.DataFrame(columns=[‘q0.75’, ‘2024_q0.9’]) >>> build_q_column_names(df, [0.75, 0.9]) [‘q0.75’, ‘2024_q0.9’]