Utils Modules

Tides utility functions and class. Mostly for handling tags, generating tree, or finding and selecting data gaps.

tide.utils.tide_request(data_columns, request=None)[source]

Select columns by matching structured TIDE-style tags.

Column names follow the format:

name__unit__bloc__sub_bloc

Tags are separated by double underscores (“__”). Not all levels are required.

Before matching, column names are automatically enriched to the maximum tag depth present in data_columns. Missing tag levels are filled using DEFAULT_TAGS, ensuring consistent hierarchical comparison.

The request argument defines tag queries:

  • Tags are separated by “__”

  • OR conditions are separated by “|”

  • Multiple request entries are OR-combined

  • Matching is exact per tag part (no substring matching)

Parameters:

  • data_columns (pandas.Index or list of str) – Collection of column names using TIDE-style tagging.

  • request (str or list[str] or pandas.Index, optional) –

    Tag query expression(s). Each expression may contain:

    • A full tag path (e.g., “name__°C__bloc2”)

    • A partial tag (e.g., “°C”, “bloc1”)

    • OR groups separated by “|” (e.g., “kWh|°C”)

    If None, all columns are returned.

Returns:

Column names matching at least one request expression. Order is preserved and duplicates are removed.

Return type:

list[str]

Notes

  • Matching is performed on enriched tag representations.

  • Default tag values (e.g., “OTHER”) may be injected during enrichment.

  • Matching is exact at tag level, not substring-based.

  • Requests may contain between 1 and 4 tag levels.

Examples

>>> tide_request(DF_COLUMNS, "°C")
>>> tide_request(DF_COLUMNS, "kWh|°C")
>>> tide_request(DF_COLUMNS, ["kWh|°C", "name_5__kWh"])