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:

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

Returns:

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

Parameters:

df (DataFrame)
quantiles (list[float | str])
value_prefix (str | None)
dt_value (list[str | int] | None)
strict_match (bool)

Return type:

list[str]

See also

kdiagram.utils.diagnose_q.validate_quantiles: For quantile value validation
pandas.Series.str.contains: For column pattern matching

Notes

Constructs column names using the pattern:

(1)¶\[\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']