Explorar guías rápidas · Python

Tecnología: PythonCategoría: Análisis de datosNivel: IntermedioActualizado

Trabajar con fechas y marcas de tiempo

Analiza, compara, filtra, normaliza, localiza, convierte, agrupa y valida fechas y marcas de tiempo en pandas sin introducir errores de zona horaria ni de límites.

En esta página
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Analizar una columna datetime
  5. 2. Analizar explícitamente un formato conocido
  6. 3. Analizar las marcas de tiempo directamente como UTC
  7. 4. Comprobar si una columna datetime tiene zona horaria
  8. 5. Localizar marcas de tiempo naive en la zona horaria del origen
  9. 6. Convertir marcas de tiempo con zona horaria
  10. 7. Gestionar de forma deliberada la ambigüedad del horario de verano
  11. 8. Filtrar un día completo de forma segura
  12. 9. Filtrar un mes completo de forma segura
  13. 10. Filtrar marcas de tiempo con zona horaria usando límites coherentes
  14. 11. Filtrar por la fecha local del negocio
  15. 12. Extraer componentes de fecha y hora
  16. 13. Normalizar las marcas de tiempo a medianoche
  17. 14. Convertir a valores date de Python
  18. 15. Redondear las marcas de tiempo hacia abajo a un intervalo
  19. 16. Redondear marcas de tiempo
  20. 17. Agrupar por día con pd.Grouper
  21. 18. Agrupar por mes
  22. 19. Calcular diferencias de tiempo
  23. 20. Sumar desplazamientos de tiempo
  24. 21. Ordenar por marca de tiempo
  25. 22. Obtener la fila más reciente por entidad
  26. 23. Obtener la marca de tiempo del evento anterior
  27. 24. Comparar de forma segura marcas de tiempo de distintos orígenes
  28. 25. Usar merge_asof para joins por fecha de vigencia
  29. 26. Limitar la distancia temporal de las coincidencias con una tolerancia
  30. 27. Encontrar fechas no válidas o faltantes después del análisis
  31. 28. Comprobar el rango de fechas después del análisis
  32. 29. Comprobar marcas de tiempo duplicadas dentro de una clave de negocio
  33. Qué significa el resultado
  34. Qué revisar
  35. Muchos valores se convierten en NaT
  36. La marca de tiempo parece desplazada varias horas
  37. Los totales diarios difieren entre sistemas
  38. Faltan filas del final del día
  39. La duración es inesperadamente inferior a un día
  40. Los cambios de horario de verano producen horas locales ambiguas o inexistentes
  41. Notas de producción
  42. Almacena las marcas de tiempo de los eventos en UTC cuando sea posible
  43. No pierdas la información de zona horaria demasiado pronto
  44. Los valores solo de fecha y las marcas de tiempo son conceptos distintos
  45. Los intervalos semiabiertos evitan errores de límite
  46. El análisis puede ser costoso
  47. La conversión de zona horaria puede cambiar las fechas de los informes
  48. La aritmética de calendario difiere de las duraciones fijas
  49. Errores comunes
  50. 1. Comparar cadenas de fecha en lugar de marcas de tiempo analizadas
  51. 2. Usar tz_localize() cuando lo que quieres es tz_convert()
  52. 3. Marcar marcas de tiempo locales como UTC
  53. 4. Filtrar hasta 23:59:59
  54. 5. Usar .dt.date demasiado pronto
  55. 6. Usar .dt.seconds para duraciones completas
  56. 7. Ignorar los cambios de horario de verano
  57. 8. Agrupar por día marcas de tiempo UTC para un informe en hora local del negocio
  58. 9. Sobrescribir los fallos de análisis sin inspeccionarlos
  59. Siguiente paso
  60. Para profundizar

Problema

Las fechas y las marcas de tiempo parecen sencillas hasta que los datos de producción incluyen:

  • varios formatos
  • valores no válidos
  • marcas de tiempo con y sin zona horaria (aware y naive)
  • hora UTC y hora local mezcladas
  • errores de límite al final del día
  • cambios de horario de verano
  • informes solo por fecha mezclados con marcas de tiempo precisas de eventos
  • joins con datos de referencia que tienen fechas de vigencia

El objetivo es tratar el tiempo de forma explícita para que los filtros, las agrupaciones, las comparaciones, los joins y los informes sigan siendo correctos.

Tienes que responder:

  • ¿La columna es realmente de tipo datetime?
  • ¿Qué filas no se pudieron analizar?
  • ¿Las marcas de tiempo tienen zona horaria o son naive?
  • ¿Se conoce la zona horaria del origen?
  • ¿Los datos deben almacenarse en UTC?
  • ¿Los límites de los rangos de fechas son inclusivos o exclusivos?
  • ¿Los periodos de agrupación se basan en UTC o en la hora local del negocio?

Respuesta rápida

Analiza de forma deliberada:

df["event_time"] = pd.to_datetime(
    df["event_time"],
    errors="coerce",
)

Inspecciona los fallos de análisis:

failed = df.loc[
    df["event_time"].isna()
]

Filtra un mes con un intervalo semiabierto:

start = pd.Timestamp("2026-10-01")
end = pd.Timestamp("2026-11-01")

october = df.loc[
    (df["event_time"] >= start)
    & (df["event_time"] < end)
]

Para datos de producción con zona horaria, normaliza a UTC:

df["event_time"] = pd.to_datetime(
    df["event_time"],
    utc=True,
    errors="coerce",
)

Después, convierte a hora local solo cuando la regla de negocio lo requiera.

Código / comandos

1. Analizar una columna datetime

df["event_time"] = pd.to_datetime(
    df["event_time"],
    errors="coerce",
)

errors="coerce" convierte los valores no válidos en NaT.

Esto es útil durante la ingesta, porque los valores incorrectos se vuelven visibles en lugar de lanzar un error y detenerlo todo de inmediato.

No sobrescribas la columna de origen antes de inspeccionar los fallos de conversión si el texto original importa para la depuración.

Más seguro durante la investigación:

parsed = pd.to_datetime(
    df["event_time"],
    errors="coerce",
)

failed = df.loc[
    df["event_time"].notna()
    & parsed.isna()
]

print(failed)

2. Analizar explícitamente un formato conocido

Si el formato de entrada es estable, especifícalo.

df["event_date"] = pd.to_datetime(
    df["event_date"],
    format="%Y-%m-%d",
    errors="coerce",
)

Para marcas de tiempo:

df["event_time"] = pd.to_datetime(
    df["event_time"],
    format="%Y-%m-%d %H:%M:%S",
    errors="coerce",
)

Los formatos explícitos aclaran la intención y ayudan a detectar cambios inesperados en el origen.


3. Analizar las marcas de tiempo directamente como UTC

df["event_time"] = pd.to_datetime(
    df["event_time"],
    utc=True,
    errors="coerce",
)

Úsalo cuando:

  • las marcas de tiempo del origen ya incluyen desplazamientos de zona horaria
  • el origen está documentado como UTC
  • quieres una representación coherente con zona horaria

Ten cuidado al analizar marcas de tiempo locales naive con utc=True.

Si el texto de origen representa la hora local de reloj, localízalo primero en lugar de fingir que estaba en UTC.


4. Comprobar si una columna datetime tiene zona horaria

print(df["event_time"].dtype)

Ejemplos:

datetime64[ns]

significa sin zona horaria (naive).

datetime64[ns, UTC]

significa con zona horaria, en UTC.

También puedes inspeccionar:

print(df["event_time"].dt.tz)

Para una Series datetime naive, esto devuelve None.


5. Localizar marcas de tiempo naive en la zona horaria del origen

Supón que se sabe que los valores de origen representan la hora local de Nueva York:

df["event_time"] = (
    pd.to_datetime(
        df["event_time"],
        errors="coerce",
    )
    .dt.tz_localize("America/New_York")
)

Usa tz_localize() cuando las marcas de tiempo sean naive pero se conozca su zona horaria real.

No uses tz_convert() con marcas de tiempo naive.


6. Convertir marcas de tiempo con zona horaria

Una vez que las marcas de tiempo tienen zona horaria:

df["event_time_local"] = (
    df["event_time"]
    .dt.tz_convert("America/New_York")
)

Usa tz_convert() para representar el mismo instante en otra zona horaria.

El instante en el tiempo sigue siendo el mismo; solo cambia la representación mostrada en hora local de reloj.


7. Gestionar de forma deliberada la ambigüedad del horario de verano

La localización puede encontrarse con horas locales ambiguas o inexistentes.

Ejemplo:

localized = (
    pd.to_datetime(df["event_time"], errors="coerce")
    .dt.tz_localize(
        "America/New_York",
        ambiguous="NaT",
        nonexistent="NaT",
    )
)

Esto es más seguro para la investigación que adivinar en silencio.

Inspecciona las filas afectadas antes de elegir una regla de producción.


8. Filtrar un día completo de forma segura

Para marcas de tiempo precisas, prefiere un intervalo semiabierto.

start = pd.Timestamp("2026-10-04")
end = pd.Timestamp("2026-10-05")

day_rows = df.loc[
    (df["event_time"] >= start)
    & (df["event_time"] < end)
]

Esto incluye todas las marcas de tiempo del 4 de octubre sin depender de un 23:59:59.999999 artificial.


9. Filtrar un mes completo de forma segura

start = pd.Timestamp("2026-10-01")
end = pd.Timestamp("2026-11-01")

october = df.loc[
    (df["event_time"] >= start)
    & (df["event_time"] < end)
]

Este patrón es robusto para marcas de tiempo con precisión inferior al segundo.


10. Filtrar marcas de tiempo con zona horaria usando límites coherentes

Si la Series está en UTC con zona horaria:

start = pd.Timestamp(
    "2026-10-01",
    tz="UTC",
)

end = pd.Timestamp(
    "2026-11-01",
    tz="UTC",
)

filtered = df.loc[
    (df["event_time"] >= start)
    & (df["event_time"] < end)
]

No compares marcas de tiempo con zona horaria con límites sin zona horaria.


11. Filtrar por la fecha local del negocio

Supón que las marcas de tiempo se almacenan en UTC, pero los informes deben usar los días naturales de Nueva York.

Convierte antes de derivar la fecha local:

local_time = (
    df["event_time"]
    .dt.tz_convert("America/New_York")
)

df["local_date"] = local_time.dt.date

Después, filtra:

filtered = df.loc[
    df["local_date"]
    == pd.Timestamp("2026-10-04").date()
]

Esto importa para los eventos cercanos a la medianoche UTC.


12. Extraer componentes de fecha y hora

df["year"] = df["event_time"].dt.year
df["month"] = df["event_time"].dt.month
df["day"] = df["event_time"].dt.day
df["hour"] = df["event_time"].dt.hour
df["weekday"] = df["event_time"].dt.day_name()

Útil para:

  • informes
  • ingeniería de características (feature engineering)
  • filtrado
  • análisis por hora del día

No materialices de forma permanente componentes que puedes derivar a bajo costo, salvo que se necesiten aguas abajo.


13. Normalizar las marcas de tiempo a medianoche

df["event_date"] = (
    df["event_time"]
    .dt.normalize()
)

En las marcas de tiempo con zona horaria, la zona horaria se conserva.

Úsalo cuando necesites una clave de día de tipo datetime en lugar de objetos date de Python.


14. Convertir a valores date de Python

df["event_date"] = (
    df["event_time"]
    .dt.date
)

Esto produce objetos date de Python y, por lo general, da una Series de tipo object.

Para operaciones temporales nativas de pandas, .dt.normalize() o .dt.floor("D") suelen conservar un dtype datetime más útil.


15. Redondear las marcas de tiempo hacia abajo a un intervalo

Por hora:

df["event_hour"] = (
    df["event_time"]
    .dt.floor("h")
)

Por día:

df["event_day"] = (
    df["event_time"]
    .dt.floor("D")
)

Úsalo para agrupar marcas de tiempo exactas en intervalos de informe.


16. Redondear marcas de tiempo

df["rounded_time"] = (
    df["event_time"]
    .dt.round("15min")
)

Redondea solo cuando el intervalo más cercano sea de verdad la regla deseada.

Para los intervalos de informe, el redondeo hacia abajo (floor) suele ser más predecible.


17. Agrupar por día con pd.Grouper

daily = (
    df.groupby(
        pd.Grouper(
            key="event_time",
            freq="D",
        )
    )
    .agg(
        events=("event_id", "count"),
        revenue=("revenue", "sum"),
    )
    .reset_index()
)

Así la clave temporal se mantiene como datetime.


18. Agrupar por mes

monthly = (
    df.groupby(
        pd.Grouper(
            key="event_time",
            freq="MS",
        )
    )
    .agg(
        events=("event_id", "count"),
        revenue=("revenue", "sum"),
    )
    .reset_index()
)

MS significa frecuencia de inicio de mes.

Usa ME cuando quieras explícitamente etiquetas de fin de mes, en una versión de pandas que admita ese alias.


19. Calcular diferencias de tiempo

df["processing_time"] = (
    df["completed_at"]
    - df["started_at"]
)

Resultado:

timedelta64[ns]

Convertir a segundos:

df["processing_seconds"] = (
    df["processing_time"]
    .dt.total_seconds()
)

No uses .dt.seconds cuando necesites la duración completa.

.dt.seconds es solo el componente de segundos dentro del día.


20. Sumar desplazamientos de tiempo

df["expires_at"] = (
    df["created_at"]
    + pd.Timedelta(hours=24)
)

Días:

df["next_day"] = (
    df["event_time"]
    + pd.Timedelta(days=1)
)

Para desplazamientos que tienen en cuenta el calendario:

df["next_month"] = (
    df["event_time"]
    + pd.offsets.MonthBegin(1)
)

Usa desplazamientos de calendario cuando «el mes siguiente» sea lógica de calendario de negocio y no un número fijo de días.


21. Ordenar por marca de tiempo

df = df.sort_values(
    ["customer_id", "event_time"]
)

Esto es importante antes de:

  • rellenar hacia delante (forward fill)
  • rellenar hacia atrás (backward fill)
  • cálculos móviles
  • seleccionar el registro más reciente
  • análisis de secuencias

Nunca supongas que el orden de las filas del origen es cronológico.


22. Obtener la fila más reciente por entidad

latest = (
    df.sort_values(
        ["customer_id", "event_time"]
    )
    .groupby(
        "customer_id",
        as_index=False,
    )
    .tail(1)
)

Esto conserva la fila real asociada a la marca de tiempo más reciente.

No uses:

groupby().agg("max")

para reconstruir una fila «más reciente» a partir de columnas no relacionadas.


23. Obtener la marca de tiempo del evento anterior

df = df.sort_values(
    ["customer_id", "event_time"]
)

df["previous_event_time"] = (
    df.groupby("customer_id")["event_time"]
    .shift(1)
)

df["seconds_since_previous"] = (
    df["event_time"]
    - df["previous_event_time"]
).dt.total_seconds()

Útil para:

  • reconstrucción de sesiones (sessionization)
  • análisis de huecos entre eventos
  • cálculos de latencia
  • detección de solicitudes repetidas

24. Comparar de forma segura marcas de tiempo de distintos orígenes

Antes de comparar, normaliza ambos lados.

Ejemplo:

left_time = pd.to_datetime(
    left["event_time"],
    utc=True,
    errors="coerce",
)

right_time = pd.to_datetime(
    right["event_time"],
    utc=True,
    errors="coerce",
)

Después, compara o haz merge.

No compares una Series UTC con zona horaria con una Series local naive suponiendo que la diferencia es solo de formato.


25. Usar merge_asof para joins por fecha de vigencia

Ejemplo: asociar a cada evento el último precio vigente antes de ese evento.

events = events.sort_values(
    ["product_id", "event_time"]
)

prices = prices.sort_values(
    ["product_id", "effective_time"]
)

result = pd.merge_asof(
    events,
    prices,
    left_on="event_time",
    right_on="effective_time",
    by="product_id",
    direction="backward",
)

Úsalo cuando la igualdad exacta de marcas de tiempo no sea la regla de negocio.

Valida:

  • el orden de clasificación
  • la coherencia de las zonas horarias
  • la clave de entidad
  • la dirección
  • la tolerancia, si corresponde

26. Limitar la distancia temporal de las coincidencias con una tolerancia

result = pd.merge_asof(
    events,
    prices,
    left_on="event_time",
    right_on="effective_time",
    by="product_id",
    direction="backward",
    tolerance=pd.Timedelta("7D"),
)

Esto evita coincidencias con datos de referencia demasiado antiguos.

Usa una tolerancia solo cuando la regla de negocio defina una separación máxima significativa.


27. Encontrar fechas no válidas o faltantes después del análisis

parsed = pd.to_datetime(
    df["event_time_raw"],
    errors="coerce",
)

invalid = df.loc[
    df["event_time_raw"].notna()
    & parsed.isna()
]

print(invalid)

Esta es una comprobación crítica de la ingesta.

Una llamada correcta a pd.to_datetime() con errors="coerce" puede seguir ocultando valores de origen incorrectos si no inspeccionas las conversiones forzadas.


28. Comprobar el rango de fechas después del análisis

print(df["event_time"].min())
print(df["event_time"].max())

Úsalo para detectar:

  • fechas futuras
  • fechas inesperadamente antiguas
  • años mal analizados
  • desplazamientos de zona horaria
  • periodos que faltan en el origen

29. Comprobar marcas de tiempo duplicadas dentro de una clave de negocio

duplicates = df.loc[
    df.duplicated(
        subset=["customer_id", "event_time"],
        keep=False,
    )
].sort_values(
    ["customer_id", "event_time"]
)

print(duplicates)

Una marca de tiempo duplicada puede ser válida.

La pregunta importante es si la clave de negocio y la granularidad de los eventos permiten varias filas en el mismo instante.

Qué significa el resultado

Concepto Significado
datetime64[ns] dtype datetime de pandas/NumPy sin zona horaria.
datetime64[ns, UTC] dtype datetime con zona horaria, en UTC.
pd.Timestamp Escalar de pandas que representa una fecha/hora.
NaT Valor datetime/timedelta faltante.
tz_localize() Asigna una zona horaria a marcas de tiempo naive sin cambiar la hora de reloj.
tz_convert() Convierte marcas de tiempo con zona horaria a otra zona horaria conservando el instante.
Timedelta Duración entre marcas de tiempo o desplazamiento de tiempo fijo.
DateOffset Desplazamiento que tiene en cuenta el calendario, como un avance de un mes o de un día hábil.
floor() Redondea hacia abajo hasta un límite temporal.
normalize() Pone la hora del día a medianoche conservando el contexto de fecha y zona horaria.

Qué revisar

Muchos valores se convierten en NaT

Esto significa que el análisis falló.

Posibles causas:

  • cambió el formato
  • formatos mezclados
  • fechas imposibles
  • texto de zona horaria
  • datos de origen mal formados

Inspecciona las cadenas originales.

La marca de tiempo parece desplazada varias horas

Probablemente hay una confusión de zona horaria.

Comprueba:

  • la zona horaria del origen
  • si el origen ya estaba en UTC
  • si tz_localize() y tz_convert() se usaron en el orden correcto

Los totales diarios difieren entre sistemas

Comprueba si los sistemas agrupan por:

  • fecha UTC
  • fecha local del negocio
  • zona horaria del servidor
  • zona horaria del usuario

El mismo evento puede pertenecer a días naturales distintos según la zona usada para los informes.

Faltan filas del final del día

Esto suele deberse a filtrar con:

timestamp <= "2026-10-31"

que representa la medianoche al inicio del día.

Usa un intervalo semiabierto que termine en el día o el mes siguiente.

La duración es inesperadamente inferior a un día

Comprueba si el código usó:

timedelta.dt.seconds

en lugar de:

timedelta.dt.total_seconds()

Los cambios de horario de verano producen horas locales ambiguas o inexistentes

Es el comportamiento esperado en las zonas horarias con cambios de horario de verano.

Gestiona la ambigüedad de forma explícita en lugar de adivinar en silencio.

Notas de producción

Almacena las marcas de tiempo de los eventos en UTC cuando sea posible

UTC suele ser la representación canónica más segura para:

  • el almacenamiento de eventos
  • los sistemas entre regiones
  • las API
  • el procesamiento distribuido
  • los data lakes

Convierte a la hora local del negocio en la frontera de los informes o la presentación, cuando sea necesario.

No pierdas la información de zona horaria demasiado pronto

Convertir marcas de tiempo con zona horaria en marcas de tiempo naive puede volver ambigua su interpretación posterior.

Conserva la zona horaria hasta que la regla de negocio exija explícitamente lo contrario.

Los valores solo de fecha y las marcas de tiempo son conceptos distintos

Ejemplos:

2026-10-04
2026-10-04T15:27:18Z

El primero es una fecha de calendario.

El segundo es un instante en el tiempo.

No los modeles como si fueran intercambiables.

Los intervalos semiabiertos evitan errores de límite

Prefiere:

start <= timestamp < next_start

en lugar de construir manualmente una marca de tiempo máxima de final de día.

Este patrón es más fácil de razonar y funciona con cualquier precisión de marca de tiempo.

El análisis puede ser costoso

En DataFrames grandes:

  • analiza una sola vez
  • evita conversiones repetidas
  • especifica los formatos conocidos cuando corresponda
  • selecciona solo las columnas necesarias
  • lleva el filtrado por fecha al motor de almacenamiento o de consultas cuando sea posible

La conversión de zona horaria puede cambiar las fechas de los informes

Una marca de tiempo UTC cercana a la medianoche puede pasar al día local anterior tras la conversión.

Convierte siempre antes de derivar las partes de fecha local del negocio.

La aritmética de calendario difiere de las duraciones fijas

Un mes no siempre tiene 30 días.

Usa DateOffset o frecuencias de calendario para las reglas basadas en el calendario.

Usa Timedelta para duraciones transcurridas fijas.

Errores comunes

1. Comparar cadenas de fecha en lugar de marcas de tiempo analizadas

La comparación de cadenas puede parecer que funciona con formatos ISO, pero es frágil y semánticamente incorrecta para la lógica general de fechas.

Analiza primero.

2. Usar tz_localize() cuando lo que quieres es tz_convert()

Usa:

tz_localize -> de marca de tiempo naive a marca de tiempo con zona horaria
tz_convert  -> de una zona horaria a otra zona horaria

Resuelven problemas distintos.

3. Marcar marcas de tiempo locales como UTC

Esto cambia el significado de los datos.

Si 08:00 era la hora local de Nueva York, no asignes UTC sin más.

Localiza primero en Nueva York y después convierte a UTC.

4. Filtrar hasta 23:59:59

Esto todavía puede omitir marcas de tiempo con mayor precisión.

Usa el siguiente límite con <.

5. Usar .dt.date demasiado pronto

Convierte las marcas de tiempo en objetos date de Python y pierde la hora del día.

Conserva las marcas de tiempo hasta que de verdad necesites una semántica de solo fecha.

6. Usar .dt.seconds para duraciones completas

.dt.seconds excluye los días completos.

Usa .dt.total_seconds().

7. Ignorar los cambios de horario de verano

Las horas locales pueden ser ambiguas o inexistentes.

Gestiónalas de forma explícita.

8. Agrupar por día marcas de tiempo UTC para un informe en hora local del negocio

Convierte primero a la zona horaria del negocio.

De lo contrario, los eventos cercanos a la medianoche pueden caer en el día de informe equivocado.

9. Sobrescribir los fallos de análisis sin inspeccionarlos

errors="coerce" es útil, pero puede ocultar datos incorrectos si nunca revisas los nuevos valores NaT.

Siguiente paso

Usa el problema de tiempo para elegir la siguiente acción.

  • Fallos de análisis → inspecciona los valores sin procesar y define formatos y reglas de origen explícitos.
  • Discrepancia de zona horaria → determina la zona horaria del origen y normaliza a una zona canónica.
  • Los informes de negocio usan fechas locales → convierte la zona horaria antes de derivar los campos de día o mes.
  • Faltan filas en los límites → sustituye las marcas de tiempo finales inclusivas por intervalos semiabiertos.
  • Necesitas resúmenes diarios o mensuales → usa pd.Grouper.
  • Necesitas la fila más reciente por entidad → ordena por clave + marca de tiempo y selecciona la fila real.
  • Necesitas los datos de referencia vigentes más cercanos → usa merge_asof.
  • Aparece ambigüedad por el horario de verano → define un tratamiento explícito de las horas ambiguas o inexistentes.
  • El procesamiento de tiempos es costoso → analiza una sola vez y acerca el filtrado y la agrupación al origen de datos cuando sea posible.

← Todas las guías rápidas