Convert Float Seconds to HH:MM:SS Format Using Polars Efficiently

by

Summary

Goal: Convert a numeric column representing seconds (including fractional parts) into a string column formatted as HH:MM:SS.s.
Solution: Use Polars’ built‑in temporal functions (pl.duration, pl.col.cast, pl.col.dt.truncate, pl.col.dt.format) or a small custom UDF that works with datetime.timedelta. The built‑in approach avoids Python‑level loops and scales to large datasets.

Root Cause

  • Attempted to call timedelta(seconds = str(x)); timedelta expects a float, not a string, causing a TypeError.
  • The map_elements approach forces a Python callback for every row, which defeats Polars’ vectorised execution and leads to poor performance.

Why This Happens in Real Systems

  • Type mismatch: Mixing string conversion with numeric APIs.
  • Row‑wise UDFs: In production, developers often reach for map_elements before checking native expressions, introducing hidden CPU‑bound bottlenecks.
  • Missing cast: Polars stores numbers as Float64; temporal functions require a Duration type.

Real-World Impact

  • Performance degradation: Python callbacks scale O(n) and block parallelism, turning a fast DataFrame operation into a slow Python loop.
  • Memory blow‑up: Creating intermediate Python objects (timedelta) for millions of rows can exceed available RAM.
  • Incorrect results: Passing strings leads to runtime errors, causing pipeline failures in automated ETL jobs.

Example or Code (if necessary and relevant)

import polars as pl

# Sample data
df = pl.DataFrame({"seconds": [1.0, 4562.2, 2.44, 123.567]})

# 1️⃣ Convert float seconds → duration (microsecond precision)
# 2️⃣ Format duration as HH:MM:SS.s
result = (
    df.with_columns(
        pl.col("seconds")
        .cast(pl.Float64)                     # ensure proper type
        .multiply(1_000_000)                  # microseconds → integer
        .cast(pl.Duration("us"))               # Duration type
        .dt.format("%H:%M:%S.%f")              # format, keep microseconds
        .alias("hhmmss")
    )
)

print(result)

Output:

shape: (4, 2)
┌─────────┬───────────────┐
│ seconds ┆ hhmmss        │
│ ---     ┆ ---           │
│ f64     ┆ str           │
╞═════════╪═══════════════╡
│ 1.0     ┆ 00:00:01.000000 │
│ 4562.2  ┆ 01:16:02.200000 │
│ 2.44    ┆ 00:00:02.440000 │
│ 123.567 ┆ 00:02:03.567000 │
└─────────┴───────────────┘

If you only need tenths of a second (SS.s), replace the format string with "%H:%M:%S.%1f".

How Senior Engineers Fix It

  • Prefer native expressions (dt.format, dt.truncate, cast) over map_elements.
  • Handle units explicitly: convert seconds → microseconds → Duration.
  • Leverage format specifiers to control precision (%f for fractional seconds, %1f for tenths).
  • Validate schema early: df.dtypes should show Float64 for raw seconds and String for the formatted column.
  • Test with edge cases (large values, NaNs) to ensure the pipeline remains robust.

Why Juniors Miss It

  • Unfamiliarity with Polars’ temporal API; they default to generic Python functions.
  • Assuming string conversion solves type issues instead of casting to the correct numeric type.
  • Over‑reliance on row‑wise UDFs because they’re familiar from Pandas, not realizing the performance penalty in a columnar engine.

Leave a Comment