bdf.normalize#

bdf.normalize(df: pl.DataFrame | pl.LazyFrame | pd.DataFrame, *, normalizer: TableNormalizer | dict[str, str] | None = None, validate: bool = True, include_unknown: bool = False, tz: str = 'UTC') → pl.DataFrame | pl.LazyFrame | pd.DataFrame[source]#

Map vendor columns to BDF canonical names with unit conversion and dtype casting.

Accepts pl.DataFrame, pl.LazyFrame, or pandas.DataFrame. Return type matches input. validate defaults to True: this checks required columns even if no normalizer can be auto-detected from df’s headers (see TableNormalizer.normalize). Pass validate=False to fall back to a soft warning instead of raising.

Parameters:

  • df – Input dataframe in any supported format.

  • normalizer – Explicit TableNormalizer, column map dict, or None for auto-detection.

  • validate – Validate column names against the BDF ontology when True (default; raises on missing required columns instead of warning).

  • include_unknown – Keep columns outside of the BDF spec in the dataframe (default False).

  • tz – IANA timezone applied to naive unix_time_second datetime formats. Defaults to "UTC"; emits a UserWarning when a naive format is in play and tz is left at its default. Around daylight-saving clock changes, repeated local times are converted to the earlier possible Unix Time / s value. For example, if clocks move back from UTC+1 to UTC+0, 01:30 is treated as 00:30 UTC rather than 01:30 UTC. Local times skipped when clocks move forward become null.

Returns:

Normalized dataframe in the same format as input.

Raises:

  • ValueError – If tz is not a recognized IANA timezone name.

  • BDFValidationError – If validate=True and required BDF columns are missing.